Added diff-only and tar-only options

[apt.git] / doc / apt.conf.5.yo

mailto(apt@packages.debian.org)
manpage(apt.conf)(5)(5 Dec 1998)(apt)()
manpagename(apt.conf)(configuration file for APT)

manpagedescription()
bf(apt.conf) is the main configuration file for the APT suite of
tools, all tools make use of the configuration file and a common command line
parser to provide a uniform environment. When an APT tool starts up it will
read bf(/etc/apt/apt.conf), then read the configuration specified by the
bf($APT_CONFIG) environment variable and then finally apply the command line
options to override the configuration directives, possibly loading more 
config files.

The configuration file is organized in a tree with options organized into
functional groups. Option specification is given with a double colon
notation, for instance em(APT::Get::Assume-Yes) is an option within the
APT tool group, for the Get tool. Options do not inherit from their parent
groups.

Syntacticly the configuration language is modeled after what the ISC tools
such as bind and dhcp use. Each line is of the form
quote(APT::Get::Assume-Yes "true";) The trailing semicolon is required and
the quotes are optional. A new em(scope) can be opened with curly braces,
like: 
verb(APT {
  Get {
    Assume-Yes "true";
    Fix-Broken "true";
  };
};
)
with newlines placed to make
it more readable. Lists can be created by opening a scope an including a 
single word enclosed in quotes followed by a semicolon. 
In general the sample configuration file in
em(/usr/doc/apt/examples/apt.conf) is a good guide for how it should look.

All of the APT tools take a -o option which allows an arbitary configuration 
directive to be specified on the command line. The syntax is a full option
name (APT::Get::Assume-Yes for instance) followed by an equals sign then the
new value of the option. Lists can be appended too by adding a trailing ::
to the list name.

manpagesection(The APT Group)
This group of options controls general APT behavoir as well as holding the
options for all of the tools.

startdit()
dit(bf(Architecture))
System Architecture; sets the architecture to use when fetching files and
parsing package lists. The internal default is the architecture apt was 
compiled for.

dit(bf(Ignore-Hold))
Ignore Held packages; This global options causes the problem resolver to
ignore held packages in its decision making. 

dit(bf(Immediate-Configure))
Disable Immedate Configuration; This dangerous option disables some
of APT's ordering code to cause it to make fewer dpkg calls. Doing
so may be necessary on some extremely slow single user systems but 
is very dangerous and may cause package install scripts to fail or worse.
Use at your own risk.

dit(bf(Force-LoopBreak))
Never Enable this option unless you -really- know what you are doing. It
permits APT to temporarily remove an essential package to break a
Conflicts/Conflicts or Conflicts/Pre-Depend loop between two essential
packages. SUCH A LOOP SHOULD NEVER EXIST AND IS A GRAVE BUG. This option will
work if the essential packages are not tar, gzip, libc, dpkg, bash or 
anything that those packages depend on.

dit(bf(Get))
The Get subsection controls the bf(apt-get(8)) tool, please see its
documentation for more information about the options here.

dit(bf(Cache))
The Cache subsection controls the bf(apt-cache(8)) tool, please see its
documentation for more information about the options here.

dit(bf(CDROM))
The CDROM subsection controls the bf(apt-cdrom(8)) tool, please see its
documentation for more information about the options here.

enddit()

manpagesection(The Acquire Group)
The bf(Acquire) group of options controls the download of packages and the 
URI handlers. 

startdit()
dit(bf(Queue-Mode))
Queuing mode; bf(Queue-Mode) can be one of bf(host) or bf(access) which 
determins how APT parallelizes outgoing connections. bf(host) means that
one connection per target host will be opened, bf(access) means that one
connection per URI type will be opened.

dit(bf(Retries))
Number of retries to perform. If this is non-zero apt will retry failed 
files the given number of times.

dit(bf(Acquire::Source-Symlinks))
Use symlinks for source archives. If set to true then source archives will
be symlinked when possible instead of copying. True is the default

