pkg.conf.5

.\"
.\" FreeBSD pkg - a next generation package for the installation and maintenance
.\" of non-core utilities.
.\"
.\" 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.
.\"
.\"
.\"     @(#)pkg.1
.\" $FreeBSD$
.\"
.Dd March 13, 2021
.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.
Default: derived from the ABI of the
.Pa /usr/bin/uname
binary, if not found then
.Pa /bin/sh
binary.
.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
.Xr pkg 8
will backup ancient libraries if they are removed as the result of an upgrade
and keep a copy in the path define in
.Cm BACKUP_LIBRARY_PATH .
If it does not exist yet a new package
.Qq compat-libraries
will be created. the version will be bumped each time a new library is backed up
Default: NO.
.It Cm BACKUP_LIBRARY_PATH: string
Location where the libraries are backed up.
Default:
.Pa /usr/local/lib/compat/pkg .
.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 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 fetch 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 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 allows control over underlying libraries like
.Xr fetch 3 ,
which can be configured by e.g., setting
.Ev FTP_PROXY
and
.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 PLIST_ACCEPT_DIRECTORIES: boolean
Accept directories listed like plain files in plist.
Default: NO.
.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.
.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 URL schemes supported by
.Xr libfetch 3
can be used, including:
.Dv http:// ,
.Dv https:// ,
.Dv ftp:// ,
or
.Dv file:// .
In addition a
.Dv ssh://
URL scheme is also supported.
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 8
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
.It Va OSNAME
Expands to the full version of the name of the operating system.
.It Va RELEASE
Expands to the full version of the operating system.
.It Va VERSION_MAJOR
If supported, expands to the major version of the operating system.
(Only supported on
.Fx
)
.It Va VERSION_MINOR
If supported, expands to the minor version of the operating system.
(Only supported on
.Fx
)
.It Va ARCH
Expands the architecture of the system.
.El
.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
Repository configuration file:
.Bd -literal -offset indent
FreeBSD: {
    url: "pkg+http://pkg.freebsd.org/${ABI}/latest",
    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_printf 3 ,
.Xr pkg_repos 3 ,
.Xr pkg-lua-script 5 ,
.Xr pkg-repository 5 ,
.Xr pkg-script 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-backup 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-lock 8 ,
.Xr pkg-query 8 ,
.Xr pkg-register 8 ,
.Xr pkg-repo 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-update 8 ,
.Xr pkg-updating 8 ,
.Xr pkg-upgrade 8 ,
.Xr pkg-version 8 ,
.Xr pkg-which 8