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> and the the
  35       files contained in <filename>/etc/apt/sources.list.d/</filename> are
  36       designed to support any number of active sources and a variety of source
  37       media. The files list one source per line (one line style) or contain multiline
  38       stanzas defining one or more sources per stanza (deb822 style), with the
  39       most preferred source listed first (in case a single version is available from more than one source). The information available from the
  40       configured sources is acquired by <command>apt-get update</command> (or
  41       by an equivalent command from another APT front-end).
  42    </para>
  43  </refsect1>
  44
  45  <refsect1><title>sources.list.d</title>
  46     <para>The <filename>/etc/apt/sources.list.d</filename> directory provides
  47        a way to add sources.list entries in separate files.
  48        Two different file formats are allowed as described in the next two sections.
  49        Filenames need to have either the extension <filename>.list</filename> or
  50        <filename>.sources</filename> depending on the contained format.
  51        The filenames may only contain letters (a-z and A-Z),
  52        digits (0-9), underscore (_), hyphen (-) and period (.) characters.
  53        Otherwise APT will print a notice that it has ignored a file, unless that
  54        file matches a pattern in the <literal>Dir::Ignore-Files-Silently</literal>
  55        configuration list - in which case it will be silently ignored.</para>
  56  </refsect1>
  57
  58  <refsect1><title>one line style format</title>
  59     <para>
  60        Files in this format have the extension <filename>.list</filename>.
  61        Each line specifying a source starts with a type (e.g. <literal>deb-src</literal>)
  62        followed by options and arguments for this type.
  63
  64        Individual entries cannot be continued onto a following line. Empty lines
  65        are ignored, and a <literal>#</literal> character anywhere on a line marks
  66        the remainder of that line as a comment. Consequently an entry can be
  67        disabled by commenting out the entire line.
  68
  69        If options should be provided they are separated by spaces and all of
  70        them together are enclosed by square brackets (<literal>[]</literal>)
  71        included in the line after the type separated from it with a space.
  72        If an option allows multiple values these are separated from each other
  73        with a comma (<literal>,</literal>). An option name is separated from its
  74        value(s) by a equal sign (<literal>=</literal>). Multivalue options have
  75        also <literal>-=</literal> and <literal>+=</literal> as separator which
  76        instead of replacing the default with the given value(s) modify the default
  77        value(s) to remove or include the given values.
  78    </para><para>
  79        This is the traditional format and supported by all apt versions.
  80        Note that not all options as described below are supported by all apt versions.
  81        Note also that some older applications parsing this format on its own might not
  82        expect to encounter options as they were uncommon before the introduction of
  83        multi-architecture support.
  84     </para>
  85  </refsect1>
  86
  87  <refsect1><title>deb822 style format</title>
  88     <para>
  89        Files in this format have the extension <filename>.sources</filename>.
  90        The format is similar in syntax to other files used by Debian and its
  91        derivatives, like the metadata itself apt will download from the configured
  92        sources or the <filename>debian/control</filename> file in a Debian source package.
  93
  94        Individual entries are separated by an empty line, additional empty
  95        lines are ignored, and a <literal>#</literal> character at the start of
  96        the line marks the entire line as a comment. An entry can hence be
  97        disabled by commenting out each line belonging to the stanza, but it is
  98        usually easier to add the field "Enabled: no" to the stanza to disable
  99        the entry. Removing the field or setting it to yes reenables it.
 100
 101        Options have the same syntax as every other field: A fieldname separated by
 102        a colon (<literal>:</literal>) and optionally spaces from its value(s).
 103        Note especially that multiple values are separated by spaces, not by
 104        commas as in the one line format. Multivalue fields like <literal>Architectures</literal>
 105        also have <literal>Architectures-Add</literal> and <literal>Architectures-Remove</literal>
 106        to modify the default value rather than replacing it.
 107    </para><para>
 108        This is a new format supported by apt itself since version 1.1. Previous
 109        versions ignore such files with a notice message as described earlier.
 110        It is intended to make this format gradually the default format and
 111        deprecating the previously described one line style format as it is
 112        easier to create, extend and modify by humans and machines alike
 113        especially if a lot of sources and/or options are involved.
 114
 115        Developers who are working with and/or parsing apt sources are highly
 116        encouraged to add support for this format and to contact the APT team
 117        to coordinate and share this work. Users can freely adopt this format
 118        already, but could encounter problems with software not supporting
 119        the format yet.
 120     </para>
 121  </refsect1>
 122
 123  <refsect1><title>The deb and deb-src types: General Format</title>
 124    <para>The <literal>deb</literal> type references a typical two-level Debian
 125    archive, <filename>distribution/component</filename>. The
 126    <literal>distribution</literal> is generally a suite name like
 127    <literal>stable</literal> or <literal>testing</literal> or a codename like
 128    <literal>&stable-codename;</literal> or <literal>&testing-codename;</literal>
 129    while component is one of <literal>main</literal>, <literal>contrib</literal> or
 130    <literal>non-free</literal>. The
 131    <literal>deb-src</literal> type references a Debian distribution's source
 132    code in the same form as the <literal>deb</literal> type.
 133    A <literal>deb-src</literal> line is required to fetch source indexes.</para>
 134
 135    <para>The format for two one line style entries using the
 136    <literal>deb</literal> and <literal>deb-src</literal> types is:</para>
 137
 138    <literallayout>deb [ option1=value1 option2=value2 ] uri suite [component1] [component2] [...]
 139 deb-src [ option1=value1 option2=value2 ] uri suite [component1] [component2] [...]</literallayout>
 140
 141    <para>Alternatively the equivalent entry in deb822 style looks like this:
 142    <literallayout>
 143      Types: deb deb-src
 144      URIs: uri
 145      Suites: suite
 146      Components: [component1] [component2] [...]
 147      option1: value1
 148      option2: value2
 149    </literallayout>
 150    </para>
 151
 152    <para>The URI for the <literal>deb</literal> type must specify the base of the
 153    Debian distribution, from which APT will find the information it needs.
 154    <literal>suite</literal> can specify an exact path, in which case the
 155    components must be omitted and <literal>suite</literal> must end with
 156    a slash (<literal>/</literal>). This is useful for the case when only a
 157    particular sub-directory of the archive denoted by the URI is of interest.
 158    If <literal>suite</literal> does not specify an exact path, at least
 159    one <literal>component</literal> must be present.</para>
 160
 161    <para><literal>suite</literal> may also contain a variable,
 162    <literal>$(ARCH)</literal>
 163    which expands to the Debian architecture (such as <literal>amd64</literal> or
 164    <literal>armel</literal>) used on the system. This permits architecture-independent
 165    <filename>sources.list</filename> files to be used. In general this is only
 166    of interest when specifying an exact path, <literal>APT</literal> will
 167    automatically generate a URI with the current architecture otherwise.</para>
 168
 169    <para>Especially in the one line style format since only one distribution
 170       can be specified per line it may be necessary to have multiple lines for
 171       the same URI, if a subset of all available distributions or components at
 172       that location is desired.  APT will sort the URI list after it has
 173       generated a complete set internally, and will collapse multiple
 174       references to the same Internet host, for instance, into a single
 175       connection, so that it does not inefficiently establish a
 176       connection, close it, do something else, and then re-establish a
 177       connection to that same host. APT also parallelizes connections to
 178       different hosts to more effectively deal with sites with low
 179       bandwidth.</para>
 180
 181    <para>It is important to list sources in order of preference, with the most
 182    preferred source listed first. Typically this will result in sorting
 183    by speed from fastest to slowest (CD-ROM followed by hosts on a local
 184    network, followed by distant Internet hosts, for example).</para>
 185
 186    <para>As an example, the sources for your distribution could look like this
 187       in one line style format:
 188       <literallayout>&sourceslist-list-format;</literallayout> or like this in
 189       deb822 style format:
 190       <literallayout>&sourceslist-sources-format;</literallayout></para>
 191  </refsect1>
 192
 193  <refsect1><title>The deb and deb-src types: Options</title>
 194     <para>Each source entry can have options specified modifying which and how
 195        the source is accessed and data acquired from it. Format, syntax and names
 196        of the options varies between the two formats one line and deb822 style
 197        as described, but they have both the same options available. For simplicity
 198        we list the deb822 fieldname and provide the one line name in brackets.
 199        Remember that beside setting multivalue options explicitly, there is also
 200        the option to modify them based on the default, but we aren't listing those
 201        names explicitly here. Unsupported options are silently ignored by all
 202        APT versions.
 203
 204        <itemizedlist>
 205           <listitem><para><option>Architectures</option>
 206                 (<option>arch</option>) is a multivalue option defining for
 207                 which architectures information should be downloaded. If this
 208                 option isn't set the default is all architectures as defined by
 209                 the <option>APT::Architectures</option> config option.
 210           </para></listitem>
 211
 212           <listitem><para><option>Languages</option>
 213                 (<option>lang</option>) is a multivalue option defining for
 214                 which languages information like translated package
 215                 descriptions should be downloaded.  If this option isn't set
 216                 the default is all languages as defined by the
 217                 <option>Acquire::Languages</option> config option.
 218           </para></listitem>
 219
 220           <listitem><para><option>Targets</option>
 221                 (<option>target</option>) is a multivalue option defining
 222                 which download targets apt will try to acquire from this
 223                 source. If not specified, the default set is defined by the
 224                 <option>Acquire::IndexTargets</option> configuration scope.
 225                 Aditionally, specific targets can be enabled or disabled by
 226                 using the identifier as field name instead of using this
 227                 multivalue option.
 228           </para></listitem>
 229
 230           <listitem><para><option>PDiffs</option> (<option>pdiffs</option>)
 231                 is a yes/no value which controls if APT should try to use PDiffs
 232                 to update old indexes instead of downloading the new indexes
 233                 entirely. The value of this option is ignored if the repository
 234                 doesn't announce the availability of PDiffs.  Defaults to the
 235                 value of the option with the same name for a specific index file
 236                 defined in the <option>Acquire::IndexTargets</option> scope,
 237                 which itself default to the value of configuration option
 238                 <option>Acquire::PDiffs</option> which defaults to
 239                 <literal>yes</literal>.
 240           </para></listitem>
 241
 242           <listitem><para><option>By-Hash</option> (<option>by-hash</option>)
 243                 can have the value "yes", "no" or "force" and controls if APT
 244                 should try to acquire indexes via an URI constructed from a
 245                 hashsum of the expected file instead of using the well-known
 246                 stable filename of the index. Using this can avoid hashsum
 247                 mismatches, but requires a supporting mirror. The value
 248                 "yes"/"no" activates/disables the use of this feature if this
 249                 source indicates support for it, while "force" will enable the
 250                 feature regardless of what the source indicates.
 251                 Defaults to the value of the option of the same name for a
 252                 specific index file defined in the
 253                 <option>Acquire::IndexTargets</option> scope, which itself
 254                 defaults to the value of configuration option
 255                 <option>Acquire::By-Hash</option> which defaults to
 256                 <literal>yes</literal>.
 257           </para></listitem>
 258
 259        </itemizedlist>
 260
 261        Further more, there are options which if set effect
 262        <emphasis>all</emphasis> sources with the same URI and Suite, so they
 263        have to be set on all such entries and can not be varied between
 264        different components. APT will try to detect and error out on such
 265        anomalies.
 266
 267        <itemizedlist>
 268           <listitem><para><option>Trusted</option> (<option>trusted</option>)
 269                 is a tri-state value which defaults to APT deciding if a source
 270                 is considered trusted or if warnings should be raised before e.g.
 271                 packages are installed from this source. This option can be used
 272                 to override this decision either with the value <literal>yes</literal>,
 273                 which lets APT consider this source always as a trusted source
 274                 even if it has no or fails authentication checks by disabling parts
 275                 of &apt-secure; and should therefore only be used in a local and trusted
 276                 context (if at all) as otherwise security is breached. The opposite
 277                 can be achieved with the value no, which causes the source to be handled
 278                 as untrusted even if the authentication checks passed successfully.
 279                 The default value can't be set explicitly.
 280           </para></listitem>
 281
 282           <listitem><para><option>Signed-By</option> (<option>signed-by</option>)
 283                 is either an absolute path to a keyring file (has to be
 284                 accessible and readable for the <literal>_apt</literal> user,
 285                 so ensure everyone has read-permissions on the file) or a
 286                 fingerprint of a key in either the
 287                 <filename>trusted.gpg</filename> keyring or in one of the
 288                 keyrings in the <filename>trusted.gpg.d/</filename> directory
 289                 (see <command>apt-key fingerprint</command>). If the option is
 290                 set only the key(s) in this keyring or only the key with this
 291                 fingerprint is used for the &apt-secure; verification of this
 292                 repository. Otherwise all keys in the trusted keyrings are
 293                 considered valid signers for this repository.
 294           </para></listitem>
 295
 296           <listitem><para><option>Check-Valid-Until</option> (<option>check-valid-until</option>)
 297                 is a yes/no value which controls if APT should try to detect
 298                 replay attacks. A repository creator can declare until then the
 299                 data provided in the repository should be considered valid and
 300                 if this time is reached, but no new data is provided the data
 301                 is considered expired and an error is raised.  Beside
 302                 increasing security as a malicious attacker can't sent old data
 303                 forever denying a user to be able to upgrade to a new version,
 304                 this also helps users identify mirrors which are no longer
 305                 updated. Some repositories like historic archives aren't
 306                 updated anymore by design through, so this check can be
 307                 disabled by setting this option to <literal>no</literal>.
 308                 Defaults to the value of configuration option
 309                 <option>Acquire::Check-Valid-Until</option> which itself
 310                 defaults to <literal>yes</literal>.
 311           </para></listitem>
 312
 313           <listitem><para><option>Valid-Until-Min</option>
 314                 (<option>valid-until-min</option>) and
 315                 <option>Valid-Until-Max</option>
 316                 (<option>valid-until-max</option>) can be used to raise or
 317                 lower the time period in seconds in which the data from this
 318                 repository is considered valid. -Max can be especially useful
 319                 if the repository provides no Valid-Until field on its Release
 320                 file to set your own value, while -Min can be used to increase
 321                 the valid time on seldom updated (local) mirrors of a more
 322                 frequently updated but less accessible archive (which is in the
 323                 sources.list as well) instead of disabling the check entirely.
 324                 Default to the value of the configuration options
 325                 <option>Acquire::Min-ValidTime</option> and
 326                 <option>Acquire::Max-ValidTime</option> which are both unset by
 327                 default.
 328           </para></listitem>
 329
 330        </itemizedlist>
 331
 332     </para>
 333  </refsect1>
 334
 335  <refsect1><title>URI specification</title>
 336
 337     <para>The currently recognized URI types are:
 338    <variablelist>
 339     <varlistentry><term><command>file</command></term>
 340     <listitem><para>
 341     The file scheme allows an arbitrary directory in the file system to be
 342     considered an archive. This is useful for NFS mounts and local mirrors or
 343     archives.</para></listitem>
 344     </varlistentry>
 345
 346     <varlistentry><term><command>cdrom</command></term>
 347     <listitem><para>
 348     The cdrom scheme allows APT to use a local CD-ROM drive with media
 349     swapping. Use the &apt-cdrom; program to create cdrom entries in the
 350     source list.</para></listitem>
 351     </varlistentry>
 352
 353     <varlistentry><term><command>http</command></term>
 354     <listitem><para>
 355     The http scheme specifies an HTTP server for the archive. If an environment
 356     variable <envar>http_proxy</envar> is set with the format
 357     http://server:port/, the proxy server specified in
 358     <envar>http_proxy</envar> will be used. Users of authenticated
 359     HTTP/1.1 proxies may use a string of the format
 360     http://user:pass@server:port/.
 361     Note that this is an insecure method of authentication.</para></listitem>
 362     </varlistentry>
 363
 364     <varlistentry><term><command>ftp</command></term>
 365     <listitem><para>
 366     The ftp scheme specifies an FTP server for the archive. APT's FTP behavior
 367     is highly configurable; for more information see the
 368     &apt-conf; manual page. Please note that an FTP proxy can be specified
 369     by using the <envar>ftp_proxy</envar> environment variable. It is possible
 370     to specify an HTTP proxy (HTTP proxy servers often understand FTP URLs)
 371     using this environment variable and <emphasis>only</emphasis> this
 372     environment variable. Proxies using HTTP specified in
 373     the configuration file will be ignored.</para></listitem>
 374     </varlistentry>
 375
 376     <varlistentry><term><command>copy</command></term>
 377     <listitem><para>
 378     The copy scheme is identical to the file scheme except that packages are
 379     copied into the cache directory instead of used directly at their location.
 380     This is useful for people using removable media to copy files around with APT.</para></listitem>
 381     </varlistentry>
 382
 383     <varlistentry><term><command>rsh</command></term><term><command>ssh</command></term>
 384     <listitem><para>
 385     The rsh/ssh method invokes RSH/SSH to connect to a remote host and
 386     access the files as a given user. Prior configuration of rhosts or RSA keys
 387     is recommended. The standard <command>find</command> and <command>dd</command>
 388     commands are used to perform the file transfers from the remote host.
 389     </para></listitem>
 390     </varlistentry>
 391
 392     <varlistentry><term>adding more recognizable URI types</term>
 393     <listitem><para>
 394     APT can be extended with more methods shipped in other optional packages, which should
 395     follow the naming scheme <package>apt-transport-<replaceable>method</replaceable></package>.
 396     For instance, the APT team also maintains the package <package>apt-transport-https</package>,
 397     which provides access methods for HTTPS URIs with features similar to the http method.
 398     Methods for using e.g. debtorrent are also available - see &apt-transport-debtorrent;.
 399     </para></listitem>
 400     </varlistentry>
 401   </variablelist>
 402  </para>
 403  </refsect1>
 404
 405  <refsect1><title>Examples</title>
 406    <para>Uses the archive stored locally (or NFS mounted) at /home/apt/debian
 407    for stable/main, stable/contrib, and stable/non-free.</para>
 408    <literallayout>deb file:/home/apt/debian stable main contrib non-free</literallayout>
 409    <literallayout>Types: deb
 410 URIs: file:/home/apt/debian
 411 Suites: stable
 412 Components: main contrib non-free</literallayout>
 413
 414    <para>As above, except this uses the unstable (development) distribution.</para>
 415    <literallayout>deb file:/home/apt/debian unstable main contrib non-free</literallayout>
 416    <literallayout>Types: deb
 417 URIs: file:/home/apt/debian
 418 Suites: unstable
 419 Components: main contrib non-free</literallayout>
 420
 421    <para>Source line for the above</para>
 422    <literallayout>deb-src file:/home/apt/debian unstable main contrib non-free</literallayout>
 423    <literallayout>Types: deb-src
 424 URIs: file:/home/apt/debian
 425 Suites: unstable
 426 Components: main contrib non-free</literallayout>
 427
 428
 429    <para>The first line gets package information for the architectures in <literal>APT::Architectures</literal>
 430    while the second always retrieves <literal>amd64</literal> and <literal>armel</literal>.</para>
 431    <literallayout>deb http://httpredir.debian.org/debian &stable-codename; main
 432 deb [ arch=amd64,armel ] http://httpredir.debian.org/debian &stable-codename; main</literallayout>
 433    <literallayout>Types: deb
 434 URIs: http://httpredir.debian.org/debian
 435 Suites: &stable-codename;
 436 Components: main
 437
 438 Types: deb
 439 URIs: http://httpredir.debian.org/debian
 440 Suites: &stable-codename;
 441 Components: main
 442 Architectures: amd64 armel
 443 </literallayout>
 444
 445    <para>Uses HTTP to access the archive at archive.debian.org, and uses only
 446    the hamm/main area.</para>
 447    <literallayout>deb http://archive.debian.org/debian-archive hamm main</literallayout>
 448    <literallayout>Types: deb
 449 URIs: http://archive.debian.org/debian-archive
 450 Suites: hamm
 451 Components: main</literallayout>
 452
 453    <para>Uses FTP to access the archive at ftp.debian.org, under the debian
 454    directory, and uses only the &stable-codename;/contrib area.</para>
 455    <literallayout>deb ftp://ftp.debian.org/debian &stable-codename; contrib</literallayout>
 456    <literallayout>Types: deb
 457 URIs: ftp://ftp.debian.org/debian
 458 Suites: &stable-codename;
 459 Components: contrib</literallayout>
 460
 461    <para>Uses FTP to access the archive at ftp.debian.org, under the debian
 462    directory, and uses only the unstable/contrib area. If this line appears as
 463    well as the one in the previous example in <filename>sources.list</filename>
 464    a single FTP session will be used for both resource lines.</para>
 465    <literallayout>deb ftp://ftp.debian.org/debian unstable contrib</literallayout>
 466    <literallayout>Types: deb
 467 URIs: ftp://ftp.debian.org/debian
 468 Suites: unstable
 469 Components: contrib</literallayout>
 470
 471    <para>Uses HTTP to access the archive at ftp.tlh.debian.org, under the
 472    universe directory, and uses only files found under
 473    <filename>unstable/binary-i386</filename> on i386 machines,
 474    <filename>unstable/binary-amd64</filename> on amd64, and so
 475    forth for other supported architectures. [Note this example only
 476    illustrates how to use the substitution variable; official debian
 477    archives are not structured like this]
 478    <literallayout>deb http://ftp.tlh.debian.org/universe unstable/binary-$(ARCH)/</literallayout>
 479    <literallayout>Types: deb
 480 URIs: http://ftp.tlh.debian.org/universe
 481 Suites: unstable/binary-$(ARCH)/</literallayout>
 482    </para>
 483
 484    <para>Uses HTTP to get binary packages as well as sources from the stable, testing and unstable
 485       suites and the components main and contrib.</para>
 486    <literallayout>deb http://httpredir.debian.org/debian stable main contrib
 487 deb-src http://httpredir.debian.org/debian stable main contrib
 488 deb http://httpredir.debian.org/debian testing main contrib
 489 deb-src http://httpredir.debian.org/debian testing main contrib
 490 deb http://httpredir.debian.org/debian unstable main contrib
 491 deb-src http://httpredir.debian.org/debian unstable main contrib</literallayout>
 492    <literallayout>Types: deb deb-src
 493 URIs: http://httpredir.debian.org/debian
 494 Suites: stable testing unstable
 495 Components: main contrib
 496 </literallayout>
 497
 498  </refsect1>
 499
 500  <refsect1><title>See Also</title>
 501    <para>&apt-get;, &apt-conf;
 502    </para>
 503  </refsect1>
 504
 505  &manbugs;
 506
 507 </refentry>