diff options
Diffstat (limited to '')
| -rw-r--r-- | doc/sources.list.5.xml | 586 |
1 files changed, 586 insertions, 0 deletions
diff --git a/doc/sources.list.5.xml b/doc/sources.list.5.xml new file mode 100644 index 0000000..3021549 --- /dev/null +++ b/doc/sources.list.5.xml @@ -0,0 +1,586 @@ +<?xml version="1.0" encoding="utf-8" standalone="no"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % aptent SYSTEM "apt.ent"> %aptent; +<!ENTITY % aptverbatiment SYSTEM "apt-verbatim.ent"> %aptverbatiment; +<!ENTITY % aptvendor SYSTEM "apt-vendor.ent"> %aptvendor; +]> + +<refentry> + + <refentryinfo> + &apt-author.jgunthorpe; + &apt-author.team; + &apt-email; + &apt-product; + <!-- The last update date --> + <date>2018-08-17T00:00:00Z</date> + </refentryinfo> + + <refmeta> + <refentrytitle>sources.list</refentrytitle> + <manvolnum>5</manvolnum> + <refmiscinfo class="manual">APT</refmiscinfo> + </refmeta> + + <!-- Man page title --> + <refnamediv> + <refname>sources.list</refname> + <refpurpose>List of configured APT data sources</refpurpose> + </refnamediv> + + <refsect1><title>Description</title> + <para> + The source list <filename>/etc/apt/sources.list</filename> and the + files contained in <filename>/etc/apt/sources.list.d/</filename> 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 <command>apt-get update</command> (or + by an equivalent command from another APT front-end). + </para> + </refsect1> + + <refsect1><title>sources.list.d</title> + <para>The <filename>/etc/apt/sources.list.d</filename> 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 <filename>.list</filename> or + <filename>.sources</filename> 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 <literal>Dir::Ignore-Files-Silently</literal> + configuration list - in which case it will be silently ignored.</para> + </refsect1> + + <refsect1><title>One-Line-Style Format</title> + <para> + Files in this format have the extension <filename>.list</filename>. + Each line specifying a source starts with a type (e.g. <literal>deb-src</literal>) + followed by options and arguments for this type. + + Individual entries cannot be continued onto a following line. Empty lines + are ignored, and a <literal>#</literal> 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 (<literal>[]</literal>) + 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 (<literal>,</literal>). An option name is separated from its + value(s) by an equals sign (<literal>=</literal>). Multivalue options also + have <literal>-=</literal> and <literal>+=</literal> 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. + </para><para> + 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. + </para> + </refsect1> + + <refsect1><title>deb822-Style Format</title> + <para> + Files in this format have the extension <filename>.sources</filename>. + 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 <filename>debian/control</filename> file in a Debian source package. + + Individual entries are separated by an empty line; additional empty + lines are ignored, and a <literal>#</literal> 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 re-enables it. + + Options have the same syntax as every other field: A fieldname separated by + a colon (<literal>:</literal>) and optionally spaces from its value(s). + Note especially that multiple values are separated by whitespaces (like spaces, + tabs and newlines), not by commas as in the one-line format. + + Multivalue fields like <literal>Architectures</literal> also have + <literal>Architectures-Add</literal> and <literal>Architectures-Remove</literal> + to modify the default value rather than replacing it. + </para><para> + 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. + </para> + </refsect1> + + <refsect1><title>The deb and deb-src Types: General Format</title> + <para>The <literal>deb</literal> type references a typical two-level Debian + archive, <filename>distribution/component</filename>. The + <literal>distribution</literal> is generally a suite name like + <literal>stable</literal> or <literal>testing</literal> or a codename like + <literal>&debian-stable-codename;</literal> or <literal>&debian-testing-codename;</literal> + while component is one of <literal>main</literal>, <literal>contrib</literal> or + <literal>non-free</literal>. The + <literal>deb-src</literal> type references a Debian distribution's source + code in the same form as the <literal>deb</literal> type. + A <literal>deb-src</literal> line is required to fetch source indexes.</para> + + <para>The format for two one-line-style entries using the + <literal>deb</literal> and <literal>deb-src</literal> types is:</para> + + <literallayout>deb [ option1=value1 option2=value2 ] uri suite [component1] [component2] [...] +deb-src [ option1=value1 option2=value2 ] uri suite [component1] [component2] [...]</literallayout> + + <para>Alternatively the equivalent entry in deb822 style looks like this: + <literallayout> + Types: deb deb-src + URIs: uri + Suites: suite + Components: [component1] [component2] [...] + option1: value1 + option2: value2 + </literallayout> + </para> + + <para>The URI for the <literal>deb</literal> type must specify the base of the + Debian distribution, from which APT will find the information it needs. + <literal>suite</literal> can specify an exact path, in which case the + components must be omitted and <literal>suite</literal> must end with + a slash (<literal>/</literal>). This is useful for the case when only a + particular sub-directory of the archive denoted by the URI is of interest. + If <literal>suite</literal> does not specify an exact path, at least + one <literal>component</literal> must be present.</para> + + <para><literal>suite</literal> may also contain a variable, + <literal>$(ARCH)</literal> + which expands to the Debian architecture (such as <literal>amd64</literal> or + <literal>armel</literal>) used on the system. This permits architecture-independent + <filename>sources.list</filename> files to be used. In general this is only + of interest when specifying an exact path; <literal>APT</literal> will + automatically generate a URI with the current architecture otherwise.</para> + + <para>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.</para> + + <para>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).</para> + + <para>As an example, the sources for your distribution could look like this + in one-line-style format: + <literallayout>&sourceslist-list-format;</literallayout> or like this in + deb822 style format: + <literallayout>&sourceslist-sources-format;</literallayout></para> + </refsect1> + + <refsect1><title>The deb and deb-src types: Options</title> + <para>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't listing those + names explicitly here. Unsupported options are silently ignored by all + APT versions. + + <itemizedlist> + <listitem><para><option>Architectures</option> + (<option>arch</option>) 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 <option>APT::Architectures</option> config option. + </para></listitem> + + <listitem><para><option>Languages</option> + (<option>lang</option>) is a multivalue option defining for + which languages information such as translated package + descriptions should be downloaded. If this option isn't set + the default is all languages as defined by the + <option>Acquire::Languages</option> config option. + </para></listitem> + + <listitem><para><option>Targets</option> + (<option>target</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 + <option>Acquire::IndexTargets</option> configuration scope + (targets are specified by their name in the + <literal>Created-By</literal> field). + Additionally, targets can be enabled or disabled by using the + <literal>Identifier</literal> field as an option with a boolean + value instead of using this multivalue option. + </para></listitem> + + <listitem><para><option>PDiffs</option> (<option>pdiffs</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 <option>Acquire::IndexTargets</option> scope, + which itself defaults to the value of configuration option + <option>Acquire::PDiffs</option> which defaults to + <literal>yes</literal>. + </para></listitem> + + <listitem><para><option>By-Hash</option> (<option>by-hash</option>) + can have the value <literal>yes</literal>, <literal>no</literal> + or <literal>force</literal> 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 <literal>yes</literal> or + <literal>no</literal> value activates/disables the use of this + feature if this source indicates support for it, while + <literal>force</literal> 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 + <option>Acquire::IndexTargets</option> scope, which itself + defaults to the value of configuration option + <option>Acquire::By-Hash</option> which defaults to + <literal>yes</literal>. + </para></listitem> + + </itemizedlist> + + Furthermore, there are options which if set affect + <emphasis>all</emphasis> 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. + + <itemizedlist> + <listitem><para><option>Allow-Insecure</option> (<option>allow-insecure</option>), + <option>Allow-Weak</option> (<option>allow-weak</option>) and + <option>Allow-Downgrade-To-Insecure</option> (<option>allow-downgrade-to-insecure</option>) + are boolean values which all default to <literal>no</literal>. + If set to <literal>yes</literal> they circumvent parts of &apt-secure; + and should therefore not be used lightly! + </para></listitem> + + <listitem><para><option>Trusted</option> (<option>trusted</option>) + 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 <literal>yes</literal> tells APT + always to consider this source as trusted, even if it doesn't pass + authentication checks. It disables parts of &apt-secure;, and should + therefore only be used in a local and trusted context (if at all) as + otherwise security is breached. The value <literal>no</literal> does + the opposite, causing the source to be handled as untrusted even if + the authentication checks passed successfully. The default value can't + be set explicitly. + </para></listitem> + + <listitem><para><option>Signed-By</option> (<option>signed-by</option>) + is an option to require a repository to pass &apt-secure; verification + with a certain set of keys rather than all trusted keys apt has configured. + It is specified as a list of absolute paths to keyring files (have to be + accessible and readable for the <literal>_apt</literal> system user, + so ensure everyone has read-permissions on the file) and fingerprints + of keys to select from these keyrings. If no keyring files are specified + the default is the <filename>trusted.gpg</filename> keyring and + all keyrings in the <filename>trusted.gpg.d/</filename> directory + (see <command>apt-key fingerprint</command>). If no fingerprint is + specified all keys in the keyrings are selected. A fingerprint will + accept also all signatures by a subkey of this key, if this isn't + desired an exclamation mark (<literal>!</literal>) can be appended to + the fingerprint to disable this behaviour. + The option defaults to the value of the option with the same name + if set in the previously acquired <filename>Release</filename> file + of this repository (only fingerprints can be specified there through). + Otherwise all keys in the trusted keyrings are considered valid + signers for this repository. + </para></listitem> + + <listitem><para><option>Check-Valid-Until</option> (<option>check-valid-until</option>) + 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't 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 <literal>no</literal>. + Defaults to the value of configuration option + <option>Acquire::Check-Valid-Until</option> which itself + defaults to <literal>yes</literal>. + </para></listitem> + + <listitem><para><option>Valid-Until-Min</option> + (<option>valid-until-min</option>) and + <option>Valid-Until-Max</option> + (<option>valid-until-max</option>) 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 + <option>Acquire::Min-ValidTime</option> and + <option>Acquire::Max-ValidTime</option> which are both unset by + default. + </para></listitem> + + <listitem><para><option>Check-Date</option> (<option>check-date</option>) + is a yes/no value which controls if APT should consider + the machine's time correct and hence perform time related + checks, such as verifying that a Release file is not + from the future. Disabling it also disables the + <option>Check-Valid-Until</option> option + mentioned above. + </para></listitem> + + <listitem><para><option>Date-Max-Future</option> + (<option>date-max-future</option>) controls how far + from the future a repository may be. + Default to the value of the configuration option + <option>Acquire::Max-FutureTime</option> which is + 10 seconds by default. + </para></listitem> + + <listitem><para><option>InRelease-Path</option> (<option>inrelease-path</option>) + determines the path to the InRelease file, relative + to the normal position of an <filename>InRelease</filename> file. + By default, this option is unset and APT will try to fetch an <filename>InRelease</filename> + or, if that fails, a <filename>Release</filename> file and its associated <filename>Release.gpg</filename> file. By setting this option, + the specified path will be tried instead of the InRelease file, + and the fallback to <filename>Release</filename> files will be disabled. + </para></listitem> + + </itemizedlist> + + </para> + </refsect1> + + <refsect1><title>URI Specification</title> + + <para>The currently recognized URI types are: + <variablelist> + <varlistentry><term><command>http</command> (&apt-transport-http;)</term> + <listitem><para> + The http scheme specifies an HTTP server for an archive and is the most + commonly used method. The URI can directly include login information if the + archive requires it, but the use of &apt-authconf; should be preferred. + The method also supports SOCKS5 and HTTP(S) proxies either configured via + apt-specific configuration or specified by the environment variable + <envar>http_proxy</envar> in the format (assuming an HTTP proxy requiring + authentication) <replaceable>http://user:pass@server:port/</replaceable>. + The authentication details for proxies can also be supplied via + &apt-authconf;.</para> + <para>Note that these forms of authentication are insecure as the whole + communication with the remote server (or proxy) is not encrypted so a + sufficiently capable attacker can observe and record login as well as all + other interactions. The attacker can <emphasis>not</emphasis> modify the + communication through as APTs data security model is independent of the + chosen transport method. See &apt-secure; for details.</para></listitem> + </varlistentry> + + <varlistentry><term><command>https</command> (&apt-transport-https;)</term> + <listitem><para> + The https scheme specifies an HTTPS server for an archive and is very + similar in use and available options to the http scheme. The main + difference is that the communication between apt and server (or proxy) is + encrypted. Note that the encryption does not prevent an attacker from + knowing which server (or proxy) apt is communicating with and deeper + analysis can potentially still reveal which data was downloaded. If this is + a concern the Tor-based schemes mentioned further below might be a suitable + alternative.</para></listitem> + </varlistentry> + + <varlistentry><term><command>mirror</command>, <command>mirror+<replaceable>scheme</replaceable></command> (&apt-transport-mirror;)</term> + <listitem><para> + The mirror scheme specifies the location of a mirrorlist. By default the + scheme used for the location is <literal>http</literal>, but any other + scheme can be used via <command>mirror+<replaceable>scheme</replaceable></command>. + The mirrorlist itself can contain many different URIs for mirrors the APT client + can transparently pick, choose and fallback between intended to help both + with distributing the load over the available mirrors and ensuring that + clients can acquire data even if some configured mirrors are not available. + </para></listitem> + </varlistentry> + + <varlistentry><term><command>file</command></term> + <listitem><para> + 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.</para></listitem> + </varlistentry> + + <varlistentry><term><command>cdrom</command></term> + <listitem><para> + The cdrom scheme allows APT to use a local CD-ROM, DVD or USB drive with media + swapping. Use the &apt-cdrom; program to create cdrom entries in the + source list.</para></listitem> + </varlistentry> + + <varlistentry><term><command>ftp</command></term> + <listitem><para> + The ftp scheme specifies an FTP server for an archive. Use of FTP is on the + decline in favour of <literal>http</literal> and <literal>https</literal> + and many archives either never offered or are retiring FTP access. If you + still need this method many configuration options for it are available in + the <literal>Acquire::ftp</literal> scope and detailed in &apt-conf;.</para> + <para>Please note that an FTP proxy can be specified + by using the <envar>ftp_proxy</envar> environment variable. It is possible + to specify an HTTP proxy (HTTP proxy servers often understand FTP URLs) + using this environment variable and <emphasis>only</emphasis> this + environment variable. Proxies using HTTP specified in + the configuration file will be ignored.</para></listitem> + </varlistentry> + + <varlistentry><term><command>copy</command></term> + <listitem><para> + 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.</para></listitem> + </varlistentry> + + <varlistentry><term><command>rsh</command></term><term><command>ssh</command></term> + <listitem><para> + 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 <command>find</command> and <command>dd</command> + commands are used to perform the file transfers from the remote host. + </para></listitem> + </varlistentry> + + <varlistentry><term>adding more recognizable URI types</term> + <listitem><para> + APT can be extended with more methods shipped in other optional packages, which should + follow the naming scheme <package>apt-transport-<replaceable>method</replaceable></package>. + For instance, the APT team also maintains the package <package>apt-transport-tor</package>, + which provides access methods for HTTP and HTTPS URIs routed via the Tor network. + </para></listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1><title>Examples</title> + <para>Uses the archive stored locally (or NFS mounted) at /home/apt/debian + for stable/main, stable/contrib, and stable/non-free.</para> + <literallayout>deb file:/home/apt/debian stable main contrib non-free</literallayout> + <literallayout>Types: deb +URIs: file:/home/apt/debian +Suites: stable +Components: main contrib non-free</literallayout> + + <para>As above, except this uses the unstable (development) distribution.</para> + <literallayout>deb file:/home/apt/debian unstable main contrib non-free</literallayout> + <literallayout>Types: deb +URIs: file:/home/apt/debian +Suites: unstable +Components: main contrib non-free</literallayout> + + <para>Sources specification for the above.</para> + <literallayout>deb-src file:/home/apt/debian unstable main contrib non-free</literallayout> + <literallayout>Types: deb-src +URIs: file:/home/apt/debian +Suites: unstable +Components: main contrib non-free</literallayout> + + <para>The first line gets package information for the architectures in <literal>APT::Architectures</literal> + while the second always retrieves <literal>amd64</literal> and <literal>armel</literal>.</para> + <literallayout>deb http://deb.debian.org/debian &debian-stable-codename; main +deb [ arch=amd64,armel ] http://deb.debian.org/debian &debian-stable-codename; main</literallayout> + <literallayout>Types: deb +URIs: http://deb.debian.org/debian +Suites: &debian-stable-codename; +Components: main + +Types: deb +URIs: http://deb.debian.org/debian +Suites: &debian-stable-codename; +Components: main +Architectures: amd64 armel +</literallayout> + + <para>Uses HTTP to access the archive at archive.debian.org, and uses only + the hamm/main area.</para> + <literallayout>deb http://archive.debian.org/debian-archive hamm main</literallayout> + <literallayout>Types: deb +URIs: http://archive.debian.org/debian-archive +Suites: hamm +Components: main</literallayout> + + <para>Uses FTP to access the archive at ftp.debian.org, under the debian + directory, and uses only the &debian-stable-codename;/contrib area.</para> + <literallayout>deb ftp://ftp.debian.org/debian &debian-stable-codename; contrib</literallayout> + <literallayout>Types: deb +URIs: ftp://ftp.debian.org/debian +Suites: &debian-stable-codename; +Components: contrib</literallayout> + + <para>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 <filename>sources.list</filename> + a single FTP session will be used for both resource lines.</para> + <literallayout>deb ftp://ftp.debian.org/debian unstable contrib</literallayout> + <literallayout>Types: deb +URIs: ftp://ftp.debian.org/debian +Suites: unstable +Components: contrib</literallayout> + + <para>Uses HTTP to access the archive at ftp.tlh.debian.org, under the + universe directory, and uses only files found under + <filename>unstable/binary-i386</filename> on i386 machines, + <filename>unstable/binary-amd64</filename> 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] + <literallayout>deb http://ftp.tlh.debian.org/universe unstable/binary-$(ARCH)/</literallayout> + <literallayout>Types: deb +URIs: http://ftp.tlh.debian.org/universe +Suites: unstable/binary-$(ARCH)/</literallayout> + </para> + + <para>Uses HTTP to get binary packages as well as sources from the stable, testing and unstable + suites and the components main and contrib.</para> + <literallayout>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</literallayout> + <literallayout>Types: deb deb-src +URIs: http://deb.debian.org/debian +Suites: stable testing unstable +Components: main contrib +</literallayout> + + </refsect1> + + <refsect1><title>See Also</title> + <para>&apt-get;, &apt-conf;, &apt-acquire-additional-files;</para> + </refsect1> + + &manbugs; + +</refentry> |