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;
12 &apt-author.jgunthorpe;
16 <!-- The last update date -->
17 <date>2016-
07-
08T00:
00:
00Z
</date>
21 <refentrytitle>sources.list
</refentrytitle>
22 <manvolnum>5</manvolnum>
23 <refmiscinfo class=
"manual">APT
</refmiscinfo>
26 <!-- Man page title -->
28 <refname>sources.list
</refname>
29 <refpurpose>List of configured APT data sources
</refpurpose>
32 <refsect1><title>Description
</title>
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).
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>
59 <refsect1><title>One-Line-Style Format
</title>
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.
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.
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.
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.
88 <refsect1><title>deb822-Style Format
</title>
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.
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.
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.
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.
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
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>
136 <para>The format for two one-line-style entries using the
137 <literal>deb
</literal> and
<literal>deb-src
</literal> types is:
</para>
139 <literallayout>deb [ option1=value1 option2=value2 ] uri suite [component1] [component2] [...]
140 deb-src [ option1=value1 option2=value2 ] uri suite [component1] [component2] [...]
</literallayout>
142 <para>Alternatively the equivalent entry in deb822 style looks like this:
147 Components: [component1] [component2] [...]
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>
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>
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
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>
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
191 <literallayout>&sourceslist-sources-format;
</literallayout></para>
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
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.
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.
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.
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>.
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>.
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
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!
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
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.
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>.
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
349 <refsect1><title>URI Specification
</title>
351 <para>The currently recognized URI types are:
353 <varlistentry><term><command>file
</command></term>
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>
360 <varlistentry><term><command>cdrom
</command></term>
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>
367 <varlistentry><term><command>http
</command></term>
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>
378 <varlistentry><term><command>ftp
</command></term>
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>
390 <varlistentry><term><command>copy
</command></term>
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>
397 <varlistentry><term><command>rsh
</command></term><term><command>ssh
</command></term>
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.
406 <varlistentry><term>adding more recognizable URI types
</term>
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;.
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
426 Components: main contrib non-free
</literallayout>
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
433 Components: main contrib non-free
</literallayout>
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
440 Components: main contrib non-free
</literallayout>
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://httpredir.debian.org/debian &debian-stable-codename; main
445 deb [ arch=amd64,armel ] http://httpredir.debian.org/debian &debian-stable-codename; main
</literallayout>
446 <literallayout>Types: deb
447 URIs: http://httpredir.debian.org/debian
448 Suites: &debian-stable-codename;
452 URIs: http://httpredir.debian.org/debian
453 Suites: &debian-stable-codename;
455 Architectures: amd64 armel
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
464 Components: main
</literallayout>
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>
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
482 Components: contrib
</literallayout>
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>
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://httpredir.debian.org/debian stable main contrib
500 deb-src http://httpredir.debian.org/debian stable main contrib
501 deb http://httpredir.debian.org/debian testing main contrib
502 deb-src http://httpredir.debian.org/debian testing main contrib
503 deb http://httpredir.debian.org/debian unstable main contrib
504 deb-src http://httpredir.debian.org/debian unstable main contrib
</literallayout>
505 <literallayout>Types: deb deb-src
506 URIs: http://httpredir.debian.org/debian
507 Suites: stable testing unstable
508 Components: main contrib
513 <refsect1><title>See Also
</title>
514 <para>&apt-get;, &apt-conf;, &apt-acquire-additional-files;
</para>