GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages
PKG.CONF(5) FreeBSD File Formats Manual PKG.CONF(5)

pkg.conf
system-wide configuration file for pkg(8)

pkg.conf is the system-wide configuration file used by the pkg(8) tools.

The default location of this file is /usr/local/etc/pkg.conf.

Lines in the file beginning with a "#" are comments and are ignored.

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.

The following types of options are recognized - boolean, string and list options.

A boolean option is marked as enabled if one of the following values is specified in the configuration file - YES, TRUE and ON.

The following options can be defined in pkg.conf:
The ABI of the package you want to install. Default: derived from the ABI of the /usr/bin/uname binary, if not found then /bin/sh binary.
Define local aliases for various pkg(8) standard command lines. Whenever the key text occurs as a separate ‘action’ word in a command line of the form pkg key ..., substitute the value text verbatim. The replacement can consist of any sequence of text, which should form a syntactically correct pkg(8) command line when substituted in and followed by any remaining tokens from the original command line. Default: not set.
When creating a package, create a symlink to it using the legacy extension, this is a backward compatibility option, default: true
Automatically cleanout the content of PKG_CACHEDIR after each non dry-run call to pkg-install(8) or pkg-upgrade(8).
When this option is enabled pkg(1) will default to "yes" for all questions which require user confirmation before doing anything. Default: NO.
When this option is enabled pkg(1) will automatically assume "yes" to all questions which require user confirmation before doing anything, as if it the -y flag was specified. Default: NO.
If set to true 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 BACKUP_LIBRARY_PATH. If it does not exist yet a new package “compat-libraries” will be created. the version will be bumped each time a new library is backed up Default: NO.
Location where the libraries are backed up. Default: /usr/local/lib/compat/pkg.
Set the default compression level, special values are:
0 default value per libarchive developers
 
-1 default value per pkg developers (default)
 
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.
Experimental: tells pkg to use an external CUDF solver. Default: not set.
Match package names or regular expressions given on the command line against values in the database in a case sensitive way. Default: NO.
Incremental values from 1 to 4 produce successively more verbose debugging output. A setting of 0 disables debugging output. Overridden by the -d command line option. Default: 0.
Activate debug mode for scripts (aka set -x) Default: NO.
Makes certain errors immediately fatal. Adds various warnings and suggestions to the output of pkg(1) as an aid to port maintainers, including indicating when the port might be marked as architecture independent. Default: NO.
When defined to a valid path, pkg will generate a dot(1) file with the dependency graph of the concerned transaction.
Send all event messages to the specified FIFO or Unix socket. Events messages should be formatted as JSON. Default: not set.
Number of times to retry a failed fetch of a file. Default: 3.
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 fetch(3) functions. Default: 30.
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 /etc/rc.conf. Default: NO.
Define User-agent to be sent to HTTP server when getting repository data.
Ignore FreeBSD OS version check, useful on -STABLE and -CURRENT branches. Default: NO.
If set, the directory to search for INDEXFILE in. If unset, PORTSDIR will be searched instead. Default: not set.
The filename of the ports index, searched for in INDEXDIR or PORTSDIR. Default: INDEX-N where N is the OS major version number.
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.
Number of attempts to obtain a lock before giving up and exiting. Default: 5.
Wait time in seconds to regain a lock if it is not available. Default: 1.
If set, pkg(8) will write a METALOG of the extracted files.
Hostname or IPv4 or IPv6 address of name server to use for DNS resolution, overriding the system defaults in /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 getaddrinfo(3).
Ignore conflicts while registering a package. Note that the conflicting files will not be recorded as owned by the new package. Default: NO.
Specifies the cache directory for packages. Default: /var/cache/pkg.
When set to a true value, make pkg-create(8) use verbose mode as standard. Default: NO.
Specifies the directory to use for storing the package database files. Default: /var/db/pkg.
When set to “YES”, activate plugin support. Default: YES.
This tells pkg(8) to set key/values to be passed in the environment. This allows control over underlying libraries like fetch(3), which can be configured by e.g., setting FTP_PROXY and HTTP_PROXY. Default: not set.
Directory which pkg(8) will load plugins from. Default: /usr/local/lib/pkg.
Enable or disable execution of triggers at the end of the transactions. Default: YES.
Directory where the triggers are stored Default: /usr/local/share/pkg/triggers.
Extra arguments to pass to ssh(1). Default: not set.
Directory containing definitions of plist keywords. Default: PORTSDIR/keyword.
Accept directories listed like plain files in plist. Default: NO.
List of plugins that pkg(8) should load. Default: not set.
Directory containing per-plugin configuration files. Default: /usr/local/etc/pkg.
Specifies the location to the Ports directory. Default: /usr/ports.
Use read locking for query database. Default: NO.
List of directories to search for repository configuration files. Default: /etc/pkg/, /usr/local/etc/pkg/repos/.
When true, automatically check for and download updates to /var/db/pkg/repo.sqlite when running one of: pkg fetch, pkg install, pkg rquery, pkg search, pkg upgrade, or pkg version -R. Default: YES.
Run pre-/post-installation action scripts. Default: YES.
Experimental: tells pkg to use an external SAT solver. Default: not set.
Profile SQLite queries. Default: NO.
Directory which the ssh subsystem will be restricted to. Default: not set.
Log all of the installation/deinstallation/upgrade operations via syslog(3). Default: YES.
Do not include timestamps in the package tar(1) archive. Normally, timestamps are copied from the staging directory the package is created from. Default: NO.
Default database for comparing version numbers in pkg-version(8). Valid values are I for index, P for ports, R for remote. Default: If unset, the algorithm described in pkg-version(8) is used to determine the version source automatically.
List of url scheme that pkg can accept while parsing the repository confguration file.
Specifies the URL to fetch the vuln.xml vulnerability database from. Default: http://vuxml.freebsd.org/freebsd/vuln.xml.xz.
When download and total change is less than than this option, don't ask the user to confirm the desired action. Default: 1048576 (1MB).
How many workers are used for pkg-repo. If set to 0, hw.ncpu is used. Default: 0.

