doc/sources.list.5

   1 .\" $Id: sources.list.5,v 1.2 1998/11/23 01:16:01 jgg Exp $
   2 .\" This manpage is copyright (C) 1998 Branden Robinson <branden@debian.org>.
   3 .\"
   4 .\" This is free software; you may redistribute it and/or modify
   5 .\" it under the terms of the GNU General Public License as
   6 .\" published by the Free Software Foundation; either version 2,
   7 .\" or (at your option) any later version.
   8 .\"
   9 .\" This is distributed in the hope that it will be useful, but
  10 .\" WITHOUT ANY WARRANTY; without even the implied warranty of
  11 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12 .\" GNU General Public License for more details.
  13 .\"
  14 .\" You should have received a copy of the GNU General Public
  15 .\" License along with APT; if not, write to the Free Software
  16 .\" Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
  17 .\" 02111-1307 USA
  18 .TH sources.list 5 "16 June 1998" "Debian GNU/Linux"
  19 .SH NAME
  20 sources.list \- package resource list for APT
  21 .SH DESCRIPTION
  22 The package resource list is used to locate archives of the package
  23 distribution system in use on the system. At this time, this manual page
  24 documents only the packaging system used by the Debian GNU/Linux system.
  25 .PP
  26 The source list is designed to support any number of active sources and a
  27 variety of source media. The file lists one source per line, with the
  28 most preferred source listed first. The format of each line is:
  29 .I type uri args
  30 The first item,
  31 .IR type ,
  32 determines the format for
  33 .IR args .
  34 .I uri
  35 is a Universal Resource Identifier (URI), which is a superset of the more
  36 specific and well-known Universal Resource Locator, or URL.
  37 .SS The deb type
  38 The
  39 .B deb
  40 type describes a typical two-level Debian archive,
  41 .IR distribution / component .
  42 Typically,
  43 .I distribution
  44 is one of
  45 .BR stable ,
  46 .BR unstable ,
  47 or
  48 .BR frozen ,
  49 while component is one of
  50 .BR main ,
  51 .BR contrib ,
  52 .BR non-free ,
  53 or
  54 .BR non-us .
  55 The format for a
  56 .I sources.list
  57 entry using the
  58 .B deb
  59 type is:
  60 .RS
  61 deb
  62 .I uri distribution
  63 .RI [ component
  64 .I ...
  65 ]
  66 .RE
  67 The URI for the
  68 .B deb
  69 type must specify the base of the Debian distribution, from which
  70 .B APT
  71 will find the information it needs.
  72 .I distribution
  73 can specify an exact path, in which case the
  74 .IR component s
  75 must be omitted and
  76 .I distribution
  77 must end with a slash (/). This is useful for when only a particular
  78 sub-section of the archive denoted by the URI is of interest.
  79 If
  80 .I distribution
  81 does not specify an exact path, at least one
  82 .I component
  83 must be present.
  84 .PP
  85 .I distribution
  86 may also contain a variable,
  87 .BR $(ARCH) ,
  88 which expands to the Debian architecture (i386, m68k, powerpc, ...)
  89 used on the system. This permits archiecture-independent
  90 .I sources.list
  91 files to be used.
  92 .PP
  93 Since only one distribution can be specified per line it may be necessary
  94 to have multiple lines for the same URI, if a subset of all available
  95 distributions or components at that location is desired.
  96 .B APT
  97 will sort the URI list after it has generated a complete set internally,
  98 and will collapse multiple references to the same Internet host, for
  99 instance, into a single connection, so that it does not inefficiently
 100 establish an FTP connection, close it, do something else, and then
 101 re-establish a connection to that same host. This feature is useful
 102 for accessing busy FTP sites with limits on the number of simultaneous
 103 anonymous users.
 104 .PP
 105 It is important to list sources in order of preference, with the most
 106 preferred source listed first. Typically this will result in sorting
 107 by speed from fastest to slowest (CD-ROM followed by hosts on a local
 108 network, followed by distant Internet hosts, for example).
 109 .SS URI specification
 110 The three currently recognized URI types are file, http, and ftp.
 111 .IP file
 112 The file scheme allows an arbitrary directory in the file system to be
 113 considered an archive. This is useful for NFS mounts and local mirrors or
 114 archives.
 115 .IP http
 116 The http scheme specifies an HTTP server for the archive. If an environment
 117 variable
 118 .B $http_proxy
 119 is set with the format
 120 .\" Ugly hackery ahead, nroff doesn't like three different typefaces in a
 121 .\" row with no spaces between anything.
 122 .BI http:// server : port /\c
 123 , the proxy server specified in
 124 .B $http_proxy
 125 will be used. Users of
 126 authenticated HTTP/1.1 proxies may use a string of the format
 127 .BI http:// user : pass @ server : port /\c
 128 .\" For some reason, starting the next line with \. didn't work. So we kludge.
 129 \&. Note that this is an insecure method of authentication.
 130 .IP ftp
 131 The ftp scheme specifies an FTP server for the archive. APT's FTP behavior
 132 is highly configurable; for more information see the
 133 .BR ftp.conf (5)
 134 manual page.
 135 .SH EXAMPLES
 136 .IP "deb file:/home/jason/debian stable main contrib non-free"
 137 Uses the archive stored locally (or NFS mounted) at
 138 .I /home/jason/debian
 139 for stable/main, stable/contrib, and stable/non-free.
 140 .IP "deb file:/home/jason/debian unstable main contrib non-free"
 141 As above, except this uses the unstable (development) distribution.
 142 .IP "deb http://www.debian.org/archive stable main"
 143 Uses HTTP to access the archive at www.debian.org, and uses only the
 144 stable/main area.
 145 .IP "deb ftp://ftp.debian.org/debian stable contrib"
 146 Uses FTP to access the archive at ftp.debian.org, under the debian
 147 directory, and uses only the stable/contrib area.
 148 .IP "deb ftp://ftp.debian.org/debian unstable contrib"
 149 Uses FTP to access the archive at ftp.debian.org, under the debian
 150 directory, and uses only the unstable/contrib area. If this line appears as
 151 well as the one in the previous example in
 152 .IR sources.list ,
 153 a single FTP session will be used for both resource lines.
 154 .IP "deb ftp://nonus.debian.org/debian-non-US unstable/binary-i386/"
 155 Uses FTP to access the archive at nonus.debian.org, under the debian-non-US
 156 directory, and uses only files found under unstable/binary-i386.
 157 .IP "deb http://ftp.de.debian.org/debian-non-US unstable/binary-$(ARCH)/"
 158 Uses HTTP to access the archive at nonus.debian.org, under the
 159 debian-non-US directory, and uses only files found under
 160 unstable/binary-i386 on i386 machines, unstable/binary-m68k on m68k, and so
 161 forth for other supported architectures.
 162 .SH SEE ALSO
 163 .BR apt-cache (8),
 164 .BR apt-get (8),
 165 .SH BUGS
 166 See <http://www.debian.org/Bugs/db/pa/lapt.html>.  If you wish to report a
 167 bug in
 168 .BR apt-get ,
 169 please see
 170 .I /usr/doc/debian/bug-reporting.txt
 171 or the
 172 .BR bug (1)
 173 command.
 174 .SH AUTHOR
 175 APT was written by the APT team <apt@packages.debian.org>.