Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
PKG.CONF(5)		      File Formats Manual		   PKG.CONF(5)

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

DESCRIPTION
       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/vs-
       takhov/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, for example
		    `FreeBSD:14:amd64'.	 This should  be  set  in  combination
		    with  the OSVERSION	option if targeting FreeBSD to specify
		    the	exact  target  version.	  Default:  derived  based  on
		    ABI_FILE.

       ABI_FILE: string
		    Set	 the  file used	to determine the target	ABI.  Default:
		    /usr/bin/uname, or if not found, /bin/sh.

       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  syn-
		    tactically correct pkg(8) command line when	substituted in
		    and	 followed  by  any  remaining tokens from the original
		    command line.  Default: not	set.

       ARCHIVE_SYMLINK:	boolean
		    When creating a package, create a symlink to it using  the
		    legacy extension, this is a	backward compatibility option,
		    default: true

       AUTOCLEAN: boolean
		    Automatically  cleanout  the content of PKG_CACHEDIR after
		    each non dry-run call to pkg-install(8) or pkg-upgrade(8).

       DEFAULT_ALWAYS_YES: boolean
		    When this option is	enabled	pkg(1) will default  to	 "yes"
		    for	 all  questions	which require user confirmation	before
		    doing anything.  Default: NO.

       ASSUME_ALWAYS_YES: boolean
		    When this option is	enabled	pkg(1) will automatically  as-
		    sume  "yes"	 to all	questions which	require	user confirma-
		    tion before	doing anything,	as if it the -y	flag was spec-
		    ified.  Default: NO.

       BACKUP_LIBRARIES: boolean
		    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 li-
		    brary is backed up Default:	NO.

       BACKUP_LIBRARY_PATH: string
		    Location where the	libraries  are	backed	up.   Default:
		    /usr/local/lib/compat/pkg.

       COMPRESSION_FORMAT: string
		    Set	 the  default compression format: tzst,	txz (default),
		    tbz, tar.  Default:	per pkg	developers.

       COMPRESSION_LEVEL: integer
		    Set	the default compression	level, special values are:

		    0 default value per	libarchive developers

		    -1 default value per pkg developers	(default)

       COMPRESSION_THREADS: integer
		    Set	the number of threads to use during compression	 (only
		    functional for txz and tzst)

       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.

       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 sen-
		    sitive way.	 Default: NO.

       DEBUG_LEVEL: integer
		    Incremental	values from 1 to 4 produce  successively  more
		    verbose  debugging output.	A setting of 0 disables	debug-
		    ging 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 aid
		    to port maintainers, including indicating  when  the  port
		    might be marked as architecture independent.  Default: NO.

       DOT_FILE: string
		    When  defined  to a	valid path, pkg	will generate a	dot(1)
		    file with the dependency graph of the  concerned  transac-
		    tion.

       EVENT_PIPE: string
		    Send  all  event  messages	to  the	specified FIFO or Unix
		    socket.  Events messages should be formatted as JSON.  De-
		    fault: not set.

       FETCH_RETRY: integer
		    Number of times to retry a failed fetch of	a  file.   De-
		    fault: 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 de-
		    installation.  Services are	only started  on  installation
		    if they are	enabled	in /etc/rc.conf.  Default: NO.

       HTTP_USER_AGENT:	string
		    Define  User-agent	to be sent to HTTP server when getting
		    repository data.

       IGNORE_OSVERSION: boolean [FreeBSD specific]
		    Ignore FreeBSD OS version check,  useful  on  -STABLE  and
		    -CURRENT branches.	Default: NO.

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

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

       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  com-
		    mand line options can override this	setting.  Default: 0.

       LOCK_RETRIES: integer
		    Number  of	attempts to obtain a lock before giving	up and
		    exiting.  Default: 5.

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

       METALOG:	string
		    If	set,  pkg(8)  will  write  a  METALOG of the extracted
		    files.

       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 con-
		    verted to a	list of	IPv4 or	IPv6 addresses by the  default
		    mechanisms configured on the system.  See getaddrinfo(3).

       OSVERSION: integer
		    Specifiy  the  exact  FreeBSD  version for the target ABI.
		    This should	be set in combination  with  the  ABI  option.
		    The	 format	is the same as the format of __FreeBSD_version
		    in /usr/include/sys/param.h.  Default:  derived  based  on
		    ABI_FILE.

       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_CREATE_VERBOSE: boolean
		    When  set  to a true value,	make pkg-create(8) use verbose
		    mode as standard.  Default:	NO.

       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 allow setting  variables	 to  configure
		    the	 http(s) fetcher.  Which accepts environment variables
		    compatible with fetch(3), e.g., HTTP_PROXY.	 Default:  not
		    set.

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

       PKG_TRIGGERS_ENABLE
		    Enable or disable execution	of triggers at the end of  the
		    transactions.  Default: YES.

       PKG_TRIGGERS_DIR
		    Directory	where	the   triggers	 are  stored  Default:
		    /usr/local/share/pkg/triggers.

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

       PLIST_KEYWORDS_DIR: string
		    Directory containing definitions of	plist  keywords.   De-
		    fault: PORTSDIR/keyword.

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

       PLUGINS_CONF_DIR: string
		    Directory containing per-plugin configuration files.   De-
		    fault: /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  an	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 of the installation/deinstallation/upgrade	opera-
		    tions 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.

       VERSION_SOURCE: string
		    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 de-
		    scribed in pkg-version(8) is used to determine the version
		    source automatically.

       VALID_URL_SCHEME
		    List of url	scheme that pkg	can accept while  parsing  the
		    repository confguration file.

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

       WARN_SIZE_LIMIT:	integer
		    When  download and total change is less than than this op-
		    tion, don't	ask the	user to	confirm	 the  desired  action.
		    Default: 1048576 (1MB).

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

       PKG_REINSTALL_ON_OPTIONS_CHANGE
		    Reinstall packages if options changed  between  the	 local
		    version and	the remote version.  Default: true

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	direc-
       tories 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:

		ENV: object	     A list of key value entries that will  be
				     passed  as	 environment  variable for the
				     bundled fetch(3), per repository.

		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. (de-
				     fault: NONE)

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

		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.

		PRIORITY: integer    Set  the  priority	 of  the   repository.
				     Higher values are preferred.  Default: 0.

       For  a  MIRROR_TYPE of NONE, any	of the following URL schemes: http://,
       https://, file://, ssh://,  tcp://.   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 accord-
       ing 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 reposi-
       tory 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(5) for details.

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

VARIABLES
       The  following  variables  will	be  expanded  during  the  parsing  of
       pkg.conf.

       ABI     Expands to the ABI string (e.g. `FreeBSD:14:amd64').

       OSNAME  Expands to the the name of the target operating system.

       RELEASE
	       Expands to the full version of the target operating system.

       VERSION_MAJOR
	       Expands to the major version of the target operating system.

       VERSION_MINOR
	       Expands to the minor version of the target operating system.

       OSVERSION
	       If targeting FreeBSD, expands to	the target version in the same
	       format as __FreeBSD_version in

       ARCH    Expands to the architecture of the system.

       Since the values	of these variables are affected	by some	 options  that
       may  be	set in pkg.conf	(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.

ENVIRONMENT
       An environment variable with the	same name as the option	in the config-
       uration file always overrides the value of an option set	in the file.

EXAMPLES
       FreeBSD latest repository configuration:

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

       FreeBSD quarterly kernel	modules	repository configuration:

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

       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  ig-
       nored), and reads the configuration files instead.

SEE ALSO
       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-triggers(5),	 pkg(8),  pkg-add(8),  pkg-alias(8),  pkg-annotate(8),
       pkg-audit(8),	pkg-autoremove(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-key(8), pkg-lock(8),	pkg-query(8), pkg-register(8),
       pkg-repo(8),    pkg-repositories(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)

FreeBSD	14.3			March 17, 2025			   PKG.CONF(5)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=pkg.conf&sektion=5&manpath=FreeBSD+14.3-RELEASE+and+Ports>

home | help