Browse Source

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.
tags/devuan/2.0.1+devuan1
David Kalnischkies 3 years ago
parent
commit
956145444e
7 changed files with 159 additions and 73 deletions
  1. +1
    -0
      debian/apt.install
  2. +1
    -0
      doc/CMakeLists.txt
  3. +138
    -0
      doc/apt-transport-http.1.xml
  4. +11
    -0
      doc/apt-verbatim.ent
  5. +0
    -64
      doc/apt.conf.5.xml
  6. +1
    -0
      doc/po4a.conf
  7. +7
    -9
      doc/sources.list.5.xml

+ 1
- 0
debian/apt.install View File

@@ -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.*


+ 1
- 0
doc/CMakeLists.txt View File

@@ -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}


+ 138
- 0
doc/apt-transport-http.1.xml View File

@@ -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>

+ 11
- 0
doc/apt-verbatim.ent View File

@@ -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>


+ 0
- 64
doc/apt.conf.5.xml View File

@@ -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>,


+ 1
- 0
doc/po4a.conf View File

@@ -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


+ 7
- 9
doc/sources.list.5.xml View File

@@ -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


Loading…
Cancel
Save