~ubuntu-branches/debian/jessie/apt/jessie

'\" 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.8

.\"  Language: English

.\"

.TH "SOURCES\&.LIST" "5" "18\ \&January\ \&2014" "APT 1.0.8" "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

wheezy

or

jessie

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 wheezy main contrib non\-free

deb http://security\&.debian\&.org/ wheezy/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 wheezy main

deb [ arch=amd64,armel ] http://ftp\&.debian\&.org/debian wheezy 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 wheezy/contrib area\&.

.sp

.if n \{\

.RS 4

.\}

.nf

deb ftp://ftp\&.debian\&.org/debian wheezy 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