]>
Commit | Line | Data |
---|---|---|
1 | <!-- -*- mode: sgml; mode: fold -*- --> | |
2 | <!doctype refentry PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [ | |
3 | ||
4 | <!ENTITY % aptent SYSTEM "apt.ent"> | |
5 | %aptent; | |
6 | ||
7 | ]> | |
8 | ||
9 | <refentry> | |
10 | &apt-docinfo; | |
11 | ||
12 | <refmeta> | |
13 | <refentrytitle>apt.conf</> | |
14 | <manvolnum>5</> | |
15 | </refmeta> | |
16 | ||
17 | <!-- Man page title --> | |
18 | <refnamediv> | |
19 | <refname>apt.conf</> | |
20 | <refpurpose>Configuration file for APT</> | |
21 | </refnamediv> | |
22 | ||
23 | <RefSect1><Title>Description</> | |
24 | <para> | |
25 | <filename/apt.conf/ is the main configuration file for the APT suite of | |
26 | tools, all tools make use of the configuration file and a common command line | |
27 | parser to provide a uniform environment. When an APT tool starts up it will | |
28 | read the configuration specified by the <envar/APT_CONFIG/ environment | |
29 | variable (if any) and then read the files in <literal/Dir::Etc::Parts/ | |
30 | then read the main configuration file specified by | |
31 | <literal/Dir::Etc::main/ then finally apply the | |
32 | command line options to override the configuration directives, possibly | |
33 | loading even more config files. | |
34 | <para> | |
35 | The configuration file is organized in a tree with options organized into | |
36 | functional groups. Option specification is given with a double colon | |
37 | notation, for instance <literal/APT::Get::Assume-Yes/ is an option within | |
38 | the APT tool group, for the Get tool. Options do not inherit from their | |
39 | parent groups. | |
40 | <para> | |
41 | Syntacticly the configuration language is modeled after what the ISC tools | |
42 | such as bind and dhcp use. Each line is of the form | |
43 | <literallayout>APT::Get::Assume-Yes "true";</literallayout> The trailing | |
44 | semicolon is required and the quotes are optional. A new scope can be | |
45 | opened with curly braces, like: | |
46 | <informalexample><programlisting> | |
47 | APT { | |
48 | Get { | |
49 | Assume-Yes "true"; | |
50 | Fix-Broken "true"; | |
51 | }; | |
52 | }; | |
53 | </programlisting></informalexample> | |
54 | with newlines placed to make it more readable. Lists can be created by | |
55 | opening a scope and including a single word enclosed in quotes followed by a | |
56 | semicolon. Multiple entries can be included, each separated by a semicolon. | |
57 | <informalexample><programlisting> | |
58 | DPkg::Pre-Install-Pkgs {"/usr/sbin/dpkg-preconfigure --apt";}; | |
59 | </programlisting></informalexample> | |
60 | <para> | |
61 | In general the sample configuration file in | |
62 | <filename>&docdir;examples/apt.conf</> &configureindex; | |
63 | is a good guide for how it should look. | |
64 | <para> | |
65 | Two specials are allowed, <literal/#include/ and <literal/#clear/. | |
66 | <literal/#include/ will include the given file, unless the filename | |
67 | ends in a slash, then the whole directory is included. | |
68 | <literal/#clear/ is used to erase a list of names. | |
69 | <para> | |
70 | All of the APT tools take a -o option which allows an arbitrary configuration | |
71 | directive to be specified on the command line. The syntax is a full option | |
72 | name (<literal/APT::Get::Assume-Yes/ for instance) followed by an equals | |
73 | sign then the new value of the option. Lists can be appended too by adding | |
74 | a trailing :: to the list name. | |
75 | </RefSect1> | |
76 | ||
77 | <RefSect1><Title>The APT Group</> | |
78 | <para> | |
79 | This group of options controls general APT behavior as well as holding the | |
80 | options for all of the tools. | |
81 | ||
82 | <VariableList> | |
83 | <VarListEntry><Term>Architecture</Term> | |
84 | <ListItem><Para> | |
85 | System Architecture; sets the architecture to use when fetching files and | |
86 | parsing package lists. The internal default is the architecture apt was | |
87 | compiled for. | |
88 | </VarListEntry> | |
89 | ||
90 | <VarListEntry><Term>Ignore-Hold</Term> | |
91 | <ListItem><Para> | |
92 | Ignore Held packages; This global option causes the problem resolver to | |
93 | ignore held packages in its decision making. | |
94 | </VarListEntry> | |
95 | ||
96 | <VarListEntry><Term>Clean-Installed</Term> | |
97 | <ListItem><Para> | |
98 | Defaults to on. When turned on the autoclean feature will remove any packages | |
99 | which can no longer be downloaded from the cache. If turned off then | |
100 | packages that are locally installed are also excluded from cleaning - but | |
101 | note that APT provides no direct means to reinstall them. | |
102 | </VarListEntry> | |
103 | ||
104 | <VarListEntry><Term>Immediate-Configure</Term> | |
105 | <ListItem><Para> | |
106 | Disable Immediate Configuration; This dangerous option disables some | |
107 | of APT's ordering code to cause it to make fewer dpkg calls. Doing | |
108 | so may be necessary on some extremely slow single user systems but | |
109 | is very dangerous and may cause package install scripts to fail or worse. | |
110 | Use at your own risk. | |
111 | </VarListEntry> | |
112 | ||
113 | <VarListEntry><Term>Force-LoopBreak</Term> | |
114 | <ListItem><Para> | |
115 | Never Enable this option unless you -really- know what you are doing. It | |
116 | permits APT to temporarily remove an essential package to break a | |
117 | Conflicts/Conflicts or Conflicts/Pre-Depend loop between two essential | |
118 | packages. SUCH A LOOP SHOULD NEVER EXIST AND IS A GRAVE BUG. This option | |
119 | will work if the essential packages are not tar, gzip, libc, dpkg, bash or | |
120 | anything that those packages depend on. | |
121 | </VarListEntry> | |
122 | ||
123 | <VarListEntry><Term>Cache-Limit</Term> | |
124 | <ListItem><Para> | |
125 | APT uses a fixed size memory mapped cache file to store the 'available' | |
126 | information. This sets the size of that cache. | |
127 | </VarListEntry> | |
128 | ||
129 | <VarListEntry><Term>Build-Essential</Term> | |
130 | <ListItem><Para> | |
131 | Defines which package(s) are considered essential build dependencies. | |
132 | </VarListEntry> | |
133 | ||
134 | <VarListEntry><Term>Get</Term> | |
135 | <ListItem><Para> | |
136 | The Get subsection controls the &apt-get; tool, please see its | |
137 | documentation for more information about the options here. | |
138 | </VarListEntry> | |
139 | ||
140 | <VarListEntry><Term>Cache</Term> | |
141 | <ListItem><Para> | |
142 | The Cache subsection controls the &apt-cache; tool, please see its | |
143 | documentation for more information about the options here. | |
144 | </VarListEntry> | |
145 | ||
146 | <VarListEntry><Term>CDROM</Term> | |
147 | <ListItem><Para> | |
148 | The CDROM subsection controls the &apt-cdrom; tool, please see its | |
149 | documentation for more information about the options here. | |
150 | </VarListEntry> | |
151 | </VariableList> | |
152 | </RefSect1> | |
153 | ||
154 | <RefSect1><Title>The Acquire Group</> | |
155 | <para> | |
156 | The <literal/Acquire/ group of options controls the download of packages | |
157 | and the URI handlers. | |
158 | ||
159 | <VariableList> | |
160 | <VarListEntry><Term>Queue-Mode</Term> | |
161 | <ListItem><Para> | |
162 | Queuing mode; <literal/Queue-Mode/ can be one of <literal/host/ or | |
163 | <literal/access/ which determines how APT parallelizes outgoing | |
164 | connections. <literal/host/ means that one connection per target host | |
165 | will be opened, <literal/access/ means that one connection per URI type | |
166 | will be opened. | |
167 | </VarListEntry> | |
168 | ||
169 | <VarListEntry><Term>Retries</Term> | |
170 | <ListItem><Para> | |
171 | Number of retries to perform. If this is non-zero APT will retry failed | |
172 | files the given number of times. | |
173 | </VarListEntry> | |
174 | ||
175 | <VarListEntry><Term>Source-Symlinks</Term> | |
176 | <ListItem><Para> | |
177 | Use symlinks for source archives. If set to true then source archives will | |
178 | be symlinked when possible instead of copying. True is the default | |
179 | </VarListEntry> | |
180 | ||
181 | <VarListEntry><Term>http</Term> | |
182 | <ListItem><Para> | |
183 | HTTP URIs; http::Proxy is the default http proxy to use. It is in the | |
184 | standard form of <literal>http://[[user][:pass]@]host[:port]/</>. Per | |
185 | host proxies can also be specified by using the form | |
186 | <literal/http::Proxy::<host>/ with the special keyword <literal/DIRECT/ | |
187 | meaning to use no proxies. The <envar/http_proxy/ environment variable | |
188 | will override all settings. | |
189 | <para> | |
190 | Three settings are provided for cache control with HTTP/1.1 compliant | |
191 | proxy caches. <literal/No-Cache/ tells the proxy to not use its cached | |
192 | response under any circumstances, <literal/Max-Age/ is sent only for | |
193 | index files and tells the cache to refresh its object if it is older than | |
194 | the given number of seconds. Debian updates its index files daily so the | |
195 | default is 1 day. <literal/No-Store/ specifies that the cache should never | |
196 | store this request, it is only set for archive files. This may be useful | |
197 | to prevent polluting a proxy cache with very large .deb files. Note: | |
198 | Squid 2.0.2 does not support any of these options. | |
199 | <para> | |
200 | The option <literal/timeout/ sets the timeout timer used by the method, | |
201 | this applies to all things including connection timeout and data timeout. | |
202 | <para> | |
203 | One setting is provided to control the pipeline depth in cases where the | |
204 | remote server is not RFC conforming or buggy (such as Squid 2.0.2) | |
205 | <literal/Acquire::http::Pipeline-Depth/ can be a value from 0 to 5 | |
206 | indicating how many outstanding requests APT should send. A value of | |
207 | zero MUST be specified if the remote host does not properly linger | |
208 | on TCP connections - otherwise data corruption will occur. Hosts which | |
209 | require this are in violation of RFC 2068. | |
210 | </VarListEntry> | |
211 | ||
212 | <VarListEntry><Term>ftp</Term> | |
213 | <ListItem><Para> | |
214 | FTP URIs; ftp::Proxy is the default proxy server to use. It is in the | |
215 | standard form of <literal>ftp://[[user][:pass]@]host[:port]/</> and is | |
216 | overridden by the <envar/ftp_proxy/ environment variable. To use a ftp | |
217 | proxy you will have to set the <literal/ftp::ProxyLogin/ script in the | |
218 | configuration file. This entry specifies the commands to send to tell | |
219 | the proxy server what to connect to. Please see | |
220 | &configureindex; for an example of | |
221 | how to do this. The subsitution variables available are | |
222 | <literal/$(PROXY_USER)/, <literal/$(PROXY_PASS)/, <literal/$(SITE_USER)/, | |
223 | <literal/$(SITE_PASS)/, <literal/$(SITE)/, and <literal/$(SITE_PORT)/. | |
224 | Each is taken from it's respective URI component. | |
225 | <para> | |
226 | The option <literal/timeout/ sets the timeout timer used by the method, | |
227 | this applies to all things including connection timeout and data timeout. | |
228 | <para> | |
229 | Several settings are provided to control passive mode. Generally it is | |
230 | safe to leave passive mode on, it works in nearly every environment. | |
231 | However some situations require that passive mode be disabled and port | |
232 | mode ftp used instead. This can be done globally, for connections that | |
233 | go through a proxy or for a specific host (See the sample config file | |
234 | for examples) | |
235 | <para> | |
236 | It is possible to proxy FTP over HTTP by setting the <envar/ftp_proxy/ | |
237 | environment variable to a http url - see the discussion of the http method | |
238 | above for syntax. You cannot set this in the configuration file and it is | |
239 | not recommended to use FTP over HTTP due to its low efficiency. | |
240 | <para> | |
241 | The setting <literal/ForceExtended/ controls the use of RFC2428 | |
242 | <literal/EPSV/ and <literal/EPRT/ commands. The defaut is false, which means | |
243 | these commands are only used if the control connection is IPv6. Setting this | |
244 | to true forces their use even on IPv4 connections. Note that most FTP servers | |
245 | do not support RFC2428. | |
246 | </VarListEntry> | |
247 | ||
248 | <VarListEntry><Term>cdrom</Term> | |
249 | <ListItem><Para> | |
250 | CDROM URIs; the only setting for CDROM URIs is the mount point, | |
251 | <literal/cdrom::Mount/ which must be the mount point for the CDROM drive | |
252 | as specified in <filename>/etc/fstab</>. It is possible to provide | |
253 | alternate mount and unmount commands if your mount point cannot be listed | |
254 | in the fstab (such as an SMB mount and old mount packages). The syntax | |
255 | is to put <literallayout>"/cdrom/"::Mount "foo";</literallayout> within | |
256 | the cdrom block. It is important to have the trailing slash. Unmount | |
257 | commands can be specified using UMount. | |
258 | </VarListEntry> | |
259 | </VariableList> | |
260 | </RefSect1> | |
261 | ||
262 | <RefSect1><Title>Directories</> | |
263 | <para> | |
264 | The <literal/Dir::State/ section has directories that pertain to local | |
265 | state information. <literal/lists/ is the directory to place downloaded | |
266 | package lists in and <literal/status/ is the name of the dpkg status file. | |
267 | <literal/preferences/ is the name of the APT preferences file. | |
268 | <literal/Dir::State/ contains the default directory to prefix on all sub | |
269 | items if they do not start with <filename>/</> or <filename>./</>. | |
270 | <para> | |
271 | <literal/Dir::Cache/ contains locations pertaining to local cache | |
272 | information, such as the two package caches <literal/srcpkgcache/ and | |
273 | <literal/pkgcache/ as well as the location to place downloaded archives, | |
274 | <literal/Dir::Cache::archives/. Generation of caches can be turned off | |
275 | by setting their names to be blank. This will slow down startup but | |
276 | save disk space. It is probably prefered to turn off the pkgcache rather | |
277 | than the srcpkgcache. Like <literal/Dir::State/ the default | |
278 | directory is contained in <literal/Dir::Cache/ | |
279 | <para> | |
280 | <literal/Dir::Etc/ contains the location of configuration files, | |
281 | <literal/sourcelist/ gives the location of the sourcelist and | |
282 | <literal/main/ is the default configuration file (setting has no effect, | |
283 | unless it is done from the config file specified by | |
284 | <envar/APT_CONFIG/). | |
285 | <para> | |
286 | The <literal/Dir::Parts/ setting reads in all the config fragments in | |
287 | lexical order from the directory specified. After this is done then the | |
288 | main config file is loaded. | |
289 | <para> | |
290 | Binary programs are pointed to by <literal/Dir::Bin/. <literal/methods/ | |
291 | specifies the location of the method handlers and <literal/gzip/, | |
292 | <literal/dpkg/, <literal/apt-get/, <literal/dpkg-source/, | |
293 | <literal/dpkg-buildpackage/ and <literal/apt-cache/ specify the location | |
294 | of the respective programs. | |
295 | </RefSect1> | |
296 | ||
297 | <RefSect1><Title>APT in DSelect</> | |
298 | <para> | |
299 | When APT is used as a &dselect; method several configuration directives | |
300 | control the default behaviour. These are in the <literal/DSelect/ section. | |
301 | ||
302 | <VariableList> | |
303 | <VarListEntry><Term>Clean</Term> | |
304 | <ListItem><Para> | |
305 | Cache Clean mode; this value may be one of always, prompt, auto, | |
306 | pre-auto and never. always and prompt will remove all packages from | |
307 | the cache after upgrading, prompt (the default) does so conditionally. | |
308 | auto removes only those packages which are no longer downloadable | |
309 | (replaced with a new version for instance). pre-auto performs this | |
310 | action before downloading new packages. | |
311 | </VarListEntry> | |
312 | ||
313 | <VarListEntry><Term>Options</Term> | |
314 | <ListItem><Para> | |
315 | The contents of this variable is passed to &apt-get; as command line | |
316 | options when it is run for the install phase. | |
317 | </VarListEntry> | |
318 | ||
319 | <VarListEntry><Term>UpdateOptions</Term> | |
320 | <ListItem><Para> | |
321 | The contents of this variable is passed to &apt-get; as command line | |
322 | options when it is run for the update phase. | |
323 | </VarListEntry> | |
324 | ||
325 | <VarListEntry><Term>PromptAfterUpdate</Term> | |
326 | <ListItem><Para> | |
327 | If true the [U]pdate operation in &dselect; will always prompt to continue. | |
328 | The default is to prompt only on error. | |
329 | </VarListEntry> | |
330 | </VariableList> | |
331 | </RefSect1> | |
332 | ||
333 | <RefSect1><Title>How APT calls dpkg</> | |
334 | <para> | |
335 | Several configuration directives control how APT invokes &dpkg;. These are | |
336 | in the <literal/DPkg/ section. | |
337 | ||
338 | <VariableList> | |
339 | <VarListEntry><Term>Options</Term> | |
340 | <ListItem><Para> | |
341 | This is a list of options to pass to dpkg. The options must be specified | |
342 | using the list notation and each list item is passed as a single argument | |
343 | to &dpkg;. | |
344 | </VarListEntry> | |
345 | ||
346 | <VarListEntry><Term>Pre-Invoke</Term><Term>Post-Invoke</Term> | |
347 | <ListItem><Para> | |
348 | This is a list of shell commands to run before/after invoking &dpkg;. | |
349 | Like <literal/Options/ this must be specified in list notation. The | |
350 | commands are invoked in order using <filename>/bin/sh</>, should any | |
351 | fail APT will abort. | |
352 | </VarListEntry> | |
353 | ||
354 | <VarListEntry><Term>Pre-Install-Pkgs</Term> | |
355 | <ListItem><Para> | |
356 | This is a list of shell commands to run before invoking dpkg. Like | |
357 | <literal/Options/ this must be specified in list notation. The commands | |
358 | are invoked in order using <filename>/bin/sh</>, should any fail APT | |
359 | will abort. APT will pass to the commands on standard input the | |
360 | filenames of all .deb files it is going to install, one per line. | |
361 | <para> | |
362 | Version 2 of this protocol dumps more information, including the | |
363 | protocol version, the APT configuration space and the packages, files | |
364 | and versions being changed. Version 2 is enabled by setting | |
365 | <literal/DPkg::Tools::Options::cmd::Version/ to 2. <literal/cmd/ is a | |
366 | command given to <literal/Pre-Install-Pkgs/. | |
367 | </VarListEntry> | |
368 | ||
369 | <VarListEntry><Term>Run-Directory</Term> | |
370 | <ListItem><Para> | |
371 | APT chdirs to this directory before invoking dpkg, the default is | |
372 | <filename>/</>. | |
373 | </VarListEntry> | |
374 | ||
375 | <VarListEntry><Term>Build-Options</Term> | |
376 | <ListItem><Para> | |
377 | These options are passed to &dpkg-buildpackage; when compiling packages, | |
378 | the default is to disable signing and produce all binaries. | |
379 | </VarListEntry> | |
380 | </VariableList> | |
381 | </RefSect1> | |
382 | ||
383 | <RefSect1><Title>Debug Options</> | |
384 | <para> | |
385 | Most of the options in the <literal/debug/ section are not interesting to | |
386 | the normal user, however <literal/Debug::pkgProblemResolver/ shows | |
387 | interesting output about the decisions dist-upgrade makes. | |
388 | <literal/Debug::NoLocking/ disables file locking so APT can do some | |
389 | operations as non-root and <literal/Debug::pkgDPkgPM/ will print out the | |
390 | command line for each dpkg invokation. <literal/Debug::IdentCdrom/ will | |
391 | disable the inclusion of statfs data in CDROM IDs. | |
392 | </RefSect1> | |
393 | ||
394 | <RefSect1><Title>Examples</> | |
395 | <para> | |
396 | &configureindex; contains a | |
397 | sample configuration file showing the default values for all possible | |
398 | options. | |
399 | </RefSect1> | |
400 | ||
401 | <RefSect1><Title>Files</> | |
402 | <para> | |
403 | <filename>/etc/apt/apt.conf</> | |
404 | </RefSect1> | |
405 | ||
406 | <RefSect1><Title>See Also</> | |
407 | <para> | |
408 | &apt-cache;, &apt-config;<!-- ? reading apt.conf -->, &apt-preferences;. | |
409 | </RefSect1> | |
410 | ||
411 | &manbugs; | |
412 | &manauthor; | |
413 | ||
414 | </refentry> |