To use a repository you will need at least one repository configuration file.

Repository configuration files are searched for in order of the directories listed in the REPOS_DIR array, which defaults to /etc/pkg/ and /usr/local/etc/pkg/repos/.

Filenames are arbitrary, but should end in ‘.conf’. For example /usr/local/etc/pkg/repos/myrepo.conf.

A repository file is in UCL format and has the following form:

A list of key value entries that will be passed as environment variable for the bundled fetch(3), per repository.
URL for this repository only.
The repository will be used only if this option is enabled. Default: YES.
MIRROR_TYPE for this repository only. Default: NONE. Any of HTTP or SRV or NONE.
Specifies what type of signature this repository uses. Can be one of NONE, PUBKEY or FINGERPRINTS. (default: NONE)
This should be set to a path containing public key for this repository only. (default: NONE)
This should be set to a path containing known signatures for the repository.
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.
Set the priority of the repository. Higher values are preferred. Default: 0.

For a MIRROR_TYPE of NONE, any of the URL schemes supported by libfetch(3) can be used, including: http://, https://, ftp://, or file://. In addition a ssh:// URL scheme is also supported. Where MIRROR_TYPE is SRV, you should use a pkg+http:// or pkg+https:// (etc.) URL scheme. Using an http:// URL implies that the hostname part is a simple hostname according to RFC 2616, and is no longer accepted.

When SIGNATURE_TYPE is NONE, then no signature checking will be done on the repository. When SIGNATURE_TYPE is PUBKEY, then the PUBKEY option will be used for signature verification. This option is for use with the built-in signing support. When SIGNATURE_TYPE is FINGERPRINTS, then the FINGERPRINTS option will be used for signature verification. This option is for use with an external signing command. See pkg-repo(8) for more discussion on signature types.

If FINGERPRINTS is set to /usr/local/etc/pkg/fingerprints/myrepo, then the directories /usr/local/etc/pkg/fingerprints/myrepo/trusted and /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:

function: sha256
fingerprint: sha256_representation_of_the_public_key

The repository tag myrepo is an arbitrary string. Reusing the repository tag will cause those items defined in configuration files later on the 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 FreeBSD configuration shipped in /etc/pkg/FreeBSD.conf. Rather than editing that file directly, create /usr/local/etc/pkg/repos/FreeBSD.conf with this content:

FreeBSD: { enabled: NO }

Repositories are processed in the order they are found on the 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 CONSERVATIVE_UPGRADE is set to 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 repository annotation of the installed package. See pkg-repository(8) for details.

It is possible to specify more than one repository per file.

The following variables will be expanded during the parsing of pkg.conf
ABI
 
OSNAME
Expands to the full version of the name of the operating system.
RELEASE
Expands to the full version of the operating system.
VERSION_MAJOR
If supported, expands to the major version of the operating system. (Only supported on FreeBSD )
VERSION_MINOR
If supported, expands to the minor version of the operating system. (Only supported on FreeBSD )
ARCH
Expands the architecture of the system.

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.

Repository configuration file:
FreeBSD: {
    url: "pkg+http://pkg.freebsd.org/${ABI}/latest",
    enabled: true,
    signature_type: "fingerprints",
    fingerprints: "/usr/share/keys/pkg",
    mirror_type: "srv"
}

Example for pkg.conf:

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'"
}

To bootstrap pkg(8) using a private repository (Assuming a pkg(7) new enough to support the bootstrap command.):

# 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

Note that pkg(7) uses PACKAGESITE for the URL to download pkg(8) from, and subsequently passes it in the environment to pkg-static(8), which ignores it (possibly with a deprecation warning that should be ignored), and reads the configuration files instead.

pkg_create(3), pkg_printf(3), pkg_repos(3), pkg-keywords(5), pkg-lua-script(5), pkg-repository(5), pkg-script(5), pkg-triggers(5), pkg(8), pkg-add(8), pkg-alias(8), pkg-annotate(8), pkg-audit(8), pkg-autoremove(8), pkg-backup(8), pkg-check(8), pkg-clean(8), pkg-config(8), pkg-create(8), pkg-delete(8), pkg-fetch(8), pkg-info(8), pkg-install(8), pkg-lock(8), pkg-query(8), pkg-register(8), pkg-repo(8), pkg-rquery(8), pkg-search(8), pkg-set(8), pkg-shell(8), pkg-shlib(8), pkg-ssh(8), pkg-stats(8), pkg-triggers(8), pkg-update(8), pkg-updating(8), pkg-upgrade(8), pkg-version(8), pkg-which(8)
March 13, 2021 FreeBSD 13.1-RELEASE

Search for    or go to Top of page |  Section 5 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.