diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/CMakeLists.txt | 1 | ||||
| -rw-r--r-- | doc/apt-transport-http.1.xml | 138 | ||||
| -rw-r--r-- | doc/apt-verbatim.ent | 11 | ||||
| -rw-r--r-- | doc/apt.conf.5.xml | 64 | ||||
| -rw-r--r-- | doc/po4a.conf | 1 | ||||
| -rw-r--r-- | doc/sources.list.5.xml | 16 |
6 files changed, 158 insertions, 73 deletions
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::<host></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 |