| 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 | |
| 5 | <!ENTITY % aptent SYSTEM "apt.ent"> |
| 6 | %aptent; |
| 7 | |
| 8 | <!ENTITY % aptverbatiment SYSTEM "apt-verbatim.ent"> |
| 9 | %aptverbatiment; |
| 10 | |
| 11 | <!ENTITY % aptvendor SYSTEM "apt-vendor.ent"> |
| 12 | %aptvendor; |
| 13 | ]> |
| 14 | |
| 15 | <refentry> |
| 16 | |
| 17 | <refentryinfo> |
| 18 | &apt-author.jgunthorpe; |
| 19 | &apt-author.team; |
| 20 | &apt-email; |
| 21 | &apt-product; |
| 22 | <!-- The last update date --> |
| 23 | <date>2014-01-18T00:00:00Z</date> |
| 24 | </refentryinfo> |
| 25 | |
| 26 | <refmeta> |
| 27 | <refentrytitle>sources.list</refentrytitle> |
| 28 | <manvolnum>5</manvolnum> |
| 29 | <refmiscinfo class="manual">APT</refmiscinfo> |
| 30 | </refmeta> |
| 31 | |
| 32 | <!-- Man page title --> |
| 33 | <refnamediv> |
| 34 | <refname>sources.list</refname> |
| 35 | <refpurpose>List of configured APT data sources</refpurpose> |
| 36 | </refnamediv> |
| 37 | |
| 38 | <refsect1><title>Description</title> |
| 39 | <para> |
| 40 | The source list <filename>/etc/apt/sources.list</filename> is designed to support |
| 41 | any number of active sources and a variety of source media. The file lists one |
| 42 | source per line, with the most preferred source listed first. The information available |
| 43 | from the configured sources is acquired by <command>apt-get update</command> |
| 44 | (or by an equivalent command from another APT front-end). |
| 45 | </para> |
| 46 | <para> |
| 47 | Each line specifying a source starts with type (e.g. <literal>deb-src</literal>) |
| 48 | followed by options and arguments for this type. |
| 49 | Individual entries cannot be continued onto a following line. Empty lines |
| 50 | are ignored, and a <literal>#</literal> character anywhere on a line marks |
| 51 | the remainder of that line as a comment. |
| 52 | </para> |
| 53 | </refsect1> |
| 54 | |
| 55 | <refsect1><title>sources.list.d</title> |
| 56 | <para>The <filename>/etc/apt/sources.list.d</filename> directory provides |
| 57 | a way to add sources.list entries in separate files. |
| 58 | The format is the same as for the regular <filename>sources.list</filename> file. |
| 59 | File names need to end with |
| 60 | <filename>.list</filename> and may only contain letters (a-z and A-Z), |
| 61 | digits (0-9), underscore (_), hyphen (-) and period (.) characters. |
| 62 | Otherwise APT will print a notice that it has ignored a file, unless that |
| 63 | file matches a pattern in the <literal>Dir::Ignore-Files-Silently</literal> |
| 64 | configuration list - in which case it will be silently ignored.</para> |
| 65 | </refsect1> |
| 66 | |
| 67 | <refsect1><title>The deb and deb-src types</title> |
| 68 | <para>The <literal>deb</literal> type references a typical two-level Debian |
| 69 | archive, <filename>distribution/component</filename>. The |
| 70 | <literal>distribution</literal> is generally an archive name like |
| 71 | <literal>stable</literal> or <literal>testing</literal> or a codename like |
| 72 | <literal>&stable-codename;</literal> or <literal>&testing-codename;</literal> |
| 73 | while component is one of <literal>main</literal>, <literal>contrib</literal> or |
| 74 | <literal>non-free</literal>. The |
| 75 | <literal>deb-src</literal> type references a Debian distribution's source |
| 76 | code in the same form as the <literal>deb</literal> type. |
| 77 | A <literal>deb-src</literal> line is required to fetch source indexes.</para> |
| 78 | |
| 79 | <para>The format for a <filename>sources.list</filename> entry using the |
| 80 | <literal>deb</literal> and <literal>deb-src</literal> types is:</para> |
| 81 | |
| 82 | <literallayout>deb [ options ] uri suite [component1] [component2] [...]</literallayout> |
| 83 | |
| 84 | <para>Alternatively a rfc822 style format is also supported: |
| 85 | <literallayout> |
| 86 | Types: deb deb-src |
| 87 | URIs: http://example.com |
| 88 | Suites: stable testing |
| 89 | Sections: component1 component2 |
| 90 | Description: short |
| 91 | long long long |
| 92 | [option1]: [option1-value] |
| 93 | |
| 94 | Types: deb |
| 95 | URIs: http://another.example.com |
| 96 | Suites: experimental |
| 97 | Sections: component1 component2 |
| 98 | Enabled: no |
| 99 | Description: short |
| 100 | long long long |
| 101 | [option1]: [option1-value] |
| 102 | </literallayout> |
| 103 | </para> |
| 104 | |
| 105 | <para>The URI for the <literal>deb</literal> type must specify the base of the |
| 106 | Debian distribution, from which APT will find the information it needs. |
| 107 | <literal>suite</literal> can specify an exact path, in which case the |
| 108 | components must be omitted and <literal>suite</literal> must end with |
| 109 | a slash (<literal>/</literal>). This is useful for the case when only a |
| 110 | particular sub-section of the archive denoted by the URI is of interest. |
| 111 | If <literal>suite</literal> does not specify an exact path, at least |
| 112 | one <literal>component</literal> must be present.</para> |
| 113 | |
| 114 | <para><literal>suite</literal> may also contain a variable, |
| 115 | <literal>$(ARCH)</literal> |
| 116 | which expands to the Debian architecture (such as <literal>amd64</literal> or |
| 117 | <literal>armel</literal>) used on the system. This permits architecture-independent |
| 118 | <filename>sources.list</filename> files to be used. In general this is only |
| 119 | of interest when specifying an exact path, <literal>APT</literal> will |
| 120 | automatically generate a URI with the current architecture otherwise.</para> |
| 121 | |
| 122 | <para>In the traditional style sources.list format since only one |
| 123 | distribution can be specified per line it may be necessary to have |
| 124 | multiple lines for the same URI, if a subset of all available |
| 125 | distributions or components at that location is desired. APT will |
| 126 | sort the URI list after it has generated a complete set internally, |
| 127 | and will collapse multiple references to the same Internet host, |
| 128 | for instance, into a single connection, so that it does not |
| 129 | inefficiently establish an FTP connection, close it, do something |
| 130 | else, and then re-establish a connection to that same host. This |
| 131 | feature is useful for accessing busy FTP sites with limits on the |
| 132 | number of simultaneous anonymous users. APT also parallelizes |
| 133 | connections to different hosts to more effectively deal with sites |
| 134 | with low bandwidth.</para> |
| 135 | |
| 136 | <para><literal>options</literal> is always optional and needs to be surrounded by |
| 137 | square brackets. It can consist of multiple settings in the form |
| 138 | <literal><replaceable>setting</replaceable>=<replaceable>value</replaceable></literal>. |
| 139 | Multiple settings are separated by spaces. The following settings are supported by APT |
| 140 | (note however that unsupported settings will be ignored silently): |
| 141 | <itemizedlist> |
| 142 | <listitem><para><literal>arch=<replaceable>arch1</replaceable>,<replaceable>arch2</replaceable>,…</literal> |
| 143 | can be used to specify for which architectures information should |
| 144 | be downloaded. If this option is not set all architectures defined by the |
| 145 | <literal>APT::Architectures</literal> option will be downloaded.</para></listitem> |
| 146 | <listitem><para><literal>arch+=<replaceable>arch1</replaceable>,<replaceable>arch2</replaceable>,…</literal> |
| 147 | and <literal>arch-=<replaceable>arch1</replaceable>,<replaceable>arch2</replaceable>,…</literal> |
| 148 | which can be used to add/remove architectures from the set which will be downloaded.</para></listitem> |
| 149 | <listitem><para><literal>trusted=yes</literal> can be set to indicate that packages |
| 150 | from this source are always authenticated even if the <filename>Release</filename> file |
| 151 | is not signed or the signature can't be checked. This disables parts of &apt-secure; |
| 152 | and should therefore only be used in a local and trusted context. <literal>trusted=no</literal> |
| 153 | is the opposite which handles even correctly authenticated sources as not authenticated.</para></listitem> |
| 154 | </itemizedlist></para> |
| 155 | |
| 156 | <para>It is important to list sources in order of preference, with the most |
| 157 | preferred source listed first. Typically this will result in sorting |
| 158 | by speed from fastest to slowest (CD-ROM followed by hosts on a local |
| 159 | network, followed by distant Internet hosts, for example).</para> |
| 160 | |
| 161 | <para>Some examples:</para> |
| 162 | <literallayout> |
| 163 | deb http://ftp.debian.org/debian &stable-codename; main contrib non-free |
| 164 | deb http://security.debian.org/ &stable-codename;/updates main contrib non-free |
| 165 | </literallayout> |
| 166 | |
| 167 | </refsect1> |
| 168 | |
| 169 | <refsect1><title>URI specification</title> |
| 170 | |
| 171 | <para>The currently recognized URI types are: |
| 172 | <variablelist> |
| 173 | <varlistentry><term><command>file</command></term> |
| 174 | <listitem><para> |
| 175 | The file scheme allows an arbitrary directory in the file system to be |
| 176 | considered an archive. This is useful for NFS mounts and local mirrors or |
| 177 | archives.</para></listitem> |
| 178 | </varlistentry> |
| 179 | |
| 180 | <varlistentry><term><command>cdrom</command></term> |
| 181 | <listitem><para> |
| 182 | The cdrom scheme allows APT to use a local CD-ROM drive with media |
| 183 | swapping. Use the &apt-cdrom; program to create cdrom entries in the |
| 184 | source list.</para></listitem> |
| 185 | </varlistentry> |
| 186 | |
| 187 | <varlistentry><term><command>http</command></term> |
| 188 | <listitem><para> |
| 189 | The http scheme specifies an HTTP server for the archive. If an environment |
| 190 | variable <envar>http_proxy</envar> is set with the format |
| 191 | http://server:port/, the proxy server specified in |
| 192 | <envar>http_proxy</envar> will be used. Users of authenticated |
| 193 | HTTP/1.1 proxies may use a string of the format |
| 194 | http://user:pass@server:port/. |
| 195 | Note that this is an insecure method of authentication.</para></listitem> |
| 196 | </varlistentry> |
| 197 | |
| 198 | <varlistentry><term><command>ftp</command></term> |
| 199 | <listitem><para> |
| 200 | The ftp scheme specifies an FTP server for the archive. APT's FTP behavior |
| 201 | is highly configurable; for more information see the |
| 202 | &apt-conf; manual page. Please note that an FTP proxy can be specified |
| 203 | by using the <envar>ftp_proxy</envar> environment variable. It is possible |
| 204 | to specify an HTTP proxy (HTTP proxy servers often understand FTP URLs) |
| 205 | using this environment variable and <emphasis>only</emphasis> this |
| 206 | environment variable. Proxies using HTTP specified in |
| 207 | the configuration file will be ignored.</para></listitem> |
| 208 | </varlistentry> |
| 209 | |
| 210 | <varlistentry><term><command>copy</command></term> |
| 211 | <listitem><para> |
| 212 | The copy scheme is identical to the file scheme except that packages are |
| 213 | copied into the cache directory instead of used directly at their location. |
| 214 | This is useful for people using removable media to copy files around with APT.</para></listitem> |
| 215 | </varlistentry> |
| 216 | |
| 217 | <varlistentry><term><command>rsh</command></term><term><command>ssh</command></term> |
| 218 | <listitem><para> |
| 219 | The rsh/ssh method invokes RSH/SSH to connect to a remote host and |
| 220 | access the files as a given user. Prior configuration of rhosts or RSA keys |
| 221 | is recommended. The standard <command>find</command> and <command>dd</command> |
| 222 | commands are used to perform the file transfers from the remote host. |
| 223 | </para></listitem> |
| 224 | </varlistentry> |
| 225 | |
| 226 | <varlistentry><term>adding more recognizable URI types</term> |
| 227 | <listitem><para> |
| 228 | APT can be extended with more methods shipped in other optional packages, which should |
| 229 | follow the naming scheme <package>apt-transport-<replaceable>method</replaceable></package>. |
| 230 | For instance, the APT team also maintains the package <package>apt-transport-https</package>, |
| 231 | which provides access methods for HTTPS URIs with features similar to the http method. |
| 232 | Methods for using e.g. debtorrent are also available - see &apt-transport-debtorrent;. |
| 233 | </para></listitem> |
| 234 | </varlistentry> |
| 235 | </variablelist> |
| 236 | </para> |
| 237 | </refsect1> |
| 238 | |
| 239 | <refsect1><title>Examples</title> |
| 240 | <para>Uses the archive stored locally (or NFS mounted) at /home/jason/debian |
| 241 | for stable/main, stable/contrib, and stable/non-free.</para> |
| 242 | <literallayout>deb file:/home/jason/debian stable main contrib non-free</literallayout> |
| 243 | |
| 244 | <para>As above, except this uses the unstable (development) distribution.</para> |
| 245 | <literallayout>deb file:/home/jason/debian unstable main contrib non-free</literallayout> |
| 246 | |
| 247 | <para>Source line for the above</para> |
| 248 | <literallayout>deb-src file:/home/jason/debian unstable main contrib non-free</literallayout> |
| 249 | |
| 250 | <para>The first line gets package information for the architectures in <literal>APT::Architectures</literal> |
| 251 | while the second always retrieves <literal>amd64</literal> and <literal>armel</literal>.</para> |
| 252 | <literallayout>deb http://ftp.debian.org/debian &stable-codename; main |
| 253 | deb [ arch=amd64,armel ] http://ftp.debian.org/debian &stable-codename; main</literallayout> |
| 254 | |
| 255 | <para>Uses HTTP to access the archive at archive.debian.org, and uses only |
| 256 | the hamm/main area.</para> |
| 257 | <literallayout>deb http://archive.debian.org/debian-archive hamm main</literallayout> |
| 258 | |
| 259 | <para>Uses FTP to access the archive at ftp.debian.org, under the debian |
| 260 | directory, and uses only the &stable-codename;/contrib area.</para> |
| 261 | <literallayout>deb ftp://ftp.debian.org/debian &stable-codename; contrib</literallayout> |
| 262 | |
| 263 | <para>Uses FTP to access the archive at ftp.debian.org, under the debian |
| 264 | directory, and uses only the unstable/contrib area. If this line appears as |
| 265 | well as the one in the previous example in <filename>sources.list</filename> |
| 266 | a single FTP session will be used for both resource lines.</para> |
| 267 | <literallayout>deb ftp://ftp.debian.org/debian unstable contrib</literallayout> |
| 268 | |
| 269 | <para>Uses HTTP to access the archive at ftp.tlh.debian.org, under the |
| 270 | universe directory, and uses only files found under |
| 271 | <filename>unstable/binary-i386</filename> on i386 machines, |
| 272 | <filename>unstable/binary-amd64</filename> on amd64, and so |
| 273 | forth for other supported architectures. [Note this example only |
| 274 | illustrates how to use the substitution variable; official debian |
| 275 | archives are not structured like this] |
| 276 | <literallayout>deb http://ftp.tlh.debian.org/universe unstable/binary-$(ARCH)/</literallayout> |
| 277 | </para> |
| 278 | </refsect1> |
| 279 | |
| 280 | <refsect1><title>See Also</title> |
| 281 | <para>&apt-cache; &apt-conf; |
| 282 | </para> |
| 283 | </refsect1> |
| 284 | |
| 285 | &manbugs; |
| 286 | |
| 287 | </refentry> |
| 288 | |