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