PKG.CONF(5)

NAME
pkg.conf - System-wide configuration file for pkg(1)

DESCRIPTION
pkg.conf is the system-wide configuration file used by the pkg(1) 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.

OPTIONS
The following options can be defined in pkg.conf:

ABI: string
    the abi of the package you want to install. Default: derived from the ABI of the /bin/sh binary.

ALIAS: key/value list
    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.

ASSUME_ALWAYS_YES: boolean
    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.

CUDF_SOLVER: string
    Experimental: tells pkg to use an external CUDF solver. Default: not set.

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.

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 -d command line option. Default: 0.

DEBUG_SCRIPTS: boolean
    Activate debug mode for scripts (aka set -x) Default: no.

DEVELOPER_MODE: boolean
    Makes certain errors immediately fatal. Adds various warnings and suggestions to the output of pkg(1) as an aide to port maintainers, including indicating when the port might be marked as architecture independent. Default: no.

DISABLE_MTREE: boolean
    For experimental purposes only. Not for use on production systems. All this option does is prevent processing of +MTREE data when installing a package. +MTREE files are a legacy feature of the ports tree, which provide functionality necessary for pkg-install(8) as it cannot handle creating arbitrary directory hierarchies otherwise. pkg(8) can create such directory structures natively, but currently still uses the +MTREE data. This option exists to facilitate developing +MTREE free package sets. Default: no.

EVENT_PIPE: string
    Send all event messages to the specified fifo or Unix socket. Events messages should be formatted as JSON. Default: not set.

FETCH_RETRY: integer
    Number of times to retry a failed fetch of a file. Default: 3.

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 fetch(3) functions. Default: 30.

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 /etc/rc.conf. Default: no.

INDEXDIR: string
    If set, the directory to search for INDEXFILE in. If unset, PORTSDIR will be searched instead. Default: not set.

INDEXFILE: string
    The filename of the ports index, searched for in INDEXFILE or PORTSDIR. Default: INDEX-N where N is the OS major version number.

LOCK_RETRIES: integer
    Retries performed to obtain a lock. Default: 5.

LOCK_WAIT: integer
    Wait time in seconds to regain a lock if it is not available. Default: 1.

NAMESERVER: string
    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).

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.

PKG_CACHEDIR: string
    Specifies the cache directory for packages. Default: /var/cache/pkg

PKG_DBDIR: string
    Specifies the directory to use for storing the package database files. Default: /var/db/pkg

PKG_ENABLE_PLUGINS: boolean
    When set to “yes”, activate plugin support. Default: yes.

PKG_ENV: Key/Value list
    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.

PKG_PLUGINS_DIR: string
    Directory which pkg(8) will load plugins from. Default: /usr/local/lib/pkg

PKG_SSH_ARGS: string
    Extra arguments to pass to ssh(1). Default: not set.

PLIST_KEYWORDS_DIR: string
    Directory containing definitions of plist keywords. Default: not set.

PLUGINS: array
    List of plugins that pkg(8) should load. Default: not set.

PLUGINS_CONF_DIR: string
    Directory containing per-plugin configuration files. Default: /usr/local/etc/pkg

PORTSDIR: string
    Specifies the location to the Ports directory. Default: /usr/ports

READ_LOCK: boolean
    Use read locking for query database. Default: no.

REPOS_DIR: array
    List of directories to search for repository configuration files. Default: /etc/pkg/, /usr/local/etc/pkg/repos/.

REPO_AUTOUPDATE: boolean
    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_SCRIPTS: boolean
    Run pre-/post-installation action scripts. Default: yes.

SAT_SOLVER: string
    Experimental: tells pkg to use and external SAT solver. Default: not set.

SQLITE_PROFILE: boolean
    Profile sqlite queries. Default: no.

SSH_RESTRICT_DIR: string
    Directory which the ssh subsystem will be restricted to. Default: not set.

SYSLOG: boolean
    Log all the installation/deinstallation/upgrade operation via syslog(3). Default: yes.

UNSET_TIMESTAMP: boolean
    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.

VULNXML_SITE: string
    Specifies the URL to fetch the vuln.xml vulnerability database from. Default: http://www.vuxml.org/freebsd/vuln.xml.bz2.

WORKERS_COUNT: integer
    How many workers are used for pkg-repo. If set to 0, hw.ncpu is used. Default: 0.

REPOSITORY CONFIGURATION
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:

myrepo:

    URL: string
        URL for this repository only.

    ENABLED: boolean
        The repository will be used only if this option is enabled. (default: YES)

    MIRROR_TYPE: string
        MIRROR_TYPE for this repository only. (default: NONE). Any of HTTP or SRV or NONE.

    SIGNATURE_TYPE: string
        Specifies what type of signature this repository uses. Can be one of NONE, PUBKEY or FINGERPRINTS. (default: NONE)

    PUBKEY: string
        This should be set to a path containing public key for this repository only. (default: NONE)

    FINGERPRINTS: string
        This should be set to a path containing known signatures for the repository.

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 http:// URLS 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 builtin 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 prioritized 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. Earlier files take precedence, meaning that packages will be downloaded from them preferentially where the same package is available from several repositories. This behaviour may be overridden per-package by adding a repository annotation to the installed package. See pkg-repository(8) for details.

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

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.

EXAMPLES
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
    autodeps: 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.

SEE ALSO
fetch(3), pkg_printf(3), pkg_repos(3), pkg-repository(5), pkg(8), pkg-add(8), pkg-annotate(8), pkg-audit(8), pkg-autoremove(8), pkg-backup(8), pkg-check(8), pkg-clean(8), pkg-config(8), pkg-convert(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-update(8), pkg-updating(8), pkg-upgrade(8), pkg-version(8), pkg-which(8)