You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 

553 lines
14 KiB

  1. .\"
  2. .\" FreeBSD pkg - a next generation package for the installation and maintenance
  3. .\" of non-core utilities.
  4. .\"
  5. .\" Redistribution and use in source and binary forms, with or without
  6. .\" modification, are permitted provided that the following conditions
  7. .\" are met:
  8. .\" 1. Redistributions of source code must retain the above copyright
  9. .\" notice, this list of conditions and the following disclaimer.
  10. .\" 2. Redistributions in binary form must reproduce the above copyright
  11. .\" notice, this list of conditions and the following disclaimer in the
  12. .\" documentation and/or other materials provided with the distribution.
  13. .\"
  14. .\"
  15. .\" @(#)pkg.1
  16. .\" $FreeBSD$
  17. .\"
  18. .Dd November 18, 2014
  19. .Dt PKG.CONF 5
  20. .Os
  21. .Sh NAME
  22. .Nm "pkg.conf"
  23. .Nd system-wide configuration file for
  24. .Xr pkg 1
  25. .Sh DESCRIPTION
  26. .Nm
  27. is the system-wide configuration file used by the
  28. .Xr pkg 1
  29. tools.
  30. .Pp
  31. The default location of this file is
  32. .Pa /usr/local/etc/pkg.conf
  33. .Pp
  34. Lines in the file beginning with a "#" are comments
  35. and are ignored.
  36. .Pp
  37. The file is in UCL format.
  38. For more information on the syntax of UCL,
  39. please visit the official UCL website - http://github.com/vstakhov/libucl.
  40. .Pp
  41. The following types of options are recognized -
  42. boolean, string and list options.
  43. .Pp
  44. A boolean option is marked as enabled if one of the following values is
  45. specified in the configuration file -
  46. .Dv YES, TRUE
  47. and
  48. .Dv ON.
  49. .Sh OPTIONS
  50. The following options can be defined in
  51. .Nm :
  52. .Bl -tag -width ".Cm ABI: string"
  53. .It Cm ABI: string
  54. The ABI of the package you want to install.
  55. Default: derived from the ABI of the /bin/sh binary.
  56. .It Cm ALIAS: key/value list
  57. Define local aliases for various
  58. .Xr pkg 8
  59. standard command lines.
  60. Whenever the
  61. .Em key
  62. text occurs as a separate
  63. .Sq action
  64. word in a command line of the form
  65. .Nm pkg Em key ... ,
  66. substitute the
  67. .Em value
  68. text verbatim.
  69. The replacement can consist of any sequence of text, which should form
  70. a syntactically correct
  71. .Xr pkg 8
  72. command line when substituted in and followed by any remaining tokens from
  73. the original command line.
  74. Default: not set.
  75. .It Cm ASSUME_ALWAYS_YES: boolean
  76. When this option is enabled
  77. .Xr pkg 1
  78. will automatically assume "yes" to all questions
  79. which require user confirmation before doing anything, as if it
  80. the
  81. .Fl y
  82. flag was specified.
  83. Default: NO.
  84. .It Cm CUDF_SOLVER: string
  85. Experimental: tells pkg to use an external CUDF solver.
  86. Default: not set.
  87. .It Cm CASE_SENSITIVE_MATCH: boolean
  88. Match package names or regular expressions given on the command line
  89. against values in the database in a case sensitive way.
  90. Default: NO.
  91. .It Cm DEBUG_LEVEL: integer
  92. Incremental values from 1 to 4 produce successively more verbose
  93. debugging output.
  94. A setting of 0 disables debugging output.
  95. Overridden by the
  96. .Fl d
  97. command line option.
  98. Default: 0.
  99. .It Cm DEBUG_SCRIPTS: boolean
  100. Activate debug mode for scripts (aka set -x)
  101. Default: NO.
  102. .It Cm DEVELOPER_MODE: boolean
  103. Makes certain errors immediately fatal.
  104. Adds various warnings and
  105. suggestions to the output of
  106. .Xr pkg 1
  107. as an aide to port maintainers, including indicating when the port
  108. might be marked as architecture independent.
  109. Default: NO.
  110. .It Cm EVENT_PIPE: string
  111. Send all event messages to the specified FIFO or Unix socket.
  112. Events messages should be formatted as JSON.
  113. Default: not set.
  114. .It Cm FETCH_RETRY: integer
  115. Number of times to retry a failed fetch of a file.
  116. Default: 3.
  117. .It Cm FETCH_TIMEOUT: integer
  118. Maximum number of seconds to wait for any one file to download from the
  119. network, either by SSH or any of the protocols supported by
  120. .Xr fetch 3
  121. functions.
  122. Default: 30.
  123. .It Cm HANDLE_RC_SCRIPTS: boolean
  124. When enabled, this option will automatically perform start/stop of
  125. services during package installation and deinstallation.
  126. Services are only started on installation if they are enabled in
  127. .Pa /etc/rc.conf .
  128. Default: NO.
  129. .It Cm INDEXDIR: string
  130. If set, the directory to search for
  131. .Cm INDEXFILE
  132. in.
  133. If unset,
  134. .Cm PORTSDIR
  135. will be searched instead.
  136. Default: not set.
  137. .It Cm INDEXFILE: string
  138. The filename of the ports index, searched for in
  139. .Cm INDEXFILE
  140. or
  141. .Cm PORTSDIR .
  142. Default: INDEX-N where
  143. .Cm N
  144. is the OS major version number.
  145. .It Cm IP_VERSION: integer
  146. Restrict network access to specified IP version.
  147. Could be 4 for IPv4, 6 for IPv6 or any other value for system default.
  148. Repositories or command line options could override this setting.
  149. Default: 0.
  150. .It Cm LOCK_RETRIES: integer
  151. Retries performed to obtain a lock.
  152. Default: 5.
  153. .It Cm LOCK_WAIT: integer
  154. Wait time in seconds to regain a lock if it is not available.
  155. Default: 1.
  156. .It Cm NAMESERVER: string
  157. Hostname or IPv4 or IPv6 address of name server to use for DNS
  158. resolution, overriding the system defaults in
  159. .Pa /etc/resolv.conf .
  160. When given as a hostname, will be converted to a list of IPv4 or IPv6
  161. addresses by the default mechanisms configured on the system. See
  162. .Xr getaddrinfo 3 .
  163. .It Cm PERMISSIVE: boolean
  164. Ignore conflicts while registering a package. Note that the
  165. conflicting files will not be recorded as owned by the new package.
  166. Default: NO.
  167. .It Cm PKG_CACHEDIR: string
  168. Specifies the cache directory for packages.
  169. Default:
  170. .Pa /var/cache/pkg
  171. .It Cm PKG_DBDIR: string
  172. Specifies the directory to use for storing the package
  173. database files.
  174. Default:
  175. .Pa /var/db/pkg
  176. .It Cm PKG_ENABLE_PLUGINS: boolean
  177. When set to
  178. .Dq YES ,
  179. activate plugin support.
  180. Default: YES.
  181. .It Cm PKG_ENV: Key/Value list
  182. This tells
  183. .Xr pkg 8
  184. to set key/values to be passed in the environment.
  185. This allows control over underlying libraries like
  186. .Xr fetch 3 ,
  187. which can be configured by e.g., setting
  188. .Ev FTP_PROXY
  189. and
  190. .Ev HTTP_PROXY .
  191. Default: not set.
  192. .It Cm PKG_PLUGINS_DIR: string
  193. Directory which
  194. .Xr pkg 8
  195. will load plugins from.
  196. Default:
  197. .Pa /usr/local/lib/pkg
  198. .It Cm PKG_SSH_ARGS: string
  199. Extra arguments to pass to
  200. .Xr ssh 1 .
  201. Default: not set.
  202. .It Cm PLIST_KEYWORDS_DIR: string
  203. Directory containing definitions of plist keywords.
  204. Default: not set.
  205. .It Cm PLIST_ACCEPT_DIRECTORIES: boolean
  206. Accept directories listed like plain files in plist.
  207. Default: NO.
  208. .It Cm PLUGINS: array
  209. List of plugins that
  210. .Xr pkg 8
  211. should load.
  212. Default: not set.
  213. .It Cm PLUGINS_CONF_DIR: string
  214. Directory containing per-plugin configuration files.
  215. Default:
  216. .Pa /usr/local/etc/pkg
  217. .It Cm PORTSDIR: string
  218. Specifies the location to the Ports directory.
  219. Default:
  220. .Pa /usr/ports
  221. .It Cm READ_LOCK: boolean
  222. Use read locking for query database.
  223. Default: NO.
  224. .It Cm REPOS_DIR: array
  225. List of directories to search for repository configuration files.
  226. Default:
  227. .Pa /etc/pkg/ ,
  228. .Pa /usr/local/etc/pkg/repos/ .
  229. .It Cm REPO_AUTOUPDATE: boolean
  230. When true, automatically check for and download updates to
  231. .Pa /var/db/pkg/repo.sqlite
  232. when running one of:
  233. .Nm pkg fetch ,
  234. .Nm pkg install ,
  235. .Nm pkg rquery ,
  236. .Nm pkg search ,
  237. .Nm pkg upgrade ,
  238. or
  239. .Nm pkg version -R .
  240. Default: YES.
  241. .It Cm RUN_SCRIPTS: boolean
  242. Run pre-/post-installation action scripts.
  243. Default: YES.
  244. .It Cm SAT_SOLVER: string
  245. Experimental: tells pkg to use and external SAT solver.
  246. Default: not set.
  247. .It Cm SQLITE_PROFILE: boolean
  248. Profile SQLite queries.
  249. Default: NO.
  250. .It Cm SSH_RESTRICT_DIR: string
  251. Directory which the ssh subsystem will be restricted to.
  252. Default: not set.
  253. .It Cm SYSLOG: boolean
  254. Log all the installation/deinstallation/upgrade operation via
  255. .Xr syslog 3 .
  256. Default: YES.
  257. .It Cm UNSET_TIMESTAMP: boolean
  258. Do not include timestamps in the package
  259. .Xr tar 1
  260. archive.
  261. Normally, timestamps are copied from the staging directory the
  262. package is created from.
  263. Default: NO.
  264. .It Cm VERSION_SOURCE: string
  265. Default database for comparing version numbers in
  266. .Xr pkg-version 8 .
  267. Valid values are
  268. .Sy I
  269. for index,
  270. .Sy P ,
  271. for ports,
  272. .Sy R
  273. for remote.
  274. Default: If unset, the algorithm described in
  275. .Xr pkg-version 8
  276. is used to determine the version source automatically.
  277. .It Cm VULNXML_SITE: string
  278. Specifies the URL to fetch the
  279. .Pa vuln.xml
  280. vulnerability database from.
  281. Default:
  282. .Pa http://www.vuxml.org/freebsd/vuln.xml.bz2 .
  283. .It Cm WORKERS_COUNT: integer
  284. How many workers are used for pkg-repo. If set to 0,
  285. .Va hw.ncpu
  286. is used.
  287. Default: 0.
  288. .El
  289. .Sh REPOSITORY CONFIGURATION
  290. To use a repository you will need at least one repository
  291. configuration file.
  292. .Pp
  293. Repository configuration files are searched for in order of the
  294. directories listed in the
  295. .Cm REPOS_DIR
  296. array,
  297. which defaults to
  298. .Pa /etc/pkg/
  299. and
  300. .Pa /usr/local/etc/pkg/repos/ .
  301. .Pp
  302. Filenames are arbitrary, but should end in
  303. .Sq .conf
  304. For example
  305. .Pa /usr/local/etc/pkg/repos/myrepo.conf .
  306. .Pp
  307. A repository file is in UCL format and has the following form:
  308. .Bl -tag -width ".Cm myrepo:"
  309. .It Cm myrepo:
  310. .Bl -tag -width ".Cm MIRROR_TYPE: string"
  311. .It Cm URL: string
  312. URL for this repository only.
  313. .It Cm ENABLED: boolean
  314. The repository will be used only if this option is enabled.
  315. Default: YES.
  316. .It Cm MIRROR_TYPE: string
  317. MIRROR_TYPE for this repository only.
  318. Default: NONE.
  319. Any of
  320. .Dv HTTP
  321. or
  322. .Dv SRV
  323. or
  324. .Dv NONE .
  325. .It Cm SIGNATURE_TYPE: string
  326. Specifies what type of signature this repository uses.
  327. Can be one of
  328. .Dv NONE ,
  329. .Dv PUBKEY or
  330. .Dv FINGERPRINTS .
  331. (default: NONE)
  332. .It Cm PUBKEY: string
  333. This should be set to a path containing public key for this repository
  334. only. (default: NONE)
  335. .It Cm FINGERPRINTS: string
  336. This should be set to a path containing known signatures for the repository.
  337. .It Cm IP_VERSION: integer
  338. Restrict network access to specified IP version.
  339. Could be 4 for IPv4, 6 for IPv6 or any other value for system default.
  340. This option overrides the global setting with the same name and can be
  341. overwritten by a command line option.
  342. Default: 0.
  343. .El
  344. .El
  345. .Pp
  346. For a
  347. .Cm MIRROR_TYPE
  348. of
  349. .Dv NONE ,
  350. any of the URL schemes supported by
  351. .Xr libfetch 3
  352. can be used, including:
  353. .Dv http:// ,
  354. .Dv https:// ,
  355. .Dv ftp:// ,
  356. or
  357. .Dv file:// .
  358. In addition a
  359. .Dv ssh://
  360. URL scheme is also supported.
  361. Where
  362. .Sy MIRROR_TYPE
  363. is
  364. .Dv SRV ,
  365. you should use a
  366. .Dv pkg+http://
  367. or
  368. .Dv pkg+https://
  369. (etc.) URL scheme.
  370. Using
  371. .Dv http://
  372. URLS implies that the hostname part is a simple hostname according to
  373. RFC 2616, and is no longer accepted.
  374. .Pp
  375. When
  376. .Sy SIGNATURE_TYPE
  377. is
  378. .Dv NONE ,
  379. then no signature checking will be done on the repository.
  380. When
  381. .Sy SIGNATURE_TYPE
  382. is
  383. .Dv PUBKEY ,
  384. then the
  385. .Sy PUBKEY
  386. option will be used for signature verification.
  387. This option is for use with the built-in signing support.
  388. When
  389. .Sy SIGNATURE_TYPE
  390. is
  391. .Dv FINGERPRINTS ,
  392. then the
  393. .Sy FINGERPRINTS
  394. option will be used for signature verification.
  395. This option is for use with an external signing command.
  396. See
  397. .Xr pkg-repo 8
  398. for more discussion on signature types.
  399. .Pp
  400. If
  401. .Sy FINGERPRINTS
  402. is set to
  403. .Pa /usr/local/etc/pkg/fingerprints/myrepo ,
  404. then the directories
  405. .Pa /usr/local/etc/pkg/fingerprints/myrepo/trusted
  406. and
  407. .Pa /usr/local/etc/pkg/fingerprints/myrepo/revoked
  408. should exist with known good and bad fingerprints, respectively.
  409. Files in those directories should be in the format:
  410. .Bd -literal -offset indent
  411. function: sha256
  412. fingerprint: sha256_representation_of_the_public_key
  413. .Ed
  414. .Pp
  415. The repository tag
  416. .Fa myrepo
  417. is an arbitrary string.
  418. Reusing the repository tag will cause those items defined in
  419. configuration files later on the
  420. .Sy REPOS_DIR
  421. search path to overwrite the equivalent settings for the same tag
  422. earlier on the search path.
  423. Hence the very common idiom, used to turn off the default
  424. .Cm FreeBSD
  425. configuration shipped in
  426. .Pa /etc/pkg/FreeBSD.conf .
  427. Rather than editing that file directly, create
  428. .Pa /usr/local/etc/pkg/repos/FreeBSD.conf
  429. with this content:
  430. .Bd -literal -offset indent
  431. FreeBSD: { enabled: NO }
  432. .Ed
  433. .Pp
  434. Repositories are prioritized in the order they are found on the
  435. .Sy REPOS_DIR
  436. search path, with individual repository configuration files in the
  437. same directory processed in alphabetical order.
  438. Earlier files take precedence, meaning that packages will be downloaded
  439. from them preferentially where the same package is available from several
  440. repositories.
  441. This behaviour may be overridden per-package by adding a
  442. .Sy repository
  443. annotation to the installed package.
  444. See
  445. .Xr pkg-repository 8
  446. for details.
  447. .Pp
  448. It is possible to specify more than one repository per file.
  449. .Sh ENVIRONMENT
  450. An environment variable with the same name as the option in the
  451. configuration file always overrides the value of an option set in the
  452. file.
  453. .Sh EXAMPLES
  454. Repository configuration file:
  455. .Bd -literal -offset indent
  456. FreeBSD: {
  457. url: "pkg+http://pkg.freebsd.org/${ABI}/latest",
  458. enabled: true,
  459. signature_type: "fingerprints",
  460. fingerprints: "/usr/share/keys/pkg",
  461. mirror_type: "srv"
  462. }
  463. .Ed
  464. Example for pkg.conf
  465. .Bd -literal -offset indent
  466. pkg_dbdir: "/var/db/pkg"
  467. pkg_cachedir: "/var/cache/pkg"
  468. portsdir: "/usr/ports"
  469. handle_rc_scripts: false
  470. assume_always_yes: false
  471. repos_dir: [
  472. "/etc/pkg",
  473. "/usr/local/etc/pkg/repos",
  474. ]
  475. syslog: true
  476. autodeps: true
  477. developer_mode: false
  478. pkg_env: {
  479. http_proxy: "http://myproxy:3128",
  480. }
  481. alias: {
  482. origin: "info -qo",
  483. nonauto: "query -e '%a == 0' '%n-%v'"
  484. }
  485. .Ed
  486. To bootstrap
  487. .Xr pkg 8
  488. using a private repository (Assuming a
  489. .Xr pkg 7
  490. new enough to support the
  491. .Cm bootstrap
  492. command.)
  493. .Bd -literal -offset indent
  494. # cat > /usr/local/etc/pkg/repos/example.conf <<EOF
  495. example: {
  496. url: http://pkgrepo.example.com/${ABI}
  497. }
  498. EOF
  499. # cat > /usr/local/etc/pkg/repos/FreeBSD.conf <<EOF
  500. FreeBSD: {
  501. enabled: NO
  502. }
  503. EOF
  504. # env PACKAGESITE='http://pkgrepo.example.com/${ABI}' \
  505. /usr/sbin/pkg bootstrap
  506. .Ed
  507. Note that
  508. .Xr pkg 7
  509. uses
  510. .Ev PACKAGESITE
  511. for the URL to download
  512. .Xr pkg 8
  513. from, and subsequently passes it in the environment to
  514. .Xr pkg-static 8 ,
  515. which ignores it (possibly with a deprecation warning that should be
  516. ignored), and reads the configuration files instead.
  517. .Sh SEE ALSO
  518. .Xr fetch 3 ,
  519. .Xr pkg_printf 3 ,
  520. .Xr pkg_repos 3 ,
  521. .Xr pkg-repository 5 ,
  522. .Xr pkg 8 ,
  523. .Xr pkg-add 8 ,
  524. .Xr pkg-annotate 8 ,
  525. .Xr pkg-audit 8 ,
  526. .Xr pkg-autoremove 8 ,
  527. .Xr pkg-backup 8 ,
  528. .Xr pkg-check 8 ,
  529. .Xr pkg-clean 8 ,
  530. .Xr pkg-config 8 ,
  531. .Xr pkg-convert 8 ,
  532. .Xr pkg-create 8 ,
  533. .Xr pkg-delete 8 ,
  534. .Xr pkg-fetch 8 ,
  535. .Xr pkg-info 8 ,
  536. .Xr pkg-install 8 ,
  537. .Xr pkg-lock 8 ,
  538. .Xr pkg-query 8 ,
  539. .Xr pkg-register 8 ,
  540. .Xr pkg-repo 8 ,
  541. .Xr pkg-rquery 8 ,
  542. .Xr pkg-search 8 ,
  543. .Xr pkg-set 8 ,
  544. .Xr pkg-shell 8 ,
  545. .Xr pkg-shlib 8 ,
  546. .Xr pkg-ssh 8 ,
  547. .Xr pkg-stats 8 ,
  548. .Xr pkg-update 8 ,
  549. .Xr pkg-updating 8 ,
  550. .Xr pkg-upgrade 8 ,
  551. .Xr pkg-version 8 ,
  552. .Xr pkg-which 8