summaryrefslogtreecommitdiff
path: root/doc/sources.list.5.xml
diff options
context:
space:
mode:
Diffstat (limited to 'doc/sources.list.5.xml')
-rw-r--r--doc/sources.list.5.xml519
1 files changed, 519 insertions, 0 deletions
diff --git a/doc/sources.list.5.xml b/doc/sources.list.5.xml
new file mode 100644
index 000000000..d3e74bbdf
--- /dev/null
+++ b/doc/sources.list.5.xml
@@ -0,0 +1,519 @@
+<?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>2016-09-20T00: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 reenables 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 spaces, 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 either an absolute path to a keyring file (has to be
+ accessible and readable for the <literal>_apt</literal> user,
+ so ensure everyone has read-permissions on the file) or one or
+ more fingerprints of keys either in the
+ <filename>trusted.gpg</filename> keyring or in the
+ keyrings in the <filename>trusted.gpg.d/</filename> directory
+ (see <command>apt-key fingerprint</command>). If the option is
+ set, only the key(s) in this keyring or only the keys with these
+ fingerprints are used for the &apt-secure; verification of this
+ repository. Defaults to the value of the option with the same name
+ if set in the previously acquired <filename>Release</filename> file.
+ 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>
+
+ </itemizedlist>
+
+ </para>
+ </refsect1>
+
+ <refsect1><title>URI Specification</title>
+
+ <para>The currently recognized URI types are:
+ <variablelist>
+ <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 drive with media
+ swapping. Use the &apt-cdrom; program to create cdrom entries in the
+ source list.</para></listitem>
+ </varlistentry>
+
+ <varlistentry><term><command>http</command></term>
+ <listitem><para>
+ The http scheme specifies an HTTP server for the archive. If an environment
+ variable <envar>http_proxy</envar> is set with the format
+ http://server:port/, the proxy server specified in
+ <envar>http_proxy</envar> 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.</para></listitem>
+ </varlistentry>
+
+ <varlistentry><term><command>ftp</command></term>
+ <listitem><para>
+ 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 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-https</package>,
+ 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;.
+ </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>