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.  Default: de-
		    rived from the ABI of the /usr/bin/uname  binary,  if  not
		    found then /bin/sh binary.	E.g., `FreeBSD:14:amd64'.

       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)

       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).

       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.

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

       OSNAME  Expands to the full version of the name of the  operating  sys-
	       tem.

       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.

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
       Repository configuration	file:

	     FreeBSD: {
		 url: "pkg+https://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  ig-
       nored), and reads the configuration files instead.

SEE ALSO
       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-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)

FreeBSD	13.2		       November	24, 2023		   PKG.CONF(5)

NAME | DESCRIPTION | OPTIONS | REPOSITORY CONFIGURATION | VARIABLES | ENVIRONMENT | EXAMPLES | SEE ALSO

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.0-RELEASE+and+Ports>

home | help