From 9cb03b68709aec0797360b53efecdc6a1c916d1f Mon Sep 17 00:00:00 2001 From: Leonid Pliushch Date: Mon, 23 Sep 2019 20:19:48 +0300 Subject: [PATCH] apt: add man pages Fixes https://github.com/termux/termux-packages/issues/2419. --- packages/apt/build.sh | 6 +- packages/apt/man/man5/apt.conf.5 | 1289 +++++++++++++++++++++++ packages/apt/man/man5/apt_preferences.5 | 889 ++++++++++++++++ packages/apt/man/man5/sources.list.5 | 730 +++++++++++++ packages/apt/man/man8/apt-cache.8 | 533 ++++++++++ packages/apt/man/man8/apt-config.8 | 145 +++ packages/apt/man/man8/apt-get.8 | 710 +++++++++++++ packages/apt/man/man8/apt-key.8 | 190 ++++ packages/apt/man/man8/apt-mark.8 | 191 ++++ packages/apt/man/man8/apt-secure.8 | 263 +++++ packages/apt/man/man8/apt.8 | 170 +++ 11 files changed, 5115 insertions(+), 1 deletion(-) create mode 100644 packages/apt/man/man5/apt.conf.5 create mode 100644 packages/apt/man/man5/apt_preferences.5 create mode 100644 packages/apt/man/man5/sources.list.5 create mode 100644 packages/apt/man/man8/apt-cache.8 create mode 100644 packages/apt/man/man8/apt-config.8 create mode 100644 packages/apt/man/man8/apt-get.8 create mode 100644 packages/apt/man/man8/apt-key.8 create mode 100644 packages/apt/man/man8/apt-mark.8 create mode 100644 packages/apt/man/man8/apt-secure.8 create mode 100644 packages/apt/man/man8/apt.8 diff --git a/packages/apt/build.sh b/packages/apt/build.sh index 7a8be794c..c1d1313cd 100644 --- a/packages/apt/build.sh +++ b/packages/apt/build.sh @@ -2,7 +2,7 @@ TERMUX_PKG_HOMEPAGE=https://packages.debian.org/apt TERMUX_PKG_DESCRIPTION="Front-end for the dpkg package manager" TERMUX_PKG_LICENSE="GPL-2.0" TERMUX_PKG_VERSION=1.4.9 -TERMUX_PKG_REVISION=15 +TERMUX_PKG_REVISION=16 TERMUX_PKG_SRCURL=http://ftp.debian.org/debian/pool/main/a/apt/apt_${TERMUX_PKG_VERSION}.tar.xz TERMUX_PKG_SHA256=d4d65e7c84da86f3e6dcc933bba46a08db429c9d933b667c864f5c0e880bac0d # apt-key requires utilities from coreutils, findutils, gpgv, grep, sed. @@ -60,4 +60,8 @@ termux_step_post_make_install() { ln -sfr $TERMUX_PREFIX/lib/apt/methods/http $TERMUX_PREFIX/lib/apt/methods/tor ln -sfr $TERMUX_PREFIX/lib/apt/methods/http $TERMUX_PREFIX/lib/apt/methods/tor+http ln -sfr $TERMUX_PREFIX/lib/apt/methods/https $TERMUX_PREFIX/lib/apt/methods/tor+https + + # man pages + mkdir -p $TERMUX_PREFIX/share/man/ + cp -Rf $TERMUX_PKG_BUILDER_DIR/man/* $TERMUX_PREFIX/share/man/ } diff --git a/packages/apt/man/man5/apt.conf.5 b/packages/apt/man/man5/apt.conf.5 new file mode 100644 index 000000000..9c7b08735 --- /dev/null +++ b/packages/apt/man/man5/apt.conf.5 @@ -0,0 +1,1289 @@ +'\" t +.\" Title: apt.conf +.\" Author: Jason Gunthorpe +.\" Generator: DocBook XSL Stylesheets v1.79.1 +.\" Date: 25\ \&November\ \&2016 +.\" Manual: APT +.\" Source: APT 1.4.9 +.\" Language: English +.\" +.TH "APT\&.CONF" "5" "25\ \&November\ \&2016" "APT 1.4.9" "APT" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +apt.conf \- Configuration file for APT +.SH "DESCRIPTION" +.PP +/etc/apt/apt\&.conf +is the main configuration file shared by all the tools in the APT suite of tools, though it is by no means the only place options can be set\&. The suite also shares a common command line parser to provide a uniform environment\&. +.PP +When an APT tool starts up it will read the configuration files in the following order: +.sp +.RS 4 +.ie n \{\ +\h'-04' 1.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 1." 4.2 +.\} +the file specified by the +\fBAPT_CONFIG\fR +environment variable (if any) +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 2.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 2." 4.2 +.\} +all files in +Dir::Etc::Parts +in alphanumeric ascending order which have either no or "conf" as filename extension and which only contain alphanumeric, hyphen (\-), underscore (_) and period (\&.) characters\&. Otherwise APT will print a notice that it has ignored a file, unless that file matches a pattern in the +Dir::Ignore\-Files\-Silently +configuration list \- in which case it will be silently ignored\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 3.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 3." 4.2 +.\} +the main configuration file specified by +Dir::Etc::main +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 4.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 4." 4.2 +.\} +all options set in the binary specific configuration subtree are moved into the root of the tree\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 5.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 5." 4.2 +.\} +the command line options are applied to override the configuration directives or to load even more configuration files\&. +.RE +.SH "SYNTAX" +.PP +The configuration file is organized in a tree with options organized into functional groups\&. Option specification is given with a double colon notation; for instance +APT::Get::Assume\-Yes +is an option within the APT tool group, for the Get tool\&. Options do not inherit from their parent groups\&. +.PP +Syntactically the configuration language is modeled after what the ISC tools such as bind and dhcp use\&. Lines starting with +// +are treated as comments (ignored), as well as all text between +/* +and +*/, just like C/C++ comments\&. Each line is of the form +APT::Get::Assume\-Yes "true";\&. The quotation marks and trailing semicolon are required\&. The value must be on one line, and there is no kind of string concatenation\&. Values must not include backslashes or extra quotation marks\&. Option names are made up of alphanumeric characters and the characters "/\-:\&._+"\&. A new scope can be opened with curly braces, like this: +.sp +.if n \{\ +.RS 4 +.\} +.nf + +APT { + Get { + Assume\-Yes "true"; + Fix\-Broken "true"; + }; +}; +.fi +.if n \{\ +.RE +.\} +.PP +with newlines placed to make it more readable\&. Lists can be created by opening a scope and including a single string enclosed in quotes followed by a semicolon\&. Multiple entries can be included, separated by a semicolon\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf + +DPkg::Pre\-Install\-Pkgs {"/usr/sbin/dpkg\-preconfigure \-\-apt";}; +.fi +.if n \{\ +.RE +.\} +.PP +In general the sample configuration file +/usr/share/doc/apt/examples/configure\-index\&.gz +is a good guide for how it should look\&. +.PP +Case is not significant in names of configuration items, so in the previous example you could use +dpkg::pre\-install\-pkgs\&. +.PP +Names for the configuration items are optional if a list is defined as can be seen in the +DPkg::Pre\-Install\-Pkgs +example above\&. If you don\*(Aqt specify a name a new entry will simply add a new option to the list\&. If you specify a name you can override the option in the same way as any other option by reassigning a new value to the option\&. +.PP +Two special commands are defined: +#include +(which is deprecated and not supported by alternative implementations) and +#clear\&. +#include +will include the given file, unless the filename ends in a slash, in which case the whole directory is included\&. +#clear +is used to erase a part of the configuration tree\&. The specified element and all its descendants are erased\&. (Note that these lines also need to end with a semicolon\&.) +.PP +The +#clear +command is the only way to delete a list or a complete scope\&. Reopening a scope (or using the syntax described below with an appended +::) will +\fInot\fR +override previously written entries\&. Options can only be overridden by addressing a new value to them \- lists and scopes can\*(Aqt be overridden, only cleared\&. +.PP +All of the APT tools take an \-o option which allows an arbitrary configuration directive to be specified on the command line\&. The syntax is a full option name (APT::Get::Assume\-Yes +for instance) followed by an equals sign then the new value of the option\&. To append a new element to a list, add a trailing +:: +to the name of the list\&. (As you might suspect, the scope syntax can\*(Aqt be used on the command line\&.) +.PP +Note that appending items to a list using +:: +only works for one item per line, and that you should not use it in combination with the scope syntax (which adds +:: +implicitly)\&. Using both syntaxes together will trigger a bug which some users unfortunately depend on: an option with the unusual name "::" which acts like every other option with a name\&. This introduces many problems; for one thing, users who write multiple lines in this +\fIwrong\fR +syntax in the hope of appending to a list will achieve the opposite, as only the last assignment for this option "::" will be used\&. Future versions of APT will raise errors and stop working if they encounter this misuse, so please correct such statements now while APT doesn\*(Aqt explicitly complain about them\&. +.SH "THE APT GROUP" +.PP +This group of options controls general APT behavior as well as holding the options for all of the tools\&. +.PP +\fBArchitecture\fR +.RS 4 +System Architecture; sets the architecture to use when fetching files and parsing package lists\&. The internal default is the architecture apt was compiled for\&. +.RE +.PP +\fBArchitectures\fR +.RS 4 +All Architectures the system supports\&. For instance, CPUs implementing the +amd64 +(also called +x86\-64) instruction set are also able to execute binaries compiled for the +i386 +(x86) instruction set\&. This list is used when fetching files and parsing package lists\&. The initial default is always the system\*(Aqs native architecture (APT::Architecture), and foreign architectures are added to the default list when they are registered via +\fBdpkg \-\-add\-architecture\fR\&. +.RE +.PP +\fBCompressor\fR +.RS 4 +This scope defines which compression formats are supported, how compression and decompression can be performed if support for this format isn\*(Aqt built into apt directly and a cost\-value indicating how costly it is to compress something in this format\&. As an example the following configuration stanza would allow apt to download and uncompress as well as create and store files with the low\-cost +\&.reversed +file extension which it will pass to the command +\fBrev\fR +without additional commandline parameters for compression and uncompression: +.sp .if n \{\ .RS 4 .\} .nf APT::Compressor::rev { Name "rev"; Extension "\&.reversed"; Binary "rev"; CompressArg {}; UncompressArg {}; Cost "10"; }; .fi .if n \{\ .RE .\} +.RE +.PP +\fBBuild\-Profiles\fR +.RS 4 +List of all build profiles enabled for build\-dependency resolution, without the "profile\&." namespace prefix\&. By default this list is empty\&. The +\fBDEB_BUILD_PROFILES\fR +as used by +\fBdpkg-buildpackage\fR(1) +overrides the list notation\&. +.RE +.PP +\fBDefault\-Release\fR +.RS 4 +Default release to install packages from if more than one version is available\&. Contains release name, codename or release version\&. Examples: \*(Aqstable\*(Aq, \*(Aqtesting\*(Aq, \*(Aqunstable\*(Aq, \*(Aqstretch\*(Aq, \*(Aqbuster\*(Aq, \*(Aq4\&.0\*(Aq, \*(Aq5\&.0*\*(Aq\&. See also +\fBapt_preferences\fR(5)\&. +.RE +.PP +\fBIgnore\-Hold\fR +.RS 4 +Ignore held packages; this global option causes the problem resolver to ignore held packages in its decision making\&. +.RE +.PP +\fBClean\-Installed\fR +.RS 4 +Defaults to on\&. When turned on the autoclean feature will remove any packages which can no longer be downloaded from the cache\&. If turned off then packages that are locally installed are also excluded from cleaning \- but note that APT provides no direct means to reinstall them\&. +.RE +.PP +\fBImmediate\-Configure\fR +.RS 4 +Defaults to on, which will cause APT to install essential and important packages as soon as possible in an install/upgrade operation, in order to limit the effect of a failing +\fBdpkg\fR(1) +call\&. If this option is disabled, APT treats an important package in the same way as an extra package: between the unpacking of the package A and its configuration there can be many other unpack or configuration calls for other unrelated packages B, C etc\&. If these cause the +\fBdpkg\fR(1) +call to fail (e\&.g\&. because package B\*(Aqs maintainer scripts generate an error), this results in a system state in which package A is unpacked but unconfigured \- so any package depending on A is now no longer guaranteed to work, as its dependency on A is no longer satisfied\&. +.sp +The immediate configuration marker is also applied in the potentially problematic case of circular dependencies, since a dependency with the immediate flag is equivalent to a Pre\-Dependency\&. In theory this allows APT to recognise a situation in which it is unable to perform immediate configuration, abort, and suggest to the user that the option should be temporarily deactivated in order to allow the operation to proceed\&. Note the use of the word "theory" here; in the real world this problem has rarely been encountered, in non\-stable distribution versions, and was caused by wrong dependencies of the package in question or by a system in an already broken state; so you should not blindly disable this option, as the scenario mentioned above is not the only problem it can help to prevent in the first place\&. +.sp +Before a big operation like +dist\-upgrade +is run with this option disabled you should try to explicitly +install +the package APT is unable to configure immediately; but please make sure you also report your problem to your distribution and to the APT team with the buglink below, so they can work on improving or correcting the upgrade process\&. +.RE +.PP +\fBForce\-LoopBreak\fR +.RS 4 +Never enable this option unless you +\fIreally\fR +know what you are doing\&. It permits APT to temporarily remove an essential package to break a Conflicts/Conflicts or Conflicts/Pre\-Depends loop between two essential packages\&. +\fISuch a loop should never exist and is a grave bug\fR\&. This option will work if the essential packages are not +\fBtar\fR, +\fBgzip\fR, +\fBlibc\fR, +\fBdpkg\fR, +\fBdash\fR +or anything that those packages depend on\&. +.RE +.PP +\fBCache\-Start\fR, \fBCache\-Grow\fR, \fBCache\-Limit\fR +.RS 4 +APT uses since version 0\&.7\&.26 a resizable memory mapped cache file to store the available information\&. +Cache\-Start +acts as a hint of the size the cache will grow to, and is therefore the amount of memory APT will request at startup\&. The default value is 20971520 bytes (~20 MB)\&. Note that this amount of space needs to be available for APT; otherwise it will likely fail ungracefully, so for memory restricted devices this value should be lowered while on systems with a lot of configured sources it should be increased\&. +Cache\-Grow +defines in bytes with the default of 1048576 (~1 MB) how much the cache size will be increased in the event the space defined by +Cache\-Start +is not enough\&. This value will be applied again and again until either the cache is big enough to store all information or the size of the cache reaches the +Cache\-Limit\&. The default of +Cache\-Limit +is 0 which stands for no limit\&. If +Cache\-Grow +is set to 0 the automatic growth of the cache is disabled\&. +.RE +.PP +\fBBuild\-Essential\fR +.RS 4 +Defines which packages are considered essential build dependencies\&. +.RE +.PP +\fBGet\fR +.RS 4 +The Get subsection controls the +\fBapt-get\fR(8) +tool; please see its documentation for more information about the options here\&. +.RE +.PP +\fBCache\fR +.RS 4 +The Cache subsection controls the +\fBapt-cache\fR(8) +tool; please see its documentation for more information about the options here\&. +.RE +.PP +\fBCDROM\fR +.RS 4 +The CDROM subsection controls the +\fBapt-cdrom\fR(8) +tool; please see its documentation for more information about the options here\&. +.RE +.SH "THE ACQUIRE GROUP" +.PP +The +Acquire +group of options controls the download of packages as well as the various "acquire methods" responsible for the download itself (see also +\fBsources.list\fR(5))\&. +.PP +\fBCheck\-Valid\-Until\fR +.RS 4 +Security related option defaulting to true, as giving a Release file\*(Aqs validation an expiration date prevents replay attacks over a long timescale, and can also for example help users to identify mirrors that are no longer updated \- but the feature depends on the correctness of the clock on the user system\&. Archive maintainers are encouraged to create Release files with the +Valid\-Until +header, but if they don\*(Aqt or a stricter value is desired the +Max\-ValidTime +option below can be used\&. The +\fBCheck\-Valid\-Until\fR +option of +\fBsources.list\fR(5) +entries should be preferred to disable the check selectively instead of using this global override\&. +.RE +.PP +\fBMax\-ValidTime\fR +.RS 4 +Maximum time (in seconds) after its creation (as indicated by the +Date +header) that the +Release +file should be considered valid\&. If the Release file itself includes a +Valid\-Until +header the earlier date of the two is used as the expiration date\&. The default value is +0 +which stands for "valid forever"\&. Archive specific settings can be made by appending the label of the archive to the option name\&. Preferably, the same can be achieved for specific +\fBsources.list\fR(5) +entries by using the +\fBValid\-Until\-Max\fR +option there\&. +.RE +.PP +\fBMin\-ValidTime\fR +.RS 4 +Minimum time (in seconds) after its creation (as indicated by the +Date +header) that the +Release +file should be considered valid\&. Use this if you need to use a seldom updated (local) mirror of a more frequently updated archive with a +Valid\-Until +header instead of completely disabling the expiration date checking\&. Archive specific settings can and should be used by appending the label of the archive to the option name\&. Preferably, the same can be achieved for specific +\fBsources.list\fR(5) +entries by using the +\fBValid\-Until\-Min\fR +option there\&. +.RE +.PP +\fBPDiffs\fR +.RS 4 +Try to download deltas called +PDiffs +for indexes (like +Packages +files) instead of downloading whole ones\&. True by default\&. Preferably, this can be set for specific +\fBsources.list\fR(5) +entries or index files by using the +\fBPDiffs\fR +option there\&. +.sp +Two sub\-options to limit the use of PDiffs are also available: +FileLimit +can be used to specify a maximum number of PDiff files should be downloaded to update a file\&. +SizeLimit +on the other hand is the maximum percentage of the size of all patches compared to the size of the targeted file\&. If one of these limits is exceeded the complete file is downloaded instead of the patches\&. +.RE +.PP +\fBBy\-Hash\fR +.RS 4 +Try to download indexes via an URI constructed from a hashsum of the expected file rather than downloaded via a well\-known stable filename\&. True by default, but automatically disabled if the source indicates no support for it\&. Usage can be forced with the special value "force"\&. Preferably, this can be set for specific +\fBsources.list\fR(5) +entries or index files by using the +\fBBy\-Hash\fR +option there\&. +.RE +.PP +\fBQueue\-Mode\fR +.RS 4 +Queuing mode; +Queue\-Mode +can be one of +host +or +access +which determines how APT parallelizes outgoing connections\&. +host +means that one connection per target host will be opened, +access +means that one connection per URI type will be opened\&. +.RE +.PP +\fBRetries\fR +.RS 4 +Number of retries to perform\&. If this is non\-zero APT will retry failed files the given number of times\&. +.RE +.PP +\fBSource\-Symlinks\fR +.RS 4 +Use symlinks for source archives\&. If set to true then source archives will be symlinked when possible instead of copying\&. True is the default\&. +.RE +.PP +\fBhttp\fR +.RS 4 +http::Proxy +sets the default proxy to use for HTTP URIs\&. It is in the standard form of +http://[[user][:pass]@]host[:port]/\&. Per host proxies can also be specified by using the form +http::Proxy:: +with the special keyword +DIRECT +meaning to use no proxies\&. If no one of the above settings is specified, +\fBhttp_proxy\fR +environment variable will be used\&. +.sp +Three settings are provided for cache control with HTTP/1\&.1 compliant proxy caches\&. +No\-Cache +tells the proxy not to use its cached response under any circumstances\&. +Max\-Age +sets the allowed maximum age (in seconds) of an index file in the cache of the proxy\&. +No\-Store +specifies that the proxy should not store the requested archive files in its cache, which can be used to prevent the proxy from polluting its cache with (big) \&.deb files\&. +.sp +The option +timeout +sets the timeout timer used by the method; this value applies to the connection as well as the data timeout\&. +.sp +The setting +Acquire::http::Pipeline\-Depth +can be used to enable HTTP pipelining (RFC 2616 section 8\&.1\&.2\&.2) which can be beneficial e\&.g\&. on high\-latency connections\&. It specifies how many requests are sent in a pipeline\&. APT tries to detect and workaround misbehaving webservers and proxies at runtime, but if you know that yours does not conform to the HTTP/1\&.1 specification pipelining can be disabled by setting the value to 0\&. It is enabled by default with the value 10\&. +.sp +Acquire::http::AllowRedirect +controls whether APT will follow redirects, which is enabled by default\&. +.sp +The used bandwidth can be limited with +Acquire::http::Dl\-Limit +which accepts integer values in kilobytes per second\&. The default value is 0 which deactivates the limit and tries to use all available bandwidth\&. Note that this option implicitly disables downloading from multiple servers at the same time\&. +.sp +Acquire::http::User\-Agent +can be used to set a different User\-Agent for the http download method as some proxies allow access for clients only if the client uses a known identifier\&. +.sp +Acquire::http::Proxy\-Auto\-Detect +can be used to specify an external command to discover the http proxy to use\&. The first and only parameter is an URI denoting the host to be contacted to allow for host\-specific configuration\&. APT expects the command to output the proxy on stdout as a single line in the style +http://proxy:port/ +or the word +DIRECT +if no proxy should be used\&. No output indicates that the generic proxy settings should be used\&. Note that auto\-detection will not be used for a host if a host\-specific proxy configuration is already set via +Acquire::http::Proxy::\fIHOST\fR\&. See the +\fBsquid-deb-proxy-client\fR(1) +package for an example implementation that uses avahi\&. This option takes precedence over the legacy option name +ProxyAutoDetect\&. +.RE +.PP +\fBhttps\fR +.RS 4 +The +Cache\-control, +Timeout, +AllowRedirect, +Dl\-Limit +and +proxy +options work for HTTPS URIs in the same way as for the +http +method, and default to the same values if they are not explicitly set\&. The +Pipeline\-Depth +option is not yet supported\&. +.sp +CaInfo +suboption specifies place of file that holds info about trusted certificates\&. +::CaInfo +is the corresponding per\-host option\&. +Verify\-Peer +boolean suboption determines whether or not the server\*(Aqs host certificate should be verified against trusted certificates\&. +::Verify\-Peer +is the corresponding per\-host option\&. +Verify\-Host +boolean suboption determines whether or not the server\*(Aqs hostname should be verified\&. +::Verify\-Host +is the corresponding per\-host option\&. +SslCert +determines what certificate to use for client authentication\&. +::SslCert +is the corresponding per\-host option\&. +SslKey +determines what private key to use for client authentication\&. +::SslKey +is the corresponding per\-host option\&. +SslForceVersion +overrides default SSL version to use\&. It can contain either of the strings \*(AqTLSv1\*(Aq or \*(AqSSLv3\*(Aq\&. +::SslForceVersion +is the corresponding per\-host option\&. +.RE +.PP +\fBftp\fR +.RS 4 +ftp::Proxy +sets the default proxy to use for FTP URIs\&. It is in the standard form of +ftp://[[user][:pass]@]host[:port]/\&. Per host proxies can also be specified by using the form +ftp::Proxy:: +with the special keyword +DIRECT +meaning to use no proxies\&. If no one of the above settings is specified, +\fBftp_proxy\fR +environment variable will be used\&. To use an FTP proxy you will have to set the +ftp::ProxyLogin +script in the configuration file\&. This entry specifies the commands to send to tell the proxy server what to connect to\&. Please see +/usr/share/doc/apt/examples/configure\-index\&.gz +for an example of how to do this\&. The substitution variables representing the corresponding URI component are +$(PROXY_USER), +$(PROXY_PASS), +$(SITE_USER), +$(SITE_PASS), +$(SITE) +and +$(SITE_PORT)\&. +.sp +The option +timeout +sets the timeout timer used by the method; this value applies to the connection as well as the data timeout\&. +.sp +Several settings are provided to control passive mode\&. Generally it is safe to leave passive mode on; it works in nearly every environment\&. However, some situations require that passive mode be disabled and port mode FTP used instead\&. This can be done globally or for connections that go through a proxy or for a specific host (see the sample config file for examples)\&. +.sp +It is possible to proxy FTP over HTTP by setting the +\fBftp_proxy\fR +environment variable to an HTTP URL \- see the discussion of the http method above for syntax\&. You cannot set this in the configuration file and it is not recommended to use FTP over HTTP due to its low efficiency\&. +.sp +The setting +ForceExtended +controls the use of RFC2428 +EPSV +and +EPRT +commands\&. The default is false, which means these commands are only used if the control connection is IPv6\&. Setting this to true forces their use even on IPv4 connections\&. Note that most FTP servers do not support RFC2428\&. +.RE +.PP +\fBcdrom\fR +.RS 4 +For URIs using the +cdrom +method, the only configurable option is the mount point, +cdrom::Mount, which must be the mount point for the CD\-ROM (or DVD, or whatever) drive as specified in +/etc/fstab\&. It is possible to provide alternate mount and unmount commands if your mount point cannot be listed in the fstab\&. The syntax is to put +.sp +.if n \{\ +.RS 4 +.\} +.nf +/cdrom/::Mount "foo"; +.fi +.if n \{\ +.RE +.\} +.sp +within the +cdrom +block\&. It is important to have the trailing slash\&. Unmount commands can be specified using UMount\&. +.RE +.PP +\fBgpgv\fR +.RS 4 +For GPGV URIs the only configurable option is +gpgv::Options, which passes additional parameters to gpgv\&. +.RE +.PP +\fBCompressionTypes\fR +.RS 4 +List of compression types which are understood by the acquire methods\&. Files like +Packages +can be available in various compression formats\&. By default the acquire methods can decompress and recompress many common formats like +\fBxz\fR +and +\fBgzip\fR; with this scope the supported formats can be queried, modified as well as support for more formats added (see also +\fBAPT::Compressor\fR)\&. The syntax for this is: +.sp +.if n \{\ +.RS 4 +.\} +.nf +Acquire::CompressionTypes::\fIFileExtension\fR "\fIMethodname\fR"; +.fi +.if n \{\ +.RE +.\} +.sp +Also, the +Order +subgroup can be used to define in which order the acquire system will try to download the compressed files\&. The acquire system will try the first and proceed with the next compression type in this list on error, so to prefer one over the other type simply add the preferred type first \- types not already added will be implicitly appended to the end of the list, so e\&.g\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +Acquire::CompressionTypes::Order:: "gz"; +.fi +.if n \{\ +.RE +.\} +.sp +can be used to prefer +\fBgzip\fR +compressed files over all other compression formats\&. If +\fBxz\fR +should be preferred over +\fBgzip\fR +and +\fBbzip2\fR +the configure setting should look like this: +.sp +.if n \{\ +.RS 4 +.\} +.nf +Acquire::CompressionTypes::Order { "xz"; "gz"; }; +.fi +.if n \{\ +.RE +.\} +.sp +It is not needed to add +bz2 +to the list explicitly as it will be added automatically\&. +.sp +Note that the +Dir::Bin::\fIMethodname\fR +will be checked at run time\&. If this option has been set and support for this format isn\*(Aqt directly built into apt, the method will only be used if this file exists; e\&.g\&. for the +bzip2 +method (the inbuilt) setting is: +.sp +.if n \{\ +.RS 4 +.\} +.nf +Dir::Bin::bzip2 "/bin/bzip2"; +.fi +.if n \{\ +.RE +.\} +.sp +Note also that list entries specified on the command line will be added at the end of the list specified in the configuration files, but before the default entries\&. To prefer a type in this case over the ones specified in the configuration files you can set the option direct \- not in list style\&. This will not override the defined list; it will only prefix the list with this type\&. +.sp +The special type +uncompressed +can be used to give uncompressed files a preference, but note that most archives don\*(Aqt provide uncompressed files so this is mostly only useable for local mirrors\&. +.RE +.PP +\fBGzipIndexes\fR +.RS 4 +When downloading +gzip +compressed indexes (Packages, Sources, or Translations), keep them gzip compressed locally instead of unpacking them\&. This saves quite a lot of disk space at the expense of more CPU requirements when building the local package caches\&. False by default\&. +.RE +.PP +\fBLanguages\fR +.RS 4 +The Languages subsection controls which +Translation +files are downloaded and in which order APT tries to display the description\-translations\&. APT will try to display the first available description in the language which is listed first\&. Languages can be defined with their short or long language codes\&. Note that not all archives provide +Translation +files for every language \- the long language codes are especially rare\&. +.sp +The default list includes "environment" and "en"\&. "environment" has a special meaning here: it will be replaced at runtime with the language codes extracted from the +LC_MESSAGES +environment variable\&. It will also ensure that these codes are not included twice in the list\&. If +LC_MESSAGES +is set to "C" only the +Translation\-en +file (if available) will be used\&. To force APT to use no Translation file use the setting +Acquire::Languages=none\&. "none" is another special meaning code which will stop the search for a suitable +Translation +file\&. This tells APT to download these translations too, without actually using them unless the environment specifies the languages\&. So the following example configuration will result in the order "en, de" in an English locale or "de, en" in a German one\&. Note that "fr" is downloaded, but not used unless APT is used in a French locale (where the order would be "fr, de, en")\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +Acquire::Languages { "environment"; "de"; "en"; "none"; "fr"; }; +.fi +.if n \{\ +.RE +.\} +.sp +Note: To prevent problems resulting from APT being executed in different environments (e\&.g\&. by different users or by other programs) all Translation files which are found in +/var/lib/apt/lists/ +will be added to the end of the list (after an implicit "none")\&. +.RE +.PP +\fBForceIPv4\fR +.RS 4 +When downloading, force to use only the IPv4 protocol\&. +.RE +.PP +\fBForceIPv6\fR +.RS 4 +When downloading, force to use only the IPv6 protocol\&. +.RE +.PP +\fBMaxReleaseFileSize\fR +.RS 4 +The maximum file size of Release/Release\&.gpg/InRelease files\&. The default is 10MB\&. +.RE +.PP +\fBEnableSrvRecords\fR +.RS 4 +This option controls if apt will use the DNS SRV server record as specified in RFC 2782 to select an alternative server to connect to\&. The default is "true"\&. +.RE +.PP +\fBAllowInsecureRepositories\fR +.RS 4 +Allow update operations to load data files from repositories without sufficient security information\&. The default value is "false"\&. Concept, implications as well as alternatives are detailed in +\fBapt-secure\fR(8)\&. +.RE +.PP +\fBAllowWeakRepositories\fR +.RS 4 +Allow update operations to load data files from repositories which provide security information, but these are deemed no longer cryptographically strong enough\&. The default value is "false"\&. Concept, implications as well as alternatives are detailed in +\fBapt-secure\fR(8)\&. +.RE +.PP +\fBAllowDowngradeToInsecureRepositories\fR +.RS 4 +Allow that a repository that was previously gpg signed to become unsigned during an update operation\&. When there is no valid signature for a previously trusted repository apt will refuse the update\&. This option can be used to override this protection\&. You almost certainly never want to enable this\&. The default is +false\&. Concept, implications as well as alternatives are detailed in +\fBapt-secure\fR(8)\&. +.RE +.PP +\fBChangelogs::URI\fR scope +.RS 4 +Acquiring changelogs can only be done if an URI is known from where to get them\&. Preferable the Release file indicates this in a \*(AqChangelogs\*(Aq field\&. If this isn\*(Aqt available the Label/Origin field of the Release file is used to check if a +Acquire::Changelogs::URI::Label::\fILABEL\fR +or +Acquire::Changelogs::URI::Origin::\fIORIGIN\fR +option exists and if so this value is taken\&. The value in the Release file can be overridden with +Acquire::Changelogs::URI::Override::Label::\fILABEL\fR +or +Acquire::Changelogs::URI::Override::Origin::\fIORIGIN\fR\&. The value should be a normal URI to a text file, except that package specific data is replaced with the placeholder +@CHANGEPATH@\&. The value for it is: 1\&. if the package is from a component (e\&.g\&. +main) this is the first part otherwise it is omitted, 2\&. the first letter of source package name, except if the source package name starts with \*(Aqlib\*(Aq in which case it will be the first four letters\&. 3\&. The complete source package name\&. 4\&. the complete name again and 5\&. the source version\&. The first (if present), second, third and fourth part are separated by a slash (\*(Aq/\*(Aq) and between the fourth and fifth part is an underscore (\*(Aq_\*(Aq)\&. The special value \*(Aqno\*(Aq is available for this option indicating that this source can\*(Aqt be used to acquire changelog files from\&. Another source will be tried if available in this case\&. +.RE +.SH "BINARY SPECIFIC CONFIGURATION" +.PP +Especially with the introduction of the +\fBapt\fR +binary it can be useful to set certain options only for a specific binary as even options which look like they would effect only a certain binary like +\fBAPT::Get::Show\-Versions\fR +effect +\fBapt\-get\fR +as well as +\fBapt\fR\&. +.PP +Setting an option for a specific binary only can be achieved by setting the option inside the +\fBBinary::\fR\fB\fIspecific\-binary\fR\fR +scope\&. Setting the option +\fBAPT::Get::Show\-Versions\fR +for the +\fBapt\fR +only can e\&.g\&. by done by setting +\fBBinary::apt::APT::Get::Show\-Versions\fR +instead\&. +.PP +Note that as seen in the DESCRIPTION section further above you can\*(Aqt set binary\-specific options on the commandline itself nor in configuration files loaded via the commandline\&. +.SH "DIRECTORIES" +.PP +The +Dir::State +section has directories that pertain to local state information\&. +lists +is the directory to place downloaded package lists in and +status +is the name of the +\fBdpkg\fR(1) +status file\&. +preferences +is the name of the APT +preferences +file\&. +Dir::State +contains the default directory to prefix on all sub\-items if they do not start with +/ +or +\&./\&. +.PP +Dir::Cache +contains locations pertaining to local cache information, such as the two package caches +srcpkgcache +and +pkgcache +as well as the location to place downloaded archives, +Dir::Cache::archives\&. Generation of caches can be turned off by setting +pkgcache +or +srcpkgcache +to +""\&. This will slow down startup but save disk space\&. It is probably preferable to turn off the pkgcache rather than the srcpkgcache\&. Like +Dir::State +the default directory is contained in +Dir::Cache +.PP +Dir::Etc +contains the location of configuration files, +sourcelist +gives the location of the sourcelist and +main +is the default configuration file (setting has no effect, unless it is done from the config file specified by +\fBAPT_CONFIG\fR)\&. +.PP +The +Dir::Parts +setting reads in all the config fragments in lexical order from the directory specified\&. After this is done then the main config file is loaded\&. +.PP +Binary programs are pointed to by +Dir::Bin\&. +Dir::Bin::Methods +specifies the location of the method handlers and +gzip, +bzip2, +lzma, +dpkg, +apt\-get +dpkg\-source +dpkg\-buildpackage +and +apt\-cache +specify the location of the respective programs\&. +.PP +The configuration item +RootDir +has a special meaning\&. If set, all paths will be relative to +RootDir, +\fIeven paths that are specified absolutely\fR\&. So, for instance, if +RootDir +is set to +/tmp/staging +and +Dir::State::status +is set to +/var/lib/dpkg/status, then the status file will be looked up in +/tmp/staging/var/lib/dpkg/status\&. If you want to prefix only relative paths, set +Dir +instead\&. +.PP +The +Ignore\-Files\-Silently +list can be used to specify which files APT should silently ignore while parsing the files in the fragment directories\&. Per default a file which end with +\&.disabled, +~, +\&.bak +or +\&.dpkg\-[a\-z]+ +is silently ignored\&. As seen in the last default value these patterns can use regular expression syntax\&. +.SH "APT IN DSELECT" +.PP +When APT is used as a +\fBdselect\fR(1) +method several configuration directives control the default behavior\&. These are in the +DSelect +section\&. +.PP +\fBClean\fR +.RS 4 +Cache Clean mode; this value may be one of +always, +prompt, +auto, +pre\-auto +and +never\&. +always +and +prompt +will remove all packages from the cache after upgrading, +prompt +(the default) does so conditionally\&. +auto +removes only those packages which are no longer downloadable (replaced with a new version for instance)\&. +pre\-auto +performs this action before downloading new packages\&. +.RE +.PP +\fBoptions\fR +.RS 4 +The contents of this variable are passed to +\fBapt-get\fR(8) +as command line options when it is run for the install phase\&. +.RE +.PP +\fBUpdateoptions\fR +.RS 4 +The contents of this variable are passed to +\fBapt-get\fR(8) +as command line options when it is run for the update phase\&. +.RE +.PP +\fBPromptAfterUpdate\fR +.RS 4 +If true the [U]pdate operation in +\fBdselect\fR(1) +will always prompt to continue\&. The default is to prompt only on error\&. +.RE +.SH "HOW APT CALLS DPKG(1)" +.PP +Several configuration directives control how APT invokes +\fBdpkg\fR(1)\&. These are in the +DPkg +section\&. +.PP +\fBoptions\fR +.RS 4 +This is a list of options to pass to +\fBdpkg\fR(1)\&. The options must be specified using the list notation and each list item is passed as a single argument to +\fBdpkg\fR(1)\&. +.RE +.PP +\fBPre\-Invoke\fR, \fBPost\-Invoke\fR +.RS 4 +This is a list of shell commands to run before/after invoking +\fBdpkg\fR(1)\&. Like +options +this must be specified in list notation\&. The commands are invoked in order using +/bin/sh; should any fail APT will abort\&. +.RE +.PP +\fBPre\-Install\-Pkgs\fR +.RS 4 +This is a list of shell commands to run before invoking +\fBdpkg\fR(1)\&. Like +options +this must be specified in list notation\&. The commands are invoked in order using +/bin/sh; should any fail APT will abort\&. APT will pass the filenames of all \&.deb files it is going to install to the commands, one per line on the requested file descriptor, defaulting to standard input\&. +.sp +Version 2 of this protocol sends more information through the requested file descriptor: a line with the text +VERSION 2, the APT configuration space, and a list of package actions with filename and version information\&. +.sp +Each configuration directive line has the form +key=value\&. Special characters (equal signs, newlines, nonprintable characters, quotation marks, and percent signs in +key +and newlines, nonprintable characters, and percent signs in +value) are %\-encoded\&. Lists are represented by multiple +key::=value +lines with the same key\&. The configuration section ends with a blank line\&. +.sp +Package action lines consist of five fields in Version 2: package name (without architecture qualification even if foreign), old version, direction of version change (< for upgrades, > for downgrades, = for no change), new version, action\&. The version fields are "\-" for no version at all (for example when installing a package for the first time; no version is treated as earlier than any real version, so that is an upgrade, indicated as +\- < 1\&.23\&.4)\&. The action field is "**CONFIGURE**" if the package is being configured, "**REMOVE**" if it is being removed, or the filename of a \&.deb file if it is being unpacked\&. +.sp +In Version 3 after each version field follows the architecture of this version, which is "\-" if there is no version, and a field showing the MultiArch type "same", "foreign", "allowed" or "none"\&. Note that "none" is an incorrect typename which is just kept to remain compatible, it should be read as "no" and users are encouraged to support both\&. +.sp +The version of the protocol to be used for the command +\fIcmd\fR +can be chosen by setting +DPkg::Tools::options::\fIcmd\fR::Version +accordingly, the default being version 1\&. If APT isn\*(Aqt supporting the requested version it will send the information in the highest version it has support for instead\&. +.sp +The file descriptor to be used to send the information can be requested with +DPkg::Tools::options::\fIcmd\fR::InfoFD +which defaults to +0 +for standard input and is available since version 0\&.9\&.11\&. Support for the option can be detected by looking for the environment variable +\fBAPT_HOOK_INFO_FD\fR +which contains the number of the used file descriptor as a confirmation\&. +.RE +.PP +\fBRun\-Directory\fR +.RS 4 +APT chdirs to this directory before invoking +\fBdpkg\fR(1), the default is +/\&. +.RE +.PP +\fBBuild\-options\fR +.RS 4 +These options are passed to +\fBdpkg-buildpackage\fR(1) +when compiling packages; the default is to disable signing and produce all binaries\&. +.RE +.PP +\fBDPkg::ConfigurePending\fR +.RS 4 +If this option is set APT will call +\fBdpkg \-\-configure \-\-pending\fR +to let +\fBdpkg\fR(1) +handle all required configurations and triggers\&. This option is activated by default, but deactivating it could be useful if you want to run APT multiple times in a row \- e\&.g\&. in an installer\&. In this scenario you could deactivate this option in all but the last run\&. +.RE +.SH "PERIODIC AND ARCHIVES OPTIONS" +.PP +APT::Periodic +and +APT::Archives +groups of options configure behavior of apt periodic updates, which is done by the +/usr/lib/apt/apt\&.systemd\&.daily +script\&. See the top of this script for the brief documentation of these options\&. +.SH "DEBUG OPTIONS" +.PP +Enabling options in the +Debug:: +section will cause debugging information to be sent to the standard error stream of the program utilizing the +apt +libraries, or enable special program modes that are primarily useful for debugging the behavior of +apt\&. Most of these options are not interesting to a normal user, but a few may be: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Debug::pkgProblemResolver +enables output about the decisions made by +dist\-upgrade, upgrade, install, remove, purge\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Debug::NoLocking +disables all file locking\&. This can be used to run some operations (for instance, +apt\-get \-s install) as a non\-root user\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Debug::pkgDPkgPM +prints out the actual command line each time that +apt +invokes +\fBdpkg\fR(1)\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Debug::IdentCdrom +disables the inclusion of statfs data in CD\-ROM IDs\&. +.RE +.PP +A full list of debugging options to apt follows\&. +.PP +\fBDebug::Acquire::cdrom\fR +.RS 4 +Print information related to accessing +cdrom:// +sources\&. +.RE +.PP +\fBDebug::Acquire::ftp\fR +.RS 4 +Print information related to downloading packages using FTP\&. +.RE +.PP +\fBDebug::Acquire::http\fR +.RS 4 +Print information related to downloading packages using HTTP\&. +.RE +.PP +\fBDebug::Acquire::https\fR +.RS 4 +Print information related to downloading packages using HTTPS\&. +.RE +.PP +\fBDebug::Acquire::gpgv\fR +.RS 4 +Print information related to verifying cryptographic signatures using +gpg\&. +.RE +.PP +\fBDebug::aptcdrom\fR +.RS 4 +Output information about the process of accessing collections of packages stored on CD\-ROMs\&. +.RE +.PP +\fBDebug::BuildDeps\fR +.RS 4 +Describes the process of resolving build\-dependencies in +\fBapt-get\fR(8)\&. +.RE +.PP +\fBDebug::Hashes\fR +.RS 4 +Output each cryptographic hash that is generated by the +apt +libraries\&. +.RE +.PP +\fBDebug::IdentCDROM\fR +.RS 4 +Do not include information from +statfs, namely the number of used and free blocks on the CD\-ROM filesystem, when generating an ID for a CD\-ROM\&. +.RE +.PP +\fBDebug::NoLocking\fR +.RS 4 +Disable all file locking\&. For instance, this will allow two instances of +\(lqapt\-get update\(rq +to run at the same time\&. +.RE +.PP +\fBDebug::pkgAcquire\fR +.RS 4 +Log when items are added to or removed from the global download queue\&. +.RE +.PP +\fBDebug::pkgAcquire::Auth\fR +.RS 4 +Output status messages and errors related to verifying checksums and cryptographic signatures of downloaded files\&. +.RE +.PP +\fBDebug::pkgAcquire::Diffs\fR +.RS 4 +Output information about downloading and applying package index list diffs, and errors relating to package index list diffs\&. +.RE +.PP +\fBDebug::pkgAcquire::RRed\fR +.RS 4 +Output information related to patching apt package lists when downloading index diffs instead of full indices\&. +.RE +.PP +\fBDebug::pkgAcquire::Worker\fR +.RS 4 +Log all interactions with the sub\-processes that actually perform downloads\&. +.RE +.PP +\fBDebug::pkgAutoRemove\fR +.RS 4 +Log events related to the automatically\-installed status of packages and to the removal of unused packages\&. +.RE +.PP +\fBDebug::pkgDepCache::AutoInstall\fR +.RS 4 +Generate debug messages describing which packages are being automatically installed to resolve dependencies\&. This corresponds to the initial auto\-install pass performed in, e\&.g\&., +apt\-get install, and not to the full +apt +dependency resolver; see +Debug::pkgProblemResolver +for that\&. +.RE +.PP +\fBDebug::pkgDepCache::Marker\fR +.RS 4 +Generate debug messages describing which packages are marked as keep/install/remove while the ProblemResolver does his work\&. Each addition or deletion may trigger additional actions; they are shown indented two additional spaces under the original entry\&. The format for each line is +MarkKeep, +MarkDelete +or +MarkInstall +followed by +package\-name d\&.e\&.f | x\&.y\&.z> (section) +where +a\&.b\&.c +is the current version of the package, +d\&.e\&.f +is the version considered for installation and +x\&.y\&.z +is a newer version, but not considered for installation (because of a low pin score)\&. The later two can be omitted if there is none or if it is the same as the installed version\&. +section +is the name of the section the package appears in\&. +.RE +.PP +\fBDebug::pkgDPkgPM\fR +.RS 4 +When invoking +\fBdpkg\fR(1), output the precise command line with which it is being invoked, with arguments separated by a single space character\&. +.RE +.PP +\fBDebug::pkgDPkgProgressReporting\fR +.RS 4 +Output all the data received from +\fBdpkg\fR(1) +on the status file descriptor and any errors encountered while parsing it\&. +.RE +.PP +\fBDebug::pkgOrderList\fR +.RS 4 +Generate a trace of the algorithm that decides the order in which +apt +should pass packages to +\fBdpkg\fR(1)\&. +.RE +.PP +\fBDebug::pkgPackageManager\fR +.RS 4 +Output status messages tracing the steps performed when invoking +\fBdpkg\fR(1)\&. +.RE +.PP +\fBDebug::pkgPolicy\fR +.RS 4 +Output the priority of each package list on startup\&. +.RE +.PP +\fBDebug::pkgProblemResolver\fR +.RS 4 +Trace the execution of the dependency resolver (this applies only to what happens when a complex dependency problem is encountered)\&. +.RE +.PP +\fBDebug::pkgProblemResolver::ShowScores\fR +.RS 4 +Display a list of all installed packages with their calculated score used by the pkgProblemResolver\&. The description of the package is the same as described in +Debug::pkgDepCache::Marker +.RE +.PP +\fBDebug::sourceList\fR +.RS 4 +Print information about the vendors read from +/etc/apt/vendors\&.list\&. +.RE +.PP +\fBDebug::RunScripts\fR +.RS 4 +Display the external commands that are called by apt hooks\&. This includes e\&.g\&. the config options +DPkg::{Pre,Post}\-Invoke +or +APT::Update::{Pre,Post}\-Invoke\&. +.RE +.SH "EXAMPLES" +.PP +/usr/share/doc/apt/examples/configure\-index\&.gz +is a configuration file showing example values for all possible options\&. +.SH "FILES" +.PP +/etc/apt/apt\&.conf +.RS 4 +APT configuration file\&. Configuration Item: +Dir::Etc::Main\&. +.RE +.PP +/etc/apt/apt\&.conf\&.d/ +.RS 4 +APT configuration file fragments\&. Configuration Item: +Dir::Etc::Parts\&. +.RE +.SH "SEE ALSO" +.PP +\fBapt-cache\fR(8), +\fBapt-config\fR(8), +\fBapt_preferences\fR(5)\&. +.SH "BUGS" +.PP +\m[blue]\fBAPT bug page\fR\m[]\&\s-2\u[1]\d\s+2\&. If you wish to report a bug in APT, please see +/usr/share/doc/debian/bug\-reporting\&.txt +or the +\fBreportbug\fR(1) +command\&. +.SH "AUTHORS" +.PP +\fBJason Gunthorpe\fR +.RS 4 +.RE +.PP +\fBAPT team\fR +.RS 4 +.RE +.PP +\fBDaniel Burrows\fR <\&dburrows@debian\&.org\&> +.RS 4 +Initial documentation of Debug::*\&. +.RE +.SH "NOTES" +.IP " 1." 4 +APT bug page +.RS 4 +\%http://bugs.debian.org/src:apt +.RE diff --git a/packages/apt/man/man5/apt_preferences.5 b/packages/apt/man/man5/apt_preferences.5 new file mode 100644 index 000000000..7b18330fc --- /dev/null +++ b/packages/apt/man/man5/apt_preferences.5 @@ -0,0 +1,889 @@ +'\" t +.\" Title: apt_preferences +.\" Author: APT team +.\" Generator: DocBook XSL Stylesheets v1.79.1 +.\" Date: 15\ \&August\ \&2015 +.\" Manual: APT +.\" Source: APT 1.4.9 +.\" Language: English +.\" +.TH "APT_PREFERENCES" "5" "15\ \&August\ \&2015" "APT 1.4.9" "APT" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +apt_preferences \- Preference control file for APT +.SH "DESCRIPTION" +.PP +The APT preferences file +/etc/apt/preferences +and the fragment files in the +/etc/apt/preferences\&.d/ +folder can be used to control which versions of packages will be selected for installation\&. +.PP +Several versions of a package may be available for installation when the +\fBsources.list\fR(5) +file contains references to more than one distribution (for example, +stable +and +testing)\&. APT assigns a priority to each version that is available\&. Subject to dependency constraints, +\fBapt\-get\fR +selects the version with the highest priority for installation\&. The APT preferences override the priorities that APT assigns to package versions by default, thus giving the user control over which one is selected for installation\&. +.PP +Several instances of the same version of a package may be available when the +\fBsources.list\fR(5) +file contains references to more than one source\&. In this case +\fBapt\-get\fR +downloads the instance listed earliest in the +\fBsources.list\fR(5) +file\&. The APT preferences do not affect the choice of instance, only the choice of version\&. +.PP +Preferences are a strong power in the hands of a system administrator but they can become also their biggest nightmare if used without care! APT will not question the preferences, so wrong settings can lead to uninstallable packages or wrong decisions while upgrading packages\&. Even more problems will arise if multiple distribution releases are mixed without a good understanding of the following paragraphs\&. Packages included in a specific release aren\*(Aqt tested in (and therefore don\*(Aqt always work as expected in) older or newer releases, or together with other packages from different releases\&. You have been warned\&. +.PP +Note that the files in the +/etc/apt/preferences\&.d +directory are parsed in alphanumeric ascending order and need to obey the following naming convention: The files have either no or "pref" as filename extension and only contain alphanumeric, hyphen (\-), underscore (_) and period (\&.) characters\&. Otherwise APT will print a notice that it has ignored a file, unless that file matches a pattern in the +Dir::Ignore\-Files\-Silently +configuration list \- in which case it will be silently ignored\&. +.SS "APT\*(Aqs Default Priority Assignments" +.PP +If there is no preferences file or if there is no entry in the file that applies to a particular version then the priority assigned to that version is the priority of the distribution to which that version belongs\&. It is possible to single out a distribution, "the target release", which receives a higher priority than other distributions do by default\&. The target release can be set on the +\fBapt\-get\fR +command line or in the APT configuration file +/etc/apt/apt\&.conf\&. Note that this has precedence over any general priority you set in the +/etc/apt/preferences +file described later, but not over specifically pinned packages\&. For example, +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBapt\-get install \-t testing \fR\fB\fIsome\-package\fR\fR +.fi +.if n \{\ +.RE +.\} +.sp + +.sp +.if n \{\ +.RS 4 +.\} +.nf +APT::Default\-Release "stable"; +.fi +.if n \{\ +.RE +.\} +.PP +If the target release has been specified then APT uses the following algorithm to set the priorities of the versions of a package\&. Assign: +.PP +priority 1 +.RS 4 +to the versions coming from archives which in their +Release +files are marked as "NotAutomatic: yes" but +\fInot\fR +as "ButAutomaticUpgrades: yes" like the Debian +experimental +archive\&. +.RE +.PP +priority 100 +.RS 4 +to the version that is already installed (if any) and to the versions coming from archives which in their +Release +files are marked as "NotAutomatic: yes" and "ButAutomaticUpgrades: yes" like the Debian backports archive since +squeeze\-backports\&. +.RE +.PP +priority 500 +.RS 4 +to the versions that do not belong to the target release\&. +.RE +.PP +priority 990 +.RS 4 +to the versions that belong to the target release\&. +.RE +The highest of those priorities whose description matches the version is assigned to the version\&. +.PP +If the target release has not been specified then APT simply assigns priority 100 to all installed package versions and priority 500 to all uninstalled package versions, except versions coming from archives which in their +Release +files are marked as "NotAutomatic: yes" \- these versions get the priority 1 or priority 100 if it is additionally marked as "ButAutomaticUpgrades: yes"\&. +.PP +APT then applies the following rules, listed in order of precedence, to determine which version of a package to install\&. +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Never downgrade unless the priority of an available version exceeds 1000\&. ("Downgrading" is installing a less recent version of a package in place of a more recent version\&. Note that none of APT\*(Aqs default priorities exceeds 1000; such high priorities can only be set in the preferences file\&. Note also that downgrading a package can be risky\&.) +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Install the highest priority version\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +If two or more versions have the same priority, install the most recent one (that is, the one with the higher version number)\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +If two or more versions have the same priority and version number but either the packages differ in some of their metadata or the +\-\-reinstall +option is given, install the uninstalled one\&. +.RE +.PP +In a typical situation, the installed version of a package (priority 100) is not as recent as one of the versions available from the sources listed in the +\fBsources.list\fR(5) +file (priority 500 or 990)\&. Then the package will be upgraded when +\fBapt\-get install \fR\fB\fIsome\-package\fR\fR +or +\fBapt\-get upgrade\fR +is executed\&. +.PP +More rarely, the installed version of a package is +\fImore\fR +recent than any of the other available versions\&. The package will not be downgraded when +\fBapt\-get install \fR\fB\fIsome\-package\fR\fR +or +\fBapt\-get upgrade\fR +is executed\&. +.PP +Sometimes the installed version of a package is more recent than the version belonging to the target release, but not as recent as a version belonging to some other distribution\&. Such a package will indeed be upgraded when +\fBapt\-get install \fR\fB\fIsome\-package\fR\fR +or +\fBapt\-get upgrade\fR +is executed, because at least +\fIone\fR +of the available versions has a higher priority than the installed version\&. +.SS "The Effect of APT Preferences" +.PP +The APT preferences file allows the system administrator to control the assignment of priorities\&. The file consists of one or more multi\-line records separated by blank lines\&. Records can have one of two forms, a specific form and a general form\&. +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +The specific form assigns a priority (a "Pin\-Priority") to one or more specified packages with a specified version or version range\&. For example, the following record assigns a high priority to all versions of the +perl +package whose version number begins with "5\&.20"\&. Multiple packages can be separated by spaces\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +Package: perl +Pin: version 5\&.20* +Pin\-Priority: 1001 +.fi +.if n \{\ +.RE +.\} +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +The general form assigns a priority to all of the package versions in a given distribution (that is, to all the versions of packages that are listed in a certain +Release +file) or to all of the package versions coming from a particular Internet site, as identified by the site\*(Aqs fully qualified domain name\&. +.sp +This general\-form entry in the APT preferences file applies only to groups of packages\&. For example, the following record assigns a high priority to all package versions available from the local site\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +Package: * +Pin: origin "" +Pin\-Priority: 999 +.fi +.if n \{\ +.RE +.\} +.sp +A note of caution: the keyword used here is "origin" which can be used to match a hostname\&. The following record will assign a high priority to all versions available from the server identified by the hostname "ftp\&.de\&.debian\&.org" +.sp +.if n \{\ +.RS 4 +.\} +.nf +Package: * +Pin: origin "ftp\&.de\&.debian\&.org" +Pin\-Priority: 999 +.fi +.if n \{\ +.RE +.\} +.sp +This should +\fInot\fR +be confused with the Origin of a distribution as specified in a +Release +file\&. What follows the "Origin:" tag in a +Release +file is not an Internet address but an author or vendor name, such as "Debian" or "Ximian"\&. +.sp +The following record assigns a low priority to all package versions belonging to any distribution whose Archive name is "unstable"\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +Package: * +Pin: release a=unstable +Pin\-Priority: 50 +.fi +.if n \{\ +.RE +.\} +.sp +The following record assigns a high priority to all package versions belonging to any distribution whose Codename is "buster"\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +Package: * +Pin: release n=buster +Pin\-Priority: 900 +.fi +.if n \{\ +.RE +.\} +.sp +The following record assigns a high priority to all package versions belonging to any release whose Archive name is "stable" and whose release Version number is "9"\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +Package: * +Pin: release a=stable, v=9 +Pin\-Priority: 500 +.fi +.if n \{\ +.RE +.\} +.RE +.sp +The effect of the comma operator is similar to an "and" in logic: All conditions must be satisfied for the pin to match\&. There is one exception: For any type of condition (such as two "a" conditions), only the last such condition is checked\&. +.SS "Regular expressions and glob(7) syntax" +.PP +APT also supports pinning by +\fBglob\fR(7) +expressions, and regular expressions surrounded by slashes\&. For example, the following example assigns the priority 500 to all packages from experimental where the name starts with gnome (as a +\fBglob\fR(7)\-like expression) or contains the word kde (as a POSIX extended regular expression surrounded by slashes)\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +Package: gnome* /kde/ +Pin: release a=experimental +Pin\-Priority: 500 +.fi +.if n \{\ +.RE +.\} +.PP +The rule for those expressions is that they can occur anywhere where a string can occur\&. Thus, the following pin assigns the priority 990 to all packages from a release starting with xenial\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +Package: * +Pin: release n=xenial* +Pin\-Priority: 990 +.fi +.if n \{\ +.RE +.\} +.PP +If a regular expression occurs in a +Package +field, the behavior is the same as if this regular expression were replaced with a list of all package names it matches\&. It is undecided whether this will change in the future; thus you should always list wild\-card pins first, so later specific pins override it\&. The pattern "*" in a Package field is not considered a +\fBglob\fR(7) +expression in itself\&. +.SS "How APT Interprets Priorities" +.PP +Priorities (P) assigned in the APT preferences file must be positive or negative integers\&. They are interpreted as follows (roughly speaking): +.PP +P >= 1000 +.RS 4 +causes a version to be installed even if this constitutes a downgrade of the package +.RE +.PP +990 <= P < 1000 +.RS 4 +causes a version to be installed even if it does not come from the target release, unless the installed version is more recent +.RE +.PP +500 <= P < 990 +.RS 4 +causes a version to be installed unless there is a version available belonging to the target release or the installed version is more recent +.RE +.PP +100 <= P < 500 +.RS 4 +causes a version to be installed unless there is a version available belonging to some other distribution or the installed version is more recent +.RE +.PP +0 < P < 100 +.RS 4 +causes a version to be installed only if there is no installed version of the package +.RE +.PP +P < 0 +.RS 4 +prevents the version from being installed +.RE +.PP +P = 0 +.RS 4 +has undefined behaviour, do not use it\&. +.RE +.PP +The first specific\-form record matching an available package version determines the priority of the package version\&. Failing that, the priority of the package is defined as the maximum of all priorities defined by generic\-form records matching the version\&. Records defined using patterns in the Pin field other than "*" are treated like specific\-form records\&. +.PP +For example, suppose the APT preferences file contains the three records presented earlier: +.sp +.if n \{\ +.RS 4 +.\} +.nf +Package: perl +Pin: version 5\&.20* +Pin\-Priority: 1001 + +Package: * +Pin: origin "" +Pin\-Priority: 999 + +Package: * +Pin: release unstable +Pin\-Priority: 50 +.fi +.if n \{\ +.RE +.\} +.PP +Then: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +The most recent available version of the +perl +package will be installed, so long as that version\*(Aqs version number begins with "5\&.20"\&. If +\fIany\fR +5\&.20* version of +perl +is available and the installed version is 5\&.24*, then +perl +will be downgraded\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +A version of any package other than +perl +that is available from the local system has priority over other versions, even versions belonging to the target release\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +A version of a package whose origin is not the local system but some other site listed in +\fBsources.list\fR(5) +and which belongs to an +unstable +distribution is only installed if it is selected for installation and no version of the package is already installed\&. +.RE +.sp +.SS "Determination of Package Version and Distribution Properties" +.PP +The locations listed in the +\fBsources.list\fR(5) +file should provide +Packages +and +Release +files to describe the packages available at that location\&. +.PP +The +Packages +file is normally found in the directory +\&.\&.\&./dists/\fIdist\-name\fR/\fIcomponent\fR/\fIarch\fR: for example, +\&.\&.\&./dists/stable/main/binary\-i386/Packages\&. It consists of a series of multi\-line records, one for each package available in that directory\&. Only two lines in each record are relevant for setting APT priorities: +.PP +the Package: line +.RS 4 +gives the package name +.RE +.PP +the Version: line +.RS 4 +gives the version number for the named package +.RE +.PP +The +Release +file is normally found in the directory +\&.\&.\&./dists/\fIdist\-name\fR: for example, +\&.\&.\&./dists/stable/Release, or +\&.\&.\&./dists/stretch/Release\&. It consists of a single multi\-line record which applies to +\fIall\fR +of the packages in the directory tree below its parent\&. Unlike the +Packages +file, nearly all of the lines in a +Release +file are relevant for setting APT priorities: +.PP +the Archive: or Suite: line +.RS 4 +names the archive to which all the packages in the directory tree belong\&. For example, the line "Archive: stable" or "Suite: stable" specifies that all of the packages in the directory tree below the parent of the +Release +file are in a +stable +archive\&. Specifying this value in the APT preferences file would require the line: +.sp +.if n \{\ +.RS 4 +.\} +.nf +Pin: release a=stable +.fi +.if n \{\ +.RE +.\} +.RE +.PP +the Codename: line +.RS 4 +names the codename to which all the packages in the directory tree belong\&. For example, the line "Codename: buster" specifies that all of the packages in the directory tree below the parent of the +Release +file belong to a version named +buster\&. Specifying this value in the APT preferences file would require the line: +.sp +.if n \{\ +.RS 4 +.\} +.nf +Pin: release n=buster +.fi +.if n \{\ +.RE +.\} +.RE +.PP +the Version: line +.RS 4 +names the release version\&. For example, the packages in the tree might belong to Debian release version 9\&. Note that there is normally no version number for the +testing +and +unstable +distributions because they have not been released yet\&. Specifying this in the APT preferences file would require one of the following lines\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +Pin: release v=9 +Pin: release a=stable, v=9 +Pin: release 9 +.fi +.if n \{\ +.RE +.\} +.RE +.PP +the Component: line +.RS 4 +names the licensing component associated with the packages in the directory tree of the +Release +file\&. For example, the line "Component: main" specifies that all the packages in the directory tree are from the +main +component, which entails that they are licensed under terms listed in the Debian Free Software Guidelines\&. Specifying this component in the APT preferences file would require the line: +.sp +.if n \{\ +.RS 4 +.\} +.nf +Pin: release c=main +.fi +.if n \{\ +.RE +.\} +.RE +.PP +the Origin: line +.RS 4 +names the originator of the packages in the directory tree of the +Release +file\&. Most commonly, this is +Debian\&. Specifying this origin in the APT preferences file would require the line: +.sp +.if n \{\ +.RS 4 +.\} +.nf +Pin: release o=Debian +.fi +.if n \{\ +.RE +.\} +.RE +.PP +the Label: line +.RS 4 +names the label of the packages in the directory tree of the +Release +file\&. Most commonly, this is +Debian\&. Specifying this label in the APT preferences file would require the line: +.sp +.if n \{\ +.RS 4 +.\} +.nf +Pin: release l=Debian +.fi +.if n \{\ +.RE +.\} +.RE +.PP +All of the +Packages +and +Release +files retrieved from locations listed in the +\fBsources.list\fR(5) +file are stored in the directory +/var/lib/apt/lists, or in the file named by the variable +Dir::State::Lists +in the +apt\&.conf +file\&. For example, the file +debian\&.lcs\&.mit\&.edu_debian_dists_unstable_contrib_binary\-i386_Release +contains the +Release +file retrieved from the site +debian\&.lcs\&.mit\&.edu +for +binary\-i386 +architecture files from the +contrib +component of the +unstable +distribution\&. +.SS "Optional Lines in an APT Preferences Record" +.PP +Each record in the APT preferences file can optionally begin with one or more lines beginning with the word +Explanation:\&. This provides a place for comments\&. +.SH "EXAMPLES" +.SS "Tracking Stable" +.PP +The following APT preferences file will cause APT to assign a priority higher than the default (500) to all package versions belonging to a +stable +distribution and a prohibitively low priority to package versions belonging to other +Debian +distributions\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +Explanation: Uninstall or do not install any Debian\-originated +Explanation: package versions other than those in the stable distro +Package: * +Pin: release a=stable +Pin\-Priority: 900 + +Package: * +Pin: release o=Debian +Pin\-Priority: \-10 +.fi +.if n \{\ +.RE +.\} +.PP +With a suitable +\fBsources.list\fR(5) +file and the above preferences file, any of the following commands will cause APT to upgrade to the latest +stable +version(s)\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +apt\-get install \fIpackage\-name\fR +apt\-get upgrade +apt\-get dist\-upgrade +.fi +.if n \{\ +.RE +.\} +.PP +The following command will cause APT to upgrade the specified package to the latest version from the +testing +distribution; the package will not be upgraded again unless this command is given again\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +apt\-get install \fIpackage\fR/testing +.fi +.if n \{\ +.RE +.\} +.sp +.SS "Tracking Testing or Unstable" +.PP +The following APT preferences file will cause APT to assign a high priority to package versions from the +testing +distribution, a lower priority to package versions from the +unstable +distribution, and a prohibitively low priority to package versions from other +Debian +distributions\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +Package: * +Pin: release a=testing +Pin\-Priority: 900 + +Package: * +Pin: release a=unstable +Pin\-Priority: 800 + +Package: * +Pin: release o=Debian +Pin\-Priority: \-10 +.fi +.if n \{\ +.RE +.\} +.PP +With a suitable +\fBsources.list\fR(5) +file and the above preferences file, any of the following commands will cause APT to upgrade to the latest +testing +version(s)\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +apt\-get install \fIpackage\-name\fR +apt\-get upgrade +apt\-get dist\-upgrade +.fi +.if n \{\ +.RE +.\} +.PP +The following command will cause APT to upgrade the specified package to the latest version from the +unstable +distribution\&. Thereafter, +\fBapt\-get upgrade\fR +will upgrade the package to the most recent +testing +version if that is more recent than the installed version, otherwise, to the most recent +unstable +version if that is more recent than the installed version\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +apt\-get install \fIpackage\fR/unstable +.fi +.if n \{\ +.RE +.\} +.sp +.SS "Tracking the evolution of a codename release" +.PP +The following APT preferences file will cause APT to assign a priority higher than the default (500) to all package versions belonging to a specified codename of a distribution and a prohibitively low priority to package versions belonging to other +Debian +distributions, codenames and archives\&. Note that with this APT preference APT will follow the migration of a release from the archive +testing +to +stable +and later +oldstable\&. If you want to follow for example the progress in +testing +notwithstanding the codename changes you should use the example configurations above\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +Explanation: Uninstall or do not install any Debian\-originated package versions +Explanation: other than those in the distribution codenamed with buster or sid +Package: * +Pin: release n=buster +Pin\-Priority: 900 + +Explanation: Debian unstable is always codenamed with sid +Package: * +Pin: release n=sid +Pin\-Priority: 800 + +Package: * +Pin: release o=Debian +Pin\-Priority: \-10 +.fi +.if n \{\ +.RE +.\} +.PP +With a suitable +\fBsources.list\fR(5) +file and the above preferences file, any of the following commands will cause APT to upgrade to the latest version(s) in the release codenamed with +buster\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +apt\-get install \fIpackage\-name\fR +apt\-get upgrade +apt\-get dist\-upgrade +.fi +.if n \{\ +.RE +.\} +.PP +The following command will cause APT to upgrade the specified package to the latest version from the +sid +distribution\&. Thereafter, +\fBapt\-get upgrade\fR +will upgrade the package to the most recent +buster +version if that is more recent than the installed version, otherwise, to the most recent +sid +version if that is more recent than the installed version\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +apt\-get install \fIpackage\fR/sid +.fi +.if n \{\ +.RE +.\} +.sp +.SH "FILES" +.PP +/etc/apt/preferences +.RS 4 +Version preferences file\&. This is where you would specify "pinning", i\&.e\&. a preference to get certain packages from a separate source or from a different version of a distribution\&. Configuration Item: +Dir::Etc::Preferences\&. +.RE +.PP +/etc/apt/preferences\&.d/ +.RS 4 +File fragments for the version preferences\&. Configuration Item: +Dir::Etc::PreferencesParts\&. +.RE +.SH "SEE ALSO" +.PP +\fBapt-get\fR(8) +\fBapt-cache\fR(8) +\fBapt.conf\fR(5) +\fBsources.list\fR(5) +.SH "BUGS" +.PP +\m[blue]\fBAPT bug page\fR\m[]\&\s-2\u[1]\d\s+2\&. If you wish to report a bug in APT, please see +/usr/share/doc/debian/bug\-reporting\&.txt +or the +\fBreportbug\fR(1) +command\&. +.SH "AUTHOR" +.PP +\fBAPT team\fR +.RS 4 +.RE +.SH "NOTES" +.IP " 1." 4 +APT bug page +.RS 4 +\%http://bugs.debian.org/src:apt +.RE diff --git a/packages/apt/man/man5/sources.list.5 b/packages/apt/man/man5/sources.list.5 new file mode 100644 index 000000000..41d03c204 --- /dev/null +++ b/packages/apt/man/man5/sources.list.5 @@ -0,0 +1,730 @@ +'\" t +.\" Title: sources.list +.\" Author: Jason Gunthorpe +.\" Generator: DocBook XSL Stylesheets v1.79.1 +.\" Date: 25\ \&November\ \&2016 +.\" Manual: APT +.\" Source: APT 1.4.9 +.\" Language: English +.\" +.TH "SOURCES\&.LIST" "5" "25\ \&November\ \&2016" "APT 1.4.9" "APT" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +sources.list \- List of configured APT data sources +.SH "DESCRIPTION" +.PP +The source list +/etc/apt/sources\&.list +and the files contained in +/etc/apt/sources\&.list\&.d/ +are designed to support any number of active sources and a variety of source media\&. The files list one source per line (one\-line style) or contain multiline stanzas defining one or more sources per stanza (deb822 style), with the most preferred source listed first (in case a single version is available from more than one source)\&. The information available from the configured sources is acquired by +\fBapt\-get update\fR +(or by an equivalent command from another APT front\-end)\&. +.SH "SOURCES\&.LIST\&.D" +.PP +The +/etc/apt/sources\&.list\&.d +directory provides a way to add sources\&.list entries in separate files\&. Two different file formats are allowed as described in the next two sections\&. Filenames need to have either the extension +\&.list +or +\&.sources +depending on the contained format\&. The filenames may only contain letters (a\-z and A\-Z), digits (0\-9), underscore (_), hyphen (\-) and period (\&.) characters\&. Otherwise APT will print a notice that it has ignored a file, unless that file matches a pattern in the +Dir::Ignore\-Files\-Silently +configuration list \- in which case it will be silently ignored\&. +.SH "ONE\-LINE\-STYLE FORMAT" +.PP +Files in this format have the extension +\&.list\&. Each line specifying a source starts with a type (e\&.g\&. +deb\-src) followed by options and arguments for this type\&. Individual entries cannot be continued onto a following line\&. Empty lines are ignored, and a +# +character anywhere on a line marks the remainder of that line as a comment\&. Consequently an entry can be disabled by commenting out the entire line\&. If options should be provided they are separated by spaces and all of them together are enclosed by square brackets ([]) included in the line after the type separated from it with a space\&. If an option allows multiple values these are separated from each other with a comma (,)\&. An option name is separated from its value(s) by an equals sign (=)\&. Multivalue options also have +\-= +and ++= +as separators, which instead of replacing the default with the given value(s) modify the default value(s) to remove or include the given values\&. +.PP +This is the traditional format and supported by all apt versions\&. Note that not all options as described below are supported by all apt versions\&. Note also that some older applications parsing this format on their own might not expect to encounter options as they were uncommon before the introduction of multi\-architecture support\&. +.SH "DEB822\-STYLE FORMAT" +.PP +Files in this format have the extension +\&.sources\&. The format is similar in syntax to other files used by Debian and its derivatives, such as the metadata files that apt will download from the configured sources or the +debian/control +file in a Debian source package\&. Individual entries are separated by an empty line; additional empty lines are ignored, and a +# +character at the start of the line marks the entire line as a comment\&. An entry can hence be disabled by commenting out each line belonging to the stanza, but it is usually easier to add the field "Enabled: no" to the stanza to disable the entry\&. Removing the field or setting it to yes reenables it\&. Options have the same syntax as every other field: A fieldname separated by a colon (:) and optionally spaces from its value(s)\&. Note especially that multiple values are separated by spaces, not by commas as in the one\-line format\&. Multivalue fields like +Architectures +also have +Architectures\-Add +and +Architectures\-Remove +to modify the default value rather than replacing it\&. +.PP +This is a new format supported by apt itself since version 1\&.1\&. Previous versions ignore such files with a notice message as described earlier\&. It is intended to make this format gradually the default format, deprecating the previously described one\-line\-style format, as it is easier to create, extend and modify for humans and machines alike especially if a lot of sources and/or options are involved\&. Developers who are working with and/or parsing apt sources are highly encouraged to add support for this format and to contact the APT team to coordinate and share this work\&. Users can freely adopt this format already, but may encounter problems with software not supporting the format yet\&. +.SH "THE DEB AND DEB\-SRC TYPES: GENERAL FORMAT" +.PP +The +deb +type references a typical two\-level Debian archive, +distribution/component\&. The +distribution +is generally a suite name like +stable +or +testing +or a codename like +stretch +or +buster +while component is one of +main, +contrib +or +non\-free\&. The +deb\-src +type references a Debian distribution\*(Aqs source code in the same form as the +deb +type\&. A +deb\-src +line is required to fetch source indexes\&. +.PP +The format for two one\-line\-style entries using the +deb +and +deb\-src +types is: +.sp +.if n \{\ +.RS 4 +.\} +.nf +deb [ option1=value1 option2=value2 ] uri suite [component1] [component2] [\&.\&.\&.] +deb\-src [ option1=value1 option2=value2 ] uri suite [component1] [component2] [\&.\&.\&.] +.fi +.if n \{\ +.RE +.\} +.PP +Alternatively the equivalent entry in deb822 style looks like this: +.sp +.if n \{\ +.RS 4 +.\} +.nf + Types: deb deb\-src + URIs: uri + Suites: suite + Components: [component1] [component2] [\&.\&.\&.] + option1: value1 + option2: value2 + +.fi +.if n \{\ +.RE +.\} +.PP +The URI for the +deb +type must specify the base of the Debian distribution, from which APT will find the information it needs\&. +suite +can specify an exact path, in which case the components must be omitted and +suite +must end with a slash (/)\&. This is useful for the case when only a particular sub\-directory of the archive denoted by the URI is of interest\&. If +suite +does not specify an exact path, at least one +component +must be present\&. +.PP +suite +may also contain a variable, +$(ARCH) +which expands to the Debian architecture (such as +amd64 +or +armel) used on the system\&. This permits architecture\-independent +sources\&.list +files to be used\&. In general this is only of interest when specifying an exact path; +APT +will automatically generate a URI with the current architecture otherwise\&. +.PP +Especially in the one\-line\-style format since only one distribution can be specified per line it may be necessary to have multiple lines for the same URI, if a subset of all available distributions or components at that location is desired\&. APT will sort the URI list after it has generated a complete set internally, and will collapse multiple references to the same Internet host, for instance, into a single connection, so that it does not inefficiently establish a connection, close it, do something else, and then re\-establish a connection to that same host\&. APT also parallelizes connections to different hosts to more effectively deal with sites with low bandwidth\&. +.PP +It is important to list sources in order of preference, with the most preferred source listed first\&. Typically this will result in sorting by speed from fastest to slowest (CD\-ROM followed by hosts on a local network, followed by distant Internet hosts, for example)\&. +.PP +As an example, the sources for your distribution could look like this in one\-line\-style format: +.sp +.if n \{\ +.RS 4 +.\} +.nf +deb http://deb\&.debian\&.org/debian stretch main contrib non\-free +deb http://security\&.debian\&.org stretch/updates main contrib non\-free +.fi +.if n \{\ +.RE +.\} +.sp +or like this in deb822 style format: +.sp +.if n \{\ +.RS 4 +.\} +.nf +Types: deb +URIs: http://deb\&.debian\&.org/debian +Suites: stretch +Components: main contrib non\-free + +Types: deb +URIs: http://security\&.debian\&.org +Suites: stretch/updates +Components: main contrib non\-free +.fi +.if n \{\ +.RE +.\} +.SH "THE DEB AND DEB\-SRC TYPES: OPTIONS" +.PP +Each source entry can have options specified to modify which source is accessed and how data is acquired from it\&. Format, syntax and names of the options vary between the one\-line\-style and deb822\-style formats as described, but they both have the same options available\&. For simplicity we list the deb822 fieldname and provide the one\-line name in brackets\&. Remember that besides setting multivalue options explicitly, there is also the option to modify them based on the default, but we aren\*(Aqt listing those names explicitly here\&. Unsupported options are silently ignored by all APT versions\&. +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBArchitectures\fR +(\fBarch\fR) is a multivalue option defining for which architectures information should be downloaded\&. If this option isn\*(Aqt set the default is all architectures as defined by the +\fBAPT::Architectures\fR +config option\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBLanguages\fR +(\fBlang\fR) is a multivalue option defining for which languages information such as translated package descriptions should be downloaded\&. If this option isn\*(Aqt set the default is all languages as defined by the +\fBAcquire::Languages\fR +config option\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBTargets\fR +(\fBtarget\fR) is a multivalue option defining which download targets apt will try to acquire from this source\&. If not specified, the default set is defined by the +\fBAcquire::IndexTargets\fR +configuration scope (targets are specified by their name in the +Created\-By +field)\&. Additionally, targets can be enabled or disabled by using the +Identifier +field as an option with a boolean value instead of using this multivalue option\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBPDiffs\fR +(\fBpdiffs\fR) is a yes/no value which controls if APT should try to use PDiffs to update old indexes instead of downloading the new indexes entirely\&. The value of this option is ignored if the repository doesn\*(Aqt announce the availability of PDiffs\&. Defaults to the value of the option with the same name for a specific index file defined in the +\fBAcquire::IndexTargets\fR +scope, which itself defaults to the value of configuration option +\fBAcquire::PDiffs\fR +which defaults to +yes\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBBy\-Hash\fR +(\fBby\-hash\fR) can have the value +yes, +no +or +force +and controls if APT should try to acquire indexes via a URI constructed from a hashsum of the expected file instead of using the well\-known stable filename of the index\&. Using this can avoid hashsum mismatches, but requires a supporting mirror\&. A +yes +or +no +value activates/disables the use of this feature if this source indicates support for it, while +force +will enable the feature regardless of what the source indicates\&. Defaults to the value of the option of the same name for a specific index file defined in the +\fBAcquire::IndexTargets\fR +scope, which itself defaults to the value of configuration option +\fBAcquire::By\-Hash\fR +which defaults to +yes\&. +.RE +.sp +Furthermore, there are options which if set affect +\fIall\fR +sources with the same URI and Suite, so they have to be set on all such entries and can not be varied between different components\&. APT will try to detect and error out on such anomalies\&. +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBAllow\-Insecure\fR +(\fBallow\-insecure\fR), +\fBAllow\-Weak\fR +(\fBallow\-weak\fR) and +\fBAllow\-Downgrade\-To\-Insecure\fR +(\fBallow\-downgrade\-to\-insecure\fR) are boolean values which all default to +no\&. If set to +yes +they circumvent parts of +\fBapt-secure\fR(8) +and should therefore not be used lightly! +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBTrusted\fR +(\fBtrusted\fR) is a tri\-state value which defaults to APT deciding if a source is considered trusted or if warnings should be raised before e\&.g\&. packages are installed from this source\&. This option can be used to override that decision\&. The value +yes +tells APT always to consider this source as trusted, even if it doesn\*(Aqt pass authentication checks\&. It disables parts of +\fBapt-secure\fR(8), and should therefore only be used in a local and trusted context (if at all) as otherwise security is breached\&. The value +no +does the opposite, causing the source to be handled as untrusted even if the authentication checks passed successfully\&. The default value can\*(Aqt be set explicitly\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBSigned\-By\fR +(\fBsigned\-by\fR) is either an absolute path to a keyring file (has to be accessible and readable for the +_apt +user, so ensure everyone has read\-permissions on the file) or one or more fingerprints of keys either in the +trusted\&.gpg +keyring or in the keyrings in the +trusted\&.gpg\&.d/ +directory (see +\fBapt\-key fingerprint\fR)\&. If the option is set, only the key(s) in this keyring or only the keys with these fingerprints are used for the +\fBapt-secure\fR(8) +verification of this repository\&. Defaults to the value of the option with the same name if set in the previously acquired +Release +file\&. Otherwise all keys in the trusted keyrings are considered valid signers for this repository\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBCheck\-Valid\-Until\fR +(\fBcheck\-valid\-until\fR) is a yes/no value which controls if APT should try to detect replay attacks\&. A repository creator can declare a time until which the data provided in the repository should be considered valid, and if this time is reached, but no new data is provided, the data is considered expired and an error is raised\&. Besides increasing security, as a malicious attacker can\*(Aqt send old data forever to prevent a user from upgrading to a new version, this also helps users identify mirrors which are no longer updated\&. However, some repositories such as historic archives are not updated any more by design, so this check can be disabled by setting this option to +no\&. Defaults to the value of configuration option +\fBAcquire::Check\-Valid\-Until\fR +which itself defaults to +yes\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fBValid\-Until\-Min\fR +(\fBvalid\-until\-min\fR) and +\fBValid\-Until\-Max\fR +(\fBvalid\-until\-max\fR) can be used to raise or lower the time period in seconds in which the data from this repository is considered valid\&. \-Max can be especially useful if the repository provides no Valid\-Until field on its Release file to set your own value, while \-Min can be used to increase the valid time on seldom updated (local) mirrors of a more frequently updated but less accessible archive (which is in the sources\&.list as well) instead of disabling the check entirely\&. Default to the value of the configuration options +\fBAcquire::Min\-ValidTime\fR +and +\fBAcquire::Max\-ValidTime\fR +which are both unset by default\&. +.RE +.sp +.SH "URI SPECIFICATION" +.PP +The currently recognized URI types are: +.PP +\fBfile\fR +.RS 4 +The file scheme allows an arbitrary directory in the file system to be considered an archive\&. This is useful for NFS mounts and local mirrors or archives\&. +.RE +.PP +\fBcdrom\fR +.RS 4 +The cdrom scheme allows APT to use a local CD\-ROM drive with media swapping\&. Use the +\fBapt-cdrom\fR(8) +program to create cdrom entries in the source list\&. +.RE +.PP +\fBhttp\fR +.RS 4 +The http scheme specifies an HTTP server for the archive\&. If an environment variable +\fBhttp_proxy\fR +is set with the format http://server:port/, the proxy server specified in +\fBhttp_proxy\fR +will be used\&. Users of authenticated HTTP/1\&.1 proxies may use a string of the format http://user:pass@server:port/\&. Note that this is an insecure method of authentication\&. +.RE +.PP +\fBftp\fR +.RS 4 +The ftp scheme specifies an FTP server for the archive\&. APT\*(Aqs FTP behavior is highly configurable; for more information see the +\fBapt.conf\fR(5) +manual page\&. Please note that an FTP proxy can be specified by using the +\fBftp_proxy\fR +environment variable\&. It is possible to specify an HTTP proxy (HTTP proxy servers often understand FTP URLs) using this environment variable and +\fIonly\fR +this environment variable\&. Proxies using HTTP specified in the configuration file will be ignored\&. +.RE +.PP +\fBcopy\fR +.RS 4 +The copy scheme is identical to the file scheme except that packages are copied into the cache directory instead of used directly at their location\&. This is useful for people using removable media to copy files around with APT\&. +.RE +.PP +\fBrsh\fR, \fBssh\fR +.RS 4 +The rsh/ssh method invokes RSH/SSH to connect to a remote host and access the files as a given user\&. Prior configuration of rhosts or RSA keys is recommended\&. The standard +\fBfind\fR +and +\fBdd\fR +commands are used to perform the file transfers from the remote host\&. +.RE +.PP +adding more recognizable URI types +.RS 4 +APT can be extended with more methods shipped in other optional packages, which should follow the naming scheme +apt\-transport\-\fImethod\fR\&. For instance, the APT team also maintains the package +apt\-transport\-https, which provides access methods for HTTPS URIs with features similar to the http method\&. Methods for using e\&.g\&. debtorrent are also available \- see +\fBapt-transport-debtorrent\fR(1)\&. +.RE +.SH "EXAMPLES" +.PP +Uses the archive stored locally (or NFS mounted) at /home/apt/debian for stable/main, stable/contrib, and stable/non\-free\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +deb file:/home/apt/debian stable main contrib non\-free +.fi +.if n \{\ +.RE +.\} +.sp +.if n \{\ +.RS 4 +.\} +.nf +Types: deb +URIs: file:/home/apt/debian +Suites: stable +Components: main contrib non\-free +.fi +.if n \{\ +.RE +.\} +.PP +As above, except this uses the unstable (development) distribution\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +deb file:/home/apt/debian unstable main contrib non\-free +.fi +.if n \{\ +.RE +.\} +.sp +.if n \{\ +.RS 4 +.\} +.nf +Types: deb +URIs: file:/home/apt/debian +Suites: unstable +Components: main contrib non\-free +.fi +.if n \{\ +.RE +.\} +.PP +Sources specification for the above\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +deb\-src file:/home/apt/debian unstable main contrib non\-free +.fi +.if n \{\ +.RE +.\} +.sp +.if n \{\ +.RS 4 +.\} +.nf +Types: deb\-src +URIs: file:/home/apt/debian +Suites: unstable +Components: main contrib non\-free +.fi +.if n \{\ +.RE +.\} +.PP +The first line gets package information for the architectures in +APT::Architectures +while the second always retrieves +amd64 +and +armel\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +deb http://deb\&.debian\&.org/debian stretch main +deb [ arch=amd64,armel ] http://deb\&.debian\&.org/debian stretch main +.fi +.if n \{\ +.RE +.\} +.sp +.if n \{\ +.RS 4 +.\} +.nf +Types: deb +URIs: http://deb\&.debian\&.org/debian +Suites: stretch +Components: main + +Types: deb +URIs: http://deb\&.debian\&.org/debian +Suites: stretch +Components: main +Architectures: amd64 armel +.fi +.if n \{\ +.RE +.\} +.PP +Uses HTTP to access the archive at archive\&.debian\&.org, and uses only the hamm/main area\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +deb http://archive\&.debian\&.org/debian\-archive hamm main +.fi +.if n \{\ +.RE +.\} +.sp +.if n \{\ +.RS 4 +.\} +.nf +Types: deb +URIs: http://archive\&.debian\&.org/debian\-archive +Suites: hamm +Components: main +.fi +.if n \{\ +.RE +.\} +.PP +Uses FTP to access the archive at ftp\&.debian\&.org, under the debian directory, and uses only the stretch/contrib area\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +deb ftp://ftp\&.debian\&.org/debian stretch contrib +.fi +.if n \{\ +.RE +.\} +.sp +.if n \{\ +.RS 4 +.\} +.nf +Types: deb +URIs: ftp://ftp\&.debian\&.org/debian +Suites: stretch +Components: contrib +.fi +.if n \{\ +.RE +.\} +.PP +Uses FTP to access the archive at ftp\&.debian\&.org, under the debian directory, and uses only the unstable/contrib area\&. If this line appears as well as the one in the previous example in +sources\&.list +a single FTP session will be used for both resource lines\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +deb ftp://ftp\&.debian\&.org/debian unstable contrib +.fi +.if n \{\ +.RE +.\} +.sp +.if n \{\ +.RS 4 +.\} +.nf +Types: deb +URIs: ftp://ftp\&.debian\&.org/debian +Suites: unstable +Components: contrib +.fi +.if n \{\ +.RE +.\} +.PP +Uses HTTP to access the archive at ftp\&.tlh\&.debian\&.org, under the universe directory, and uses only files found under +unstable/binary\-i386 +on i386 machines, +unstable/binary\-amd64 +on amd64, and so forth for other supported architectures\&. [Note this example only illustrates how to use the substitution variable; official debian archives are not structured like this] +.sp +.if n \{\ +.RS 4 +.\} +.nf +deb http://ftp\&.tlh\&.debian\&.org/universe unstable/binary\-$(ARCH)/ +.fi +.if n \{\ +.RE +.\} +.sp + +.sp +.if n \{\ +.RS 4 +.\} +.nf +Types: deb +URIs: http://ftp\&.tlh\&.debian\&.org/universe +Suites: unstable/binary\-$(ARCH)/ +.fi +.if n \{\ +.RE +.\} +.PP +Uses HTTP to get binary packages as well as sources from the stable, testing and unstable suites and the components main and contrib\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +deb http://deb\&.debian\&.org/debian stable main contrib +deb\-src http://deb\&.debian\&.org/debian stable main contrib +deb http://deb\&.debian\&.org/debian testing main contrib +deb\-src http://deb\&.debian\&.org/debian testing main contrib +deb http://deb\&.debian\&.org/debian unstable main contrib +deb\-src http://deb\&.debian\&.org/debian unstable main contrib +.fi +.if n \{\ +.RE +.\} +.sp +.if n \{\ +.RS 4 +.\} +.nf +Types: deb deb\-src +URIs: http://deb\&.debian\&.org/debian +Suites: stable testing unstable +Components: main contrib +.fi +.if n \{\ +.RE +.\} +.SH "SEE ALSO" +.PP +\fBapt-get\fR(8), +\fBapt.conf\fR(5), +/usr/share/doc/apt\-doc/acquire\-additional\-files\&.txt +.SH "BUGS" +.PP +\m[blue]\fBAPT bug page\fR\m[]\&\s-2\u[1]\d\s+2\&. If you wish to report a bug in APT, please see +/usr/share/doc/debian/bug\-reporting\&.txt +or the +\fBreportbug\fR(1) +command\&. +.SH "AUTHORS" +.PP +\fBJason Gunthorpe\fR +.RS 4 +.RE +.PP +\fBAPT team\fR +.RS 4 +.RE +.SH "NOTES" +.IP " 1." 4 +APT bug page +.RS 4 +\%http://bugs.debian.org/src:apt +.RE diff --git a/packages/apt/man/man8/apt-cache.8 b/packages/apt/man/man8/apt-cache.8 new file mode 100644 index 000000000..b95b12c5a --- /dev/null +++ b/packages/apt/man/man8/apt-cache.8 @@ -0,0 +1,533 @@ +'\" t +.\" Title: apt-cache +.\" Author: Jason Gunthorpe +.\" Generator: DocBook XSL Stylesheets v1.79.1 +.\" Date: 25\ \&November\ \&2016 +.\" Manual: APT +.\" Source: APT 1.4.9 +.\" Language: English +.\" +.TH "APT\-CACHE" "8" "25\ \&November\ \&2016" "APT 1.4.9" "APT" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +apt-cache \- query the APT cache +.SH "SYNOPSIS" +.HP \w'\fBapt\-cache\fR\ 'u +\fBapt\-cache\fR [\fB\-agipns\fR] [\fB\-o=\fR\fB\fIconfig_string\fR\fR] [\fB\-c=\fR\fB\fIconfig_file\fR\fR] {gencaches | showpkg\ \fIpkg\fR... | showsrc\ \fIpkg\fR... | stats | dump | dumpavail | unmet | search\ \fIregex\fR... | show\ \fIpkg\fR\ [{=\fIpkg_version_number\fR\ |\ /\fItarget_release\fR}]... | depends\ \fIpkg\fR\ [{=\fIpkg_version_number\fR\ |\ /\fItarget_release\fR}]... | rdepends\ \fIpkg\fR\ [{=\fIpkg_version_number\fR\ |\ /\fItarget_release\fR}]... | pkgnames\ [\fIprefix\fR] | dotty\ \fIpkg\fR\ [{=\fIpkg_version_number\fR\ |\ /\fItarget_release\fR}]... | xvcg\ \fIpkg\fR\ [{=\fIpkg_version_number\fR\ |\ /\fItarget_release\fR}]... | policy\ [\fIpkg\fR...] | madison\ \fIpkg\fR... | {\-v\ |\ \-\-version} | {\-h\ |\ \-\-help}} +.SH "DESCRIPTION" +.PP +\fBapt\-cache\fR +performs a variety of operations on APT\*(Aqs package cache\&. +\fBapt\-cache\fR +does not manipulate the state of the system but does provide operations to search and generate interesting output from the package metadata\&. The metadata is acquired and updated via the \*(Aqupdate\*(Aq command of e\&.g\&. +\fBapt\-get\fR, so that it can be outdated if the last update is too long ago, but in exchange +\fBapt\-cache\fR +works independently of the availability of the configured sources (e\&.g\&. offline)\&. +.PP +Unless the +\fB\-h\fR, or +\fB\-\-help\fR +option is given, one of the commands below must be present\&. +.PP +\fBgencaches\fR +.RS 4 +gencaches +creates APT\*(Aqs package cache\&. This is done implicitly by all commands needing this cache if it is missing or outdated\&. +.RE +.PP +\fBshowpkg\fR \fB\fIpkg\fR\fR\fB\&...\fR +.RS 4 +showpkg +displays information about the packages listed on the command line\&. Remaining arguments are package names\&. The available versions and reverse dependencies of each package listed are listed, as well as forward dependencies for each version\&. Forward (normal) dependencies are those packages upon which the package in question depends; reverse dependencies are those packages that depend upon the package in question\&. Thus, forward dependencies must be satisfied for a package, but reverse dependencies need not be\&. For instance, +\fBapt\-cache showpkg libreadline2\fR +would produce output similar to the following: +.sp +.if n \{\ +.RS 4 +.\} +.nf +Package: libreadline2 +Versions: 2\&.1\-12(/var/state/apt/lists/foo_Packages), +Reverse Depends: + libreadlineg2,libreadline2 + libreadline2\-altdev,libreadline2 +Dependencies: +2\&.1\-12 \- libc5 (2 5\&.4\&.0\-0) ncurses3\&.0 (0 (null)) +Provides: +2\&.1\-12 \- +Reverse Provides: +.fi +.if n \{\ +.RE +.\} +Thus it may be seen that libreadline2, version 2\&.1\-12, depends on libc5 and ncurses3\&.0 which must be installed for libreadline2 to work\&. In turn, libreadlineg2 and libreadline2\-altdev depend on libreadline2\&. If libreadline2 is installed, libc5 and ncurses3\&.0 (and ldso) must also be installed; libreadlineg2 and libreadline2\-altdev do not have to be installed\&. For the specific meaning of the remainder of the output it is best to consult the apt source code\&. +.RE +.PP +\fBstats\fR +.RS 4 +stats +displays some statistics about the cache\&. No further arguments are expected\&. Statistics reported are: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Total package names +is the number of package names found in the cache\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Normal packages +is the number of regular, ordinary package names; these are packages that bear a one\-to\-one correspondence between their names and the names used by other packages for them in dependencies\&. The majority of packages fall into this category\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Pure virtual packages +is the number of packages that exist only as a virtual package name; that is, packages only "provide" the virtual package name, and no package actually uses the name\&. For instance, "mail\-transport\-agent" in the Debian system is a pure virtual package; several packages provide "mail\-transport\-agent", but there is no package named "mail\-transport\-agent"\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Single virtual packages +is the number of packages with only one package providing a particular virtual package\&. For example, in the Debian system, "X11\-text\-viewer" is a virtual package, but only one package, xless, provides "X11\-text\-viewer"\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Mixed virtual packages +is the number of packages that either provide a particular virtual package or have the virtual package name as the package name\&. For instance, in the Debian system, "debconf" is both an actual package, and provided by the debconf\-tiny package\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Missing +is the number of package names that were referenced in a dependency but were not provided by any package\&. Missing packages may be an evidence if a full distribution is not accessed, or if a package (real or virtual) has been dropped from the distribution\&. Usually they are referenced from Conflicts or Breaks statements\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Total distinct +versions is the number of package versions found in the cache\&. If more than one distribution is being accessed (for instance, "stable" and "unstable"), this value can be considerably larger than the number of total package names\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Total dependencies +is the number of dependency relationships claimed by all of the packages in the cache\&. +.RE +.sp +.RE +.PP +\fBshowsrc\fR \fB\fIpkg\fR\fR\fB\&...\fR +.RS 4 +showsrc +displays all the source package records that match the given package names\&. All versions are shown, as well as all records that declare the name to be a binary package\&. Use +\fB\-\-only\-source\fR +to display only source package names\&. +.RE +.PP +\fBdump\fR +.RS 4 +dump +shows a short listing of every package in the cache\&. It is primarily for debugging\&. +.RE +.PP +\fBdumpavail\fR +.RS 4 +dumpavail +prints out an available list to stdout\&. This is suitable for use with +\fBdpkg\fR(1) +and is used by the +\fBdselect\fR(1) +method\&. +.RE +.PP +\fBunmet\fR +.RS 4 +unmet +displays a summary of all unmet dependencies in the package cache\&. +.RE +.PP +\fBshow\fR \fB\fIpkg\fR\fR\fB\&...\fR +.RS 4 +show +performs a function similar to +\fBdpkg \-\-print\-avail\fR; it displays the package records for the named packages\&. +.RE +.PP +\fBsearch\fR \fB\fIregex\fR\fR\fB\&...\fR +.RS 4 +search +performs a full text search on all available package lists for the POSIX regex pattern given, see +\fBregex\fR(7)\&. It searches the package names and the descriptions for an occurrence of the regular expression and prints out the package name and the short description, including virtual package names\&. If +\fB\-\-full\fR +is given then output identical to +show +is produced for each matched package, and if +\fB\-\-names\-only\fR +is given then the long description is not searched, only the package name and provided packages are\&. +.sp +Separate arguments can be used to specify multiple search patterns that are and\*(Aqed together\&. +.RE +.PP +\fBdepends\fR \fB\fIpkg\fR\fR\fB\&...\fR +.RS 4 +depends +shows a listing of each dependency a package has and all the possible other packages that can fulfill that dependency\&. +.RE +.PP +\fBrdepends\fR \fB\fIpkg\fR\fR\fB\&...\fR +.RS 4 +rdepends +shows a listing of each reverse dependency a package has\&. +.RE +.PP +\fBpkgnames\fR [\fIprefix\fR] +.RS 4 +This command prints the name of each package APT knows\&. The optional argument is a prefix match to filter the name list\&. The output is suitable for use in a shell tab complete function and the output is generated extremely quickly\&. This command is best used with the +\fB\-\-generate\fR +option\&. +.sp +Note that a package which APT knows of is not necessarily available to download, installable or installed, e\&.g\&. virtual packages are also listed in the generated list\&. +.RE +.PP +\fBdotty\fR \fB\fIpkg\fR\fR\fB\&...\fR +.RS 4 +dotty +takes a list of packages on the command line and generates output suitable for use by dotty from the +\m[blue]\fBGraphViz\fR\m[]\&\s-2\u[1]\d\s+2 +package\&. The result will be a set of nodes and edges representing the relationships between the packages\&. By default the given packages will trace out all dependent packages; this can produce a very large graph\&. To limit the output to only the packages listed on the command line, set the +APT::Cache::GivenOnly +option\&. +.sp +The resulting nodes will have several shapes; normal packages are boxes, pure virtual packages are triangles, mixed virtual packages are diamonds, missing packages are hexagons\&. Orange boxes mean recursion was stopped (leaf packages), blue lines are pre\-depends, green lines are conflicts\&. +.sp +Caution, dotty cannot graph larger sets of packages\&. +.RE +.PP +\fBxvcg\fR \fB\fIpkg\fR\fR\fB\&...\fR +.RS 4 +The same as +dotty, only for xvcg from the +\m[blue]\fBVCG tool\fR\m[]\&\s-2\u[2]\d\s+2\&. +.RE +.PP +\fBpolicy\fR [\fIpkg\fR\&...] +.RS 4 +policy +is meant to help debug issues relating to the preferences file\&. With no arguments it will print out the priorities of each source\&. Otherwise it prints out detailed information about the priority selection of the named package\&. +.RE +.PP +\fBmadison\fR \fB\fIpkg\fR\fR\fB\&...\fR +.RS 4 +apt\-cache\*(Aqs +madison +command attempts to mimic the output format and a subset of the functionality of the Debian archive management tool, +madison\&. It displays available versions of a package in a tabular format\&. Unlike the original +madison, it can only display information for the architecture for which APT has retrieved package lists (APT::Architecture)\&. +.RE +.SH "OPTIONS" +.PP +All command line options may be set using the configuration file, the descriptions indicate the configuration option to set\&. For boolean options you can override the config file by using something like +\fB\-f\-\fR,\fB\-\-no\-f\fR, +\fB\-f=no\fR +or several other variations\&. +.PP +\fB\-p\fR, \fB\-\-pkg\-cache\fR +.RS 4 +Select the file to store the package cache\&. The package cache is the primary cache used by all operations\&. Configuration Item: +Dir::Cache::pkgcache\&. +.RE +.PP +\fB\-s\fR, \fB\-\-src\-cache\fR +.RS 4 +Select the file to store the source cache\&. The source is used only by +gencaches +and it stores a parsed version of the package information from remote sources\&. When building the package cache the source cache is used to avoid reparsing all of the package files\&. Configuration Item: +Dir::Cache::srcpkgcache\&. +.RE +.PP +\fB\-q\fR, \fB\-\-quiet\fR +.RS 4 +Quiet; produces output suitable for logging, omitting progress indicators\&. More q\*(Aqs will produce more quietness up to a maximum of 2\&. You can also use +\fB\-q=#\fR +to set the quietness level, overriding the configuration file\&. Configuration Item: +quiet\&. +.RE +.PP +\fB\-i\fR, \fB\-\-important\fR +.RS 4 +Print only important dependencies; for use with +unmet +and +depends\&. Causes only Depends and Pre\-Depends relations to be printed\&. Configuration Item: +APT::Cache::Important\&. +.RE +.PP +\fB\-\-no\-pre\-depends\fR, \fB\-\-no\-depends\fR, \fB\-\-no\-recommends\fR, \fB\-\-no\-suggests\fR, \fB\-\-no\-conflicts\fR, \fB\-\-no\-breaks\fR, \fB\-\-no\-replaces\fR, \fB\-\-no\-enhances\fR +.RS 4 +Per default the +\fBdepends\fR +and +\fBrdepends\fR +print all dependencies\&. This can be tweaked with these flags which will omit the specified dependency type\&. Configuration Item: +APT::Cache::Show\fIDependencyType\fR +e\&.g\&. +APT::Cache::ShowRecommends\&. +.RE +.PP +\fB\-\-implicit\fR +.RS 4 +Per default +\fBdepends\fR +and +\fBrdepends\fR +print only dependencies explicitly expressed in the metadata\&. With this flag it will also show dependencies implicitly added based on the encountered data\&. A +Conflicts: foo +e\&.g\&. expresses implicitly that this package also conflicts with the package foo from any other architecture\&. Configuration Item: +APT::Cache::ShowImplicit\&. +.RE +.PP +\fB\-f\fR, \fB\-\-full\fR +.RS 4 +Print full package records when searching\&. Configuration Item: +APT::Cache::ShowFull\&. +.RE +.PP +\fB\-a\fR, \fB\-\-all\-versions\fR +.RS 4 +Print full records for all available versions\&. This is the default; to turn it off, use +\fB\-\-no\-all\-versions\fR\&. If +\fB\-\-no\-all\-versions\fR +is specified, only the candidate version will be displayed (the one which would be selected for installation)\&. This option is only applicable to the +show +command\&. Configuration Item: +APT::Cache::AllVersions\&. +.RE +.PP +\fB\-g\fR, \fB\-\-generate\fR +.RS 4 +Perform automatic package cache regeneration, rather than use the cache as it is\&. This is the default; to turn it off, use +\fB\-\-no\-generate\fR\&. Configuration Item: +APT::Cache::Generate\&. +.RE +.PP +\fB\-\-names\-only\fR, \fB\-n\fR +.RS 4 +Only search on the package and provided package names, not the long descriptions\&. Configuration Item: +APT::Cache::NamesOnly\&. +.RE +.PP +\fB\-\-all\-names\fR +.RS 4 +Make +pkgnames +print all names, including virtual packages and missing dependencies\&. Configuration Item: +APT::Cache::AllNames\&. +.RE +.PP +\fB\-\-recurse\fR +.RS 4 +Make +depends +and +rdepends +recursive so that all packages mentioned are printed once\&. Configuration Item: +APT::Cache::RecurseDepends\&. +.RE +.PP +\fB\-\-installed\fR +.RS 4 +Limit the output of +depends +and +rdepends +to packages which are currently installed\&. Configuration Item: +APT::Cache::Installed\&. +.RE +.PP +\fB\-\-with\-source\fR \fB\fIfilename\fR\fR +.RS 4 +Adds the given file as a source for metadata\&. Can be repeated to add multiple files\&. Supported are currently +*\&.deb, +*\&.dsc, +*\&.changes, +Sources +and +Packages +files as well as source package directories\&. Files are matched based on their name only, not their content! +.sp +Sources +and +Packages +can be compressed in any format apt supports as long as they have the correct extension\&. If you need to store multiple of these files in one directory you can prefix a name of your choice with the last character being an underscore ("_")\&. Example: my\&.example_Packages\&.xz +.sp +Note that these sources are treated as trusted (see +\fBapt-secure\fR(8))\&. Configuration Item: +APT::Sources::With\&. +.RE +.PP +\fB\-h\fR, \fB\-\-help\fR +.RS 4 +Show a short usage summary\&. +.RE +.PP +\fB\-v\fR, \fB\-\-version\fR +.RS 4 +Show the program version\&. +.RE +.PP +\fB\-c\fR, \fB\-\-config\-file\fR +.RS 4 +Configuration File; Specify a configuration file to use\&. The program will read the default configuration file and then this configuration file\&. If configuration settings need to be set before the default configuration files are parsed specify a file with the +\fBAPT_CONFIG\fR +environment variable\&. See +\fBapt.conf\fR(5) +for syntax information\&. +.RE +.PP +\fB\-o\fR, \fB\-\-option\fR +.RS 4 +Set a Configuration Option; This will set an arbitrary configuration option\&. The syntax is +\fB\-o Foo::Bar=bar\fR\&. +\fB\-o\fR +and +\fB\-\-option\fR +can be used multiple times to set different options\&. +.RE +.SH "FILES" +.PP +/etc/apt/sources\&.list +.RS 4 +Locations to fetch packages from\&. Configuration Item: +Dir::Etc::SourceList\&. +.RE +.PP +/etc/apt/sources\&.list\&.d/ +.RS 4 +File fragments for locations to fetch packages from\&. Configuration Item: +Dir::Etc::SourceParts\&. +.RE +.PP +/var/lib/apt/lists/ +.RS 4 +Storage area for state information for each package resource specified in +\fBsources.list\fR(5) +Configuration Item: +Dir::State::Lists\&. +.RE +.PP +/var/lib/apt/lists/partial/ +.RS 4 +Storage area for state information in transit\&. Configuration Item: +Dir::State::Lists +(partial +will be implicitly appended) +.RE +.SH "SEE ALSO" +.PP +\fBapt.conf\fR(5), +\fBsources.list\fR(5), +\fBapt-get\fR(8) +.SH "DIAGNOSTICS" +.PP +\fBapt\-cache\fR +returns zero on normal operation, decimal 100 on error\&. +.SH "BUGS" +.PP +\m[blue]\fBAPT bug page\fR\m[]\&\s-2\u[3]\d\s+2\&. If you wish to report a bug in APT, please see +/usr/share/doc/debian/bug\-reporting\&.txt +or the +\fBreportbug\fR(1) +command\&. +.SH "AUTHORS" +.PP +\fBJason Gunthorpe\fR +.RS 4 +.RE +.PP +\fBAPT team\fR +.RS 4 +.RE +.SH "NOTES" +.IP " 1." 4 +GraphViz +.RS 4 +\%http://www.research.att.com/sw/tools/graphviz/ +.RE +.IP " 2." 4 +VCG tool +.RS 4 +\%http://rw4.cs.uni-sb.de/users/sander/html/gsvcg1.html +.RE +.IP " 3." 4 +APT bug page +.RS 4 +\%http://bugs.debian.org/src:apt +.RE diff --git a/packages/apt/man/man8/apt-config.8 b/packages/apt/man/man8/apt-config.8 new file mode 100644 index 000000000..558ded5ce --- /dev/null +++ b/packages/apt/man/man8/apt-config.8 @@ -0,0 +1,145 @@ +'\" t +.\" Title: apt-config +.\" Author: Jason Gunthorpe +.\" Generator: DocBook XSL Stylesheets v1.79.1 +.\" Date: 30\ \&November\ \&2013 +.\" Manual: APT +.\" Source: APT 1.4.9 +.\" Language: English +.\" +.TH "APT\-CONFIG" "8" "30\ \&November\ \&2013" "APT 1.4.9" "APT" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +apt-config \- APT Configuration Query program +.SH "SYNOPSIS" +.HP \w'\fBapt\-config\fR\ 'u +\fBapt\-config\fR [\fB\-\-empty\fR] [\fB\-\-format\ \*(Aq\fR\fB\fI%f\ "%v";%n\fR\fR\fB\*(Aq\fR] [\fB\-o=\fR\fB\fIconfig_string\fR\fR] [\fB\-c=\fR\fB\fIconfig_file\fR\fR] {shell | dump | {\-v\ |\ \-\-version} | {\-h\ |\ \-\-help}} +.SH "DESCRIPTION" +.PP +\fBapt\-config\fR +is an internal program used by various portions of the APT suite to provide consistent configurability\&. It accesses the main configuration file +/etc/apt/apt\&.conf +in a manner that is easy to use for scripted applications\&. +.PP +Unless the +\fB\-h\fR, or +\fB\-\-help\fR +option is given, one of the commands below must be present\&. +.PP +\fBshell\fR +.RS 4 +shell is used to access the configuration information from a shell script\&. It is given pairs of arguments, the first being a shell variable and the second the configuration value to query\&. As output it lists shell assignment commands for each value present\&. In a shell script it should be used as follows: +.sp +.if n \{\ +.RS 4 +.\} +.nf +OPTS="\-f" +RES=`apt\-config shell OPTS MyApp::options` +eval $RES +.fi +.if n \{\ +.RE +.\} +This will set the shell environment variable $OPTS to the value of MyApp::options with a default of +\fB\-f\fR\&. +.sp +The configuration item may be postfixed with a /[fdbi]\&. f returns file names, d returns directories, b returns true or false and i returns an integer\&. Each of the returns is normalized and verified internally\&. +.RE +.PP +\fBdump\fR +.RS 4 +Just show the contents of the configuration space\&. +.RE +.SH "OPTIONS" +.PP +All command line options may be set using the configuration file, the descriptions indicate the configuration option to set\&. For boolean options you can override the config file by using something like +\fB\-f\-\fR,\fB\-\-no\-f\fR, +\fB\-f=no\fR +or several other variations\&. +.PP +\fB\-\-empty\fR +.RS 4 +Include options which have an empty value\&. This is the default, so use \-\-no\-empty to remove them from the output\&. +.RE +.PP +\fB\-\-format \*(Aq\fR\fB\fI%f "%v";%n\fR\fR\fB\*(Aq\fR +.RS 4 +Defines the output of each config option\&. %t will be replaced with its individual name, %f with its full hierarchical name and %v with its value\&. Use uppercase letters and special characters in the value will be encoded to ensure that it can e\&.g\&. be safely used in a quoted\-string as defined by RFC822\&. Additionally %n will be replaced by a newline, and %N by a tab\&. A % can be printed by using %%\&. +.RE +.PP +\fB\-h\fR, \fB\-\-help\fR +.RS 4 +Show a short usage summary\&. +.RE +.PP +\fB\-v\fR, \fB\-\-version\fR +.RS 4 +Show the program version\&. +.RE +.PP +\fB\-c\fR, \fB\-\-config\-file\fR +.RS 4 +Configuration File; Specify a configuration file to use\&. The program will read the default configuration file and then this configuration file\&. If configuration settings need to be set before the default configuration files are parsed specify a file with the +\fBAPT_CONFIG\fR +environment variable\&. See +\fBapt.conf\fR(5) +for syntax information\&. +.RE +.PP +\fB\-o\fR, \fB\-\-option\fR +.RS 4 +Set a Configuration Option; This will set an arbitrary configuration option\&. The syntax is +\fB\-o Foo::Bar=bar\fR\&. +\fB\-o\fR +and +\fB\-\-option\fR +can be used multiple times to set different options\&. +.RE +.SH "SEE ALSO" +.PP +\fBapt.conf\fR(5) +.SH "DIAGNOSTICS" +.PP +\fBapt\-config\fR +returns zero on normal operation, decimal 100 on error\&. +.SH "BUGS" +.PP +\m[blue]\fBAPT bug page\fR\m[]\&\s-2\u[1]\d\s+2\&. If you wish to report a bug in APT, please see +/usr/share/doc/debian/bug\-reporting\&.txt +or the +\fBreportbug\fR(1) +command\&. +.SH "AUTHORS" +.PP +\fBJason Gunthorpe\fR +.RS 4 +.RE +.PP +\fBAPT team\fR +.RS 4 +.RE +.SH "NOTES" +.IP " 1." 4 +APT bug page +.RS 4 +\%http://bugs.debian.org/src:apt +.RE diff --git a/packages/apt/man/man8/apt-get.8 b/packages/apt/man/man8/apt-get.8 new file mode 100644 index 000000000..a253255a8 --- /dev/null +++ b/packages/apt/man/man8/apt-get.8 @@ -0,0 +1,710 @@ +'\" t +.\" Title: apt-get +.\" Author: Jason Gunthorpe +.\" Generator: DocBook XSL Stylesheets v1.79.1 +.\" Date: 22\ \&February\ \&2017 +.\" Manual: APT +.\" Source: APT 1.4.9 +.\" Language: English +.\" +.TH "APT\-GET" "8" "22\ \&February\ \&2017" "APT 1.4.9" "APT" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +apt-get \- APT package handling utility \-\- command\-line interface +.SH "SYNOPSIS" +.HP \w'\fBapt\-get\fR\ 'u +\fBapt\-get\fR [\fB\-asqdyfmubV\fR] [\fB\-o=\fR\fB\fIconfig_string\fR\fR] [\fB\-c=\fR\fB\fIconfig_file\fR\fR] [\fB\-t=\fR\fB\fItarget_release\fR\fR] [\fB\-a=\fR\fB\fIarchitecture\fR\fR] {update | upgrade | dselect\-upgrade | dist\-upgrade | install\ \fIpkg\fR\ [{=\fIpkg_version_number\fR\ |\ /\fItarget_release\fR}]... | remove\ \fIpkg\fR... | purge\ \fIpkg\fR... | source\ \fIpkg\fR\ [{=\fIpkg_version_number\fR\ |\ /\fItarget_release\fR}]... | build\-dep\ \fIpkg\fR\ [{=\fIpkg_version_number\fR\ |\ /\fItarget_release\fR}]... | download\ \fIpkg\fR\ [{=\fIpkg_version_number\fR\ |\ /\fItarget_release\fR}]... | check | clean | autoclean | autoremove | {\-v\ |\ \-\-version} | {\-h\ |\ \-\-help}} +.SH "DESCRIPTION" +.PP +\fBapt\-get\fR +is the command\-line tool for handling packages, and may be considered the user\*(Aqs "back\-end" to other tools using the APT library\&. Several "front\-end" interfaces exist, such as +\fBaptitude\fR(8), +\fBsynaptic\fR(8) +and +\fBwajig\fR(1)\&. +.PP +Unless the +\fB\-h\fR, or +\fB\-\-help\fR +option is given, one of the commands below must be present\&. +.PP +\fBupdate\fR +.RS 4 +update +is used to resynchronize the package index files from their sources\&. The indexes of available packages are fetched from the location(s) specified in +/etc/apt/sources\&.list\&. For example, when using a Debian archive, this command retrieves and scans the +Packages\&.gz +files, so that information about new and updated packages is available\&. An +update +should always be performed before an +upgrade +or +dist\-upgrade\&. Please be aware that the overall progress meter will be incorrect as the size of the package files cannot be known in advance\&. +.RE +.PP +\fBupgrade\fR +.RS 4 +upgrade +is used to install the newest versions of all packages currently installed on the system from the sources enumerated in +/etc/apt/sources\&.list\&. Packages currently installed with new versions available are retrieved and upgraded; under no circumstances are currently installed packages removed, or packages not already installed retrieved and installed\&. New versions of currently installed packages that cannot be upgraded without changing the install status of another package will be left at their current version\&. An +update +must be performed first so that +\fBapt\-get\fR +knows that new versions of packages are available\&. +.RE +.PP +\fBdist\-upgrade\fR +.RS 4 +dist\-upgrade +in addition to performing the function of +upgrade, also intelligently handles changing dependencies with new versions of packages; +\fBapt\-get\fR +has a "smart" conflict resolution system, and it will attempt to upgrade the most important packages at the expense of less important ones if necessary\&. The +dist\-upgrade +command may therefore remove some packages\&. The +/etc/apt/sources\&.list +file contains a list of locations from which to retrieve desired package files\&. See also +\fBapt_preferences\fR(5) +for a mechanism for overriding the general settings for individual packages\&. +.RE +.PP +\fBdselect\-upgrade\fR +.RS 4 +dselect\-upgrade +is used in conjunction with the traditional Debian packaging front\-end, +\fBdselect\fR(1)\&. +dselect\-upgrade +follows the changes made by +\fBdselect\fR(1) +to the +Status +field of available packages, and performs the actions necessary to realize that state (for instance, the removal of old and the installation of new packages)\&. +.RE +.PP +\fBinstall\fR +.RS 4 +install +is followed by one or more packages desired for installation or upgrading\&. Each package is a package name, not a fully qualified filename (for instance, in a Debian system, +apt\-utils +would be the argument provided, not +apt\-utils_1\&.4\&.9_amd64\&.deb)\&. All packages required by the package(s) specified for installation will also be retrieved and installed\&. The +/etc/apt/sources\&.list +file is used to locate the desired packages\&. If a hyphen is appended to the package name (with no intervening space), the identified package will be removed if it is installed\&. Similarly a plus sign can be used to designate a package to install\&. These latter features may be used to override decisions made by apt\-get\*(Aqs conflict resolution system\&. +.sp +A specific version of a package can be selected for installation by following the package name with an equals and the version of the package to select\&. This will cause that version to be located and selected for install\&. Alternatively a specific distribution can be selected by following the package name with a slash and the version of the distribution or the Archive name (stable, testing, unstable)\&. +.sp +Both of the version selection mechanisms can downgrade packages and must be used with care\&. +.sp +This is also the target to use if you want to upgrade one or more already\-installed packages without upgrading every package you have on your system\&. Unlike the "upgrade" target, which installs the newest version of all currently installed packages, "install" will install the newest version of only the package(s) specified\&. Simply provide the name of the package(s) you wish to upgrade, and if a newer version is available, it (and its dependencies, as described above) will be downloaded and installed\&. +.sp +Finally, the +\fBapt_preferences\fR(5) +mechanism allows you to create an alternative installation policy for individual packages\&. +.sp +If no package matches the given expression and the expression contains one of \*(Aq\&.\*(Aq, \*(Aq?\*(Aq or \*(Aq*\*(Aq then it is assumed to be a POSIX regular expression, and it is applied to all package names in the database\&. Any matches are then installed (or removed)\&. Note that matching is done by substring so \*(Aqlo\&.*\*(Aq matches \*(Aqhow\-lo\*(Aq and \*(Aqlowest\*(Aq\&. If this is undesired, anchor the regular expression with a \*(Aq^\*(Aq or \*(Aq$\*(Aq character, or create a more specific regular expression\&. +.RE +.PP +\fBremove\fR +.RS 4 +remove +is identical to +install +except that packages are removed instead of installed\&. Note that removing a package leaves its configuration files on the system\&. If a plus sign is appended to the package name (with no intervening space), the identified package will be installed instead of removed\&. +.RE +.PP +\fBpurge\fR +.RS 4 +purge +is identical to +remove +except that packages are removed and purged (any configuration files are deleted too)\&. +.RE +.PP +\fBsource\fR +.RS 4 +source +causes +\fBapt\-get\fR +to fetch source packages\&. APT will examine the available packages to decide which source package to fetch\&. It will then find and download into the current directory the newest available version of that source package while respecting the default release, set with the option +APT::Default\-Release, the +\fB\-t\fR +option or per package with the +pkg/release +syntax, if possible\&. +.sp +Source packages are tracked separately from binary packages via +deb\-src +lines in the +\fBsources.list\fR(5) +file\&. This means that you will need to add such a line for each repository you want to get sources from; otherwise you will probably get either the wrong (too old/too new) source versions or none at all\&. +.sp +If the +\fB\-\-compile\fR +option is specified then the package will be compiled to a binary \&.deb using +\fBdpkg\-buildpackage\fR +for the architecture as defined by the +\fB\-\-host\-architecture\fR +option\&. If +\fB\-\-download\-only\fR +is specified then the source package will not be unpacked\&. +.sp +A specific source version can be retrieved by postfixing the source name with an equals and then the version to fetch, similar to the mechanism used for the package files\&. This enables exact matching of the source package name and version, implicitly enabling the +APT::Get::Only\-Source +option\&. +.sp +Note that source packages are not installed and tracked in the +\fBdpkg\fR +database like binary packages; they are simply downloaded to the current directory, like source tarballs\&. +.RE +.PP +\fBbuild\-dep\fR +.RS 4 +build\-dep +causes apt\-get to install/remove packages in an attempt to satisfy the build dependencies for a source package\&. By default the dependencies are satisfied to build the package natively\&. If desired a host\-architecture can be specified with the +\fB\-\-host\-architecture\fR +option instead\&. +.RE +.PP +\fBcheck\fR +.RS 4 +check +is a diagnostic tool; it updates the package cache and checks for broken dependencies\&. +.RE +.PP +\fBdownload\fR +.RS 4 +download +will download the given binary package into the current directory\&. +.RE +.PP +\fBclean\fR +.RS 4 +clean +clears out the local repository of retrieved package files\&. It removes everything but the lock file from +/var/cache/apt/archives/ +and +/var/cache/apt/archives/partial/\&. +.RE +.PP +\fBautoclean\fR (and the \fBauto\-clean\fR alias since 1\&.1) +.RS 4 +Like +clean, +autoclean +clears out the local repository of retrieved package files\&. The difference is that it only removes package files that can no longer be downloaded, and are largely useless\&. This allows a cache to be maintained over a long period without it growing out of control\&. The configuration option +APT::Clean\-Installed +will prevent installed packages from being erased if it is set to off\&. +.RE +.PP +\fBautoremove\fR (and the \fBauto\-remove\fR alias since 1\&.1) +.RS 4 +autoremove +is used to remove packages that were automatically installed to satisfy dependencies for other packages and are now no longer needed\&. +.RE +.PP +\fBchangelog\fR +.RS 4 +changelog +tries to download the changelog of a package and displays it through +\fBsensible\-pager\fR\&. By default it displays the changelog for the version that is installed\&. However, you can specify the same options as for the +\fBinstall\fR +command\&. +.RE +.PP +\fBindextargets\fR +.RS 4 +Displays by default a deb822 formatted listing of information about all data files (aka index targets) +\fBapt\-get update\fR +would download\&. Supports a +\fB\-\-format\fR +option to modify the output format as well as accepts lines of the default output to filter the records by\&. The command is mainly used as an interface for external tools working with APT to get information as well as filenames for downloaded files so they can use them as well instead of downloading them again on their own\&. Detailed documentation is omitted here and can instead be found in the file +/usr/share/doc/apt\-doc/acquire\-additional\-files\&.txt +shipped by the +apt\-doc +package\&. +.RE +.SH "OPTIONS" +.PP +All command line options may be set using the configuration file, the descriptions indicate the configuration option to set\&. For boolean options you can override the config file by using something like +\fB\-f\-\fR,\fB\-\-no\-f\fR, +\fB\-f=no\fR +or several other variations\&. +.PP +\fB\-\-no\-install\-recommends\fR +.RS 4 +Do not consider recommended packages as a dependency for installing\&. Configuration Item: +APT::Install\-Recommends\&. +.RE +.PP +\fB\-\-install\-suggests\fR +.RS 4 +Consider suggested packages as a dependency for installing\&. Configuration Item: +APT::Install\-Suggests\&. +.RE +.PP +\fB\-d\fR, \fB\-\-download\-only\fR +.RS 4 +Download only; package files are only retrieved, not unpacked or installed\&. Configuration Item: +APT::Get::Download\-Only\&. +.RE +.PP +\fB\-f\fR, \fB\-\-fix\-broken\fR +.RS 4 +Fix; attempt to correct a system with broken dependencies in place\&. This option, when used with install/remove, can omit any packages to permit APT to deduce a likely solution\&. If packages are specified, these have to completely correct the problem\&. The option is sometimes necessary when running APT for the first time; APT itself does not allow broken package dependencies to exist on a system\&. It is possible that a system\*(Aqs dependency structure can be so corrupt as to require manual intervention (which usually means using +\fBdpkg \-\-remove\fR +to eliminate some of the offending packages)\&. Use of this option together with +\fB\-m\fR +may produce an error in some situations\&. Configuration Item: +APT::Get::Fix\-Broken\&. +.RE +.PP +\fB\-m\fR, \fB\-\-ignore\-missing\fR, \fB\-\-fix\-missing\fR +.RS 4 +Ignore missing packages; if packages cannot be retrieved or fail the integrity check after retrieval (corrupted package files), hold back those packages and handle the result\&. Use of this option together with +\fB\-f\fR +may produce an error in some situations\&. If a package is selected for installation (particularly if it is mentioned on the command line) and it could not be downloaded then it will be silently held back\&. Configuration Item: +APT::Get::Fix\-Missing\&. +.RE +.PP +\fB\-\-no\-download\fR +.RS 4 +Disables downloading of packages\&. This is best used with +\fB\-\-ignore\-missing\fR +to force APT to use only the \&.debs it has already downloaded\&. Configuration Item: +APT::Get::Download\&. +.RE +.PP +\fB\-q\fR, \fB\-\-quiet\fR +.RS 4 +Quiet; produces output suitable for logging, omitting progress indicators\&. More q\*(Aqs will produce more quiet up to a maximum of 2\&. You can also use +\fB\-q=#\fR +to set the quiet level, overriding the configuration file\&. Note that quiet level 2 implies +\fB\-y\fR; you should never use \-qq without a no\-action modifier such as \-d, \-\-print\-uris or \-s as APT may decide to do something you did not expect\&. Configuration Item: +quiet\&. +.RE +.PP +\fB\-s\fR, \fB\-\-simulate\fR, \fB\-\-just\-print\fR, \fB\-\-dry\-run\fR, \fB\-\-recon\fR, \fB\-\-no\-act\fR +.RS 4 +No action; perform a simulation of events that would occur based on the current system state but do not actually change the system\&. Locking will be disabled (\fBDebug::NoLocking\fR) so the system state could change while +\fBapt\-get\fR +is running\&. Simulations can also be executed by non\-root users which might not have read access to all apt configuration distorting the simulation\&. A notice expressing this warning is also shown by default for non\-root users (\fBAPT::Get::Show\-User\-Simulation\-Note\fR)\&. Configuration Item: +APT::Get::Simulate\&. +.sp +Simulated runs print out a series of lines, each representing a +\fBdpkg\fR +operation: configure (Conf), remove (Remv) or unpack (Inst)\&. Square brackets indicate broken packages, and empty square brackets indicate breaks that are of no consequence (rare)\&. +.RE +.PP +\fB\-y\fR, \fB\-\-yes\fR, \fB\-\-assume\-yes\fR +.RS 4 +Automatic yes to prompts; assume "yes" as answer to all prompts and run non\-interactively\&. If an undesirable situation, such as changing a held package, trying to install a unauthenticated package or removing an essential package occurs then +apt\-get +will abort\&. Configuration Item: +APT::Get::Assume\-Yes\&. +.RE +.PP +\fB\-\-assume\-no\fR +.RS 4 +Automatic "no" to all prompts\&. Configuration Item: +APT::Get::Assume\-No\&. +.RE +.PP +\fB\-\-no\-show\-upgraded\fR +.RS 4 +Do not show a list of all packages that are to be upgraded\&. Configuration Item: +APT::Get::Show\-Upgraded\&. +.RE +.PP +\fB\-V\fR, \fB\-\-verbose\-versions\fR +.RS 4 +Show full versions for upgraded and installed packages\&. Configuration Item: +APT::Get::Show\-Versions\&. +.RE +.PP +\fB\-a\fR, \fB\-\-host\-architecture\fR +.RS 4 +This option controls the architecture packages are built for by +\fBapt\-get source \-\-compile\fR +and how cross\-builddependencies are satisfied\&. By default is it not set which means that the host architecture is the same as the build architecture (which is defined by +APT::Architecture)\&. Configuration Item: +APT::Get::Host\-Architecture\&. +.RE +.PP +\fB\-P\fR, \fB\-\-build\-profiles\fR +.RS 4 +This option controls the activated build profiles for which a source package is built by +\fBapt\-get source \-\-compile\fR +and how build dependencies are satisfied\&. By default no build profile is active\&. More than one build profile can be activated at a time by concatenating them with a comma\&. Configuration Item: +APT::Build\-Profiles\&. +.RE +.PP +\fB\-b\fR, \fB\-\-compile\fR, \fB\-\-build\fR +.RS 4 +Compile source packages after downloading them\&. Configuration Item: +APT::Get::Compile\&. +.RE +.PP +\fB\-\-ignore\-hold\fR +.RS 4 +Ignore package holds; this causes +\fBapt\-get\fR +to ignore a hold placed on a package\&. This may be useful in conjunction with +dist\-upgrade +to override a large number of undesired holds\&. Configuration Item: +APT::Ignore\-Hold\&. +.RE +.PP +\fB\-\-with\-new\-pkgs\fR +.RS 4 +Allow installing new packages when used in conjunction with +upgrade\&. This is useful if the update of a installed package requires new dependencies to be installed\&. Instead of holding the package back +upgrade +will upgrade the package and install the new dependencies\&. Note that +upgrade +with this option will never remove packages, only allow adding new ones\&. Configuration Item: +APT::Get::Upgrade\-Allow\-New\&. +.RE +.PP +\fB\-\-no\-upgrade\fR +.RS 4 +Do not upgrade packages; when used in conjunction with +install, +no\-upgrade +will prevent packages on the command line from being upgraded if they are already installed\&. Configuration Item: +APT::Get::Upgrade\&. +.RE +.PP +\fB\-\-only\-upgrade\fR +.RS 4 +Do not install new packages; when used in conjunction with +install, +only\-upgrade +will install upgrades for already installed packages only and ignore requests to install new packages\&. Configuration Item: +APT::Get::Only\-Upgrade\&. +.RE +.PP +\fB\-\-allow\-downgrades\fR +.RS 4 +This is a dangerous option that will cause apt to continue without prompting if it is doing downgrades\&. It should not be used except in very special situations\&. Using it can potentially destroy your system! Configuration Item: +APT::Get::allow\-downgrades\&. Introduced in APT 1\&.1\&. +.RE +.PP +\fB\-\-allow\-remove\-essential\fR +.RS 4 +Force yes; this is a dangerous option that will cause apt to continue without prompting if it is removing essentials\&. It should not be used except in very special situations\&. Using it can potentially destroy your system! Configuration Item: +APT::Get::allow\-remove\-essential\&. Introduced in APT 1\&.1\&. +.RE +.PP +\fB\-\-allow\-change\-held\-packages\fR +.RS 4 +Force yes; this is a dangerous option that will cause apt to continue without prompting if it is changing held packages\&. It should not be used except in very special situations\&. Using it can potentially destroy your system! Configuration Item: +APT::Get::allow\-change\-held\-packages\&. Introduced in APT 1\&.1\&. +.RE +.PP +\fB\-\-force\-yes\fR +.RS 4 +Force yes; this is a dangerous option that will cause apt to continue without prompting if it is doing something potentially harmful\&. It should not be used except in very special situations\&. Using +force\-yes +can potentially destroy your system! Configuration Item: +APT::Get::force\-yes\&. This is deprecated and replaced by +\fB\-\-allow\-downgrades\fR, +\fB\-\-allow\-remove\-essential\fR, +\fB\-\-allow\-change\-held\-packages\fR +in 1\&.1\&. +.RE +.PP +\fB\-\-print\-uris\fR +.RS 4 +Instead of fetching the files to install their URIs are printed\&. Each URI will have the path, the destination file name, the size and the expected MD5 hash\&. Note that the file name to write to will not always match the file name on the remote site! This also works with the +source +and +update +commands\&. When used with the +update +command the MD5 and size are not included, and it is up to the user to decompress any compressed files\&. Configuration Item: +APT::Get::Print\-URIs\&. +.RE +.PP +\fB\-\-purge\fR +.RS 4 +Use purge instead of remove for anything that would be removed\&. An asterisk ("*") will be displayed next to packages which are scheduled to be purged\&. +\fBremove \-\-purge\fR +is equivalent to the +\fBpurge\fR +command\&. Configuration Item: +APT::Get::Purge\&. +.RE +.PP +\fB\-\-reinstall\fR +.RS 4 +Re\-install packages that are already installed and at the newest version\&. Configuration Item: +APT::Get::ReInstall\&. +.RE +.PP +\fB\-\-list\-cleanup\fR +.RS 4 +This option is on by default; use +\-\-no\-list\-cleanup +to turn it off\&. When it is on, +\fBapt\-get\fR +will automatically manage the contents of +/var/lib/apt/lists +to ensure that obsolete files are erased\&. The only reason to turn it off is if you frequently change your sources list\&. Configuration Item: +APT::Get::List\-Cleanup\&. +.RE +.PP +\fB\-t\fR, \fB\-\-target\-release\fR, \fB\-\-default\-release\fR +.RS 4 +This option controls the default input to the policy engine; it creates a default pin at priority 990 using the specified release string\&. This overrides the general settings in +/etc/apt/preferences\&. Specifically pinned packages are not affected by the value of this option\&. In short, this option lets you have simple control over which distribution packages will be retrieved from\&. Some common examples might be +\fB\-t \*(Aq2\&.1*\*(Aq\fR, +\fB\-t unstable\fR +or +\fB\-t sid\fR\&. Configuration Item: +APT::Default\-Release; see also the +\fBapt_preferences\fR(5) +manual page\&. +.RE +.PP +\fB\-\-trivial\-only\fR +.RS 4 +Only perform operations that are \*(Aqtrivial\*(Aq\&. Logically this can be considered related to +\fB\-\-assume\-yes\fR; where +\fB\-\-assume\-yes\fR +will answer yes to any prompt, +\fB\-\-trivial\-only\fR +will answer no\&. Configuration Item: +APT::Get::Trivial\-Only\&. +.RE +.PP +\fB\-\-no\-remove\fR +.RS 4 +If any packages are to be removed apt\-get immediately aborts without prompting\&. Configuration Item: +APT::Get::Remove\&. +.RE +.PP +\fB\-\-auto\-remove\fR, \fB\-\-autoremove\fR +.RS 4 +If the command is either +install +or +remove, then this option acts like running the +autoremove +command, removing unused dependency packages\&. Configuration Item: +APT::Get::AutomaticRemove\&. +.RE +.PP +\fB\-\-only\-source\fR +.RS 4 +Only has meaning for the +source +and +build\-dep +commands\&. Indicates that the given source names are not to be mapped through the binary table\&. This means that if this option is specified, these commands will only accept source package names as arguments, rather than accepting binary package names and looking up the corresponding source package\&. Configuration Item: +APT::Get::Only\-Source\&. +.RE +.PP +\fB\-\-diff\-only\fR, \fB\-\-dsc\-only\fR, \fB\-\-tar\-only\fR +.RS 4 +Download only the diff, dsc, or tar file of a source archive\&. Configuration Item: +APT::Get::Diff\-Only, +APT::Get::Dsc\-Only, and +APT::Get::Tar\-Only\&. +.RE +.PP +\fB\-\-arch\-only\fR +.RS 4 +Only process architecture\-dependent build\-dependencies\&. Configuration Item: +APT::Get::Arch\-Only\&. +.RE +.PP +\fB\-\-indep\-only\fR +.RS 4 +Only process architecture\-independent build\-dependencies\&. Configuration Item: +APT::Get::Indep\-Only\&. +.RE +.PP +\fB\-\-allow\-unauthenticated\fR +.RS 4 +Ignore if packages can\*(Aqt be authenticated and don\*(Aqt prompt about it\&. This can be useful while working with local repositories, but is a huge security risk if data authenticity isn\*(Aqt ensured in another way by the user itself\&. The usage of the +\fBTrusted\fR +option for +\fBsources.list\fR(5) +entries should usually be preferred over this global override\&. Configuration Item: +APT::Get::AllowUnauthenticated\&. +.RE +.PP +\fB\-\-no\-allow\-insecure\-repositories\fR +.RS 4 +Forbid the update command to acquire unverifiable data from configured sources\&. APT will fail at the update command for repositories without valid cryptographically signatures\&. See also +\fBapt-secure\fR(8) +for details on the concept and the implications\&. Configuration Item: +Acquire::AllowInsecureRepositories\&. +.RE +.PP +\fB\-\-show\-progress\fR +.RS 4 +Show user friendly progress information in the terminal window when packages are installed, upgraded or removed\&. For a machine parsable version of this data see README\&.progress\-reporting in the apt doc directory\&. Configuration Items: +Dpkg::Progress +and +Dpkg::Progress\-Fancy\&. +.RE +.PP +\fB\-\-with\-source\fR \fB\fIfilename\fR\fR +.RS 4 +Adds the given file as a source for metadata\&. Can be repeated to add multiple files\&. See +\fB\-\-with\-source\fR +description in +\fBapt-cache\fR(8) +for further details\&. +.RE +.PP +\fB\-h\fR, \fB\-\-help\fR +.RS 4 +Show a short usage summary\&. +.RE +.PP +\fB\-v\fR, \fB\-\-version\fR +.RS 4 +Show the program version\&. +.RE +.PP +\fB\-c\fR, \fB\-\-config\-file\fR +.RS 4 +Configuration File; Specify a configuration file to use\&. The program will read the default configuration file and then this configuration file\&. If configuration settings need to be set before the default configuration files are parsed specify a file with the +\fBAPT_CONFIG\fR +environment variable\&. See +\fBapt.conf\fR(5) +for syntax information\&. +.RE +.PP +\fB\-o\fR, \fB\-\-option\fR +.RS 4 +Set a Configuration Option; This will set an arbitrary configuration option\&. The syntax is +\fB\-o Foo::Bar=bar\fR\&. +\fB\-o\fR +and +\fB\-\-option\fR +can be used multiple times to set different options\&. +.RE +.SH "FILES" +.PP +/etc/apt/sources\&.list +.RS 4 +Locations to fetch packages from\&. Configuration Item: +Dir::Etc::SourceList\&. +.RE +.PP +/etc/apt/sources\&.list\&.d/ +.RS 4 +File fragments for locations to fetch packages from\&. Configuration Item: +Dir::Etc::SourceParts\&. +.RE +.PP +/etc/apt/apt\&.conf +.RS 4 +APT configuration file\&. Configuration Item: +Dir::Etc::Main\&. +.RE +.PP +/etc/apt/apt\&.conf\&.d/ +.RS 4 +APT configuration file fragments\&. Configuration Item: +Dir::Etc::Parts\&. +.RE +.PP +/etc/apt/preferences +.RS 4 +Version preferences file\&. This is where you would specify "pinning", i\&.e\&. a preference to get certain packages from a separate source or from a different version of a distribution\&. Configuration Item: +Dir::Etc::Preferences\&. +.RE +.PP +/etc/apt/preferences\&.d/ +.RS 4 +File fragments for the version preferences\&. Configuration Item: +Dir::Etc::PreferencesParts\&. +.RE +.PP +/var/cache/apt/archives/ +.RS 4 +Storage area for retrieved package files\&. Configuration Item: +Dir::Cache::Archives\&. +.RE +.PP +/var/cache/apt/archives/partial/ +.RS 4 +Storage area for package files in transit\&. Configuration Item: +Dir::Cache::Archives +(partial +will be implicitly appended) +.RE +.PP +/var/lib/apt/lists/ +.RS 4 +Storage area for state information for each package resource specified in +\fBsources.list\fR(5) +Configuration Item: +Dir::State::Lists\&. +.RE +.PP +/var/lib/apt/lists/partial/ +.RS 4 +Storage area for state information in transit\&. Configuration Item: +Dir::State::Lists +(partial +will be implicitly appended) +.RE +.SH "SEE ALSO" +.PP +\fBapt-cache\fR(8), +\fBapt-cdrom\fR(8), +\fBdpkg\fR(1), +\fBsources.list\fR(5), +\fBapt.conf\fR(5), +\fBapt-config\fR(8), +\fBapt-secure\fR(8), The APT User\*(Aqs guide in /usr/share/doc/apt\-doc/, +\fBapt_preferences\fR(5), the APT Howto\&. +.SH "DIAGNOSTICS" +.PP +\fBapt\-get\fR +returns zero on normal operation, decimal 100 on error\&. +.SH "BUGS" +.PP +\m[blue]\fBAPT bug page\fR\m[]\&\s-2\u[1]\d\s+2\&. If you wish to report a bug in APT, please see +/usr/share/doc/debian/bug\-reporting\&.txt +or the +\fBreportbug\fR(1) +command\&. +.SH "AUTHORS" +.PP +\fBJason Gunthorpe\fR +.RS 4 +.RE +.PP +\fBAPT team\fR +.RS 4 +.RE +.SH "NOTES" +.IP " 1." 4 +APT bug page +.RS 4 +\%http://bugs.debian.org/src:apt +.RE diff --git a/packages/apt/man/man8/apt-key.8 b/packages/apt/man/man8/apt-key.8 new file mode 100644 index 000000000..5368b2dab --- /dev/null +++ b/packages/apt/man/man8/apt-key.8 @@ -0,0 +1,190 @@ +'\" t +.\" Title: apt-key +.\" Author: Jason Gunthorpe +.\" Generator: DocBook XSL Stylesheets v1.79.1 +.\" Date: 25\ \&November\ \&2016 +.\" Manual: APT +.\" Source: APT 1.4.9 +.\" Language: English +.\" +.TH "APT\-KEY" "8" "25\ \&November\ \&2016" "APT 1.4.9" "APT" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +apt-key \- APT key management utility +.SH "SYNOPSIS" +.HP \w'\fBapt\-key\fR\ 'u +\fBapt\-key\fR [\fB\-\-keyring\ \fR\fB\fIfilename\fR\fR] {add\ \fIfilename\fR | del\ \fIkeyid\fR | export\ \fIkeyid\fR | exportall | list | finger | adv | update | net\-update | {\-v\ |\ \-\-version} | {\-h\ |\ \-\-help}} +.SH "DESCRIPTION" +.PP +\fBapt\-key\fR +is used to manage the list of keys used by apt to authenticate packages\&. Packages which have been authenticated using these keys will be considered trusted\&. +.PP +Note that if usage of +\fBapt\-key\fR +is desired the additional installation of the GNU Privacy Guard suite (packaged in +gnupg) is required\&. For this reason alone the programmatic usage (especially in package maintainerscripts!) is strongly discouraged\&. Further more the output format of all commands is undefined and can and does change whenever the underlying commands change\&. +\fBapt\-key\fR +will try to detect such usage and generates warnings on stderr in these cases\&. +.SH "SUPPORTED KEYRING FILES" +.PP +apt\-key supports only the binary OpenPGP format (also known as "GPG key public ring") in files with the "gpg" extension, not the keybox database format introduced in newer +\fBgpg\fR(1) +versions as default for keyring files\&. Binary keyring files intended to be used with any apt version should therefore always be created with +\fBgpg \-\-export\fR\&. +.PP +Alternatively, if all systems which should be using the created keyring have at least apt version >= 1\&.4 installed, you can use the ASCII armored format with the "asc" extension instead which can be created with +\fBgpg \-\-armor \-\-export\fR\&. +.SH "COMMANDS" +.PP +\fBadd\fR \fB\fIfilename\fR\fR +.RS 4 +Add a new key to the list of trusted keys\&. The key is read from the filename given with the parameter +\fIfilename\fR +or if the filename is +\- +from standard input\&. +.sp +It is critical that keys added manually via +\fBapt\-key\fR +are verified to belong to the owner of the repositories they claim to be for otherwise the +\fBapt-secure\fR(8) +infrastructure is completely undermined\&. +.sp +\fINote\fR: Instead of using this command a keyring should be placed directly in the +/etc/apt/trusted\&.gpg\&.d/ +directory with a descriptive name and either "gpg" or "asc" as file extension\&. +.RE +.PP +\fBdel\fR \fB\fIkeyid\fR\fR +.RS 4 +Remove a key from the list of trusted keys\&. +.RE +.PP +\fBexport\fR \fB\fIkeyid\fR\fR +.RS 4 +Output the key +\fIkeyid\fR +to standard output\&. +.RE +.PP +\fBexportall\fR +.RS 4 +Output all trusted keys to standard output\&. +.RE +.PP +\fBlist\fR, \fBfinger\fR +.RS 4 +List trusted keys with fingerprints\&. +.RE +.PP +\fBadv\fR +.RS 4 +Pass advanced options to gpg\&. With +\fBadv \-\-recv\-key\fR +you can e\&.g\&. download key from keyservers directly into the trusted set of keys\&. Note that there are +\fIno\fR +checks performed, so it is easy to completely undermine the +\fBapt-secure\fR(8) +infrastructure if used without care\&. +.RE +.PP +\fBupdate\fR (deprecated) +.RS 4 +Update the local keyring with the archive keyring and remove from the local keyring the archive keys which are no longer valid\&. The archive keyring is shipped in the +archive\-keyring +package of your distribution, e\&.g\&. the +debian\-archive\-keyring +package in Debian\&. +.sp +Note that a distribution does not need to and in fact should not use this command any longer and instead ship keyring files in the +/etc/apt/trusted\&.gpg\&.d/ +directory directly as this avoids a dependency on +gnupg +and it is easier to manage keys by simply adding and removing files for maintainers and users alike\&. +.RE +.PP +\fBnet\-update\fR +.RS 4 +Perform an update working similarly to the +\fBupdate\fR +command above, but get the archive keyring from a URI instead and validate it against a master key\&. This requires an installed +\fBwget\fR(1) +and an APT build configured to have a server to fetch from and a master keyring to validate\&. APT in Debian does not support this command, relying on +\fBupdate\fR +instead, but Ubuntu\*(Aqs APT does\&. +.RE +.SH "OPTIONS" +.PP +Note that options need to be defined before the commands described in the previous section\&. +.PP +\fB\-\-keyring\fR \fB\fIfilename\fR\fR +.RS 4 +With this option it is possible to specify a particular keyring file the command should operate on\&. The default is that a command is executed on the +trusted\&.gpg +file as well as on all parts in the +trusted\&.gpg\&.d +directory, though +trusted\&.gpg +is the primary keyring which means that e\&.g\&. new keys are added to this one\&. +.RE +.SH "FILES" +.PP +/etc/apt/trusted\&.gpg +.RS 4 +Keyring of local trusted keys, new keys will be added here\&. Configuration Item: +Dir::Etc::Trusted\&. +.RE +.PP +/etc/apt/trusted\&.gpg\&.d/ +.RS 4 +File fragments for the trusted keys, additional keyrings can be stored here (by other packages or the administrator)\&. Configuration Item +Dir::Etc::TrustedParts\&. +.RE +.SH "SEE ALSO" +.PP +\fBapt-get\fR(8), +\fBapt-secure\fR(8) +.SH "BUGS" +.PP +\m[blue]\fBAPT bug page\fR\m[]\&\s-2\u[1]\d\s+2\&. If you wish to report a bug in APT, please see +/usr/share/doc/debian/bug\-reporting\&.txt +or the +\fBreportbug\fR(1) +command\&. +.SH "AUTHOR" +.PP +APT was written by the APT team +\&. +.SH "AUTHORS" +.PP +\fBJason Gunthorpe\fR +.RS 4 +.RE +.PP +\fBAPT team\fR +.RS 4 +.RE +.SH "NOTES" +.IP " 1." 4 +APT bug page +.RS 4 +\%http://bugs.debian.org/src:apt +.RE diff --git a/packages/apt/man/man8/apt-mark.8 b/packages/apt/man/man8/apt-mark.8 new file mode 100644 index 000000000..c73fa8ad4 --- /dev/null +++ b/packages/apt/man/man8/apt-mark.8 @@ -0,0 +1,191 @@ +'\" t +.\" Title: apt-mark +.\" Author: Mike O\*(AqConnor +.\" Generator: DocBook XSL Stylesheets v1.79.1 +.\" Date: 25\ \&September\ \&2015 +.\" Manual: APT +.\" Source: APT 1.4.9 +.\" Language: English +.\" +.TH "APT\-MARK" "8" "25\ \&September\ \&2015" "APT 1.4.9" "APT" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +apt-mark \- show, set and unset various settings for a package +.SH "SYNOPSIS" +.HP \w'\fBapt\-mark\fR\ 'u +\fBapt\-mark\fR {\fB\-f=\fR\fB\fIfilename\fR\fR | {auto\ |\ manual}\ \fIpkg\fR... | {showauto\ |\ showmanual}\ [\fIpkg\fR...] } | {\-v\ |\ \-\-version} | {\-h\ |\ \-\-help} +.HP \w'\fBapt\-mark\fR\ 'u +\fBapt\-mark\fR {hold\ |\ unhold\ |\ install\ |\ remove\ |\ purge}\ \fIpkg\fR... | {showhold\ |\ showinstall\ |\ showremove\ |\ showpurge}\ [\fIpkg\fR...] +.SH "DESCRIPTION" +.PP +\fBapt\-mark\fR +can be used as a unified front\-end to set various settings for a package, such as marking a package as being automatically/manually installed or changing +\fBdpkg\fR +selections such as hold, install, deinstall and purge which are respected e\&.g\&. by +\fBapt\-get dselect\-upgrade\fR +or +\fBaptitude\fR\&. +.SH "AUTOMATICALLY AND MANUALLY INSTALLED PACKAGES" +.PP +When you request that a package is installed, and as a result other packages are installed to satisfy its dependencies, the dependencies are marked as being automatically installed, while the package you installed explicitly is marked as manually installed\&. Once an automatically installed package is no longer depended on by any manually installed package it is considered no longer needed and e\&.g\&. +\fBapt\-get\fR +or +\fBaptitude\fR +will at least suggest removing them\&. +.PP +\fBauto\fR +.RS 4 +auto +is used to mark a package as being automatically installed, which will cause the package to be removed when no more manually installed packages depend on this package\&. +.RE +.PP +\fBmanual\fR +.RS 4 +manual +is used to mark a package as being manually installed, which will prevent the package from being automatically removed if no other packages depend on it\&. +.RE +.PP +\fBshowauto\fR +.RS 4 +showauto +is used to print a list of automatically installed packages with each package on a new line\&. All automatically installed packages will be listed if no package is given\&. If packages are given only those which are automatically installed will be shown\&. +.RE +.PP +\fBshowmanual\fR +.RS 4 +showmanual +can be used in the same way as +showauto +except that it will print a list of manually installed packages instead\&. +.RE +.SS "Options" +.PP +\fB\-f=\fR\fB\fIfilename\fR\fR, \fB\-\-file=\fR\fB\fIfilename\fR\fR +.RS 4 +Read/Write package stats from the filename given with the parameter +\fIfilename\fR +instead of from the default location, which is +extended_status +in the directory defined by the Configuration Item: +Dir::State\&. +.RE +.SH "PREVENT CHANGES FOR A PACKAGE" +.PP +\fBhold\fR +.RS 4 +hold +is used to mark a package as held back, which will prevent the package from being automatically installed, upgraded or removed\&. +.RE +.PP +\fBunhold\fR +.RS 4 +unhold +is used to cancel a previously set hold on a package to allow all actions again\&. +.RE +.PP +\fBshowhold\fR +.RS 4 +showhold +is used to print a list of packages on hold in the same way as for the other show commands\&. +.RE +.SH "SCHEDULE PACKAGES FOR INSTALL, REMOVE AND PURGE" +.PP +Some front\-ends like +\fBapt\-get dselect\-upgrade\fR +can be used to apply previously scheduled changes to the install state of packages\&. Such changes can be scheduled with the +\fBinstall\fR, +\fBremove\fR +(also known as +\fBdeinstall\fR) and +\fBpurge\fR +commands\&. Packages with a specific selection can be displayed with +\fBshowinstall\fR, +\fBshowremove\fR +and +\fBshowpurge\fR +respectively\&. More information about these so called dpkg selections can be found in +\fBdpkg\fR(1)\&. +.SH "OPTIONS" +.PP +\fB\-h\fR, \fB\-\-help\fR +.RS 4 +Show a short usage summary\&. +.RE +.PP +\fB\-v\fR, \fB\-\-version\fR +.RS 4 +Show the program version\&. +.RE +.PP +\fB\-c\fR, \fB\-\-config\-file\fR +.RS 4 +Configuration File; Specify a configuration file to use\&. The program will read the default configuration file and then this configuration file\&. If configuration settings need to be set before the default configuration files are parsed specify a file with the +\fBAPT_CONFIG\fR +environment variable\&. See +\fBapt.conf\fR(5) +for syntax information\&. +.RE +.PP +\fB\-o\fR, \fB\-\-option\fR +.RS 4 +Set a Configuration Option; This will set an arbitrary configuration option\&. The syntax is +\fB\-o Foo::Bar=bar\fR\&. +\fB\-o\fR +and +\fB\-\-option\fR +can be used multiple times to set different options\&. +.RE +.SH "FILES" +.PP +/var/lib/apt/extended_states +.RS 4 +Status list of auto\-installed packages\&. Configuration Item: +Dir::State::extended_states\&. +.RE +.SH "SEE ALSO" +.PP +\fBapt-get\fR(8),\fBaptitude\fR(8),\fBapt.conf\fR(5) +.SH "DIAGNOSTICS" +.PP +\fBapt\-mark\fR +returns zero on normal operation, non\-zero on error\&. +.SH "BUGS" +.PP +\m[blue]\fBAPT bug page\fR\m[]\&\s-2\u[1]\d\s+2\&. If you wish to report a bug in APT, please see +/usr/share/doc/debian/bug\-reporting\&.txt +or the +\fBreportbug\fR(1) +command\&. +.SH "AUTHORS" +.PP +\fBMike O\*(AqConnor\fR +.RS 4 +.RE +.PP +\fBAPT team\fR +.RS 4 +.RE +.SH "NOTES" +.IP " 1." 4 +APT bug page +.RS 4 +\%http://bugs.debian.org/src:apt +.RE diff --git a/packages/apt/man/man8/apt-secure.8 b/packages/apt/man/man8/apt-secure.8 new file mode 100644 index 000000000..e920c00cd --- /dev/null +++ b/packages/apt/man/man8/apt-secure.8 @@ -0,0 +1,263 @@ +'\" t +.\" Title: apt-secure +.\" Author: Jason Gunthorpe +.\" Generator: DocBook XSL Stylesheets v1.79.1 +.\" Date: 06\ \&August\ \&2016 +.\" Manual: APT +.\" Source: APT 1.4.9 +.\" Language: English +.\" +.TH "APT\-SECURE" "8" "06\ \&August\ \&2016" "APT 1.4.9" "APT" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +apt-secure \- Archive authentication support for APT +.SH "DESCRIPTION" +.PP +Starting with version 0\&.6, +\fBAPT\fR +contains code that does signature checking of the Release file for all repositories\&. This ensures that data like packages in the archive can\*(Aqt be modified by people who have no access to the Release file signing key\&. Starting with version 1\&.1 +\fBAPT\fR +requires repositories to provide recent authentication information for unimpeded usage of the repository\&. +.PP +If an archive has an unsigned Release file or no Release file at all current APT versions will refuse to download data from them by default in +\fBupdate\fR +operations and even if forced to download front\-ends like +\fBapt-get\fR(8) +will require explicit confirmation if an installation request includes a package from such an unauthenticated archive\&. +.PP +As a temporary exception +\fBapt-get\fR(8) +(not +\fBapt\fR(8)!) raises warnings only if it encounters unauthenticated archives to give a slightly longer grace period on this backward compatibility effecting change\&. This exception will be removed in future releases and you can opt\-out of this grace period by setting the configuration option +\fBBinary::apt\-get::Acquire::AllowInsecureRepositories\fR +to +false +or +\fB\-\-no\-allow\-insecure\-repositories\fR +on the command line\&. +.PP +You can force all APT clients to raise only warnings by setting the configuration option +\fBAcquire::AllowInsecureRepositories\fR +to +true\&. Individual repositories can also be allowed to be insecure via the +\fBsources.list\fR(5) +option +allow\-insecure=yes\&. Note that insecure repositories are strongly discouraged and all options to force apt to continue supporting them will eventually be removed\&. Users also have the +\fBTrusted\fR +option available to disable even the warnings, but be sure to understand the implications as detailed in +\fBsources.list\fR(5)\&. +.PP +A repository which previously was authenticated but would loose this state in an +\fBupdate\fR +operation raises an error in all APT clients irrespective of the option to allow or forbid usage of insecure repositories\&. The error can be overcome by additionally setting +\fBAcquire::AllowDowngradeToInsecureRepositories\fR +to +true +or for Individual repositories with the +\fBsources.list\fR(5) +option +allow\-downgrade\-to\-insecure=yes\&. +.PP +Note: All APT\-based package management front\-ends like +\fBapt-get\fR(8), +\fBaptitude\fR(8) +and +\fBsynaptic\fR(8) +support this authentication feature, so this manpage uses +APT +to refer to them all for simplicity only\&. +.SH "TRUSTED REPOSITORIES" +.PP +The chain of trust from an APT archive to the end user is made up of several steps\&. +\fBapt\-secure\fR +is the last step in this chain; trusting an archive does not mean that you trust its packages not to contain malicious code, but means that you trust the archive maintainer\&. It\*(Aqs the archive maintainer\*(Aqs responsibility to ensure that the archive\*(Aqs integrity is preserved\&. +.PP +apt\-secure does not review signatures at a package level\&. If you require tools to do this you should look at +\fBdebsig\-verify\fR +and +\fBdebsign\fR +(provided in the debsig\-verify and devscripts packages respectively)\&. +.PP +The chain of trust in Debian starts (e\&.g\&.) when a maintainer uploads a new package or a new version of a package to the Debian archive\&. In order to become effective, this upload needs to be signed by a key contained in one of the Debian package maintainer keyrings (available in the debian\-keyring package)\&. Maintainers\*(Aq keys are signed by other maintainers following pre\-established procedures to ensure the identity of the key holder\&. Similar procedures exist in all Debian\-based distributions\&. +.PP +Once the uploaded package is verified and included in the archive, the maintainer signature is stripped off, and checksums of the package are computed and put in the Packages file\&. The checksums of all of the Packages files are then computed and put into the Release file\&. The Release file is then signed by the archive key for this Debian release, and distributed alongside the packages and the Packages files on Debian mirrors\&. The keys are in the Debian archive keyring available in the +debian\-archive\-keyring +package\&. +.PP +End users can check the signature of the Release file, extract a checksum of a package from it and compare it with the checksum of the package they downloaded by hand \- or rely on APT doing this automatically\&. +.PP +Notice that this is distinct from checking signatures on a per package basis\&. It is designed to prevent two possible attacks: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Network "man in the middle" attacks\&. Without signature checking, malicious agents can introduce themselves into the package download process and provide malicious software either by controlling a network element (router, switch, etc\&.) or by redirecting traffic to a rogue server (through ARP or DNS spoofing attacks)\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Mirror network compromise\&. Without signature checking, a malicious agent can compromise a mirror host and modify the files in it to propagate malicious software to all users downloading packages from that host\&. +.RE +.PP +However, it does not defend against a compromise of the master server itself (which signs the packages) or against a compromise of the key used to sign the Release files\&. In any case, this mechanism can complement a per\-package signature\&. +.SH "USER CONFIGURATION" +.PP +\fBapt\-key\fR +is the program that manages the list of keys used by APT to trust repositories\&. It can be used to add or remove keys as well as list the trusted keys\&. Limiting which key(s) are able to sign which archive is possible via the +\fBSigned\-By\fR +in +\fBsources.list\fR(5)\&. +.PP +Note that a default installation already contains all keys to securely acquire packages from the default repositories, so fiddling with +\fBapt\-key\fR +is only needed if third\-party repositories are added\&. +.PP +In order to add a new key you need to first download it (you should make sure you are using a trusted communication channel when retrieving it), add it with +\fBapt\-key\fR +and then run +\fBapt\-get update\fR +so that apt can download and verify the +InRelease +or +Release\&.gpg +files from the archives you have configured\&. +.SH "ARCHIVE CONFIGURATION" +.PP +If you want to provide archive signatures in an archive under your maintenance you have to: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fICreate a toplevel Release file\fR, if it does not exist already\&. You can do this by running +\fBapt\-ftparchive release\fR +(provided in apt\-utils)\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fISign it\fR\&. You can do this by running +\fBgpg \-\-clearsign \-o InRelease Release\fR +and +\fBgpg \-abs \-o Release\&.gpg Release\fR\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIPublish the key fingerprint\fR, so that your users will know what key they need to import in order to authenticate the files in the archive\&. It is best to ship your key in its own keyring package like Debian does with +debian\-archive\-keyring +to be able to distribute updates and key transitions automatically later\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIProvide instructions on how to add your archive and key\fR\&. If your users can\*(Aqt acquire your key securely the chain of trust described above is broken\&. How you can help users add your key depends on your archive and target audience ranging from having your keyring package included in another archive users already have configured (like the default repositories of their distribution) to leveraging the web of trust\&. +.RE +.PP +Whenever the contents of the archive change (new packages are added or removed) the archive maintainer has to follow the first two steps outlined above\&. +.SH "SEE ALSO" +.PP +\fBapt.conf\fR(5), +\fBapt-get\fR(8), +\fBsources.list\fR(5), +\fBapt-key\fR(8), +\fBapt-ftparchive\fR(1), +\fBdebsign\fR(1), +\fBdebsig-verify\fR(1), +\fBgpg\fR(1) +.PP +For more background information you might want to review the +\m[blue]\fBDebian Security Infrastructure\fR\m[]\&\s-2\u[1]\d\s+2 +chapter of the Securing Debian Manual (also available in the harden\-doc package) and the +\m[blue]\fBStrong Distribution HOWTO\fR\m[]\&\s-2\u[2]\d\s+2 +by V\&. Alex Brennen\&. +.SH "BUGS" +.PP +\m[blue]\fBAPT bug page\fR\m[]\&\s-2\u[3]\d\s+2\&. If you wish to report a bug in APT, please see +/usr/share/doc/debian/bug\-reporting\&.txt +or the +\fBreportbug\fR(1) +command\&. +.SH "AUTHOR" +.PP +APT was written by the APT team +\&. +.SH "MANPAGE AUTHORS" +.PP +This man\-page is based on the work of Javier Fernández\-Sanguino Peña, Isaac Jones, Colin Walters, Florian Weimer and Michael Vogt\&. +.SH "AUTHORS" +.PP +\fBJason Gunthorpe\fR +.RS 4 +.RE +.PP +\fBAPT team\fR +.RS 4 +.RE +.SH "NOTES" +.IP " 1." 4 +Debian Security Infrastructure +.RS 4 +\%https://www.debian.org/doc/manuals/securing-debian-howto/ch7 +.RE +.IP " 2." 4 +Strong Distribution HOWTO +.RS 4 +\%http://www.cryptnet.net/fdp/crypto/strong_distro.html +.RE +.IP " 3." 4 +APT bug page +.RS 4 +\%http://bugs.debian.org/src:apt +.RE diff --git a/packages/apt/man/man8/apt.8 b/packages/apt/man/man8/apt.8 new file mode 100644 index 000000000..5ed03997e --- /dev/null +++ b/packages/apt/man/man8/apt.8 @@ -0,0 +1,170 @@ +'\" t +.\" Title: apt +.\" Author: APT team +.\" Generator: DocBook XSL Stylesheets v1.79.1 +.\" Date: 20\ \&October\ \&2015 +.\" Manual: APT +.\" Source: APT 1.4.9 +.\" Language: English +.\" +.TH "APT" "8" "20\ \&October\ \&2015" "APT 1.4.9" "APT" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +apt \- command\-line interface +.SH "SYNOPSIS" +.HP \w'\fBapt\fR\ 'u +\fBapt\fR [\fB\-h\fR] [\fB\-o=\fR\fB\fIconfig_string\fR\fR] [\fB\-c=\fR\fB\fIconfig_file\fR\fR] [\fB\-t=\fR\fB\fItarget_release\fR\fR] [\fB\-a=\fR\fB\fIarchitecture\fR\fR] {list | search | show | update | install\ \fIpkg\fR\ [{=\fIpkg_version_number\fR\ |\ /\fItarget_release\fR}]... | remove\ \fIpkg\fR... | upgrade | full\-upgrade | edit\-sources | {\-v\ |\ \-\-version} | {\-h\ |\ \-\-help}} +.SH "DESCRIPTION" +.PP +\fBapt\fR +provides a high\-level commandline interface for the package management system\&. It is intended as an end user interface and enables some options better suited for interactive usage by default compared to more specialized APT tools like +\fBapt-get\fR(8) +and +\fBapt-cache\fR(8)\&. +.PP +Much like +\fBapt\fR +itself, its manpage is intended as an end user interface and as such only mentions the most used commands and options partly to not duplicate information in multiple places and partly to avoid overwhelming readers with a cornucopia of options and details\&. +.PP +\fBupdate\fR (\fBapt-get\fR(8)) +.RS 4 +\fBupdate\fR +is used to download package information from all configured sources\&. Other commands operate on this data to e\&.g\&. perform package upgrades or search in and display details about all packages available for installation\&. +.RE +.PP +\fBupgrade\fR (\fBapt-get\fR(8)) +.RS 4 +\fBupgrade\fR +is used to install available upgrades of all packages currently installed on the system from the sources configured via +\fBsources.list\fR(5)\&. New packages will be installed if required to satisfy dependencies, but existing packages will never be removed\&. If an upgrade for a package requires the remove of an installed package the upgrade for this package isn\*(Aqt performed\&. +.RE +.PP +\fBfull\-upgrade\fR (\fBapt-get\fR(8)) +.RS 4 +full\-upgrade +performs the function of upgrade but will remove currently installed packages if this is needed to upgrade the system as a whole\&. +.RE +.PP +\fBinstall\fR, \fBremove\fR, \fBpurge\fR (\fBapt-get\fR(8)) +.RS 4 +Performs the requested action on one or more packages specified via +\fBregex\fR(7), +\fBglob\fR(7) +or exact match\&. The requested action can be overridden for specific packages by append a plus (+) to the package name to install this package or a minus (\-) to remove it\&. +.sp +A specific version of a package can be selected for installation by following the package name with an equals (=) and the version of the package to select\&. Alternatively the version from a specific release can be selected by following the package name with a forward slash (/) and codename (stretch, buster, sid \&...) or suite name (stable, testing, unstable)\&. This will also select versions from this release for dependencies of this package if needed to satisfy the request\&. +.sp +Removing a package removes all packaged data, but leaves usually small (modified) user configuration files behind, in case the remove was an accident\&. Just issuing an installation request for the accidentally removed package will restore its function as before in that case\&. On the other hand you can get rid of these leftovers by calling +\fBpurge\fR +even on already removed packages\&. Note that this does not affect any data or configuration stored in your home directory\&. +.RE +.PP +\fBautoremove\fR (\fBapt-get\fR(8)) +.RS 4 +autoremove +is used to remove packages that were automatically installed to satisfy dependencies for other packages and are now no longer needed as dependencies changed or the package(s) needing them were removed in the meantime\&. +.sp +You should check that the list does not include applications you have grown to like even though they were once installed just as a dependency of another package\&. You can mark such a package as manually installed by using +\fBapt-mark\fR(8)\&. Packages which you have installed explicitly via +\fBinstall\fR +are also never proposed for automatic removal\&. +.RE +.PP +\fBsearch\fR (\fBapt-cache\fR(8)) +.RS 4 +\fBsearch\fR +can be used to search for the given +\fBregex\fR(7) +term(s) in the list of available packages and display matches\&. This can e\&.g\&. be useful if you are looking for packages having a specific feature\&. If you are looking for a package including a specific file try +\fBapt-file\fR(1)\&. +.RE +.PP +\fBshow\fR (\fBapt-cache\fR(8)) +.RS 4 +Show information about the given package(s) including its dependencies, installation and download size, sources the package is available from, the description of the packages content and much more\&. It can e\&.g\&. be helpful to look at this information before allowing +\fBapt\fR(8) +to remove a package or while searching for new packages to install\&. +.RE +.PP +\fBlist\fR (work\-in\-progress) +.RS 4 +\fBlist\fR +is somewhat similar to +\fBdpkg\-query \-\-list\fR +in that it can display a list of packages satisfying certain criteria\&. It supports +\fBglob\fR(7) +patterns for matching package names as well as options to list installed (\fB\-\-installed\fR), upgradeable (\fB\-\-upgradeable\fR) or all available (\fB\-\-all\-versions\fR) versions\&. +.RE +.PP +\fBedit\-sources\fR (work\-in\-progress) +.RS 4 +edit\-sources +lets you edit your +\fBsources.list\fR(5) +files in your preferred texteditor while also providing basic sanity checks\&. +.RE +.SH "SCRIPT USAGE AND DIFFERENCES FROM OTHER APT TOOLS" +.PP +The +\fBapt\fR(8) +commandline is designed as an end\-user tool and it may change behavior between versions\&. While it tries not to break backward compatibility this is not guaranteed either if a change seems beneficial for interactive use\&. +.PP +All features of +\fBapt\fR(8) +are available in dedicated APT tools like +\fBapt-get\fR(8) +and +\fBapt-cache\fR(8) +as well\&. +\fBapt\fR(8) +just changes the default value of some options (see +\fBapt.conf\fR(5) +and specifically the Binary scope)\&. So you should prefer using these commands (potentially with some additional options enabled) in your scripts as they keep backward compatibility as much as possible\&. +.SH "SEE ALSO" +.PP +\fBapt-get\fR(8), +\fBapt-cache\fR(8), +\fBsources.list\fR(5), +\fBapt.conf\fR(5), +\fBapt-config\fR(8), The APT User\*(Aqs guide in /usr/share/doc/apt\-doc/, +\fBapt_preferences\fR(5), the APT Howto\&. +.SH "DIAGNOSTICS" +.PP +\fBapt\fR +returns zero on normal operation, decimal 100 on error\&. +.SH "BUGS" +.PP +\m[blue]\fBAPT bug page\fR\m[]\&\s-2\u[1]\d\s+2\&. If you wish to report a bug in APT, please see +/usr/share/doc/debian/bug\-reporting\&.txt +or the +\fBreportbug\fR(1) +command\&. +.SH "AUTHOR" +.PP +\fBAPT team\fR +.RS 4 +.RE +.SH "NOTES" +.IP " 1." 4 +APT bug page +.RS 4 +\%http://bugs.debian.org/src:apt +.RE