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