- forgot to add apt.conf.5 on r193
[apt.git] / doc / apt.conf.5
1 .\" This manpage has been automatically generated by docbook2man 
2 .\" from a DocBook document.  This tool can be found at:
3 .\" <http://shell.ipoline.com/~elmert/comp/docbook2X/> 
4 .\" Please send any bug reports, improvements, comments, patches, 
5 .\" etc. to Steve Cheng <steve@ggi-project.org>.
6 .TH "APT.CONF" "5" "29 May 2006" "" ""
7
8 .SH NAME
9 apt.conf \- Configuration file for APT
10 .SH "DESCRIPTION"
11 .PP
12 \fIapt.conf\fR is the main configuration file for the APT suite of
13 tools, all tools make use of the configuration file and a common command line
14 parser to provide a uniform environment. When an APT tool starts up it will
15 read the configuration specified by the \fBAPT_CONFIG\fR environment 
16 variable (if any) and then read the files in Dir::Etc::Parts 
17 then read the main configuration file specified by 
18 Dir::Etc::main then finally apply the
19 command line options to override the configuration directives, possibly 
20 loading even more config files.
21 .PP
22 The configuration file is organized in a tree with options organized into
23 functional groups. Option specification is given with a double colon
24 notation, for instance APT::Get::Assume-Yes is an option within 
25 the APT tool group, for the Get tool. Options do not inherit from their 
26 parent groups.
27 .PP
28 Syntacticly the configuration language is modeled after what the ISC tools
29 such as bind and dhcp use.  Lines starting with
30 // are treated as comments (ignored).  Each line is of the form
31
32 .nf
33 APT::Get::Assume-Yes "true";
34 .fi
35 The trailing 
36 semicolon is required and the quotes are optional. A new scope can be
37 opened with curly braces, like:
38 .PP
39
40 .nf
41    
42 APT {
43   Get {
44     Assume-Yes "true";
45     Fix-Broken "true";
46   };
47 };
48 .fi
49 with newlines placed to make it more readable. Lists can be created by 
50 opening a scope and including a single word enclosed in quotes followed by a 
51 semicolon. Multiple entries can be included, each separated by a semicolon.
52 .PP
53
54 .nf
55    
56 RPM::Allow-Duplicated {"kernel"; "kernel-smp";};
57 .fi
58 .PP
59 In general the sample configuration file in 
60 \fI/usr/share/doc/apt/examples/apt.conf\fR \fI/usr/share/doc/apt/examples/configure-index.gz\fR
61 is a good guide for how it should look.
62 .PP
63 Two specials are allowed, #include and #clear\&. 
64 #include will include the given file, unless the filename
65 ends in a slash, then the whole directory is included.  
66 #clear is used to erase a list of names.
67 .PP
68 All of the APT tools take a -o option which allows an arbitrary configuration 
69 directive to be specified on the command line. The syntax is a full option
70 name (APT::Get::Assume-Yes for instance) followed by an equals
71 sign then the new value of the option. Lists can be appended too by adding 
72 a trailing :: to the list name.   
73 .SH "THE APT GROUP"
74 .PP
75 This group of options controls general APT behavior as well as holding the
76 options for all of the tools.
77 .TP
78 \fBArchitecture\fR
79 System Architecture; sets the architecture to use when fetching files and
80 parsing package lists. The internal default is the architecture apt was 
81 compiled for.
82 .TP
83 \fBIgnore-Hold\fR
84 Ignore Held packages; This global option causes the problem resolver to
85 ignore held packages in its decision making. 
86 .TP
87 \fBClean-Installed\fR
88 Defaults to on. When turned on the autoclean feature will remove any packages
89 which can no longer be downloaded from the cache. If turned off then
90 packages that are locally installed are also excluded from cleaning - but
91 note that APT provides no direct means to reinstall them.
92 .TP
93 \fBForce-LoopBreak\fR
94 Never Enable this option unless you -really- know what you are doing. It
95 permits APT to temporarily remove an essential package to break a
96 Conflicts/Conflicts or Conflicts/Pre-Depend loop between two essential
97 packages. SUCH A LOOP SHOULD NEVER EXIST AND IS A GRAVE BUG. This option 
98 will work if the essential packages are not gzip, libc, rpm, bash or
99 anything that those packages depend on.
100 .TP
101 \fBCache-Limit\fR
102 APT uses a fixed size memory mapped cache file to store the 'available'
103 information. This sets the size of that cache.
104 .TP
105 \fBBuild-Essential\fR
106 Defines which package(s) are considered essential build dependencies.
107 .TP
108 \fBGet\fR
109 The Get subsection controls the \fBapt-get\fR(8) tool, please see its
110 documentation for more information about the options here.
111 .TP
112 \fBCache\fR
113 The Cache subsection controls the \fBapt-cache\fR(8) tool, please see its
114 documentation for more information about the options here.
115 .TP
116 \fBCDROM\fR
117 The CDROM subsection controls the \fBapt-cdrom\fR(8) tool, please see its
118 documentation for more information about the options here.
119 .SH "THE ACQUIRE GROUP"
120 .PP
121 The Acquire group of options controls the download of packages 
122 and the URI handlers. 
123 .TP
124 \fBQueue-Mode\fR
125 Queuing mode; Queue-Mode can be one of host or 
126 access which determines how  APT parallelizes outgoing 
127 connections. host means that one connection per target host 
128 will be opened, access means that one connection per URI type 
129 will be opened.
130 .TP
131 \fBRetries\fR
132 Number of retries to perform. If this is non-zero APT will retry failed 
133 files the given number of times.
134 .TP
135 \fBSource-Symlinks\fR
136 Use symlinks for source archives. If set to true then source archives will
137 be symlinked when possible instead of copying. True is the default
138 .TP
139 \fBhttp\fR
140 HTTP URIs; http::Proxy is the default http proxy to use. It is in the 
141 standard form of http://[[user][:pass]@]host[:port]/\&. Per 
142 host proxies can also be specified by using the form 
143 http::Proxy::<host> with the special keyword DIRECT 
144 meaning to use no proxies. The \fBhttp_proxy\fR environment variable
145 will override all settings.
146
147 Three settings are provided for cache control with HTTP/1.1 compliant 
148 proxy caches. No-Cache tells the proxy to not use its cached 
149 response under any circumstances, Max-Age is sent only for 
150 index files and tells the cache to refresh its object if it is older than 
151 the given number of seconds. Debian updates its index files daily so the 
152 default is 1 day. No-Store specifies that the cache should never 
153 store this request, it is only set for archive files. This may be useful 
154 to prevent polluting a proxy cache with very large .deb files. Note: 
155 Squid 2.0.2 does not support any of these options.
156
157 The option timeout sets the timeout timer used by the method, 
158 this applies to all things including connection timeout and data timeout.
159
160 One setting is provided to control the pipeline depth in cases where the
161 remote server is not RFC conforming or buggy (such as Squid 2.0.2)
162 Acquire::http::Pipeline-Depth can be a value from 0 to 5 
163 indicating how many outstanding requests APT should send. A value of
164 zero MUST be specified if the remote host does not properly linger
165 on TCP connections - otherwise data corruption will occur. Hosts which
166 require this are in violation of RFC 2068.     
167 .TP
168 \fBftp\fR
169 FTP URIs; ftp::Proxy is the default proxy server to use. It is in the 
170 standard form of ftp://[[user][:pass]@]host[:port]/ and is 
171 overridden by the \fBftp_proxy\fR environment variable. To use a ftp 
172 proxy you will have to set the ftp::ProxyLogin script in the 
173 configuration file. This entry specifies the commands to send to tell 
174 the proxy server what to connect to. Please see 
175 \fI/usr/share/doc/apt/examples/configure-index.gz\fR for an example of 
176 how to do this. The subsitution variables available are 
177 $(PROXY_USER), $(PROXY_PASS), $(SITE_USER),
178 $(SITE_PASS), $(SITE), and $(SITE_PORT)\&.
179 Each is taken from it's respective URI component.
180
181 The option timeout sets the timeout timer used by the method, 
182 this applies to all things including connection timeout and data timeout.
183
184 Several settings are provided to control passive mode. Generally it is 
185 safe to leave passive mode on, it works in nearly every environment. 
186 However some situations require that passive mode be disabled and port 
187 mode ftp used instead. This can be done globally, for connections that 
188 go through a proxy or for a specific host (See the sample config file 
189 for examples)
190
191 It is possible to proxy FTP over HTTP by setting the \fBftp_proxy\fR
192 environment variable to a http url - see the discussion of the http method
193 above for syntax. You cannot set this in the configuration file and it is
194 not recommended to use FTP over HTTP due to its low efficiency.
195
196 The setting ForceExtended controls the use of RFC2428 
197 EPSV and EPRT commands. The defaut is false, which means
198 these commands are only used if the control connection is IPv6. Setting this
199 to true forces their use even on IPv4 connections. Note that most FTP servers
200 do not support RFC2428.
201 .TP
202 \fBcdrom\fR
203 CDROM URIs; the only setting for CDROM URIs is the mount point, 
204 cdrom::Mount which must be the mount point for the CDROM drive 
205 as specified in \fI/etc/fstab\fR\&. It is possible to provide 
206 alternate mount and unmount commands if your mount point cannot be listed 
207 in the fstab (such as an SMB mount and old mount packages). The syntax 
208 is to put 
209
210 .nf
211 "/cdrom/"::Mount "foo";
212 .fi
213 within 
214 the cdrom block. It is important to have the trailing slash. Unmount 
215 commands can be specified using UMount.
216 .SH "DIRECTORIES"
217 .PP
218 The Dir::State section has directories that pertain to local 
219 state information. lists is the directory to place downloaded 
220 package lists in.
221 preferences is the name of the APT preferences file.
222 Dir::State contains the default directory to prefix on all sub 
223 items if they do not start with \fI/\fR or \fI\&./\fR\&. 
224 .PP
225 Dir::Cache contains locations pertaining to local cache 
226 information, such as the two package caches srcpkgcache and 
227 pkgcache as well as the location to place downloaded archives, 
228 Dir::Cache::archives\&. Generation of caches can be turned off
229 by setting their names to be blank. This will slow down startup but
230 save disk space. It is probably prefered to turn off the pkgcache rather
231 than the srcpkgcache. Like Dir::State the default
232 directory is contained in Dir::Cache
233 .PP
234 Dir::Etc contains the location of configuration files, 
235 sourcelist gives the location of the sourcelist and 
236 main is the default configuration file (setting has no effect,
237 unless it is done from the config file specified by 
238 \fBAPT_CONFIG\fR).
239 .PP
240 The Dir::Parts setting reads in all the config fragments in 
241 lexical order from the directory specified. After this is done then the
242 main config file is loaded.
243 .PP
244 Binary programs are pointed to by Dir::Bin\&. Dir::Bin::Methods 
245 specifies the location of the method handlers and gzip, 
246 rpm, apt-get, rpmbuild
247 and apt-cache specify the location
248 of the respective programs.
249 .SH "HOW APT CALLS RPM"
250 .PP
251 Several configuration directives control how APT invokes \fBrpm\fR(8)\&. These are 
252 in the RPM section.
253 .TP
254 \fBOptions\fR
255 This is a list of options to pass to rpm for all install, upgrade and
256 remove operations. The options must be specified
257 using the list notation and each list item is passed as a single argument
258 to \fBrpm\fR(8)\&.
259 .TP
260 \fBInstall-Options\fR
261 This is a list of options to pass to rpm during install and upgrade
262 operations. The options must be specified
263 using the list notation and each list item is passed as a single argument
264 to \fBrpm\fR(8)\&.
265 .TP
266 \fBErase-Options\fR
267 This is a list of options to pass to rpm during remove operations. 
268 The options must be specified
269 using the list notation and each list item is passed as a single argument
270 to \fBrpm\fR(8)\&.
271 .TP
272 \fBPre-Invoke\fR
273 .TP
274 \fBPost-Invoke\fR
275 This is a list of shell commands to run before/after invoking \fBrpm\fR(8)\&. 
276 Like Options this must be specified in list notation. The 
277 commands are invoked in order using \fI/bin/sh\fR, should any 
278 fail APT will abort.
279 .TP
280 \fBPre-Install-Pkgs\fR
281 This is a list of shell commands to run before invoking rpm. Like
282 Options this must be specified in list notation. The commands
283 are invoked in order using \fI/bin/sh\fR, should any fail APT 
284 will abort. APT will pass to the commands on standard input the 
285 filenames of all .rpm files it is going to install, one per line.
286
287 Version 2 of this protocol dumps more information, including the 
288 protocol version, the APT configuration space and the packages, files
289 and versions being changed. Version 2 is enabled by setting 
290 DPkg::Tools::Options::cmd::Version to 2. cmd is a
291 command given to Pre-Install-Pkgs\&.
292 .TP
293 \fBRun-Directory\fR
294 APT chdirs to this directory before invoking rpm, the default is 
295 \fI/\fR\&.
296 .TP
297 \fBBuild-Options\fR
298 These options are passed to \fBrpmbuild\fR(1) when compiling packages.
299 .SH "DEBUG OPTIONS"
300 .PP
301 Most of the options in the debug section are not interesting to 
302 the normal user, however Debug::pkgProblemResolver shows 
303 interesting output about the decisions dist-upgrade makes. 
304 Debug::NoLocking disables file locking so APT can do some 
305 operations as non-root and Debug::pkgRPMPM will print out the 
306 command line for each rpm invokation. Debug::IdentCdrom will 
307 disable the inclusion of statfs data in CDROM IDs.
308 .SH "EXAMPLES"
309 .PP
310 \fI/usr/share/doc/apt/examples/configure-index.gz\fR contains a 
311 sample configuration file showing the default values for all possible 
312 options.
313 .SH "FILES"
314 .PP
315 \fI/etc/apt/apt.conf\fR
316 .SH "SEE ALSO"
317 .PP
318 \fBapt-cache\fR(8), \fBapt-config\fR(8), \fBapt_preferences\fR(5)\&.
319 .SH "BUGS"
320 .PP
321 Reporting bugs in APT-RPM is best done in the 
322 APT-RPM mailinglist <URL:http://apt-rpm.org/mailinglist.shtml>\&.
323 .SH "AUTHOR"
324 .PP
325 Maintainer and contributor information can be found in the
326 credits page <URL:http://apt-rpm.org/about.shtml> of APT-RPM.