- forgot to add apt.conf.5 on r193
authorpmatilai <pmatilai>
Thu, 1 Jun 2006 14:59:51 +0000 (14:59 +0000)
committerpmatilai <pmatilai>
Thu, 1 Jun 2006 14:59:51 +0000 (14:59 +0000)
doc/apt.conf.5 [new file with mode: 0644]

diff --git a/doc/apt.conf.5 b/doc/apt.conf.5
new file mode 100644 (file)
index 0000000..6e39dc1
--- /dev/null
@@ -0,0 +1,326 @@
+.\" This manpage has been automatically generated by docbook2man 
+.\" from a DocBook document.  This tool can be found at:
+.\" <http://shell.ipoline.com/~elmert/comp/docbook2X/> 
+.\" Please send any bug reports, improvements, comments, patches, 
+.\" etc. to Steve Cheng <steve@ggi-project.org>.
+.TH "APT.CONF" "5" "29 May 2006" "" ""
+
+.SH NAME
+apt.conf \- Configuration file for APT
+.SH "DESCRIPTION"
+.PP
+\fIapt.conf\fR 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 the configuration specified by the \fBAPT_CONFIG\fR environment 
+variable (if any) and then read the files in Dir::Etc::Parts 
+then read the main configuration file specified by 
+Dir::Etc::main then finally apply the
+command line options to override the configuration directives, possibly 
+loading even more config files.
+.PP
+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 APT::Get::Assume-Yes is an option within 
+the APT tool group, for the Get tool. Options do not inherit from their 
+parent groups.
+.PP
+Syntacticly the configuration language is modeled after what the ISC tools
+such as bind and dhcp use.  Lines starting with
+// are treated as comments (ignored).  Each line is of the form
+
+.nf
+APT::Get::Assume-Yes "true";
+.fi
+The trailing 
+semicolon is required and the quotes are optional. A new scope can be
+opened with curly braces, like:
+.PP
+
+.nf
+   
+APT {
+  Get {
+    Assume-Yes "true";
+    Fix-Broken "true";
+  };
+};
+.fi
+with newlines placed to make it more readable. Lists can be created by 
+opening a scope and including a single word enclosed in quotes followed by a 
+semicolon. Multiple entries can be included, each separated by a semicolon.
+.PP
+
+.nf
+   
+RPM::Allow-Duplicated {"kernel"; "kernel-smp";};
+.fi
+.PP
+In general the sample configuration file in 
+\fI/usr/share/doc/apt/examples/apt.conf\fR \fI/usr/share/doc/apt/examples/configure-index.gz\fR
+is a good guide for how it should look.
+.PP
+Two specials are allowed, #include and #clear\&. 
+#include will include the given file, unless the filename
+ends in a slash, then the whole directory is included.  
+#clear is used to erase a list of names.
+.PP
+All of the APT tools take a -o option which allows an arbitrary 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.   
+.SH "THE APT GROUP"
+.PP
+This group of options controls general APT behavior as well as holding the
+options for all of the tools.
+.TP
+\fBArchitecture\fR
+System Architecture; sets the architecture to use when fetching files and
+parsing package lists. The internal default is the architecture apt was 
+compiled for.
+.TP
+\fBIgnore-Hold\fR
+Ignore Held packages; This global option causes the problem resolver to
+ignore held packages in its decision making. 
+.TP
+\fBClean-Installed\fR
+Defaults to on. When turned on the autoclean feature will remove any packages
+which can no longer be downloaded from the cache. If turned off then
+packages that are locally installed are also excluded from cleaning - but
+note that APT provides no direct means to reinstall them.
+.TP
+\fBForce-LoopBreak\fR
+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 gzip, libc, rpm, bash or
+anything that those packages depend on.
+.TP
+\fBCache-Limit\fR
+APT uses a fixed size memory mapped cache file to store the 'available'
+information. This sets the size of that cache.
+.TP
+\fBBuild-Essential\fR
+Defines which package(s) are considered essential build dependencies.
+.TP
+\fBGet\fR
+The Get subsection controls the \fBapt-get\fR(8) tool, please see its
+documentation for more information about the options here.
+.TP
+\fBCache\fR
+The Cache subsection controls the \fBapt-cache\fR(8) tool, please see its
+documentation for more information about the options here.
+.TP
+\fBCDROM\fR
+The CDROM subsection controls the \fBapt-cdrom\fR(8) tool, please see its
+documentation for more information about the options here.
+.SH "THE ACQUIRE GROUP"
+.PP
+The Acquire group of options controls the download of packages 
+and the URI handlers. 
+.TP
+\fBQueue-Mode\fR
+Queuing mode; Queue-Mode can be one of host or 
+access which determines how  APT parallelizes outgoing 
+connections. host means that one connection per target host 
+will be opened, access means that one connection per URI type 
+will be opened.
+.TP
+\fBRetries\fR
+Number of retries to perform. If this is non-zero APT will retry failed 
+files the given number of times.
+.TP
+\fBSource-Symlinks\fR
+Use symlinks for source archives. If set to true then source archives will
+be symlinked when possible instead of copying. True is the default
+.TP
+\fBhttp\fR
+HTTP URIs; http::Proxy is the default http proxy to use. It is in the 
+standard form of http://[[user][:pass]@]host[:port]/\&. Per 
+host proxies can also be specified by using the form 
+http::Proxy::<host> with the special keyword DIRECT 
+meaning to use no proxies. The \fBhttp_proxy\fR environment variable
+will override all settings.
+
+Three settings are provided for cache control with HTTP/1.1 compliant 
+proxy caches. No-Cache tells the proxy to not use its cached 
+response under any circumstances, 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. No-Store specifies that the cache should never 
+store this request, it is only set for archive files. This may be useful 
+to prevent polluting a proxy cache with very large .deb files. Note: 
+Squid 2.0.2 does not support any of these options.
+
+The option timeout sets the timeout timer used by the method, 
+this applies to all things including connection timeout and data timeout.
+
+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. A value of
+zero MUST be specified if the remote host does not properly linger
+on TCP connections - otherwise data corruption will occur. Hosts which
+require this are in violation of RFC 2068.     
+.TP
+\fBftp\fR
+FTP URIs; ftp::Proxy is the default proxy server to use. It is in the 
+standard form of ftp://[[user][:pass]@]host[:port]/ and is 
+overridden by the \fBftp_proxy\fR 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 
+\fI/usr/share/doc/apt/examples/configure-index.gz\fR 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.
+
+The option timeout sets the timeout timer used by the method, 
+this applies to all things including connection timeout and data timeout.
+
+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)
+
+It is possible to proxy FTP over HTTP by setting the \fBftp_proxy\fR
+environment variable to a http url - see the discussion of the http method
+above for syntax. You cannot set this in the configuration file and it is
+not recommended to use FTP over HTTP due to its low efficiency.
+
+The setting ForceExtended controls the use of RFC2428 
+EPSV and EPRT commands. The defaut is false, which means
+these commands are only used if the control connection is IPv6. Setting this
+to true forces their use even on IPv4 connections. Note that most FTP servers
+do not support RFC2428.
+.TP
+\fBcdrom\fR
+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 \fI/etc/fstab\fR\&. 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 and old mount packages). The syntax 
+is to put 
+
+.nf
+"/cdrom/"::Mount "foo";
+.fi
+within 
+the cdrom block. It is important to have the trailing slash. Unmount 
+commands can be specified using UMount.
+.SH "DIRECTORIES"
+.PP
+The Dir::State section has directories that pertain to local 
+state information. lists is the directory to place downloaded 
+package lists in.
+preferences is the name of the APT preferences file.
+Dir::State contains the default directory to prefix on all sub 
+items if they do not start with \fI/\fR or \fI\&./\fR\&. 
+.PP
+Dir::Cache contains locations pertaining to local cache 
+information, such as the two package caches srcpkgcache and 
+pkgcache as well as the location to place downloaded archives, 
+Dir::Cache::archives\&. Generation of caches can be turned off
+by setting their names to be blank. This will slow down startup but
+save disk space. It is probably prefered to turn off the pkgcache rather
+than the srcpkgcache. Like Dir::State the default
+directory is contained in Dir::Cache
+.PP
+Dir::Etc contains the location of configuration files, 
+sourcelist gives the location of the sourcelist and 
+main is the default configuration file (setting has no effect,
+unless it is done from the config file specified by 
+\fBAPT_CONFIG\fR).
+.PP
+The Dir::Parts setting reads in all the config fragments in 
+lexical order from the directory specified. After this is done then the
+main config file is loaded.
+.PP
+Binary programs are pointed to by Dir::Bin\&. Dir::Bin::Methods 
+specifies the location of the method handlers and gzip, 
+rpm, apt-get, rpmbuild
+and apt-cache specify the location
+of the respective programs.
+.SH "HOW APT CALLS RPM"
+.PP
+Several configuration directives control how APT invokes \fBrpm\fR(8)\&. These are 
+in the RPM section.
+.TP
+\fBOptions\fR
+This is a list of options to pass to rpm for all install, upgrade and
+remove operations. The options must be specified
+using the list notation and each list item is passed as a single argument
+to \fBrpm\fR(8)\&.
+.TP
+\fBInstall-Options\fR
+This is a list of options to pass to rpm during install and upgrade
+operations. The options must be specified
+using the list notation and each list item is passed as a single argument
+to \fBrpm\fR(8)\&.
+.TP
+\fBErase-Options\fR
+This is a list of options to pass to rpm during remove operations. 
+The options must be specified
+using the list notation and each list item is passed as a single argument
+to \fBrpm\fR(8)\&.
+.TP
+\fBPre-Invoke\fR
+.TP
+\fBPost-Invoke\fR
+This is a list of shell commands to run before/after invoking \fBrpm\fR(8)\&. 
+Like Options this must be specified in list notation. The 
+commands are invoked in order using \fI/bin/sh\fR, should any 
+fail APT will abort.
+.TP
+\fBPre-Install-Pkgs\fR
+This is a list of shell commands to run before invoking rpm. Like
+Options this must be specified in list notation. The commands
+are invoked in order using \fI/bin/sh\fR, should any fail APT 
+will abort. APT will pass to the commands on standard input the 
+filenames of all .rpm files it is going to install, one per line.
+
+Version 2 of this protocol dumps more information, including the 
+protocol version, the APT configuration space and the packages, files
+and versions being changed. Version 2 is enabled by setting 
+DPkg::Tools::Options::cmd::Version to 2. cmd is a
+command given to Pre-Install-Pkgs\&.
+.TP
+\fBRun-Directory\fR
+APT chdirs to this directory before invoking rpm, the default is 
+\fI/\fR\&.
+.TP
+\fBBuild-Options\fR
+These options are passed to \fBrpmbuild\fR(1) when compiling packages.
+.SH "DEBUG OPTIONS"
+.PP
+Most of the options in the debug section are not interesting to 
+the normal user, however Debug::pkgProblemResolver shows 
+interesting output about the decisions dist-upgrade makes. 
+Debug::NoLocking disables file locking so APT can do some 
+operations as non-root and Debug::pkgRPMPM will print out the 
+command line for each rpm invokation. Debug::IdentCdrom will 
+disable the inclusion of statfs data in CDROM IDs.
+.SH "EXAMPLES"
+.PP
+\fI/usr/share/doc/apt/examples/configure-index.gz\fR contains a 
+sample configuration file showing the default values for all possible 
+options.
+.SH "FILES"
+.PP
+\fI/etc/apt/apt.conf\fR
+.SH "SEE ALSO"
+.PP
+\fBapt-cache\fR(8), \fBapt-config\fR(8), \fBapt_preferences\fR(5)\&.
+.SH "BUGS"
+.PP
+Reporting bugs in APT-RPM is best done in the 
+APT-RPM mailinglist <URL:http://apt-rpm.org/mailinglist.shtml>\&.
+.SH "AUTHOR"
+.PP
+Maintainer and contributor information can be found in the
+credits page <URL:http://apt-rpm.org/about.shtml> of APT-RPM.