doc/sources.list.5

   1 .\"     Title: sources.list
   2 .\"    Author: Jason Gunthorpe
   3 .\" Generator: DocBook XSL Stylesheets v1.71.0 <http://docbook.sf.net/>
   4 .\"      Date: 29 February 2004
   5 .\"    Manual:
   6 .\"    Source: Linux
   7 .\"
   8 .TH "SOURCES.LIST" "5" "29 February 2004" "Linux" ""
   9 .\" disable hyphenation
  10 .nh
  11 .\" disable justification (adjust text to left margin only)
  12 .ad l
  13 .SH "NAME"
  14 sources.list \- Package resource list for APT
  15 .SH "DESCRIPTION"
  16 .PP
  17 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
  18 \fI/etc/apt/sources.list\fR
  19 .PP
  20 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:
  21 type uri args
  22 The first item,
  23 type
  24 determines the format for
  25 args
  26 uri
  27 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 #.
  28 .SH "SOURCES.LIST.D"
  29 .PP
  30 The
  31 \fI/etc/apt/sources.list.d\fR
  32 directory provides a way to add sources.list entries in seperate files that end with
  33 .list. The format is the same as for the regular
  34 \fIsources.list\fR
  35 file.
  36 .SH "THE DEB AND DEB\-SRC TYPES"
  37 .PP
  38 The
  39 deb
  40 type describes a typical two\-level Debian archive,
  41 \fIdistribution/component\fR. Typically,
  42 distribution
  43 is generally one of
  44 stable
  45 unstable
  46 or
  47 testing
  48 while component is one of
  49 main
  50 contrib
  51 non\-free
  52 or
  53 non\-us
  54 The
  55 deb\-src
  56 type describes a debian distribution's source code in the same form as the
  57 deb
  58 type. A
  59 deb\-src
  60 line is required to fetch source indexes.
  61 .PP
  62 The format for a
  63 \fIsources.list\fR
  64 entry using the
  65 deb
  66 and
  67 deb\-src
  68 types are:
  69 .sp
  70 .RS 3n
  71 .nf
  72 deb uri distribution [component1] [component2] [...]
  73 .fi
  74 .RE
  75 .PP
  76 The URI for the
  77 deb
  78 type must specify the base of the Debian distribution, from which APT will find the information it needs.
  79 distribution
  80 can specify an exact path, in which case the components must be omitted and
  81 distribution
  82 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. If
  83 distribution
  84 does not specify an exact path, at least one
  85 component
  86 must be present.
  87 .PP
  88 distribution
  89 may also contain a variable,
  90 $(ARCH)
  91 which expands to the Debian architecture (i386, m68k, powerpc, ...) used on the system. This permits architecture\-independent
  92 \fIsources.list\fR
  93 files to be used. In general this is only of interest when specifying an exact path,
  94 APT
  95 will automatically generate a URI with the current architecture otherwise.
  96 .PP
  97 Since only one distribution can be specified per line it may be necessary to have multiple lines for the same URI, if a subset of all available distributions or components at that location is desired. APT will sort the URI list after it has generated a complete set internally, and will collapse multiple references to the same Internet host, for instance, into a single connection, so that it does not inefficiently establish an FTP connection, close it, do something else, and then re\-establish a connection to that same host. This feature is useful for accessing busy FTP sites with limits on the number of simultaneous anonymous users. APT also parallelizes connections to different hosts to more effectively deal with sites with low bandwidth.
  98 .PP
  99 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 network, followed by distant Internet hosts, for example).
 100 .PP
 101 Some examples:
 102 .sp
 103 .RS 3n
 104 .nf
 105 deb http://http.us.debian.org/debian stable main contrib non\-free
 106 deb http://http.us.debian.org/debian dists/stable\-updates/
 107
 108 .fi
 109 .RE
 110 .SH "URI SPECIFICATION"
 111 .PP
 112 The currently recognized URI types are cdrom, file, http, and ftp.
 113 .PP
 114 file
 115 .RS 3n
 116 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.
 117 .RE
 118 .PP
 119 cdrom
 120 .RS 3n
 121 The cdrom scheme allows APT to use a local CDROM drive with media swapping. Use the
 122 \fBapt\-cdrom\fR(8)
 123 program to create cdrom entries in the source list.
 124 .RE
 125 .PP
 126 http
 127 .RS 3n
 128 The http scheme specifies an HTTP server for the archive. If an environment variable
 129 \fBhttp_proxy\fR
 130 is set with the format http://server:port/, the proxy server specified in
 131 \fBhttp_proxy\fR
 132 will be used. Users of authenticated HTTP/1.1 proxies may use a string of the format http://user:pass@server:port/ Note that this is an insecure method of authentication.
 133 .RE
 134 .PP
 135 ftp
 136 .RS 3n
 137 The ftp scheme specifies an FTP server for the archive. APT's FTP behavior is highly configurable; for more information see the
 138 \fBapt.conf\fR(5)
 139 manual page. Please note that a ftp proxy can be specified by using the
 140 \fBftp_proxy\fR
 141 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 the configuration file will be ignored.
 142 .RE
 143 .PP
 144 copy
 145 .RS 3n
 146 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.
 147 .RE
 148 .PP
 149 rsh, ssh
 150 .RS 3n
 151 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
 152 \fBfind\fR
 153 and
 154 \fBdd\fR
 155 commands to perform the file transfers from the remote.
 156 .RE
 157 .SH "EXAMPLES"
 158 .PP
 159 Uses the archive stored locally (or NFS mounted) at /home/jason/debian for stable/main, stable/contrib, and stable/non\-free.
 160 .sp
 161 .RS 3n
 162 .nf
 163 deb file:/home/jason/debian stable main contrib non\-free
 164 .fi
 165 .RE
 166 .PP
 167 As above, except this uses the unstable (development) distribution.
 168 .sp
 169 .RS 3n
 170 .nf
 171 deb file:/home/jason/debian unstable main contrib non\-free
 172 .fi
 173 .RE
 174 .PP
 175 Source line for the above
 176 .sp
 177 .RS 3n
 178 .nf
 179 deb\-src file:/home/jason/debian unstable main contrib non\-free
 180 .fi
 181 .RE
 182 .PP
 183 Uses HTTP to access the archive at archive.debian.org, and uses only the hamm/main area.
 184 .sp
 185 .RS 3n
 186 .nf
 187 deb http://archive.debian.org/debian\-archive hamm main
 188 .fi
 189 .RE
 190 .PP
 191 Uses FTP to access the archive at ftp.debian.org, under the debian directory, and uses only the stable/contrib area.
 192 .sp
 193 .RS 3n
 194 .nf
 195 deb ftp://ftp.debian.org/debian stable contrib
 196 .fi
 197 .RE
 198 .PP
 199 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
 200 \fIsources.list\fR. a single FTP session will be used for both resource lines.
 201 .sp
 202 .RS 3n
 203 .nf
 204 deb ftp://ftp.debian.org/debian unstable contrib
 205 .fi
 206 .RE
 207 .PP
 208 Uses HTTP to access the archive at nonus.debian.org, under the debian\-non\-US directory.
 209 .sp
 210 .RS 3n
 211 .nf
 212 deb http://nonus.debian.org/debian\-non\-US stable/non\-US main contrib non\-free
 213 .fi
 214 .RE
 215 .PP
 216 Uses HTTP to access the archive at nonus.debian.org, under the debian\-non\-US directory, and uses only files found under
 217 \fIunstable/binary\-i386\fR
 218 on i386 machines,
 219 \fIunstable/binary\-m68k\fR
 220 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]
 221 .sp
 222 .RS 3n
 223 .nf
 224 deb http://ftp.de.debian.org/debian\-non\-US unstable/binary\-$(ARCH)/
 225 .fi
 226 .RE
 227 .sp
 228 .SH "SEE ALSO"
 229 .PP
 230 \fBapt\-cache\fR(8)
 231 \fBapt.conf\fR(5)
 232 .SH "BUGS"
 233 .PP
 234 [1]\&\fIAPT bug page\fR. If you wish to report a bug in APT, please see
 235 \fI/usr/share/doc/debian/bug\-reporting.txt\fR
 236 or the
 237 \fBreportbug\fR(1)
 238 command.
 239 .SH "AUTHORS"
 240 .PP
 241 \fBJason Gunthorpe\fR
 242 .sp -1n
 243 .IP "" 3n
 244 Author.
 245 .PP
 246 \fBAPT team\fR
 247 .sp -1n
 248 .IP "" 3n
 249 Author.
 250 .SH "REFERENCES"
 251 .TP 3
 252 1.\ APT bug page
 253 \%http://bugs.debian.org/src:apt