.\"
.\" FreeBSD pkg - a next generation package for the installation and maintenance
.\" of non-core utilities.
.\"
.\" Copyright (c) 2025 The FreeBSD Project
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" @(#)pkg.1
.\"
.Dd March 17, 2025
.Dt PKG.CONF 5
.Os
.Sh NAME
.Nm "pkg.conf"
.Nd system-wide configuration file for
.Xr pkg 8
.Sh DESCRIPTION
.Nm
is the system-wide configuration file used by the
.Xr pkg 8
tools.
.Pp
The default location of this file is
.Pa /usr/local/etc/pkg.conf .
.Pp
Lines in the file beginning with a "#" are comments
and are ignored.
.Pp
The file is in UCL format.
For more information on the syntax of UCL,
please visit the official UCL website - http://github.com/vstakhov/libucl.
.Pp
The following types of options are recognized -
boolean, string and list options.
.Pp
A boolean option is marked as enabled if one of the following values is
specified in the configuration file -
.Dv YES, TRUE
and
.Dv ON.
.Sh OPTIONS
The following options can be defined in
.Nm :
.Bl -tag -width ".Cm ABI: string"
.It Cm ABI: string
The ABI of the package you want to install, for example
.Ql FreeBSD:14:amd64 .
This should be set in combination with the OSVERSION option if targeting
.Fx
to specify the exact target version.
Default: derived based on ABI_FILE.
.It Cm ABI_FILE: string
Set the file used to determine the target ABI.
Default:
.Pa /usr/bin/uname ,
or if not found,
.Pa /bin/sh .
.It Cm ALIAS: key/value list
Define local aliases for various
.Xr pkg 8
standard command lines.
Whenever the
.Em key
text occurs as a separate
.Sq action
word in a command line of the form
.Nm pkg Em key ... ,
substitute the
.Em value
text verbatim.
The replacement can consist of any sequence of text, which should form
a syntactically correct
.Xr pkg 8
command line when substituted in and followed by any remaining tokens from
the original command line.
Default: not set.
.It Cm ARCHIVE_SYMLINK: boolean
When creating a package, create a symlink to it using the legacy extension,
this is a backward compatibility option, default: true
.It Cm AUTOCLEAN: boolean
Automatically cleanout the content of
.Em PKG_CACHEDIR
after each non dry-run call to
.Xr pkg-install 8
or
.Xr pkg-upgrade 8 .
.It Cm DEFAULT_ALWAYS_YES: boolean
When this option is enabled
.Xr pkg 1
will default to "yes" for all questions
which require user confirmation before doing anything.
Default: NO.
.It Cm ASSUME_ALWAYS_YES: boolean
When this option is enabled
.Xr pkg 1
will automatically assume "yes" to all questions
which require user confirmation before doing anything, as if it
the
.Fl y
flag was specified.
Default: NO.
.It Cm BACKUP_LIBRARIES: boolean
If set to
.Sy true
and if an upgrade will remove a library, then
.Xr pkg 8
will backup the library to the path defined by
.Cm BACKUP_LIBRARY_PATH .
An initial backup will create the
.Qq compat-libraries
package. The package version will be bumped whenever an additional library is backed up.
Default: NO.
.It Cm BACKUP_LIBRARY_PATH: string
Path for library backups.
Default:
.Pa /usr/local/lib/compat/pkg .
.It Cm COMPRESSION_FORMAT: string
Set the default compression format: tzst, txz, tbz, tar.
Default: tzst.
.It Cm COMPRESSION_LEVEL: integer
Set the default compression level, special values are:
.Bl -tag
.It 0 default value per libarchive developers
.It -1 default value per pkg developers (default)
.El
.It Cm COMPRESSION_THREADS: integer
Set the number of threads to use during compression (only functional for txz and tzst)
.It Cm CONSERVATIVE_UPGRADE: boolean
Ensure in multi repository mode that the priority is given as much as possible
to the repository where a package was first installed from.
Default: YES.
.It Cm CUDF_SOLVER: string
Experimental: tells pkg to use an external CUDF solver.
Default: not set.
.It Cm CASE_SENSITIVE_MATCH: boolean
Match package names or regular expressions given on the command line
against values in the database in a case sensitive way.
Default: NO.
.It Cm DEBUG_LEVEL: integer
Incremental values from 1 to 4 produce successively more verbose
debugging output.
A setting of 0 disables debugging output.
Overridden by the
.Fl d
command line option.
Default: 0.
.It Cm DEBUG_SCRIPTS: boolean
Activate debug mode for scripts (aka set -x)
Default: NO.
.It Cm DEVELOPER_MODE: boolean
Makes certain errors immediately fatal.
Adds various warnings and
suggestions to the output of
.Xr pkg 1
as an aid to port maintainers, including indicating when the port
might be marked as architecture independent.
Default: NO.
.It Cm DOT_FILE: string
When defined to a valid path, pkg will generate a
.Xr dot 1
file with the dependency graph of the concerned transaction.
.It Cm EVENT_PIPE: string
Send all event messages to the specified FIFO or Unix socket.
Events messages should be formatted as JSON.
Default: not set.
.It Cm FETCH_RETRY: integer
Number of times to retry a failed fetch of a file.
Default: 3.
.It Cm FETCH_TIMEOUT: integer
Maximum number of seconds to wait for any one file to download from the
network, either by SSH or any of the protocols supported by
.Xr libcurl 3
functions.
Default: 30.
.It Cm HANDLE_RC_SCRIPTS: boolean
When enabled, this option will automatically perform start/stop of
services during package installation and deinstallation.
Services are only started on installation if they are enabled in
.Pa /etc/rc.conf .
Default: NO.
.It Cm HTTP_USER_AGENT: string
Define User-agent to be sent to HTTP server when getting repository
data.
.It Cm IGNORE_OSVERSION: boolean [FreeBSD specific]
Ignore FreeBSD OS version check, useful on -STABLE and -CURRENT branches.
Default: NO.
.It Cm INDEXDIR: string
If set, the directory to search for
.Cm INDEXFILE
in.
If unset,
.Cm PORTSDIR
will be searched instead.
Default: not set.
.It Cm INDEXFILE: string
The filename of the ports index, searched for in
.Cm INDEXDIR
or
.Cm PORTSDIR .
Default: INDEX-N where
.Cm N
is the OS major version number.
.It Cm IP_VERSION: integer
Restrict network access to specified IP version.
4 will only allow IPv4 and 6 will only allow IPv6.
Any other value will use the system default.
Repositories or command line options can override this setting.
Default: 0.
.It Cm LOCK_RETRIES: integer
Number of attempts to obtain a lock before giving up and exiting.
Default: 5.
.It Cm LOCK_WAIT: integer
Wait time in seconds to regain a lock if it is not available.
Default: 1.
.It Cm METALOG: string
If set,
.Xr pkg 8
will write a METALOG of the extracted files.
.It Cm NAMESERVER: string
Hostname or IPv4 or IPv6 address of name server to use for DNS
resolution, overriding the system defaults in
.Pa /etc/resolv.conf .
When given as a hostname, will be converted to a list of IPv4 or IPv6
addresses by the default mechanisms configured on the system.
See
.Xr getaddrinfo 3 .
.It Cm OSVERSION: integer
Specifiy the exact
.Fx
version for the target ABI. This should be set in combination with the ABI option.
The format is the same as the format of
.Dv __FreeBSD_version
in
.Pa /usr/include/sys/param.h .
Default: derived based on ABI_FILE.
.It Cm PERMISSIVE: boolean
Ignore conflicts while registering a package.
Note that the conflicting files will not be recorded as owned by the new
package.
Default: NO.
.It Cm PKG_CACHEDIR: string
Specifies the cache directory for packages.
Default:
.Pa /var/cache/pkg .
.It Cm PKG_CREATE_VERBOSE: boolean
When set to a
.Sy true
value, make
.Xr pkg-create 8
use verbose mode as standard.
Default:
.Sy NO .
.It Cm PKG_DBDIR: string
Specifies the directory to use for storing the package
database files.
Default:
.Pa /var/db/pkg .
.It Cm PKG_ENABLE_PLUGINS: boolean
When set to
.Dq YES ,
activate plugin support.
Default: YES.
.It Cm PKG_ENV: Key/Value list
This tells
.Xr pkg 8
to set key/values to be passed in the environment.
This allow setting variables to configure the http(s) fetcher.
Which accepts environment variables compatible with
.Xr fetch 3 ,
e.g.,
.Ev HTTP_PROXY .
Default: not set.
.It Cm PKG_PLUGINS_DIR: string
Directory which
.Xr pkg 8
will load plugins from.
Default:
.Pa /usr/local/lib/pkg .
.It Cm PKG_TRIGGERS_ENABLE
Enable or disable execution of triggers at the end of the transactions.
Default: YES.
.It Cm PKG_TRIGGERS_DIR
Directory where the triggers are stored
Default:
.Pa /usr/local/share/pkg/triggers .
.It Cm PKG_SSH_ARGS: string
Extra arguments to pass to
.Xr ssh 1 .
Default: not set.
.It Cm PLIST_KEYWORDS_DIR: string
Directory containing definitions of plist keywords.
Default: PORTSDIR/keyword.
.It Cm PLUGINS: array
List of plugins that
.Xr pkg 8
should load.
Default: not set.
.It Cm PLUGINS_CONF_DIR: string
Directory containing per-plugin configuration files.
Default:
.Pa /usr/local/etc/pkg .
.It Cm PORTSDIR: string
Specifies the location to the Ports directory.
Default:
.Pa /usr/ports .
.It Cm READ_LOCK: boolean
Use read locking for query database.
Default: NO.
.It Cm REPOS_DIR: array
List of directories to search for repository configuration files.
Default:
.Pa /etc/pkg/ ,
.Pa /usr/local/etc/pkg/repos/ .
.It Cm REPO_AUTOUPDATE: boolean
When true, automatically check for and download updates to
.Pa /var/db/pkg/repo.sqlite
when running one of:
.Nm pkg fetch ,
.Nm pkg install ,
.Nm pkg rquery ,
.Nm pkg search ,
.Nm pkg upgrade ,
or
.Nm pkg version -R .
Default: YES.
.It Cm RUN_SCRIPTS: boolean
Run pre-/post-installation action scripts.
Default: YES.
.It Cm SAT_SOLVER: string
Experimental: tells pkg to use an external SAT solver.
Default: not set.
.It Cm SQLITE_PROFILE: boolean
Profile SQLite queries.
Default: NO.
.It Cm SSH_RESTRICT_DIR: string
Directory which the ssh subsystem will be restricted to.
Default: not set.
.It Cm SYSLOG: boolean
Log all of the installation/deinstallation/upgrade operations via
.Xr syslog 3 .
Default: YES.
.It Cm UNSET_TIMESTAMP: boolean
Do not include timestamps in the package
.Xr tar 1
archive.
Normally, timestamps are copied from the staging directory the
package is created from.
Default: NO.
.It Cm VERSION_SOURCE: string
Default database for comparing version numbers in
.Xr pkg-version 8 .
Valid values are
.Sy I
for index,
.Sy P
for ports,
.Sy R
for remote.
Default: If unset, the algorithm described in
.Xr pkg-version 8
is used to determine the version source automatically.
.It Cm VALID_URL_SCHEME
List of url scheme that pkg can accept while parsing the repository
confguration file.
.It Cm VULNXML_SITE: string
Specifies the URL to fetch the
.Pa vuln.xml
vulnerability database from.
Default:
.Pa http://vuxml.freebsd.org/freebsd/vuln.xml.xz .
.It Cm WARN_SIZE_LIMIT: integer
When download and total change is less than than this option, don't ask
the user to confirm the desired action.
Default:
.Sy 1048576
.Pq 1MB .
.It Cm WORKERS_COUNT: integer
How many workers are used for pkg-repo.
If set to 0,
.Va hw.ncpu
is used.
Default: 0.
.It Cm PKG_REINSTALL_ON_OPTIONS_CHANGE
Reinstall packages if options changed between the local version and the
remote version.
Default: true
.El
.Sh REPOSITORY CONFIGURATION
To use a repository you will need at least one repository
configuration file.
.Pp
Repository configuration files are searched for in order of the
directories listed in the
.Cm REPOS_DIR
array,
which defaults to
.Pa /etc/pkg/
and
.Pa /usr/local/etc/pkg/repos/ .
.Pp
Filenames are arbitrary, but should end in
.Sq .conf .
For example
.Pa /usr/local/etc/pkg/repos/myrepo.conf .
.Pp
A repository file is in UCL format and has the following form:
.Bl -tag -width ".Cm myrepo:"
.It Cm myrepo:
.Bl -tag -width ".Cm MIRROR_TYPE: string"
.It Cm ENV: object
A list of key value entries that will be passed as environment variable
for the bundled
.Xr fetch 3 ,
per repository.
.It Cm URL: string
URL for this repository only.
.It Cm ENABLED: boolean
The repository will be used only if this option is enabled.
Default: YES.
.It Cm MIRROR_TYPE: string
MIRROR_TYPE for this repository only.
Default: NONE.
Any of
.Dv HTTP
or
.Dv SRV
or
.Dv NONE .
.It Cm SIGNATURE_TYPE: string
Specifies what type of signature this repository uses.
Can be one of
.Dv NONE ,
.Dv PUBKEY or
.Dv FINGERPRINTS .
(default: NONE)
.It Cm PUBKEY: string
This should be set to a path containing public key for this repository
only. (default: NONE)
.It Cm FINGERPRINTS: string
This should be set to a path containing known signatures for the repository.
.It Cm IP_VERSION: integer
Restrict network access to specified IP version.
4 will only allow IPv4 and 6 will only allow IPv6.
Any other value will use the system default.
This option overrides the global setting with the same name and can be
overwritten by a command line option.
Default: 0.
.It Cm PRIORITY: integer
Set the priority of the repository.
Higher values are preferred.
Default: 0.
.El
.El
.Pp
For a
.Cm MIRROR_TYPE
of
.Dv NONE ,
any of the following URL schemes:
.Dv http:// ,
.Dv https:// ,
.Dv file:// ,
.Dv ssh:// ,
.Dv tcp:// .
Where
.Sy MIRROR_TYPE
is
.Dv SRV ,
you should use a
.Dv pkg+http://
or
.Dv pkg+https://
(etc.) URL scheme.
Using an
.Dv http://
URL implies that the hostname part is a simple hostname according to
RFC 2616, and is no longer accepted.
.Pp
When
.Sy SIGNATURE_TYPE
is
.Dv NONE ,
then no signature checking will be done on the repository.
When
.Sy SIGNATURE_TYPE
is
.Dv PUBKEY ,
then the
.Sy PUBKEY
option will be used for signature verification.
This option is for use with the built-in signing support.
When
.Sy SIGNATURE_TYPE
is
.Dv FINGERPRINTS ,
then the
.Sy FINGERPRINTS
option will be used for signature verification.
This option is for use with an external signing command.
See
.Xr pkg-repo 8
for more discussion on signature types.
.Pp
If
.Sy FINGERPRINTS
is set to
.Pa /usr/local/etc/pkg/fingerprints/myrepo ,
then the directories
.Pa /usr/local/etc/pkg/fingerprints/myrepo/trusted
and
.Pa /usr/local/etc/pkg/fingerprints/myrepo/revoked
should exist with known good and bad fingerprints, respectively.
Files in those directories should be in the format:
.Bd -literal -offset indent
function: sha256
fingerprint: sha256_representation_of_the_public_key
.Ed
.Pp
The repository tag
.Fa myrepo
is an arbitrary string.
Reusing the repository tag will cause those items defined in
configuration files later on the
.Sy REPOS_DIR
search path to overwrite the equivalent settings for the same tag
earlier on the search path.
Hence the very common idiom, used to turn off the default
.Cm FreeBSD
configuration shipped in
.Pa /etc/pkg/FreeBSD.conf .
Rather than editing that file directly, create
.Pa /usr/local/etc/pkg/repos/FreeBSD.conf
with this content:
.Bd -literal -offset indent
FreeBSD: { enabled: NO }
.Ed
.Pp
Repositories are processed in the order they are found on the
.Sy REPOS_DIR
search path, with individual repository configuration files in the
same directory processed in alphabetical order.
Settings from files later in the search path will override those from
earlier ones.
Packages are selected preferentially out of all the repositories that contain
them from the repository with the highest priority, so long as they are
suitable to solve the necessary dependency requirements.
However, this preference may be overruled when
.Sy CONSERVATIVE_UPGRADE
is set to
.Dv true ,
in which case a package will as far as possible always be upgraded from the
same repository the older installed version came from, as given in the
.Sy repository
annotation of the installed package.
See
.Xr pkg-repository 5
for details.
.Pp
It is possible to specify more than one repository per file.
.Sh VARIABLES
The following variables will be expanded during the parsing of
.Nm .
.Bl -tag -width Ds
.It Va ABI
Expands to the ABI string
.Po e.g.
.Ql FreeBSD:14:amd64
.Pc .
.It Va OSNAME
Expands to the the name of the target operating system.
.It Va RELEASE
Expands to the full version of the target operating system.
.It Va VERSION_MAJOR
Expands to the major version of the target operating system.
.It Va VERSION_MINOR
Expands to the minor version of the target operating system.
.It Va OSVERSION
If targeting
.Fx ,
expands to the target version in the same format as
.Dv __FreeBSD_version
in
.PA /usr/include/sys/param.h .
.It Va ARCH
Expands to the architecture of the system.
.El
.Pp
Since the values of these variables are affected by some options that
may be set in
.Nm
(for example ABI or ABI_FILE), it is necessary to parse pkg.conf in two
passes. The first pass only parses the ABI, ABI_FILE, and OSVERSION
options and does no variable expansion. The second pass expands the
variables listed above and ignores the ABI, ABI_FILE, and OSVERSION
options.
.Sh ENVIRONMENT
An environment variable with the same name as the option in the
configuration file always overrides the value of an option set in the
file.
.Sh EXAMPLES
.Fx
latest repository configuration:
.Bd -literal -offset indent
FreeBSD: {
url: "pkg+https://pkg.freebsd.org/${ABI}/latest",
enabled: true,
signature_type: "fingerprints",
fingerprints: "/usr/share/keys/pkg",
mirror_type: "srv"
}
.Ed
.Pp
.Fx
quarterly kernel modules repository configuration:
.Bd -literal -offset indent
FreeBSD-kmods: {
url: "pkg+https://pkg.freebsd.org/${ABI}/kmods_quarterly_${VERSION_MINOR}",
enabled: true,
signature_type: "fingerprints",
fingerprints: "/usr/share/keys/pkg",
mirror_type: "srv"
}
.Ed
.Pp
Example for pkg.conf:
.Bd -literal -offset indent
pkg_dbdir: "/var/db/pkg"
pkg_cachedir: "/var/cache/pkg"
portsdir: "/usr/ports"
handle_rc_scripts: false
assume_always_yes: false
repos_dir: [
"/etc/pkg",
"/usr/local/etc/pkg/repos",
]
syslog: true
developer_mode: false
pkg_env: {
http_proxy: "http://myproxy:3128",
}
alias: {
origin: "info -qo",
nonauto: "query -e '%a == 0' '%n-%v'"
}
.Ed
.Pp
To bootstrap
.Xr pkg 8
using a private repository (Assuming a
.Xr pkg 7
new enough to support the
.Cm bootstrap
command.):
.Bd -literal -offset indent
# cat > /usr/local/etc/pkg/repos/example.conf <<EOF
example: {
url: http://pkgrepo.example.com/${ABI}
}
EOF
# cat > /usr/local/etc/pkg/repos/FreeBSD.conf <<EOF
FreeBSD: {
enabled: NO
}
EOF
# env PACKAGESITE='http://pkgrepo.example.com/${ABI}' \
/usr/sbin/pkg bootstrap
.Ed
.Pp
Note that
.Xr pkg 7
uses
.Ev PACKAGESITE
for the URL to download
.Xr pkg 8
from, and subsequently passes it in the environment to
.Xr pkg-static 8 ,
which ignores it (possibly with a deprecation warning that should be
ignored), and reads the configuration files instead.
.Sh SEE ALSO
.Xr pkg_create 3 ,
.Xr pkg_printf 3 ,
.Xr pkg_repo_create 3 ,
.Xr pkg_repos 3 ,
.Xr pkg-keywords 5 ,
.Xr pkg-lua-script 5 ,
.Xr pkg-repository 5 ,
.Xr pkg-script 5 ,
.Xr pkg-triggers 5 ,
.Xr pkg 8 ,
.Xr pkg-add 8 ,
.Xr pkg-alias 8 ,
.Xr pkg-annotate 8 ,
.Xr pkg-audit 8 ,
.Xr pkg-autoremove 8 ,
.Xr pkg-check 8 ,
.Xr pkg-clean 8 ,
.Xr pkg-config 8 ,
.Xr pkg-create 8 ,
.Xr pkg-delete 8 ,
.Xr pkg-fetch 8 ,
.Xr pkg-info 8 ,
.Xr pkg-install 8 ,
.Xr pkg-key 8 ,
.Xr pkg-lock 8 ,
.Xr pkg-query 8 ,
.Xr pkg-register 8 ,
.Xr pkg-repo 8 ,
.Xr pkg-repositories 8 ,
.Xr pkg-rquery 8 ,
.Xr pkg-search 8 ,
.Xr pkg-set 8 ,
.Xr pkg-shell 8 ,
.Xr pkg-shlib 8 ,
.Xr pkg-ssh 8 ,
.Xr pkg-stats 8 ,
.Xr pkg-triggers 8 ,
.Xr pkg-update 8 ,
.Xr pkg-updating 8 ,
.Xr pkg-upgrade 8 ,
.Xr pkg-version 8 ,
.Xr pkg-which 8
