Send patches - preferably formatted by git format-patch - to patches at archlinux32 dot org.
summaryrefslogtreecommitdiff
path: root/doc/pacman.conf.5.asciidoc
diff options
context:
space:
mode:
authorEli Schwartz <eschwartz@archlinux.org>2018-05-03 00:10:21 -0400
committerAllan McRae <allan@archlinux.org>2018-05-14 09:59:17 +1000
commit076b6184de2b20e9b26225d93f6f3a7030504109 (patch)
treeca0e375b9fd89d6b6ce40026b732985c4b335841 /doc/pacman.conf.5.asciidoc
parent860e4c4943ad062bd0eff99f28e7d64804b3c08e (diff)
Ensure better text editor automatic filetype detection
Since we no longer use vim-specific modelines, use the .asciidoc file extension which is, well, reserved for asciidoc formatted files. This should presumably work everywhere without needing editor-specific workarounds and configuration. Also add a shebang to makepkg.conf to indicate it contains bash content. Signed-off-by: Eli Schwartz <eschwartz@archlinux.org> Signed-off-by: Allan McRae <allan@archlinux.org>
Diffstat (limited to 'doc/pacman.conf.5.asciidoc')
-rw-r--r--doc/pacman.conf.5.asciidoc371
1 files changed, 371 insertions, 0 deletions
diff --git a/doc/pacman.conf.5.asciidoc b/doc/pacman.conf.5.asciidoc
new file mode 100644
index 00000000..e5fffecf
--- /dev/null
+++ b/doc/pacman.conf.5.asciidoc
@@ -0,0 +1,371 @@
+pacman.conf(5)
+==============
+
+Name
+----
+pacman.conf - pacman package manager configuration file
+
+
+Synopsis
+--------
+{sysconfdir}/pacman.conf
+
+
+Description
+-----------
+Pacman, using linkman:libalpm[3], will attempt to read pacman.conf each time it
+is invoked. This configuration file is divided into sections or repositories.
+Each section defines a package repository that pacman can use when searching
+for packages in '\--sync' mode. The exception to this is the options section,
+which defines global options.
+
+
+Example
+-------
+
+--------
+#
+# pacman.conf
+#
+[options]
+NoUpgrade = etc/passwd etc/group etc/shadow
+NoUpgrade = etc/fstab
+
+[core]
+Include = /etc/pacman.d/core
+
+[custom]
+Server = file:///home/pkgs
+--------
+
+NOTE: Each directive must be in CamelCase. If the case isn't respected, the
+directive won't be recognized. For example. noupgrade or NOUPGRADE will not
+work.
+
+
+Options
+-------
+*RootDir =* /path/to/root/dir::
+ Set the default root directory for pacman to install to. This option is
+ used if you want to install a package on a temporary mounted partition
+ which is "owned" by another system, or for a chroot install.
+ *NOTE*: If database path or log file are not specified on either the
+ command line or in linkman:pacman.conf[5], their default location will
+ be inside this root path.
+
+*DBPath =* /path/to/db/dir::
+ Overrides the default location of the toplevel database directory. The
+ default is +{localstatedir}/lib/pacman/+. Most users will not need to set
+ this option. *NOTE*: if specified, this is an absolute path and the root
+ path is not automatically prepended.
+
+*CacheDir =* /path/to/cache/dir::
+ Overrides the default location of the package cache directory. The
+ default is +{localstatedir}/cache/pacman/pkg/+. Multiple cache directories can be
+ specified, and they are tried in the order they are listed in the config
+ file. If a file is not found in any cache directory, it will be downloaded
+ to the first cache directory with write access. *NOTE*: this is an absolute
+ path, the root path is not automatically prepended.
+
+*HookDir =* /path/to/hook/dir::
+ Add directories to search for alpm hooks in addition to the system hook
+ directory (+{datarootdir}/libalpm/hooks/+). The default is
+ +{sysconfdir}/pacman.d/hooks+. Multiple directories can be specified with
+ hooks in later directories taking precedence over hooks in earlier
+ directories. *NOTE*: this is an absolute path, the root path is not
+ automatically prepended. For more information on the alpm hooks, see
+ linkman:alpm-hooks[5].
+
+*GPGDir =* /path/to/gpg/dir::
+ Overrides the default location of the directory containing configuration
+ files for GnuPG. The default is +{sysconfdir}/pacman.d/gnupg/+.
+ This directory should contain two files: `pubring.gpg` and `trustdb.gpg`.
+ `pubring.gpg` holds the public keys of all packagers. `trustdb.gpg`
+ contains a so-called trust database, which specifies that the keys are
+ authentic and trusted.
+ *NOTE*: this is an absolute path, the root path is not automatically
+ prepended.
+
+*LogFile =* /path/to/log/file::
+ Overrides the default location of the pacman log file. The default
+ is +{localstatedir}/log/pacman.log+. This is an absolute path and the root directory
+ is not prepended.
+
+*HoldPkg =* package ...::
+ If a user tries to '\--remove' a package that's listed in `HoldPkg`,
+ pacman will ask for confirmation before proceeding. Shell-style glob
+ patterns are allowed.
+
+*IgnorePkg =* package ...::
+ Instructs pacman to ignore any upgrades for this package when performing
+ a '\--sysupgrade'. Shell-style glob patterns are allowed.
+
+*IgnoreGroup =* group ...::
+ Instructs pacman to ignore any upgrades for all packages in this
+ group when performing a '\--sysupgrade'. Shell-style glob patterns are
+ allowed.
+
+*Include =* /path/to/config/file::
+ Include another configuration file. This file can include repositories or
+ general configuration options. Wildcards in the specified paths will get
+ expanded based on linkman:glob[7] rules.
+
+*Architecture =* auto | i686 | x86_64 | ...::
+ If set, pacman will only allow installation of packages of the given
+ architecture (e.g. 'i686', 'x86_64', etc). The special value 'auto' will
+ use the system architecture, provided via ``uname -m''. If unset, no
+ architecture checks are made. *NOTE*: Packages with the special
+ architecture 'any' can always be installed, as they are meant to be
+ architecture independent.
+
+*XferCommand =* /path/to/command %u::
+ If set, an external program will be used to download all remote files.
+ All instances of `%u` will be replaced with the download URL. If present,
+ instances of `%o` will be replaced with the local filename, plus a
+ ``.part'' extension, which allows programs like wget to do file resumes
+ properly.
+ +
+ This option is useful for users who experience problems with built-in
+ HTTP/FTP support, or need the more advanced proxy support that comes with
+ utilities like wget.
+
+*NoUpgrade =* file ...::
+ All files listed with a `NoUpgrade` directive will never be touched during
+ a package install/upgrade, and the new files will be installed with a
+ '.pacnew' extension.
+ These files refer to files in the package archive, so do not include the
+ leading slash (the RootDir) when specifying them. Shell-style glob patterns
+ are allowed. It is possible to invert matches by prepending a file with
+ an exclamation mark. Inverted files will result in previously blacklisted
+ files being whitelisted again. Subsequent matches will override previous
+ ones. A leading literal exclamation mark or backslash needs to be escaped.
+
+*NoExtract =* file ...::
+ All files listed with a `NoExtract` directive will never be extracted from
+ a package into the filesystem. This can be useful when you don't want part
+ of a package to be installed. For example, if your httpd root uses an
+ 'index.php', then you would not want the 'index.html' file to be extracted
+ from the 'apache' package.
+ These files refer to files in the package archive, so do not include the
+ leading slash (the RootDir) when specifying them. Shell-style glob patterns
+ are allowed. It is possible to invert matches by prepending a file with
+ an exclamation mark. Inverted files will result in previously blacklisted
+ files being whitelisted again. Subsequent matches will override previous
+ ones. A leading literal exclamation mark or backslash needs to be escaped.
+
+*CleanMethod =* KeepInstalled &| KeepCurrent::
+ If set to `KeepInstalled` (the default), the '-Sc' operation will clean
+ packages that are no longer installed (not present in the local database).
+ If set to `KeepCurrent`, '-Sc' will clean outdated packages (not present in
+ any sync database).
+ The second behavior is useful when the package cache is shared among
+ multiple machines, where the local databases are usually different, but the
+ sync databases in use could be the same. If both values are specified,
+ packages are only cleaned if not installed locally and not present in any
+ known sync database.
+
+*SigLevel =* ...::
+ Set the default signature verification level. For more information, see
+ <<SC,Package and Database Signature Checking>> below.
+
+*LocalFileSigLevel =* ...::
+ Set the signature verification level for installing packages using the "-U"
+ operation on a local file. Uses the value from SigLevel as the default.
+
+*RemoteFileSigLevel =* ...::
+ Set the signature verification level for installing packages using the "-U"
+ operation on a remote file URL. Uses the value from SigLevel as the default.
+
+*UseSyslog*::
+ Log action messages through syslog(). This will insert log entries into
+ +{localstatedir}/log/messages+ or equivalent.
+
+*Color*::
+ Automatically enable colors only when pacman's output is on a tty.
+
+*UseDelta* [= ratio]::
+ Download delta files instead of complete packages if possible. Requires
+ the `xdelta3` program to be installed. If a ratio is specified (e.g.,
+ `0.5`), then it is used as a cutoff for determining whether to use deltas.
+ Allowed values are between `0.0` and `2.0`; sensible values are between
+ `0.2` and `0.9`. Using a value above `1.0` is not recommended. The
+ default is `0.7` if left unspecified.
+
+*TotalDownload*::
+ When downloading, display the amount downloaded, download rate, ETA,
+ and completed percentage of the entire download list rather
+ than the percent of each individual download target. The progress
+ bar is still based solely on the current file download.
+ This option won't work if XferCommand is used.
+
+*CheckSpace*::
+ Performs an approximate check for adequate available disk space before
+ installing packages.
+
+*VerbosePkgLists*::
+ Displays name, version and size of target packages formatted
+ as a table for upgrade, sync and remove operations.
+
+*DisableDownloadTimeout*::
+ Disable defaults for low speed limit and timeout on downloads. Use this
+ if you have issues downloading files with proxy and/or security gateway.
+
+
+Repository Sections
+-------------------
+Each repository section defines a section name and at least one location where
+the packages can be found. The section name is defined by the string within
+square brackets (the two above are 'core' and 'custom'). Repository names
+must be unique and the name 'local' is reserved for the database of installed
+packages. Locations are defined with the 'Server' directive and follow a URL
+naming structure. If you want to use a local directory, you can specify the
+full path with a ``file://'' prefix, as shown above.
+
+A common way to define DB locations utilizes the 'Include' directive. For each
+repository defined in the configuration file, a single 'Include' directive can
+contain a file that lists the servers for that repository.
+
+--------
+[core]
+# use this server first
+Server = ftp://ftp.archlinux.org/$repo/os/$arch
+# next use servers as defined in the mirrorlist below
+Include = {sysconfdir}/pacman.d/mirrorlist
+--------
+
+The order of repositories in the configuration files matters; repositories
+listed first will take precedence over those listed later in the file when
+packages in two repositories have identical names, regardless of version
+number.
+
+*Include =* path::
+ Include another config file. This file can include repositories or
+ general configuration options. Wildcards in the specified paths will get
+ expanded based on linkman:glob[7] rules.
+
+*Server =* url::
+ A full URL to a location where the database, packages, and signatures (if
+ available) for this repository can be found.
++
+During parsing, pacman will define the `$repo` variable to the name of the
+current section. This is often utilized in files specified using the 'Include'
+directive so all repositories can use the same mirrorfile. pacman also defines
+the `$arch` variable to the value of `Architecture`, so the same mirrorfile can
+even be used for different architectures.
+
+*SigLevel =* ...::
+ Set the signature verification level for this repository. For more
+ information, see <<SC,Package and Database Signature Checking>> below.
+
+*Usage =* ...::
+ Set the usage level for this repository. This option takes a list of tokens
+ which must be at least one of the following:
+ *Sync*;;
+ Enables refreshes for this repository.
+ *Search*;;
+ Enables searching for this repository.
+ *Install*;;
+ Enables installation of packages from this repository during a '\--sync'
+ operation.
+ *Upgrade*;;
+ Allows this repository to be a valid source of packages when performing
+ a '\--sysupgrade'.
+ *All*;;
+ Enables all of the above features for the repository. This is the default
+ if not specified.
++
+Note that an enabled repository can be operated on explicitly, regardless of the Usage
+level set.
+
+
+Package and Database Signature Checking[[SC]]
+---------------------------------------------
+The 'SigLevel' directive is valid in both the `[options]` and repository
+sections. If used in `[options]`, it sets a default value for any repository
+that does not provide the setting.
+
+* If set to *Never*, no signature checking will take place.
+* If set to *Optional* , signatures will be checked when present, but unsigned
+ databases and packages will also be accepted.
+* If set to *Required*, signatures will be required on all packages and
+ databases.
+
+Alternatively, you can get more fine-grained control by combining some of
+the options and prefixes described below. All options in a config file are
+processed in top-to-bottom, left-to-right fashion, where later options override
+and/or supplement earlier ones. If 'SigLevel' is specified in a repository
+section, the starting value is that from the `[options]` section, or the
+built-in system default as shown below if not specified.
+
+The options are split into two main groups, described below. Terms used such as
+``marginally trusted'' are terms used by GnuPG, for more information please
+consult linkman:gpg[1].
+
+When to Check::
+ These options control if and when signature checks should take place.
+
+ *Never*;;
+ All signature checking is suppressed, even if signatures are present.
+
+ *Optional* (default);;
+ Signatures are checked if present; absence of a signature is not an
+ error. An invalid signature is a fatal error, as is a signature from a
+ key not in the keyring.
+
+ *Required*;;
+ Signatures are required; absence of a signature or an invalid signature
+ is a fatal error, as is a signature from a key not in the keyring.
+
+What is Allowed::
+ These options control what signatures are viewed as permissible. Note that
+ neither of these options allows acceptance of invalid or expired
+ signatures, or those from revoked keys.
+
+ *TrustedOnly* (default);;
+ If a signature is checked, it must be in the keyring and fully trusted;
+ marginal trust does not meet this criteria.
+
+ *TrustAll*;;
+ If a signature is checked, it must be in the keyring, but is not
+ required to be assigned a trust level (e.g., unknown or marginal
+ trust).
+
+Options in both groups can additionally be prefixed with either *Package* or
+*Database*, which will cause it to only take effect on the specified object
+type. For example, `PackageTrustAll` would allow marginal and unknown trust
+level signatures for packages.
+
+The built-in default is the following:
+
+--------
+SigLevel = Optional TrustedOnly
+--------
+
+
+Using Your Own Repository
+-------------------------
+If you have numerous custom packages of your own, it is often easier to generate
+your own custom local repository than install them all with the '\--upgrade'
+option. All you need to do is generate a compressed package database in the
+directory with these packages so pacman can find it when run with '\--refresh'.
+
+ repo-add /home/pkgs/custom.db.tar.gz /home/pkgs/*.pkg.tar.gz
+
+The above command will generate a compressed database named
+'/home/pkgs/custom.db.tar.gz'. Note that the database must be of the form
+'\{treename\}.db.tar.{ext}', where '\{treename\}' is the name of the section
+defined in the configuration file and '\{ext\}' is a valid compression type as
+documented in linkman:repo-add[8]. That's it! Now configure your custom section
+in the configuration file as shown in the config example above. Pacman will now
+use your package repository. If you add new packages to the repository,
+remember to re-generate the database and use pacman's '\--refresh' option.
+
+For more information on the repo-add command, see ``repo-add \--help'' or
+linkman:repo-add[8].
+
+
+See Also
+--------
+linkman:pacman[8], linkman:libalpm[3]
+
+include::footer.asciidoc[]