'\" t
.\"     Title: sources.list
.\"    Author: Jason Gunthorpe
.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
.\"      Date: 18\ \&January\ \&2014
.\"    Manual: APT
.\"    Source: APT 1.0.9.8.4
.\"  Language: English
.\"
.TH "SOURCES\&.LIST" "5" "18\ \&January\ \&2014" "APT 1.0.9.8.4" "APT"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
sources.list \- List of configured APT data sources
.SH "DESCRIPTION"
.PP
The source list
/etc/apt/sources\&.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 information available from the configured sources is acquired by
\fBapt\-get update\fR
(or by an equivalent command from another APT front\-end)\&.
.PP
Each line specifying a source starts with type (e\&.g\&.
deb\-src) followed by options and arguments for this type\&. Individual entries cannot be continued onto a following line\&. Empty lines are ignored, and a
#
character anywhere on a line marks the remainder of that line as a comment\&.
.SH "SOURCES.LIST.D"
.PP
The
/etc/apt/sources\&.list\&.d
directory provides a way to add sources\&.list entries in separate files\&. The format is the same as for the regular
sources\&.list
file\&. File names need to end with
\&.list
and may only contain letters (a\-z and A\-Z), digits (0\-9), underscore (_), hyphen (\-) and period (\&.) characters\&. Otherwise APT will print a notice that it has ignored a file, unless that file matches a pattern in the
Dir::Ignore\-Files\-Silently
configuration list \- in which case it will be silently ignored\&.
.SH "THE DEB AND DEB-SRC TYPES"
.PP
The
deb
type references a typical two\-level Debian archive,
distribution/component\&. The
distribution
is generally an archive name like
stable
or
testing
or a codename like
jessie
or
stretch
while component is one of
main,
contrib
or
non\-free\&. The
deb\-src
type references a Debian distribution\*(Aqs source code in the same form as the
deb
type\&. A
deb\-src
line is required to fetch source indexes\&.
.PP
The format for a
sources\&.list
entry using the
deb
and
deb\-src
types is:
.sp
.if n \{\
.RS 4
.\}
.nf
deb [ options ] uri suite [component1] [component2] [\&.\&.\&.]
.fi
.if n \{\
.RE
.\}
.PP
Alternatively a rfc822 style format is also supported:
.sp
.if n \{\
.RS 4
.\}
.nf
     Types: deb deb\-src
     URIs: http://example\&.com
     Suites: stable testing
     Sections: component1 component2
     Description: short
      long long long
     [option1]: [option1\-value]

     Types: deb
     URIs: http://another\&.example\&.com
     Suites: experimental
     Sections: component1 component2
     Enabled: no
     Description: short
      long long long
     [option1]: [option1\-value]
   
.fi
.if n \{\
.RE
.\}
.PP
The URI for the
deb
type must specify the base of the Debian distribution, from which APT will find the information it needs\&.
suite
can specify an exact path, in which case the components must be omitted and
suite
must end with a slash (/)\&. This is useful for the case when only a particular sub\-section of the archive denoted by the URI is of interest\&. If
suite
does not specify an exact path, at least one
component
must be present\&.
.PP
suite
may also contain a variable,
$(ARCH)
which expands to the Debian architecture (such as
amd64
or
armel) used on the system\&. This permits architecture\-independent
sources\&.list
files to be used\&. In general this is only of interest when specifying an exact path,
APT
will automatically generate a URI with the current architecture otherwise\&.
.PP
In the traditional style sources\&.list format 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\&.
.PP
options
is always optional and needs to be surrounded by square brackets\&. It can consist of multiple settings in the form
\fIsetting\fR=\fIvalue\fR\&. Multiple settings are separated by spaces\&. The following settings are supported by APT (note however that unsupported settings will be ignored silently):
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
arch=\fIarch1\fR,\fIarch2\fR,\&...
can be used to specify for which architectures information should be downloaded\&. If this option is not set all architectures defined by the
APT::Architectures
option will be downloaded\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
arch+=\fIarch1\fR,\fIarch2\fR,\&...
and
arch\-=\fIarch1\fR,\fIarch2\fR,\&...
which can be used to add/remove architectures from the set which will be downloaded\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
trusted=yes
can be set to indicate that packages from this source are always authenticated even if the
Release
file is not signed or the signature can\*(Aqt be checked\&. This disables parts of
\fBapt-secure\fR(8)
and should therefore only be used in a local and trusted context\&.
trusted=no
is the opposite which handles even correctly authenticated sources as not authenticated\&.
.RE
.PP
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)\&.
.PP
Some examples:
.sp
.if n \{\
.RS 4
.\}
.nf
deb http://ftp\&.debian\&.org/debian jessie main contrib non\-free
deb http://security\&.debian\&.org/ jessie/updates main contrib non\-free
   
.fi
.if n \{\
.RE
.\}
.SH "URI SPECIFICATION"
.PP
The currently recognized URI types are:
.PP
\fBfile\fR
.RS 4
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\&.
.RE
.PP
\fBcdrom\fR
.RS 4
The cdrom scheme allows APT to use a local CD\-ROM drive with media swapping\&. Use the
\fBapt-cdrom\fR(8)
program to create cdrom entries in the source list\&.
.RE
.PP
\fBhttp\fR
.RS 4
The http scheme specifies an HTTP server for the archive\&. If an environment variable
\fBhttp_proxy\fR
is set with the format http://server:port/, the proxy server specified in
\fBhttp_proxy\fR
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\&.
.RE
.PP
\fBftp\fR
.RS 4
The ftp scheme specifies an FTP server for the archive\&. APT\*(Aqs FTP behavior is highly configurable; for more information see the
\fBapt.conf\fR(5)
manual page\&. Please note that an FTP proxy can be specified by using the
\fBftp_proxy\fR
environment variable\&. It is possible to specify an HTTP proxy (HTTP proxy servers often understand FTP URLs) using this environment variable and
\fIonly\fR
this environment variable\&. Proxies using HTTP specified in the configuration file will be ignored\&.
.RE
.PP
\fBcopy\fR
.RS 4
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 removable media to copy files around with APT\&.
.RE
.PP
\fBrsh\fR, \fBssh\fR
.RS 4
The rsh/ssh method invokes RSH/SSH to connect to a remote host and access the files as a given user\&. Prior configuration of rhosts or RSA keys is recommended\&. The standard
\fBfind\fR
and
\fBdd\fR
commands are used to perform the file transfers from the remote host\&.
.RE
.PP
adding more recognizable URI types
.RS 4
APT can be extended with more methods shipped in other optional packages, which should follow the naming scheme
apt\-transport\-\fImethod\fR\&. For instance, the APT team also maintains the package
apt\-transport\-https, which provides access methods for HTTPS URIs with features similar to the http method\&. Methods for using e\&.g\&. debtorrent are also available \- see
\fBapt-transport-debtorrent\fR(1)\&.
.RE
.SH "EXAMPLES"
.PP
Uses the archive stored locally (or NFS mounted) at /home/jason/debian for stable/main, stable/contrib, and stable/non\-free\&.
.sp
.if n \{\
.RS 4
.\}
.nf
deb file:/home/jason/debian stable main contrib non\-free
.fi
.if n \{\
.RE
.\}
.PP
As above, except this uses the unstable (development) distribution\&.
.sp
.if n \{\
.RS 4
.\}
.nf
deb file:/home/jason/debian unstable main contrib non\-free
.fi
.if n \{\
.RE
.\}
.PP
Source line for the above
.sp
.if n \{\
.RS 4
.\}
.nf
deb\-src file:/home/jason/debian unstable main contrib non\-free
.fi
.if n \{\
.RE
.\}
.PP
The first line gets package information for the architectures in
APT::Architectures
while the second always retrieves
amd64
and
armel\&.
.sp
.if n \{\
.RS 4
.\}
.nf
deb http://ftp\&.debian\&.org/debian jessie main
deb [ arch=amd64,armel ] http://ftp\&.debian\&.org/debian jessie main
.fi
.if n \{\
.RE
.\}
.PP
Uses HTTP to access the archive at archive\&.debian\&.org, and uses only the hamm/main area\&.
.sp
.if n \{\
.RS 4
.\}
.nf
deb http://archive\&.debian\&.org/debian\-archive hamm main
.fi
.if n \{\
.RE
.\}
.PP
Uses FTP to access the archive at ftp\&.debian\&.org, under the debian directory, and uses only the jessie/contrib area\&.
.sp
.if n \{\
.RS 4
.\}
.nf
deb ftp://ftp\&.debian\&.org/debian jessie contrib
.fi
.if n \{\
.RE
.\}
.PP
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
sources\&.list
a single FTP session will be used for both resource lines\&.
.sp
.if n \{\
.RS 4
.\}
.nf
deb ftp://ftp\&.debian\&.org/debian unstable contrib
.fi
.if n \{\
.RE
.\}
.PP
Uses HTTP to access the archive at ftp\&.tlh\&.debian\&.org, under the universe directory, and uses only files found under
unstable/binary\-i386
on i386 machines,
unstable/binary\-amd64
on amd64, and so forth for other supported architectures\&. [Note this example only illustrates how to use the substitution variable; official debian archives are not structured like this]
.sp
.if n \{\
.RS 4
.\}
.nf
deb http://ftp\&.tlh\&.debian\&.org/universe unstable/binary\-$(ARCH)/
.fi
.if n \{\
.RE
.\}
.sp
.SH "SEE ALSO"
.PP
\fBapt-cache\fR(8)\fBapt.conf\fR(5)
.SH "BUGS"
.PP
\m[blue]\fBAPT bug page\fR\m[]\&\s-2\u[1]\d\s+2\&. If you wish to report a bug in APT, please see
/usr/share/doc/debian/bug\-reporting\&.txt
or the
\fBreportbug\fR(1)
command\&.
.SH "AUTHORS"
.PP
\fBJason Gunthorpe\fR
.RS 4
.RE
.PP
\fBAPT team\fR
.RS 4
.RE
.SH "NOTES"
.IP " 1." 4
APT bug page
.RS 4
\%http://bugs.debian.org/src:apt
.RE