dit(bf(http))
HTTP URIs; http::Proxy is the default http proxy to use. It is in the standard
form of em(http://[[user][:pass]@]host[:port]/). Per host proxies can also
be specified by using the form http::Proxy::<host> with the special keyword
em(DIRECT) meaning to use no proxies. The em($http_proxy) environment variable
will override all settings.

Three settings are provided for cache control with HTTP/1.1 complient proxy
caches. bf(No-Cache) tells the proxy to not used its cached response under
any circumstances, bf(Max-Age) is sent only for index files and tells the
cache to refresh its object if it is older than the given number of seconds. 
Debian updates its index files daily so the default is 1 day. bf(No-Store) 
specifies that the cache should never store this request, it is only
set for archive files. This may be usefull to prevent polluting a proxy cache
with very large .deb files. Note: Squid 2.0.2 does not support any of
these options. 

One setting is provided to control the pipeline depth in cases where the
remote server is not RFC conforming or buggy (such as Squid 2.0.2)
Acquire::http::Pipeline-Depth can be a value from 0 to 5 indicating how many
outstanding requests APT should send.

dit(bf(ftp))
FTP URis; ftp::Proxy is the default proxy server to use. It is in the 
standard form of em(http://[[user][:pass]@]host[:port]/) and is overriden
by the ftp_proxy environment variable. To use a ftp proxy you will have to
set the ftp::ProxyLogin script in the configuration file. This entry 
specifies the commands to send to tell the proxy server what to connect
to. Please see em(/usr/doc/apt/examples/apt.conf) for an example of how 
to do this. The subsitution variables available are $(PROXY_USER),
$(PROXY_PASS), $(SITE_USER), $(SITE_PASS), $(SITE), and $(SITE_PORT). 
Each is taken from it's respective URI component.

Several settings are provided to control passive mode. Generally it is safe
to leave passive mode on, it works in nearly every environment. However some
situations require that passive mode be disabled and port mode ftp used
instead. This can be done globally, for connections that go through a proxy
or for a specific host (See the sample config file for examples)

dit(bf(cdrom))
CDROM URIs; the only setting for CDROM URIs is the mount point, cdrom::Mount
which must be the mount point for the CDROM drive as specified in /etc/fstab.
It is possible to provide alternate mount and unmount commands if your
mount point cannot be listed in the fstab (such as an SMB mount). The syntax
is to put "/cdrom/"::Mount "foo"; within the cdrom block. It is important to
have the trailing slash. Unmount commands can be specified using UMount.

enddit()

manpagesection(Directories)
The bf(Dir::State) section has directories that pertain to local state
information. bf(lists) is the directory to place downloaded package lists
in and bf(status) is the name of the dpkg status file. bf(Dir::State)
contains the default directory to prefix on all sub items if they do not
start with em(/) or em(./). bf(xstatus) and bf(userstatus) are for future
use.

bf(Dir::Cache) contains locations pertaining to local cache information, such
as the two package caches bf(srcpkgcache) and bf(pkgcache) as well as the
location to place downloaded archives, bf(Dir::Cache::archives). Like 
bf(Dir::State) the default directory is contained in bf(Dir::Cache)

bf(Dir::Etc) contains the location of configuration files, bf(sourcelist)
gives the location of the sourcelist and bf(main) is the default configuration
file (setting has no effect)

Binary programs are pointed to by bf(Dir::Bin). bf(methods) specifies the
location of the method handlers and bf(gzip), bf(dpkg), bf(apt-get), 
bf(dpkg-source), bf(dpkg-buildpackage) and
bf(apt-cache) specify the location of the respective programs.

manpagesection(APT in DSelect)
When APT is used as a bf(dselect(8)) method several configuration directives
control the default behavoir. These are in the bf(DSelect) section.

startdit()
dit(bf(Clean))
Cache Clean mode; this value may be one of always, auto, prompt and never.
always will remove all archives after they have been downloaded while auto
will only remove things that are no longer downloadable (replaced with a new
version for instance)

dit(bf(Options))
The contents of this variable is passed to bf(apt-get(8)) as command line
options when it is run for the install phase.

dit(bf(UpdateOptions))
The contents of this variable is passed to bf(apt-get(8)) as command line
options when it is run for the update phase.

dit(bf(PromptAfterUpdate))
If true the [U]pdate operation in dselect will always prompt to continue. 
The default is to prompt only on error.
enddit()

manpagesection(How APT calls DPkg)
Several configuration directives control how APT invokes dpkg. These are in 
the bf(DPkg) section.

startdit()
dit(bf(Options))
This is a list of options to pass to dpkg. The options must be specified
using the list notation and each list item is passed as a single arugment
to dpkg.

dit(bf(Pre-Invoke), bf(Post-Invoke))
This is a list of shell commands to run before/after invoking dpkg. Like 
bf(Options) this must be specified in list notation. The commands
are invoked in order using /bin/sh, should any fail APT will abort.

dit(bf(BPre-Install-Pkgs))
This is a list of shell commands to run before invoking dpkg. Like
bf(Options) this must be specified in list notation. The commands
are invoked in order using /bin/sh, should any fail APT will abort.
Apt will pass to the commands on standard input the filenames of all
.deb files it is going to install, one per line.

dit(bf(Run-Directory))
APT chdirs to this directory before invoking dpkg, the default is /.

dit(bf(Build-Options))
These options are passed to dpkg-buildpackage when compiling packages,
the default is to disable signing and produce all binaries.

enddit()

manpagesection(Debug Options)
Most of the options in the bf(debug) section are not interesting to the
normal user, however bf(Debug::pkgProblemResolver) shows interesting
output about the decisions dist-upgrade makes. bf(Debug::NoLocking)
disables file locking so apt can do some operations as non-root and
bf(Debug::pkgDPkgPM) will print out the command line for each dpkg 
invokation. bf(Debug::IdentCdrom) will disable the inclusion of statfs 
data in CDROM IDs.

manpagesection(EXAMPLES)
bf(/usr/doc/apt/examples/apt.conf) contains a sample configuration file
showing the default values for all possible options.

manpagesection(FILES)
/etc/apt/apt.conf

manpageseealso()
apt-cache (8),
apt-get (8)

manpagebugs()
See http://bugs.debian.org/apt.  If you wish to report a
bug in bf(apt-get), please see bf(/usr/doc/debian/bug-reporting.txt)
or the bf(bug(1)) command.

manpageauthor()
apt-get was written by the APT team <apt@packages.debian.org>.