PKG-TRIGGERS(5) FreeBSD File Formats Manual PKG-TRIGGERS(5)
NAME
triggers - trigger file format
DESCRIPTION
Package triggers define commands to be executed when particular files are
installed, modified, or removed by pkg(8). Triggers can be used, for
example, to update a database or index of files based on files installed
by other packages.
There are two kinds of triggers:
Per-transaction
Executed once at the end of the transaction, after all
packages have been processed and all file changes committed
to disk. Even if multiple packages match the same trigger,
it is executed only once and receives the combined list of
matched paths.
Per-package Executed individually for each package as it is being
installed or removed. Per-package triggers run at a
specific phase of the operation (pre-install, post-install,
pre-deinstall, or post-deinstall). Their failure is non-
blocking: the package operation continues even if the
trigger fails.
Triggers are searched for in the list of directories configured by the
PKG_TRIGGERS_DIR configuration option. By default, this includes
/usr/share/pkg/triggers and <localbase>/share/pkg/triggers. Triggers are
in UCL format and should have a .ucl extension.
Per-transaction triggers
Per-transaction trigger files are placed directly in a trigger directory.
The format is the following:
description An optional string providing a human-readable description of
what the trigger does.
path An array of strings containing exact paths. Each time a
package installs a file or directory whose name is equal to
one of the strings, the trigger will be executed at the end
of the transaction.
path_glob An array of strings containing shell-style glob patterns.
Each time a package installs a file or directory whose name
matches one of the patterns, the trigger will be executed at
the end of the transaction.
path_regexp An array of strings containing regular expressions. Each
time a package installs a file or directory whose name
matches one of the regular expressions, the trigger will be
executed at the end of the transaction.
cleanup An object which represents the script to execute in case the
transaction results in removal of the trigger from the
installation. The object requires the following fields:
type The type of the script to be executed. The only
supported type is Lua, indicated by the value "lua"
(see pkg-lua-script(5)).
script The script itself.
sandbox A boolean controlling whether the script runs
inside a capsicum(4) sandbox. Defaults to true.
When disabled, the script has full system access
including pkg.exec().
trigger An object which represents the script to execute at the end
of the transaction if a pattern has been matched. This
object is required and has the following fields:
type The type of the script to be executed. The only
supported type is Lua, indicated by the value "lua"
(see pkg-lua-script(5)).
script The script itself. It will receive as arguments
the list of paths that matched the patterns during
the transaction.
sandbox A boolean controlling whether the script runs
inside a capsicum(4) sandbox. Defaults to true.
When disabled, the script has full system access
including pkg.exec().
Per-package triggers
Per-package trigger files are placed in a subdirectory of a trigger
directory named after the phase at which they should execute:
pre_install/ Before the package files are extracted.
post_install/ After the package files have been extracted and post-
install scripts have run.
pre_deinstall/ Before the package files are removed.
post_deinstall/ After the package files have been removed and post-
deinstall scripts have run.
For example, a trigger that should run after each package installation
would be placed in:
<localbase>/share/pkg/triggers/post_install/mytrigger.ucl
The file format is the same as for per-transaction triggers. The path,
path_glob, and path_regexp fields are used to match the files and
directories of the individual package. The trigger object contains the
script to execute.
Per-package triggers are reloaded from disk before processing each
package, so a trigger installed by an earlier package in the same
transaction will be active for subsequent packages.
In addition to the arg table containing matched paths, per-package
trigger scripts have access to the following Lua global variables:
pkg_name The name of the package being processed.
pkg_version The version of the package being processed.
pkg_upgrade A boolean set to true if the operation is part of an
upgrade, or false for a fresh installation or a standalone
removal.
SEE ALSO
pkg_checksum(3), pkg_create(3), pkg_printf(3), pkg_repo_create(3),
pkg_repos(3), pkg-keywords(5), pkg-lua-script(5), pkg-repository(5),
pkg-script(5), pkg.conf(5), pkg(8), pkg-add(8), pkg-alias(8),
pkg-annotate(8), pkg-audit(8), pkg-autoremove(8), pkg-check(8),
pkg-checksum(8), pkg-clean(8), pkg-config(8), pkg-create(8),
pkg-delete(8), pkg-fetch(8), pkg-help(8), pkg-info(8), pkg-install(8),
pkg-key(8), pkg-lock(8), pkg-plugins(8), pkg-query(8), pkg-register(8),
pkg-repo(8), pkg-repositories(8), pkg-rquery(8), pkg-rwhich(8),
pkg-search(8), pkg-set(8), pkg-shell(8), pkg-shlib(8), pkg-ssh(8),
pkg-stats(8), pkg-unregister(8), pkg-update(8), pkg-updating(8),
pkg-upgrade(8), pkg-version(8), pkg-which(8)
FreeBSD 15.1-STABLE-HBSD March 4, 2026 PKG-TRIGGERS(5)