| 1 | <?xml version="1.0" encoding="utf-8" standalone="no"?> |
| 2 | <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" |
| 3 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ |
| 4 | |
| 5 | <!ENTITY % aptent SYSTEM "apt.ent"> |
| 6 | %aptent; |
| 7 | |
| 8 | ]> |
| 9 | |
| 10 | <refentry> |
| 11 | |
| 12 | <refentryinfo> |
| 13 | &apt-author.jgunthorpe; |
| 14 | &apt-author.team; |
| 15 | &apt-email; |
| 16 | &apt-product; |
| 17 | <!-- The last update date --> |
| 18 | <date>29 February 2004</date> |
| 19 | </refentryinfo> |
| 20 | |
| 21 | <refmeta> |
| 22 | <refentrytitle>sources.list</refentrytitle> |
| 23 | <manvolnum>5</manvolnum> |
| 24 | </refmeta> |
| 25 | |
| 26 | <!-- Man page title --> |
| 27 | <refnamediv> |
| 28 | <refname>sources.list</refname> |
| 29 | <refpurpose>Package resource list for APT</refpurpose> |
| 30 | </refnamediv> |
| 31 | |
| 32 | <refsect1><title>Description</title> |
| 33 | <para>The package resource list is used to locate archives of the package |
| 34 | distribution system in use on the system. At this time, this manual page |
| 35 | documents only the packaging system used by the Debian GNU/Linux system. |
| 36 | This control file is located in <filename>/etc/apt/sources.list</filename></para> |
| 37 | |
| 38 | <para>The source list is designed to support any number of active sources and a |
| 39 | variety of source media. The file lists one source per line, with the |
| 40 | most preferred source listed first. The format of each line is: |
| 41 | <literal>type uri args</literal> The first item, <literal>type</literal> |
| 42 | determines the format for <literal>args</literal> <literal>uri</literal> is |
| 43 | a Universal Resource Identifier |
| 44 | (URI), which is a superset of the more specific and well-known Universal |
| 45 | Resource Locator, or URL. The rest of the line can be marked as a comment |
| 46 | by using a #.</para> |
| 47 | </refsect1> |
| 48 | |
| 49 | <refsect1><title>sources.list.d</title> |
| 50 | <para>The <filename>/etc/apt/sources.list.d</filename> directory provides |
| 51 | a way to add sources.list entries in seperate files that end with |
| 52 | <literal>.list</literal>. The format is the same as for the regular |
| 53 | <filename>sources.list</filename> file. </para> |
| 54 | </refsect1> |
| 55 | |
| 56 | <refsect1><title>The deb and deb-src types</title> |
| 57 | <para>The <literal>deb</literal> type describes a typical two-level Debian |
| 58 | archive, <filename>distribution/component</filename>. Typically, |
| 59 | <literal>distribution</literal> is generally one of |
| 60 | <literal>stable</literal> <literal>unstable</literal> or |
| 61 | <literal>testing</literal> while component is one of <literal>main</literal> |
| 62 | <literal>contrib</literal> <literal>non-free</literal> or |
| 63 | <literal>non-us</literal> The |
| 64 | <literal>deb-src</literal> type describes a debian distribution's source |
| 65 | code in the same form as the <literal>deb</literal> type. |
| 66 | A <literal>deb-src</literal> line is required to fetch source indexes.</para> |
| 67 | |
| 68 | |
| 69 | <para>The format for a <filename>sources.list</filename> entry using the |
| 70 | <literal>deb</literal> and <literal>deb-src</literal> types are:</para> |
| 71 | |
| 72 | <literallayout>deb uri distribution [component1] [component2] [...]</literallayout> |
| 73 | |
| 74 | <para>The URI for the <literal>deb</literal> type must specify the base of the |
| 75 | Debian distribution, from which APT will find the information it needs. |
| 76 | <literal>distribution</literal> can specify an exact path, in which case the |
| 77 | components must be omitted and <literal>distribution</literal> must end with |
| 78 | a slash (/). This is useful for when only a particular sub-section of the |
| 79 | archive denoted by the URI is of interest. |
| 80 | If <literal>distribution</literal> does not specify an exact path, at least |
| 81 | one <literal>component</literal> must be present.</para> |
| 82 | |
| 83 | <para><literal>distribution</literal> may also contain a variable, |
| 84 | <literal>$(ARCH)</literal> |
| 85 | which expands to the Debian architecture (i386, m68k, powerpc, ...) |
| 86 | used on the system. This permits architecture-independent |
| 87 | <filename>sources.list</filename> files to be used. In general this is only |
| 88 | of interest when specifying an exact path, <literal>APT</literal> will |
| 89 | automatically generate a URI with the current architecture otherwise.</para> |
| 90 | |
| 91 | <para>Since only one distribution can be specified per line it may be necessary |
| 92 | to have multiple lines for the same URI, if a subset of all available |
| 93 | distributions or components at that location is desired. |
| 94 | APT will sort the URI list after it has generated a complete set |
| 95 | internally, and will collapse multiple references to the same Internet |
| 96 | host, for instance, into a single connection, so that it does not |
| 97 | inefficiently establish an FTP connection, close it, do something else, |
| 98 | and then re-establish a connection to that same host. This feature is |
| 99 | useful for accessing busy FTP sites with limits on the number of |
| 100 | simultaneous anonymous users. APT also parallelizes connections to |
| 101 | different hosts to more effectively deal with sites with low bandwidth.</para> |
| 102 | |
| 103 | <para>It is important to list sources in order of preference, with the most |
| 104 | preferred source listed first. Typically this will result in sorting |
| 105 | by speed from fastest to slowest (CD-ROM followed by hosts on a local |
| 106 | network, followed by distant Internet hosts, for example).</para> |
| 107 | |
| 108 | <para>Some examples:</para> |
| 109 | <literallayout> |
| 110 | deb http://http.us.debian.org/debian stable main contrib non-free |
| 111 | deb http://http.us.debian.org/debian dists/stable-updates/ |
| 112 | </literallayout> |
| 113 | |
| 114 | </refsect1> |
| 115 | |
| 116 | <refsect1><title>URI specification</title> |
| 117 | |
| 118 | <para>The currently recognized URI types are cdrom, file, http, and ftp. |
| 119 | <variablelist> |
| 120 | <varlistentry><term>file</term> |
| 121 | <listitem><para> |
| 122 | The file scheme allows an arbitrary directory in the file system to be |
| 123 | considered an archive. This is useful for NFS mounts and local mirrors or |
| 124 | archives.</para></listitem> |
| 125 | </varlistentry> |
| 126 | |
| 127 | <varlistentry><term>cdrom</term> |
| 128 | <listitem><para> |
| 129 | The cdrom scheme allows APT to use a local CDROM drive with media |
| 130 | swapping. Use the &apt-cdrom; program to create cdrom entries in the |
| 131 | source list.</para></listitem> |
| 132 | </varlistentry> |
| 133 | |
| 134 | <varlistentry><term>http</term> |
| 135 | <listitem><para> |
| 136 | The http scheme specifies an HTTP server for the archive. If an environment |
| 137 | variable <envar>http_proxy</envar> is set with the format |
| 138 | http://server:port/, the proxy server specified in |
| 139 | <envar>http_proxy</envar> will be used. Users of authenticated |
| 140 | HTTP/1.1 proxies may use a string of the format |
| 141 | http://user:pass@server:port/ |
| 142 | Note that this is an insecure method of authentication.</para></listitem> |
| 143 | </varlistentry> |
| 144 | |
| 145 | <varlistentry><term>ftp</term> |
| 146 | <listitem><para> |
| 147 | The ftp scheme specifies an FTP server for the archive. APT's FTP behavior |
| 148 | is highly configurable; for more information see the |
| 149 | &apt-conf; manual page. Please note that a ftp proxy can be specified |
| 150 | by using the <envar>ftp_proxy</envar> environment variable. It is possible |
| 151 | to specify a http proxy (http proxy servers often understand ftp urls) |
| 152 | using this method and ONLY this method. ftp proxies using http specified in |
| 153 | the configuration file will be ignored.</para></listitem> |
| 154 | </varlistentry> |
| 155 | |
| 156 | <varlistentry><term>copy</term> |
| 157 | <listitem><para> |
| 158 | The copy scheme is identical to the file scheme except that packages are |
| 159 | copied into the cache directory instead of used directly at their location. |
| 160 | This is useful for people using a zip disk to copy files around with APT.</para></listitem> |
| 161 | </varlistentry> |
| 162 | |
| 163 | <varlistentry><term>rsh</term><term>ssh</term> |
| 164 | <listitem><para> |
| 165 | The rsh/ssh method invokes rsh/ssh to connect to a remote host |
| 166 | as a given user and access the files. No password authentication is |
| 167 | possible, prior arrangements with RSA keys or rhosts must have been made. |
| 168 | Access to files on the remote uses standard <command>find</command> and |
| 169 | <command>dd</command> |
| 170 | commands to perform the file transfers from the remote.</para></listitem> |
| 171 | </varlistentry> |
| 172 | </variablelist> |
| 173 | </para> |
| 174 | </refsect1> |
| 175 | |
| 176 | <refsect1><title>Examples</title> |
| 177 | <para>Uses the archive stored locally (or NFS mounted) at /home/jason/debian |
| 178 | for stable/main, stable/contrib, and stable/non-free.</para> |
| 179 | <literallayout>deb file:/home/jason/debian stable main contrib non-free</literallayout> |
| 180 | |
| 181 | <para>As above, except this uses the unstable (development) distribution.</para> |
| 182 | <literallayout>deb file:/home/jason/debian unstable main contrib non-free</literallayout> |
| 183 | |
| 184 | <para>Source line for the above</para> |
| 185 | <literallayout>deb-src file:/home/jason/debian unstable main contrib non-free</literallayout> |
| 186 | |
| 187 | <para>Uses HTTP to access the archive at archive.debian.org, and uses only |
| 188 | the hamm/main area.</para> |
| 189 | <literallayout>deb http://archive.debian.org/debian-archive hamm main</literallayout> |
| 190 | |
| 191 | <para>Uses FTP to access the archive at ftp.debian.org, under the debian |
| 192 | directory, and uses only the stable/contrib area.</para> |
| 193 | <literallayout>deb ftp://ftp.debian.org/debian stable contrib</literallayout> |
| 194 | |
| 195 | <para>Uses FTP to access the archive at ftp.debian.org, under the debian |
| 196 | directory, and uses only the unstable/contrib area. If this line appears as |
| 197 | well as the one in the previous example in <filename>sources.list</filename>. |
| 198 | a single FTP session will be used for both resource lines.</para> |
| 199 | <literallayout>deb ftp://ftp.debian.org/debian unstable contrib</literallayout> |
| 200 | |
| 201 | <para>Uses HTTP to access the archive at nonus.debian.org, under the |
| 202 | debian-non-US directory.</para> |
| 203 | <literallayout>deb http://nonus.debian.org/debian-non-US stable/non-US main contrib non-free</literallayout> |
| 204 | |
| 205 | <para>Uses HTTP to access the archive at nonus.debian.org, under the |
| 206 | debian-non-US directory, and uses only files found under |
| 207 | <filename>unstable/binary-i386</filename> on i386 machines, |
| 208 | <filename>unstable/binary-m68k</filename> on m68k, and so |
| 209 | forth for other supported architectures. [Note this example only |
| 210 | illustrates how to use the substitution variable; non-us is no longer |
| 211 | structured like this] |
| 212 | <literallayout>deb http://ftp.de.debian.org/debian-non-US unstable/binary-$(ARCH)/</literallayout> |
| 213 | </para> |
| 214 | </refsect1> |
| 215 | |
| 216 | <refsect1><title>See Also</title> |
| 217 | <para>&apt-cache; &apt-conf; |
| 218 | </para> |
| 219 | </refsect1> |
| 220 | |
| 221 | &manbugs; |
| 222 | |
| 223 | </refentry> |
| 224 | |