X-Git-Url: https://git.saurik.com/apt.git/blobdiff_plain/39c7baef5ef2fe40b539833714913bd8a85279cd..4fb400a66f2436cba6c89cecdc9560c9b1c54337:/doc/sources.list.5.xml diff --git a/doc/sources.list.5.xml b/doc/sources.list.5.xml index 9762005b0..5c539798a 100644 --- a/doc/sources.list.5.xml +++ b/doc/sources.list.5.xml @@ -1,10 +1,13 @@ <?xml version="1.0" encoding="utf-8" standalone="no"?> -<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" - "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ +<!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; + ]> <refentry> @@ -15,75 +18,81 @@ &apt-email; &apt-product; <!-- The last update date --> - <date>29 February 2004</date> + <date>2012-06-09T00: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>Package resource list for APT</refpurpose> + <refpurpose>List of configured APT data sources</refpurpose> </refnamediv> <refsect1><title>Description</title> - <para>The package resource list is used to locate archives of the package - distribution system in use on the system. At this time, this manual page - documents only the packaging system used by the Debian GNU/Linux system. - This control file is located in <filename>/etc/apt/sources.list</filename></para> - - <para>The source list 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 format of each line is: - <literal>type uri args</literal> The first item, <literal>type</literal> - determines the format for <literal>args</literal> <literal>uri</literal> is - a Universal Resource Identifier - (URI), which is a superset of the more specific and well-known Universal - Resource Locator, or URL. The rest of the line can be marked as a comment - by using a #.</para> + <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 seperate files that end with - <literal>.list</literal>. The format is the same as for the regular - <filename>sources.list</filename> file. </para> + 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 describes a typical two-level Debian - archive, <filename>distribution/component</filename>. Typically, - <literal>distribution</literal> is generally one of - <literal>stable</literal> <literal>unstable</literal> or - <literal>testing</literal> while component is one of <literal>main</literal> - <literal>contrib</literal> <literal>non-free</literal> or - <literal>non-us</literal> The - <literal>deb-src</literal> type describes a debian distribution's source + <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 are:</para> + <literal>deb</literal> and <literal>deb-src</literal> types is:</para> - <literallayout>deb uri distribution [component1] [component2] [...]</literallayout> + <literallayout>deb [ options ] uri distribution [component1] [component2] [...]</literallayout> <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>distribution</literal> can specify an exact path, in which case the components must be omitted and <literal>distribution</literal> must end with - a slash (/). This is useful for when only a particular sub-section of the - archive denoted by the URI is of interest. + 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>distribution</literal> does not specify an exact path, at least one <literal>component</literal> must be present.</para> <para><literal>distribution</literal> may also contain a variable, <literal>$(ARCH)</literal> - which expands to the Debian architecture (i386, m68k, powerpc, ...) - used on the system. This permits architecture-independent + 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> @@ -100,6 +109,22 @@ 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>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 @@ -107,67 +132,77 @@ <para>Some examples:</para> <literallayout> -deb http://http.us.debian.org/debian stable main contrib non-free -deb http://http.us.debian.org/debian dists/stable-updates/ +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 cdrom, file, http, and ftp. + <para>The currently recognized URI types are: <variablelist> - <varlistentry><term>file</term> + <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>cdrom</term> + <varlistentry><term><command>cdrom</command></term> <listitem><para> - The cdrom scheme allows APT to use a local CDROM drive with media + 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>http</term> + <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/ + http://user:pass@server:port/. Note that this is an insecure method of authentication.</para></listitem> </varlistentry> - <varlistentry><term>ftp</term> + <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 a ftp proxy can be specified + &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 a http proxy (http proxy servers often understand ftp urls) - using this method and ONLY this method. ftp proxies using http specified in + 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>copy</term> + <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 a zip disk to copy files around with APT.</para></listitem> + This is useful for people using removable media to copy files around with APT.</para></listitem> </varlistentry> - <varlistentry><term>rsh</term><term>ssh</term> + <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 - as a given user and access the files. No password authentication is - possible, prior arrangements with RSA keys or rhosts must have been made. - Access to files on the remote uses standard <command>find</command> and - <command>dd</command> - commands to perform the file transfers from the remote.</para></listitem> + 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> @@ -184,32 +219,33 @@ deb http://http.us.debian.org/debian dists/stable-updates/ <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/contrib area.</para> - <literallayout>deb ftp://ftp.debian.org/debian stable contrib</literallayout> + 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>. + 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 nonus.debian.org, under the - debian-non-US directory.</para> - <literallayout>deb http://nonus.debian.org/debian-non-US stable/non-US main contrib non-free</literallayout> - - <para>Uses HTTP to access the archive at nonus.debian.org, under the - debian-non-US directory, and uses only files found under - <filename>unstable/binary-i3866</filename> on i386 machines, - <filename>unstable/binary-m68k</filename> on m68k, and so - forth for other supported architectures. [Note this example only - illustrates how to use the substitution variable; non-us is no longer - structured like this] - <literallayout>deb http://ftp.de.debian.org/debian-non-US unstable/binary-$(ARCH)/</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>