doc/sources.list.5.xml

   1 <?xml version="1.0" encoding="utf-8" standalone="no"?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
   4 <!ENTITY % aptent SYSTEM "apt.ent"> %aptent;
   5 <!ENTITY % aptverbatiment SYSTEM "apt-verbatim.ent"> %aptverbatiment;
   6 <!ENTITY % aptvendor SYSTEM "apt-vendor.ent"> %aptvendor;
   7 ]>
   8
   9 <refentry>
  10
  11  <refentryinfo>
  12    &apt-author.jgunthorpe;
  13    &apt-author.team;
  14    &apt-email;
  15    &apt-product;
  16    <!-- The last update date -->
  17    <date>2014-01-18T00:00:00Z</date>
  18  </refentryinfo>
  19
  20  <refmeta>
  21    <refentrytitle>sources.list</refentrytitle>
  22    <manvolnum>5</manvolnum>
  23    <refmiscinfo class="manual">APT</refmiscinfo>
  24  </refmeta>
  25
  26  <!-- Man page title -->
  27  <refnamediv>
  28     <refname>sources.list</refname>
  29     <refpurpose>List of configured APT data sources</refpurpose>
  30  </refnamediv>
  31
  32  <refsect1><title>Description</title>
  33    <para>
  34    The source list <filename>/etc/apt/sources.list</filename> is designed to support
  35    any number of active sources and a variety of source media. The file lists one
  36    source per line, with the most preferred source listed first. The information available
  37    from the configured sources is acquired by <command>apt-get update</command>
  38    (or by an equivalent command from another APT front-end).
  39    </para>
  40    <para>
  41    Each line specifying a source starts with type (e.g. <literal>deb-src</literal>)
  42    followed by options and arguments for this type.
  43    Individual entries cannot be continued onto a following line. Empty lines
  44    are ignored, and a <literal>#</literal> character anywhere on a line marks
  45    the remainder of that line as a comment.
  46    </para>
  47  </refsect1>
  48
  49  <refsect1><title>sources.list.d</title>
  50    <para>The <filename>/etc/apt/sources.list.d</filename> directory provides
  51    a way to add sources.list entries in separate files.
  52    The format is the same as for the regular <filename>sources.list</filename> file.
  53    File names need to end with
  54    <filename>.list</filename> and may only contain letters (a-z and A-Z),
  55    digits (0-9), underscore (_), hyphen (-) and period (.) characters.
  56    Otherwise APT will print a notice that it has ignored a file, unless that
  57    file matches a pattern in the <literal>Dir::Ignore-Files-Silently</literal>
  58    configuration list - in which case it will be silently ignored.</para>
  59  </refsect1>
  60
  61  <refsect1><title>The deb and deb-src types</title>
  62    <para>The <literal>deb</literal> type references a typical two-level Debian
  63    archive, <filename>distribution/component</filename>. The
  64    <literal>distribution</literal> is generally an archive name like
  65    <literal>stable</literal> or <literal>testing</literal> or a codename like
  66    <literal>&stable-codename;</literal> or <literal>&testing-codename;</literal>
  67    while component is one of <literal>main</literal>, <literal>contrib</literal> or
  68    <literal>non-free</literal>. The
  69    <literal>deb-src</literal> type references a Debian distribution's source
  70    code in the same form as the <literal>deb</literal> type.
  71    A <literal>deb-src</literal> line is required to fetch source indexes.</para>
  72
  73    <para>The format for a <filename>sources.list</filename> entry using the
  74    <literal>deb</literal> and <literal>deb-src</literal> types is:</para>
  75
  76    <literallayout>deb [ options ] uri suite [component1] [component2] [...]</literallayout>
  77
  78    <para>Alternatively a rfc822 style format is also supported:
  79    <literallayout>
  80      Types: deb deb-src
  81      URIs: http://example.com
  82      Suites: stable testing
  83      Sections: component1 component2
  84      Description: short
  85       long long long
  86      [option1]: [option1-value]
  87
  88      Types: deb
  89      URIs: http://another.example.com
  90      Suites: experimental
  91      Sections: component1 component2
  92      Enabled: no
  93      Description: short
  94       long long long
  95      [option1]: [option1-value]
  96    </literallayout>
  97    </para>
  98
  99    <para>The URI for the <literal>deb</literal> type must specify the base of the
 100    Debian distribution, from which APT will find the information it needs.
 101    <literal>suite</literal> can specify an exact path, in which case the
 102    components must be omitted and <literal>suite</literal> must end with
 103    a slash (<literal>/</literal>). This is useful for the case when only a
 104    particular sub-section of the archive denoted by the URI is of interest.
 105    If <literal>suite</literal> does not specify an exact path, at least
 106    one <literal>component</literal> must be present.</para>
 107
 108    <para><literal>suite</literal> may also contain a variable,
 109    <literal>$(ARCH)</literal>
 110    which expands to the Debian architecture (such as <literal>amd64</literal> or
 111    <literal>armel</literal>) used on the system. This permits architecture-independent
 112    <filename>sources.list</filename> files to be used. In general this is only
 113    of interest when specifying an exact path, <literal>APT</literal> will
 114    automatically generate a URI with the current architecture otherwise.</para>
 115
 116    <para>In the traditional style sources.list format since only one
 117    distribution can be specified per line it may be necessary to have
 118    multiple lines for the same URI, if a subset of all available
 119    distributions or components at that location is desired.  APT will
 120    sort the URI list after it has generated a complete set internally,
 121    and will collapse multiple references to the same Internet host,
 122    for instance, into a single connection, so that it does not
 123    inefficiently establish an FTP connection, close it, do something
 124    else, and then re-establish a connection to that same host. This
 125    feature is useful for accessing busy FTP sites with limits on the
 126    number of simultaneous anonymous users. APT also parallelizes
 127    connections to different hosts to more effectively deal with sites
 128    with low bandwidth.</para>
 129
 130    <para><literal>options</literal> is always optional and needs to be surrounded by
 131    square brackets. It can consist of multiple settings in the form
 132    <literal><replaceable>setting</replaceable>=<replaceable>value</replaceable></literal>.
 133    Multiple settings are separated by spaces. The following settings are supported by APT
 134    (note however that unsupported settings will be ignored silently):
 135    <itemizedlist>
 136    <listitem><para><literal>arch=<replaceable>arch1</replaceable>,<replaceable>arch2</replaceable>,…</literal>
 137    can be used to specify for which architectures information should
 138    be downloaded. If this option is not set all architectures defined by the
 139    <literal>APT::Architectures</literal> option will be downloaded.</para></listitem>
 140    <listitem><para><literal>arch+=<replaceable>arch1</replaceable>,<replaceable>arch2</replaceable>,…</literal>
 141    and <literal>arch-=<replaceable>arch1</replaceable>,<replaceable>arch2</replaceable>,…</literal>
 142    which can be used to add/remove architectures from the set which will be downloaded.</para></listitem>
 143    <listitem><para><literal>trusted=yes</literal> can be set to indicate that packages
 144    from this source are always authenticated even if the <filename>Release</filename> file
 145    is not signed or the signature can't be checked. This disables parts of &apt-secure;
 146    and should therefore only be used in a local and trusted context. <literal>trusted=no</literal>
 147    is the opposite which handles even correctly authenticated sources as not authenticated.</para></listitem>
 148    </itemizedlist></para>
 149
 150    <para>It is important to list sources in order of preference, with the most
 151    preferred source listed first. Typically this will result in sorting
 152    by speed from fastest to slowest (CD-ROM followed by hosts on a local
 153    network, followed by distant Internet hosts, for example).</para>
 154
 155    <para>Some examples:</para>
 156    <literallayout>
 157 deb http://ftp.debian.org/debian &stable-codename; main contrib non-free
 158 deb http://security.debian.org/ &stable-codename;/updates main contrib non-free
 159    </literallayout>
 160
 161  </refsect1>
 162
 163  <refsect1><title>URI specification</title>
 164
 165     <para>The currently recognized URI types are:
 166    <variablelist>
 167     <varlistentry><term><command>file</command></term>
 168     <listitem><para>
 169     The file scheme allows an arbitrary directory in the file system to be
 170     considered an archive. This is useful for NFS mounts and local mirrors or
 171     archives.</para></listitem>
 172     </varlistentry>
 173
 174     <varlistentry><term><command>cdrom</command></term>
 175     <listitem><para>
 176     The cdrom scheme allows APT to use a local CD-ROM drive with media
 177     swapping. Use the &apt-cdrom; program to create cdrom entries in the
 178     source list.</para></listitem>
 179     </varlistentry>
 180
 181     <varlistentry><term><command>http</command></term>
 182     <listitem><para>
 183     The http scheme specifies an HTTP server for the archive. If an environment
 184     variable <envar>http_proxy</envar> is set with the format
 185     http://server:port/, the proxy server specified in
 186     <envar>http_proxy</envar> will be used. Users of authenticated
 187     HTTP/1.1 proxies may use a string of the format
 188     http://user:pass@server:port/.
 189     Note that this is an insecure method of authentication.</para></listitem>
 190     </varlistentry>
 191
 192     <varlistentry><term><command>ftp</command></term>
 193     <listitem><para>
 194     The ftp scheme specifies an FTP server for the archive. APT's FTP behavior
 195     is highly configurable; for more information see the
 196     &apt-conf; manual page. Please note that an FTP proxy can be specified
 197     by using the <envar>ftp_proxy</envar> environment variable. It is possible
 198     to specify an HTTP proxy (HTTP proxy servers often understand FTP URLs)
 199     using this environment variable and <emphasis>only</emphasis> this
 200     environment variable. Proxies using HTTP specified in
 201     the configuration file will be ignored.</para></listitem>
 202     </varlistentry>
 203
 204     <varlistentry><term><command>copy</command></term>
 205     <listitem><para>
 206     The copy scheme is identical to the file scheme except that packages are
 207     copied into the cache directory instead of used directly at their location.
 208     This is useful for people using removable media to copy files around with APT.</para></listitem>
 209     </varlistentry>
 210
 211     <varlistentry><term><command>rsh</command></term><term><command>ssh</command></term>
 212     <listitem><para>
 213     The rsh/ssh method invokes RSH/SSH to connect to a remote host and
 214     access the files as a given user. Prior configuration of rhosts or RSA keys
 215     is recommended. The standard <command>find</command> and <command>dd</command>
 216     commands are used to perform the file transfers from the remote host.
 217     </para></listitem>
 218     </varlistentry>
 219
 220     <varlistentry><term>adding more recognizable URI types</term>
 221     <listitem><para>
 222     APT can be extended with more methods shipped in other optional packages, which should
 223     follow the naming scheme <package>apt-transport-<replaceable>method</replaceable></package>.
 224     For instance, the APT team also maintains the package <package>apt-transport-https</package>,
 225     which provides access methods for HTTPS URIs with features similar to the http method.
 226     Methods for using e.g. debtorrent are also available - see &apt-transport-debtorrent;.
 227     </para></listitem>
 228     </varlistentry>
 229   </variablelist>
 230  </para>
 231  </refsect1>
 232
 233  <refsect1><title>Examples</title>
 234    <para>Uses the archive stored locally (or NFS mounted) at /home/jason/debian
 235    for stable/main, stable/contrib, and stable/non-free.</para>
 236    <literallayout>deb file:/home/jason/debian stable main contrib non-free</literallayout>
 237
 238    <para>As above, except this uses the unstable (development) distribution.</para>
 239    <literallayout>deb file:/home/jason/debian unstable main contrib non-free</literallayout>
 240
 241    <para>Source line for the above</para>
 242    <literallayout>deb-src file:/home/jason/debian unstable main contrib non-free</literallayout>
 243
 244    <para>The first line gets package information for the architectures in <literal>APT::Architectures</literal>
 245    while the second always retrieves <literal>amd64</literal> and <literal>armel</literal>.</para>
 246    <literallayout>deb http://ftp.debian.org/debian &stable-codename; main
 247 deb [ arch=amd64,armel ] http://ftp.debian.org/debian &stable-codename; main</literallayout>
 248
 249    <para>Uses HTTP to access the archive at archive.debian.org, and uses only
 250    the hamm/main area.</para>
 251    <literallayout>deb http://archive.debian.org/debian-archive hamm main</literallayout>
 252
 253    <para>Uses FTP to access the archive at ftp.debian.org, under the debian
 254    directory, and uses only the &stable-codename;/contrib area.</para>
 255    <literallayout>deb ftp://ftp.debian.org/debian &stable-codename; contrib</literallayout>
 256
 257    <para>Uses FTP to access the archive at ftp.debian.org, under the debian
 258    directory, and uses only the unstable/contrib area. If this line appears as
 259    well as the one in the previous example in <filename>sources.list</filename>
 260    a single FTP session will be used for both resource lines.</para>
 261    <literallayout>deb ftp://ftp.debian.org/debian unstable contrib</literallayout>
 262
 263    <para>Uses HTTP to access the archive at ftp.tlh.debian.org, under the
 264    universe directory, and uses only files found under
 265    <filename>unstable/binary-i386</filename> on i386 machines,
 266    <filename>unstable/binary-amd64</filename> on amd64, and so
 267    forth for other supported architectures. [Note this example only
 268    illustrates how to use the substitution variable; official debian
 269    archives are not structured like this]
 270    <literallayout>deb http://ftp.tlh.debian.org/universe unstable/binary-$(ARCH)/</literallayout>
 271    </para>
 272  </refsect1>
 273
 274  <refsect1><title>See Also</title>
 275    <para>&apt-cache; &apt-conf;
 276    </para>
 277  </refsect1>
 278
 279  &manbugs;
 280
 281 </refentry>
 282