X-Git-Url: https://git.saurik.com/apt.git/blobdiff_plain/c8e5d01add32db96106241794de38bd7d7d26990..7c8206bf26b8ef6020b543bbc027305dee8f2308:/doc/sources.list.5.xml?ds=sidebyside diff --git a/doc/sources.list.5.xml b/doc/sources.list.5.xml index 09a5cbb6d..cfd98e545 100644 --- a/doc/sources.list.5.xml +++ b/doc/sources.list.5.xml @@ -1,13 +1,9 @@ - -%aptent; - - -%aptverbatiment; - + %aptent; + %aptverbatiment; + %aptvendor; ]> @@ -18,7 +14,7 @@ &apt-email; &apt-product; - 29 February 2004 + 2014-01-18T00:00:00Z @@ -30,129 +26,301 @@ sources.list - Package resource list for APT + List of configured APT data sources Description - The package resource list is used to locate archives of the package - distribution system in use on the system. At this time, this manual page - documents only the packaging system used by the Debian GNU/Linux system. - This control file is /etc/apt/sources.list. - - The source list is designed to support any number of active sources and a - variety of source media. The file lists one source per line, with the - most preferred source listed first. The format of each line is: - type uri args The first item, type - determines the format for args. uri is - a Universal Resource Identifier - (URI), which is a superset of the more specific and well-known Universal - Resource Locator, or URL. The rest of the line can be marked as a comment - by using a #. + + The source list /etc/apt/sources.list and the 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 apt-get update (or + by an equivalent command from another APT front-end). + sources.list.d - The /etc/apt/sources.list.d directory provides - a way to add sources.list entries in separate files. - The format is the same as for the regular sources.list file. - File names need to end with - .list and 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 if the file - doesn't match a pattern in the Dir::Ignore-Files-Silently - configuration list - in this case it will be silently ignored. + 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. - The deb and deb-src types - The deb type describes a typical two-level Debian - archive, distribution/component. Typically, - distribution is generally an archivename like + one line style format + + 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 a equal sign (=). Multivalue options have + also -= and += as separator which + instead of replacing the default with the given value(s) modify the default + value(s) to remove or include the given values. + + 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 its own might not + expect to encounter options as they were uncommon before the introduction of + multi-architecture support. + + + + deb822 style format + + Files in this format have the extension .sources. + The format is similar in syntax to other files used by Debian and its + derivatives, like the metadata itself 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. + + 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 and + deprecating the previously described one line style format as it is + easier to create, extend and modify by 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 could encounter problems with software not supporting + the format yet. + + + + The deb and deb-src types: General Format + 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 &stable-codename; or &testing-codename; - while component is one of main contrib or + while component is one of main, contrib or non-free. The - deb-src type describes a debian distribution's source + deb-src type references a Debian distribution's source code in the same form as the deb type. A deb-src line is required to fetch source indexes. - - The format for a sources.list entry using the + The format for two one line style entries using the deb and deb-src types is: - deb [ options ] uri distribution [component1] [component2] [...] + deb [ option1=value1 option2=value2 ] uri suite [component1] [component2] [...] +deb-src [ option1=value1 option2=value2 ] uri suite [component1] [component2] [...] + + Alternatively the equivalent entry in deb822 style looks like this: + + Types: deb deb-src + URIs: uri + Suites: suite + Components: [component1] [component2] [...] + option1: value1 + option2: value2 + + The URI for the deb type must specify the base of the - Debian distribution, from which APT will find the information it needs. - distribution can specify an exact path, in which case the - components must be omitted and distribution must end with - a slash (/). This is useful for when the case only a particular sub-section of the - archive denoted by the URI is of interest. - If distribution does not specify an exact path, at least + 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. - distribution may also contain a variable, + suite may also contain a variable, $(ARCH) - which expands to the Debian architecture (i386, m68k, powerpc, ...) - used on the system. This permits architecture-independent + 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. - 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 an FTP connection, close it, do something else, - and then re-establish a connection to that same host. This feature is - useful for accessing busy FTP sites with limits on the number of - simultaneous anonymous users. APT also parallelizes connections to - different hosts to more effectively deal with sites with low bandwidth. - - options is always optional and needs to be surounded by - square brackets. It can consist of multiple settings in the form - setting=value. - Multiple settings are separated by spaces. The following settings are supported by APT, - note though that unsupported settings will be ignored silently: - arch=arch1,arch2,… - can be used to specify for which architectures packages information should - be downloaded. If this option is not set all architectures defined by the - APT::Architectures option will be downloaded. - + 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. 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). - Some examples: - -deb http://ftp.debian.org/debian &stable-codename; main contrib non-free -deb http://security.debian.org/ &stable-codename;/updates main contrib non-free - + As an example, the sources for your distribution could look like this + in one line style format: + &sourceslist-list-format; or like this in + deb822 style format: + &sourceslist-sources-format; + + The deb and deb-src types: Options + Each source entry can have options specified modifying which and how + the source is accessed and data acquired from it. Format, syntax and names + of the options varies between the two formats one line and deb822 style + as described, but they have both the same options available. For simplicity + we list the deb822 fieldname and provide the one line name in brackets. + Remember that beside setting multivalue options explicitly, there is also + the option to modify them based on the default, but we aren't listing those + names explicitly here. Unsupported options are silently ignored by all + APT versions. + + + + () is a multivalue option defining for + which architectures information should be downloaded. If this + option isn't set the default is all architectures as defined by + the config option. + + + + () is a multivalue option defining for + which languages information like translated package + descriptions should be downloaded. If this option isn't set + the default is all languages as defined by the + config option. + + + + () 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 + configuration scope. + Aditionally, specific targets can be enabled or disabled by + using the identifier as field name instead of using this + multivalue option. + + + () + 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't announce the availability of PDiffs. Defaults to the + value of the option with the same name for a specific index file + defined in the scope, + which itself default to the value of configuration option + which defaults to + yes. + + + + + + Further more, there are options which if set effect + all 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. + + + () + 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 a + fingerprint of a key in either the + trusted.gpg keyring or in one of the + keyrings in the trusted.gpg.d/ directory + (see apt-key fingerprint). If the option is + set only the key(s) in this keyring or only the key with this + fingerprint is used for the &apt-secure; verification of this + repository. Otherwise all keys in the trusted keyrings are + considered valid signers for this repository. + + + () + is a yes/no value which controls if APT should try to detect + replay attacks. A repository creator can declare until then 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. Beside + increasing security as a malicious attacker can't sent old data + forever denying a user to be able to upgrade to a new version, + this also helps users identify mirrors which are no longer + updated. Some repositories like historic archives aren't + updated anymore by design through, so this check can be + disabled by setting this option to no. + Defaults to the value of configuration option + which itself + defaults to yes. + + + + () and + + () 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 + and + which are both unset by + default. + + + + + URI specification - The currently recognized URI types are cdrom, file, http, ftp, copy, - ssh, rsh. + The currently recognized URI types are: - file + file 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. - cdrom + cdrom - The cdrom scheme allows APT to use a local CDROM drive with media + The cdrom scheme allows APT to use a local CD-ROM drive with media swapping. Use the &apt-cdrom; program to create cdrom entries in the source list. - http + http The http scheme specifies an HTTP server for the archive. If an environment variable http_proxy is set with the format @@ -163,43 +331,41 @@ deb http://security.debian.org/ &stable-codename;/updates main contrib non-free Note that this is an insecure method of authentication. - ftp + ftp The ftp scheme specifies an FTP server for the archive. APT's FTP behavior is highly configurable; for more information see the - &apt-conf; manual page. Please note that a ftp proxy can be specified + &apt-conf; manual page. Please note that an FTP proxy can be specified by using the ftp_proxy environment variable. It is possible - to specify a http proxy (http proxy servers often understand ftp urls) - using this method and ONLY this method. ftp proxies using http specified in + to specify an HTTP proxy (HTTP proxy servers often understand FTP URLs) + using this environment variable and only this + environment variable. Proxies using HTTP specified in the configuration file will be ignored. - copy + copy 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 a zip disk to copy files around with APT. + This is useful for people using removable media to copy files around with APT. - rshssh + rshssh - The rsh/ssh method invokes rsh/ssh to connect to a remote host - as a given user and access the files. It is a good idea to do prior - arrangements with RSA keys or rhosts. - Access to files on the remote uses standard find and - dd - commands to perform the file transfers from the remote. + 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 find and dd + commands are used to perform the file transfers from the remote host. + - more recognizable URI types + adding more recognizable URI types - APT can be extended with more methods shipped in other optional packages which should - follow the nameing scheme apt-transport-method. - The APT team e.g. maintains also the apt-transport-https package which - provides access methods for https-URIs with features similar to the http method, but other - methods for using e.g. debtorrent are also available, see - apt-transport-debtorrent - 1. + APT can be extended with more methods shipped in other optional packages, which should + follow the naming scheme apt-transport-method. + 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 &apt-transport-debtorrent;. @@ -207,34 +373,70 @@ deb http://security.debian.org/ &stable-codename;/updates main contrib non-free Examples - Uses the archive stored locally (or NFS mounted) at /home/jason/debian + Uses the archive stored locally (or NFS mounted) at /home/apt/debian for stable/main, stable/contrib, and stable/non-free. - deb file:/home/jason/debian stable main contrib non-free + deb file:/home/apt/debian stable main contrib non-free + Types: deb +URIs: file:/home/apt/debian +Suites: stable +Components: main contrib non-free As above, except this uses the unstable (development) distribution. - deb file:/home/jason/debian unstable main contrib non-free + deb file:/home/apt/debian unstable main contrib non-free + Types: deb +URIs: file:/home/apt/debian +Suites: unstable +Components: main contrib non-free Source line for the above - deb-src file:/home/jason/debian unstable main contrib non-free + deb-src file:/home/apt/debian unstable main contrib non-free + Types: deb-src +URIs: file:/home/apt/debian +Suites: unstable +Components: main contrib non-free + The first line gets package information for the architectures in APT::Architectures while the second always retrieves amd64 and armel. - deb http://ftp.debian.org/debian &stable-codename; main -deb [ arch=amd64,armel ] http://ftp.debian.org/debian &stable-codename; main + deb http://httpredir.debian.org/debian &stable-codename; main +deb [ arch=amd64,armel ] http://httpredir.debian.org/debian &stable-codename; main + Types: deb +URIs: http://httpredir.debian.org/debian +Suites: &stable-codename; +Components: main + +Types: deb +URIs: http://httpredir.debian.org/debian +Suites: &stable-codename; +Components: main +Architectures: amd64 armel + Uses HTTP to access the archive at archive.debian.org, and uses only the hamm/main area. deb http://archive.debian.org/debian-archive hamm main + Types: deb +URIs: http://archive.debian.org/debian-archive +Suites: hamm +Components: main Uses FTP to access the archive at ftp.debian.org, under the debian directory, and uses only the &stable-codename;/contrib area. deb ftp://ftp.debian.org/debian &stable-codename; contrib + Types: deb +URIs: ftp://ftp.debian.org/debian +Suites: &stable-codename; +Components: contrib 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. deb ftp://ftp.debian.org/debian unstable contrib + Types: deb +URIs: ftp://ftp.debian.org/debian +Suites: unstable +Components: contrib Uses HTTP to access the archive at ftp.tlh.debian.org, under the universe directory, and uses only files found under @@ -244,15 +446,32 @@ deb [ arch=amd64,armel ] http://ftp.debian.org/debian &stable-codename; maindeb http://ftp.tlh.debian.org/universe unstable/binary-$(ARCH)/ + Types: deb +URIs: http://ftp.tlh.debian.org/universe +Suites: unstable/binary-$(ARCH)/ + + Uses HTTP to get binary packages as well as sources from the stable, testing and unstable + suites and the components main and contrib. + deb http://httpredir.debian.org/debian stable main contrib +deb-src http://httpredir.debian.org/debian stable main contrib +deb http://httpredir.debian.org/debian testing main contrib +deb-src http://httpredir.debian.org/debian testing main contrib +deb http://httpredir.debian.org/debian unstable main contrib +deb-src http://httpredir.debian.org/debian unstable main contrib + Types: deb deb-src +URIs: http://httpredir.debian.org/debian +Suites: stable testing unstable +Components: main contrib + + - + See Also - &apt-cache; &apt-conf; + &apt-get;, &apt-conf; &manbugs; - - +