]> git.saurik.com Git - apt-legacy.git/blob - doc/sources.list.5.xml
Rewrote APT's HTTP method to use CFNetwork in order to handle transparent proxy cache...
[apt-legacy.git] / doc / sources.list.5.xml
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