summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorDavid Kalnischkies <david@kalnischkies.de>2017-11-22 19:39:31 +0100
committerDavid Kalnischkies <david@kalnischkies.de>2018-01-03 18:55:41 +0100
commit956145444e1a3b7f5e660f71904711f4ea5bd262 (patch)
tree7ba59fc2f9d1d0f1110a37f00e596b91be91d559
parent5b197e9de5376e191018562309e2d42123c27a1d (diff)
document http options in new apt-transport-http manpage
We had documentation for the http transport in our "catch-all" apt.conf manpage, but it seems benefitial to document transports in their own manpage instead of pushing them all into one.
-rw-r--r--debian/apt.install1
-rw-r--r--doc/CMakeLists.txt1
-rw-r--r--doc/apt-transport-http.1.xml138
-rw-r--r--doc/apt-verbatim.ent11
-rw-r--r--doc/apt.conf.5.xml64
-rw-r--r--doc/po4a.conf1
-rw-r--r--doc/sources.list.5.xml16
7 files changed, 159 insertions, 73 deletions
diff --git a/debian/apt.install b/debian/apt.install
index d30f429b0..1d6d56096 100644
--- a/debian/apt.install
+++ b/debian/apt.install
@@ -35,6 +35,7 @@ usr/share/man/*/apt-get.*
usr/share/man/*/apt-key.*
usr/share/man/*/apt-mark.*
usr/share/man/*/apt-secure.*
+usr/share/man/*/apt-transport-http.*
usr/share/man/*/apt.*
usr/share/man/*/apt_auth.*
usr/share/man/*/apt_preferences.*
diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt
index 73d808c64..df88eb809 100644
--- a/doc/CMakeLists.txt
+++ b/doc/CMakeLists.txt
@@ -84,6 +84,7 @@ add_docbook(apt-man MANPAGE ALL
apt_preferences.5.xml
apt-secure.8.xml
apt-sortpkgs.1.xml
+ apt-transport-http.1.xml
sources.list.5.xml
DEPENDS ${ENTITIES}
TRANSLATED_ENTITIES ${TRANSLATED_ENTITIES}
diff --git a/doc/apt-transport-http.1.xml b/doc/apt-transport-http.1.xml
new file mode 100644
index 000000000..546e47761
--- /dev/null
+++ b/doc/apt-transport-http.1.xml
@@ -0,0 +1,138 @@
+<?xml version="1.0" encoding="utf-8" standalone="no"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % aptent SYSTEM "apt.ent"> %aptent;
+<!ENTITY % aptverbatiment SYSTEM "apt-verbatim.ent"> %aptverbatiment;
+<!ENTITY % aptvendor SYSTEM "apt-vendor.ent"> %aptvendor;
+]>
+
+<refentry>
+
+ <refentryinfo>
+ &apt-author.team;
+ &apt-email;
+ &apt-product;
+ <!-- The last update date -->
+ <date>2017-11-22T00:00:00Z</date>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>apt-transport-http</refentrytitle>
+ <manvolnum>1</manvolnum>
+ <refmiscinfo class="manual">APT</refmiscinfo>
+ </refmeta>
+
+ <!-- Man page title -->
+ <refnamediv>
+ <refname>apt-transport-http</refname>
+ <refpurpose>APT transport for downloading via the Hypertext Transfer Protocol (HTTP)</refpurpose>
+ </refnamediv>
+
+<refsect1><title>Description</title>
+<para>This APT transport allows the use of repositories accessed via the
+Hypertext Transfer Protocol (HTTP). It is available by default and probably the
+most used of all transports. Note that a transport is never called directly by
+a user but used by APT tools based on user configuration.</para>
+<para>HTTP is an unencrypted transport protocol meaning that the
+whole communication with the remote server (or proxy) can be observed by a
+sufficiently capable attacker referred to commonly as man in the middle (MITM).
+Such an attacker can <emphasis>not</emphasis> modify the communication to compromise
+the security of your system through as APTs data security model is independent of the
+chosen transport method. This is explained in detail in &apt-secure;. An overview over
+available transport methods is given in &sources-list;.</para>
+</refsect1>
+
+<refsect1><title>Options</title>
+<para>Various options are available to modify its behaviour which can be set in
+an &apt-conf; file ranging from proxy configuration to workaround for specific
+server insufficiencies.</para>
+
+<refsect2><title>Proxy Configuration</title>
+<para>The environment variable <envar>http_proxy</envar> is supported for system wide configuration.
+Proxies specific to apt can be configured via the option <literal>Acquire::http::Proxy</literal>.
+Proxies which should be used only for certain hosts can be specified via
+<literal>Acquire::http::Proxy::<replaceable>host</replaceable></literal>. Even more finegrained control
+can be achieved via proxy autodetection detailed further below.
+All these options use the URI format <literal><replaceable>scheme</replaceable>://[[<replaceable>user</replaceable>][:<replaceable>pass</replaceable>]@]<replaceable>host</replaceable>[:<replaceable>port</replaceable>]/</literal>.
+Supported URI schemes are <literal>socks5h</literal> (SOCKS5 with remote DNS resolution), <literal>http</literal> and <literal>https</literal>.
+Authentification details can be supplied via &apt-authconf; instead of including it in the URI directly.</para>
+<para>The various APT configuration options support the special value <literal>DIRECT</literal> meaning that
+no proxy should be used. The environment variable <envar>no_proxy</envar> with the same propose is also supported.</para>
+<para>Further more there are three settings provided for cache control with HTTP/1.1 compliant proxy caches:
+<literal>Acquire::http::No-Cache</literal> tells the proxy not to use its
+cached response under any circumstances.
+<literal>Acquire::http::Max-Age</literal> sets the allowed maximum age (in
+seconds) of an index file in the cache of the proxy.
+<literal>Acquire::http::No-Store</literal> specifies that the proxy should not
+store the requested archive files in its cache, which can be used to prevent
+the proxy from polluting its cache with (big) .deb files.</para>
+</refsect2>
+
+<refsect2><title>Automatic Proxy Configuration</title>
+<para><literal>Acquire::http::Proxy-Auto-Detect</literal> can be used to
+specify an external command to discover the http proxy to use. The first
+and only parameter is an URI denoting the host to be contacted to allow
+for host-specific configuration. APT expects the command to output the
+proxy on stdout as a single line in the previously specified URI format
+or the word <literal>DIRECT</literal> if no proxy should be used. No output
+indicates that the generic proxy settings should be used.</para>
+<para>Note that auto-detection will not be used for a host if a host-specific proxy
+configuration is already set via <literal>Acquire::http::Proxy::<replaceable>host</replaceable></literal>.</para>
+<para>See the &squid-deb-proxy-client; and &auto-apt-proxy; packages for example implementations.</para>
+<para>This option takes precedence over the legacy option name <literal>Acquire::http::ProxyAutoDetect</literal>.</para>
+</refsect2>
+
+<refsect2><title>Connection Configuration</title>
+<para>The option <literal>Acquire::http::Timeout</literal> sets the timeout timer used by the method;
+this value applies to the connection as well as the data timeout.</para>
+<para>The used bandwidth can be limited with
+<literal>Acquire::http::Dl-Limit</literal> which accepts integer values in
+kilobytes per second. The default value is 0 which deactivates the limit and
+tries to use all available bandwidth. Note that this option implicitly
+disables downloading from multiple servers at the same time.</para>
+<para>The setting <literal>Acquire::http::Pipeline-Depth</literal> can be used to
+enable HTTP pipelining (RFC 2616 section 8.1.2.2) which can be beneficial e.g. on
+high-latency connections. It specifies how many requests are sent in a pipeline.
+APT tries to detect and workaround misbehaving webservers and proxies at runtime, but
+if you know that yours does not conform to the HTTP/1.1 specification pipelining can
+be disabled by setting the value to 0. It is enabled by default with the value 10.</para>
+<para><literal>Acquire::http::AllowRedirect</literal> controls whether APT will follow
+redirects, which is enabled by default.</para>
+<para><literal>Acquire::http::User-Agent</literal> can be used to set a different
+User-Agent for the http download method as some proxies allow access for clients
+only if the client uses a known identifier.</para>
+<para><literal>Acquire::http::SendAccept</literal> is enabled by default and
+sends a <literal>Accept: text/*</literal> header field to the server for
+requests without file extensions to prevent the server from attempting content
+negotiation.</para>
+</refsect2>
+</refsect1>
+
+<refsect1><title>Examples</title>
+<literallayout>
+Acquire::http {
+ Proxy::example.org "DIRECT";
+ Proxy "socks5h://apt:pass@localhost:9050";
+ Proxy-Auto-Detect "/usr/local/bin/apt-http-proxy-auto-detect";
+ No-Cache "true";
+ Max-Age "3600";
+ No-Store "true";
+ Timeout "10";
+ Dl-Limit "42";
+ Pipeline-Depth "0";
+ AllowRedirect "false";
+ User-Agent "My APT-HTTP";
+ SendAccept "false";
+};
+</literallayout>
+</refsect1>
+
+<refsect1>
+<title>See Also</title>
+<para>&apt-conf; &apt-authconf; &sources-list;
+</para>
+</refsect1>
+
+ &manbugs;
+
+</refentry>
diff --git a/doc/apt-verbatim.ent b/doc/apt-verbatim.ent
index 946c7cc7d..1af7b174d 100644
--- a/doc/apt-verbatim.ent
+++ b/doc/apt-verbatim.ent
@@ -81,6 +81,11 @@
</citerefentry>"
>
+<!ENTITY apt-transport-http "<citerefentry>
+ <refentrytitle><command>apt-transport-http</command></refentrytitle>
+ <manvolnum>1</manvolnum>
+ </citerefentry>"
+>
<!ENTITY sources-list "<citerefentry>
<refentrytitle><filename>sources.list</filename></refentrytitle>
@@ -148,6 +153,12 @@
</citerefentry>"
>
+<!ENTITY auto-apt-proxy "<citerefentry>
+ <refentrytitle><command>auto-apt-proxy</command></refentrytitle>
+ <manvolnum>1</manvolnum>
+ </citerefentry>"
+>
+
<!ENTITY debsign "<citerefentry>
<refentrytitle><command>debsign</command></refentrytitle>
<manvolnum>1</manvolnum>
diff --git a/doc/apt.conf.5.xml b/doc/apt.conf.5.xml
index 6f47bb029..30714e66b 100644
--- a/doc/apt.conf.5.xml
+++ b/doc/apt.conf.5.xml
@@ -409,70 +409,6 @@ APT::Compressor::rev {
be symlinked when possible instead of copying. True is the default.</para></listitem>
</varlistentry>
- <varlistentry><term><option>http</option></term>
- <listitem><para><literal>http::Proxy</literal> sets the default proxy to use for HTTP
- URIs. It is in the standard form of <literal>http://[[user][:pass]@]host[:port]/</literal>.
- Per host proxies can also be specified by using the form
- <literal>http::Proxy::&lt;host&gt;</literal> with the special keyword <literal>DIRECT</literal>
- meaning to use no proxies. If no one of the above settings is specified,
- <envar>http_proxy</envar> environment variable
- will be used.</para>
-
- <para>Three settings are provided for cache control with HTTP/1.1 compliant
- proxy caches.
- <literal>No-Cache</literal> tells the proxy not to use its cached
- response under any circumstances.
- <literal>Max-Age</literal> sets the allowed maximum age (in seconds) of
- an index file in the cache of the proxy.
- <literal>No-Store</literal> specifies that the proxy should not store
- the requested archive files in its cache, which can be used to prevent
- the proxy from polluting its cache with (big) .deb files.</para>
-
- <para>The option <literal>timeout</literal> sets the timeout timer used by the method;
- this value applies to the connection as well as the data timeout.</para>
-
- <para>The setting <literal>Acquire::http::Pipeline-Depth</literal> can be used to
- enable HTTP pipelining (RFC 2616 section 8.1.2.2) which can be beneficial e.g. on
- high-latency connections. It specifies how many requests are sent in a pipeline.
- APT tries to detect and workaround misbehaving webservers and proxies at runtime, but
- if you know that yours does not conform to the HTTP/1.1 specification pipelining can
- be disabled by setting the value to 0. It is enabled by default with the value 10.</para>
-
- <para><literal>Acquire::http::AllowRedirect</literal> controls whether APT will follow
- redirects, which is enabled by default.</para>
-
- <para>The used bandwidth can be limited with
- <literal>Acquire::http::Dl-Limit</literal> which accepts integer
- values in kilobytes per second. The default value is 0 which
- deactivates the limit and tries to use all available bandwidth.
- Note that this option implicitly disables downloading from
- multiple servers at the same time.</para>
-
- <para><literal>Acquire::http::User-Agent</literal> can be used to set a different
- User-Agent for the http download method as some proxies allow access for clients
- only if the client uses a known identifier.</para>
-
- <para><literal>Acquire::http::Proxy-Auto-Detect</literal> can be used to
- specify an external command to discover the http proxy to use. The first
- and only parameter is an URI denoting the host to be contacted to allow
- for host-specific configuration. APT expects the command to output the
- proxy on stdout as a single line in the style <literal>http://proxy:port/</literal>
- or the word <literal>DIRECT</literal> if no proxy should be used. No output
- indicates that the generic proxy settings should be used.
-
- Note that auto-detection will not be used for a host if a host-specific proxy
- configuration is already set via <literal>Acquire::http::Proxy::<replaceable>HOST</replaceable></literal>.
-
- See the &squid-deb-proxy-client; package for an example implementation that
- uses avahi.
-
- This option takes precedence over the legacy option name
- <literal>ProxyAutoDetect</literal>.
- </para>
-
- </listitem>
- </varlistentry>
-
<varlistentry><term><option>https</option></term>
<listitem><para>
The <literal>Cache-control</literal>, <literal>Timeout</literal>,
diff --git a/doc/po4a.conf b/doc/po4a.conf
index 955ebbc76..4b8d33f52 100644
--- a/doc/po4a.conf
+++ b/doc/po4a.conf
@@ -27,6 +27,7 @@
[type: manpage] apt-sortpkgs.1.xml $lang:$lang/apt-sortpkgs.$lang.1.xml add_$lang:xml.add
[type: manpage] apt-ftparchive.1.xml $lang:$lang/apt-ftparchive.$lang.1.xml add_$lang:xml.add
[type: manpage] apt_auth.conf.5.xml $lang:$lang/apt_auth.conf.$lang.5.xml add_$lang:xml.add
+[type: manpage] apt-transport-http.1.xml $lang:$lang/apt-transport-http.$lang.1.xml add_$lang:xml.add
[type: docbook] guide.dbk $lang:$lang/guide.$lang.dbk
# add_$lang::$lang/addendum/docbook_$lang.add
diff --git a/doc/sources.list.5.xml b/doc/sources.list.5.xml
index 694082bea..3f81dd515 100644
--- a/doc/sources.list.5.xml
+++ b/doc/sources.list.5.xml
@@ -352,17 +352,15 @@ deb-src [ option1=value1 option2=value2 ] uri suite [component1] [component2] [.
<para>The currently recognized URI types are:
<variablelist>
- <varlistentry><term><command>http</command></term>
+ <varlistentry><term><command>http</command> (&apt-transport-http;)</term>
<listitem><para>
The http scheme specifies an HTTP server for an archive and is the most
- commonly used method, with many options in the
- <literal>Acquire::http</literal> scope detailed in &apt-conf;. The URI can
- directly include login information if the archive requires it, but the use
- of &apt-authconf; should be preferred. The method also supports SOCKS5 and
- HTTP(S) proxies either configured via apt-specific configuration or
- specified by the environment variable <envar>http_proxy</envar> in the
- format (assuming an HTTP proxy requiring authentication)
- <replaceable>http://user:pass@server:port/</replaceable>.
+ commonly used method. The URI can directly include login information if the
+ archive requires it, but the use of &apt-authconf; should be preferred.
+ The method also supports SOCKS5 and HTTP(S) proxies either configured via
+ apt-specific configuration or specified by the environment variable
+ <envar>http_proxy</envar> in the format (assuming an HTTP proxy requiring
+ authentication) <replaceable>http://user:pass@server:port/</replaceable>.
The authentication details for proxies can also be supplied via
&apt-authconf;.</para>
<para>Note that these forms of authentication are insecure as the whole