123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283 |
- <?xml version="1.0" encoding="utf-8" standalone="no"?>
- <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
- "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
- <!ENTITY % aptent SYSTEM "apt.ent"> %aptent;
- <!ENTITY % aptverbatiment SYSTEM "apt-verbatim.ent"> %aptverbatiment;
- <!ENTITY % aptvendor SYSTEM "apt-vendor.ent"> %aptvendor;
- ]>
- <refentry>
- <refentryinfo>
- &apt-author.jgunthorpe;
- &apt-author.team;
- &apt-email;
- &apt-product;
- <!-- The last update date -->
- <date>2014-01-18T00:00:00Z</date>
- </refentryinfo>
-
- <refmeta>
- <refentrytitle>sources.list</refentrytitle>
- <manvolnum>5</manvolnum>
- <refmiscinfo class="manual">APT</refmiscinfo>
- </refmeta>
-
- <!-- Man page title -->
- <refnamediv>
- <refname>sources.list</refname>
- <refpurpose>List of configured APT data sources</refpurpose>
- </refnamediv>
-
- <refsect1><title>Description</title>
- <para>
- The source list <filename>/etc/apt/sources.list</filename> is designed to support
- any number of active sources and a variety of source media. The file lists one
- source per line, with the most preferred source listed first. The information available
- from the configured sources is acquired by <command>apt-get update</command>
- (or by an equivalent command from another APT front-end).
- </para>
- <para>
- Each line specifying a source starts with type (e.g. <literal>deb-src</literal>)
- followed by options and arguments for this type.
- Individual entries cannot be continued onto a following line. Empty lines
- are ignored, and a <literal>#</literal> character anywhere on a line marks
- the remainder of that line as a comment.
- </para>
- </refsect1>
-
- <refsect1><title>sources.list.d</title>
- <para>The <filename>/etc/apt/sources.list.d</filename> directory provides
- a way to add sources.list entries in separate files.
- The format is the same as for the regular <filename>sources.list</filename> file.
- File names need to end with
- <filename>.list</filename> and may only contain letters (a-z and A-Z),
- digits (0-9), underscore (_), hyphen (-) and period (.) characters.
- Otherwise APT will print a notice that it has ignored a file, unless that
- file matches a pattern in the <literal>Dir::Ignore-Files-Silently</literal>
- configuration list - in which case it will be silently ignored.</para>
- </refsect1>
- <refsect1><title>The deb and deb-src types</title>
- <para>The <literal>deb</literal> type references a typical two-level Debian
- archive, <filename>distribution/component</filename>. The
- <literal>distribution</literal> is generally an archive name like
- <literal>stable</literal> or <literal>testing</literal> or a codename like
- <literal>&stable-codename;</literal> or <literal>&testing-codename;</literal>
- while component is one of <literal>main</literal>, <literal>contrib</literal> or
- <literal>non-free</literal>. The
- <literal>deb-src</literal> type references a Debian distribution's source
- code in the same form as the <literal>deb</literal> type.
- A <literal>deb-src</literal> line is required to fetch source indexes.</para>
- <para>The format for a <filename>sources.list</filename> entry using the
- <literal>deb</literal> and <literal>deb-src</literal> types is:</para>
- <literallayout>deb [ options ] uri suite [component1] [component2] [...]</literallayout>
- <para>Alternatively a rfc822 style format is also supported:
- <literallayout>
- Types: deb deb-src
- URIs: http://example.com
- Suites: stable testing
- Sections: component1 component2
- Description: short
- long long long
- [option1]: [option1-value]
- Types: deb
- URIs: http://another.example.com
- Suites: experimental
- Sections: component1 component2
- Enabled: no
- Description: short
- long long long
- [option1]: [option1-value]
- </literallayout>
- </para>
- <para>The URI for the <literal>deb</literal> type must specify the base of the
- Debian distribution, from which APT will find the information it needs.
- <literal>suite</literal> can specify an exact path, in which case the
- components must be omitted and <literal>suite</literal> must end with
- a slash (<literal>/</literal>). This is useful for the case when only a
- particular sub-section of the archive denoted by the URI is of interest.
- If <literal>suite</literal> does not specify an exact path, at least
- one <literal>component</literal> must be present.</para>
- <para><literal>suite</literal> may also contain a variable,
- <literal>$(ARCH)</literal>
- which expands to the Debian architecture (such as <literal>amd64</literal> or
- <literal>armel</literal>) used on the system. This permits architecture-independent
- <filename>sources.list</filename> files to be used. In general this is only
- of interest when specifying an exact path, <literal>APT</literal> will
- automatically generate a URI with the current architecture otherwise.</para>
- <para>In the traditional style sources.list format since only one
- distribution can be specified per line it may be necessary to have
- multiple lines for the same URI, if a subset of all available
- distributions or components at that location is desired. APT will
- sort the URI list after it has generated a complete set internally,
- and will collapse multiple references to the same Internet host,
- for instance, into a single connection, so that it does not
- inefficiently establish an FTP connection, close it, do something
- else, and then re-establish a connection to that same host. This
- feature is useful for accessing busy FTP sites with limits on the
- number of simultaneous anonymous users. APT also parallelizes
- connections to different hosts to more effectively deal with sites
- with low bandwidth.</para>
- <para><literal>options</literal> is always optional and needs to be surrounded by
- square brackets. It can consist of multiple settings in the form
- <literal><replaceable>setting</replaceable>=<replaceable>value</replaceable></literal>.
- Multiple settings are separated by spaces. The following settings are supported by APT
- (note however that unsupported settings will be ignored silently):
- <itemizedlist>
- <listitem><para><literal>arch=<replaceable>arch1</replaceable>,<replaceable>arch2</replaceable>,…</literal>
- can be used to specify for which architectures information should
- be downloaded. If this option is not set all architectures defined by the
- <literal>APT::Architectures</literal> option will be downloaded.</para></listitem>
- <listitem><para><literal>arch+=<replaceable>arch1</replaceable>,<replaceable>arch2</replaceable>,…</literal>
- and <literal>arch-=<replaceable>arch1</replaceable>,<replaceable>arch2</replaceable>,…</literal>
- which can be used to add/remove architectures from the set which will be downloaded.</para></listitem>
- <listitem><para><literal>trusted=yes</literal> can be set to indicate that packages
- from this source are always authenticated even if the <filename>Release</filename> file
- is not signed or the signature can't be checked. This disables parts of &apt-secure;
- and should therefore only be used in a local and trusted context. <literal>trusted=no</literal>
- is the opposite which handles even correctly authenticated sources as not authenticated.</para></listitem>
- </itemizedlist></para>
- <para>It is important to list sources in order of preference, with the most
- preferred source listed first. Typically this will result in sorting
- by speed from fastest to slowest (CD-ROM followed by hosts on a local
- network, followed by distant Internet hosts, for example).</para>
- <para>Some examples:</para>
- <literallayout>
- deb http://ftp.debian.org/debian &stable-codename; main contrib non-free
- deb http://security.debian.org/ &stable-codename;/updates main contrib non-free
- </literallayout>
- </refsect1>
- <refsect1><title>URI specification</title>
- <para>The currently recognized URI types are:
- <variablelist>
- <varlistentry><term><command>file</command></term>
- <listitem><para>
- The file scheme allows an arbitrary directory in the file system to be
- considered an archive. This is useful for NFS mounts and local mirrors or
- archives.</para></listitem>
- </varlistentry>
-
- <varlistentry><term><command>cdrom</command></term>
- <listitem><para>
- The cdrom scheme allows APT to use a local CD-ROM drive with media
- swapping. Use the &apt-cdrom; program to create cdrom entries in the
- source list.</para></listitem>
- </varlistentry>
- <varlistentry><term><command>http</command></term>
- <listitem><para>
- The http scheme specifies an HTTP server for the archive. If an environment
- variable <envar>http_proxy</envar> is set with the format
- http://server:port/, the proxy server specified in
- <envar>http_proxy</envar> will be used. Users of authenticated
- HTTP/1.1 proxies may use a string of the format
- http://user:pass@server:port/.
- Note that this is an insecure method of authentication.</para></listitem>
- </varlistentry>
- <varlistentry><term><command>ftp</command></term>
- <listitem><para>
- The ftp scheme specifies an FTP server for the archive. APT's FTP behavior
- is highly configurable; for more information see the
- &apt-conf; manual page. Please note that an FTP proxy can be specified
- by using the <envar>ftp_proxy</envar> environment variable. It is possible
- to specify an HTTP proxy (HTTP proxy servers often understand FTP URLs)
- using this environment variable and <emphasis>only</emphasis> this
- environment variable. Proxies using HTTP specified in
- the configuration file will be ignored.</para></listitem>
- </varlistentry>
- <varlistentry><term><command>copy</command></term>
- <listitem><para>
- The copy scheme is identical to the file scheme except that packages are
- copied into the cache directory instead of used directly at their location.
- This is useful for people using removable media to copy files around with APT.</para></listitem>
- </varlistentry>
-
- <varlistentry><term><command>rsh</command></term><term><command>ssh</command></term>
- <listitem><para>
- The rsh/ssh method invokes RSH/SSH to connect to a remote host and
- access the files as a given user. Prior configuration of rhosts or RSA keys
- is recommended. The standard <command>find</command> and <command>dd</command>
- commands are used to perform the file transfers from the remote host.
- </para></listitem>
- </varlistentry>
- <varlistentry><term>adding more recognizable URI types</term>
- <listitem><para>
- APT can be extended with more methods shipped in other optional packages, which should
- follow the naming scheme <package>apt-transport-<replaceable>method</replaceable></package>.
- For instance, the APT team also maintains the package <package>apt-transport-https</package>,
- which provides access methods for HTTPS URIs with features similar to the http method.
- Methods for using e.g. debtorrent are also available - see &apt-transport-debtorrent;.
- </para></listitem>
- </varlistentry>
- </variablelist>
- </para>
- </refsect1>
-
- <refsect1><title>Examples</title>
- <para>Uses the archive stored locally (or NFS mounted) at /home/jason/debian
- for stable/main, stable/contrib, and stable/non-free.</para>
- <literallayout>deb file:/home/jason/debian stable main contrib non-free</literallayout>
- <para>As above, except this uses the unstable (development) distribution.</para>
- <literallayout>deb file:/home/jason/debian unstable main contrib non-free</literallayout>
- <para>Source line for the above</para>
- <literallayout>deb-src file:/home/jason/debian unstable main contrib non-free</literallayout>
- <para>The first line gets package information for the architectures in <literal>APT::Architectures</literal>
- while the second always retrieves <literal>amd64</literal> and <literal>armel</literal>.</para>
- <literallayout>deb http://ftp.debian.org/debian &stable-codename; main
- deb [ arch=amd64,armel ] http://ftp.debian.org/debian &stable-codename; main</literallayout>
- <para>Uses HTTP to access the archive at archive.debian.org, and uses only
- the hamm/main area.</para>
- <literallayout>deb http://archive.debian.org/debian-archive hamm main</literallayout>
- <para>Uses FTP to access the archive at ftp.debian.org, under the debian
- directory, and uses only the &stable-codename;/contrib area.</para>
- <literallayout>deb ftp://ftp.debian.org/debian &stable-codename; contrib</literallayout>
- <para>Uses FTP to access the archive at ftp.debian.org, under the debian
- directory, and uses only the unstable/contrib area. If this line appears as
- well as the one in the previous example in <filename>sources.list</filename>
- a single FTP session will be used for both resource lines.</para>
- <literallayout>deb ftp://ftp.debian.org/debian unstable contrib</literallayout>
- <para>Uses HTTP to access the archive at ftp.tlh.debian.org, under the
- universe directory, and uses only files found under
- <filename>unstable/binary-i386</filename> on i386 machines,
- <filename>unstable/binary-amd64</filename> on amd64, and so
- forth for other supported architectures. [Note this example only
- illustrates how to use the substitution variable; official debian
- archives are not structured like this]
- <literallayout>deb http://ftp.tlh.debian.org/universe unstable/binary-$(ARCH)/</literallayout>
- </para>
- </refsect1>
-
- <refsect1><title>See Also</title>
- <para>&apt-cache; &apt-conf;
- </para>
- </refsect1>
- &manbugs;
-
- </refentry>
|