"Fossies" - the Fresh Open Source Software Archive

Member "apt-1.9.4/doc/apt-transport-http.1.xml" (19 Sep 2019, 6986 Bytes) of package /linux/misc/apt-1.9.4.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) XML source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the last Fossies "Diffs" side-by-side code changes report for "apt-transport-http.1.xml": 1.8.2_vs_1.9.2.

    1 <?xml version="1.0" encoding="utf-8" standalone="no"?>
    2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
    3   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
    4 <!ENTITY % aptent SYSTEM "apt.ent"> %aptent;
    5 <!ENTITY % aptverbatiment SYSTEM "apt-verbatim.ent"> %aptverbatiment;
    6 <!ENTITY % aptvendor SYSTEM "apt-vendor.ent"> %aptvendor;
    7 ]>
    8 
    9 <refentry>
   10 
   11  <refentryinfo>
   12    &apt-author.team;
   13    &apt-email;
   14    &apt-product;
   15    <!-- The last update date -->
   16    <date>2019-04-04T00:00:00Z</date>
   17  </refentryinfo>
   18 
   19  <refmeta>
   20    <refentrytitle>apt-transport-http</refentrytitle>
   21    <manvolnum>1</manvolnum>
   22    <refmiscinfo class="manual">APT</refmiscinfo>
   23  </refmeta>
   24 
   25  <!-- Man page title -->
   26  <refnamediv>
   27     <refname>apt-transport-http</refname>
   28     <refpurpose>APT transport for downloading via the Hypertext Transfer Protocol (HTTP)</refpurpose>
   29  </refnamediv>
   30 
   31 <refsect1><title>Description</title>
   32 <para>This APT transport allows the use of repositories accessed via the
   33 Hypertext Transfer Protocol (HTTP). It is available by default and probably the
   34 most used of all transports. Note that a transport is never called directly by
   35 a user but used by APT tools based on user configuration.</para>
   36 <para>HTTP is an unencrypted transport protocol meaning that the
   37 whole communication with the remote server (or proxy) can be observed by a
   38 sufficiently capable attacker commonly referred to as a "man in the middle" (MITM).
   39 However, such an attacker can <emphasis>not</emphasis> modify the communication to compromise
   40 the security of your system, as APT's data security model is independent of the
   41 chosen transport method. This is explained in detail in &apt-secure;. An overview of
   42 available transport methods is given in &sources-list;.</para>
   43 </refsect1>
   44 
   45 <refsect1><title>Options</title>
   46 <para>Various options can be set in an &apt-conf; file to modify its behavior,
   47 ranging from proxy configuration to workarounds for specific
   48 server limitations.</para>
   49 
   50 <refsect2><title>Proxy Configuration</title>
   51 <para>The environment variable <envar>http_proxy</envar> is supported for system wide configuration.
   52 Proxies specific to APT can be configured via the option <literal>Acquire::http::Proxy</literal>.
   53 Proxies which should be used only for certain hosts can be specified via
   54 <literal>Acquire::http::Proxy::<replaceable>host</replaceable></literal>. Even more fine-grained control
   55 can be achieved via proxy autodetection, detailed further below.
   56 All these options use the URI format <literal><replaceable>scheme</replaceable>://[[<replaceable>user</replaceable>][:<replaceable>pass</replaceable>]@]<replaceable>host</replaceable>[:<replaceable>port</replaceable>]/</literal>.
   57 Supported URI schemes are <literal>socks5h</literal> (SOCKS5 with remote DNS resolution), <literal>http</literal> and <literal>https</literal>.
   58 Authentication details can be supplied via &apt-authconf; instead of including it in the URI directly.</para>
   59 <para>The various APT configuration options support the special value <literal>DIRECT</literal> meaning that
   60 no proxy should be used. The environment variable <envar>no_proxy</envar> is also supported for the same purpose.</para>
   61 <para>Furthermore, there are three settings provided for cache control with HTTP/1.1 compliant proxy caches:
   62 <literal>Acquire::http::No-Cache</literal> tells the proxy not to use its
   63 cached response under any circumstances.
   64 <literal>Acquire::http::Max-Age</literal> sets the allowed maximum age (in
   65 seconds) of an index file in the cache of the proxy.
   66 <literal>Acquire::http::No-Store</literal> specifies that the proxy should not
   67 store the requested archive files in its cache, which can be used to prevent
   68 the proxy from polluting its cache with (big) .deb files.</para>
   69 </refsect2>
   70 
   71 <refsect2><title>Automatic Proxy Configuration</title>
   72 <para><literal>Acquire::http::Proxy-Auto-Detect</literal> can be used to
   73 specify an external command to discover the HTTP proxy to use. The first
   74 and only parameter is a URI denoting the host to be contacted, to allow
   75 for host-specific configuration. APT expects the command to output the
   76 proxy on stdout as a single line in the previously specified URI format
   77 or the word <literal>DIRECT</literal> if no proxy should be used. No output
   78 indicates that the generic proxy settings should be used.</para>
   79 <para>Note that auto-detection will not be used for a host if a host-specific proxy
   80 configuration is already set via <literal>Acquire::http::Proxy::<replaceable>host</replaceable></literal>.</para>
   81 <para>See the &squid-deb-proxy-client; and &auto-apt-proxy; packages for example implementations.</para>
   82 <para>This option takes precedence over the legacy option name <literal>Acquire::http::ProxyAutoDetect</literal>.</para>
   83 </refsect2>
   84 
   85 <refsect2><title>Connection Configuration</title>
   86 <para>The option <literal>Acquire::http::Timeout</literal> sets the timeout timer used by the method;
   87 this value applies to the connection as well as the data timeout.</para>
   88 <para>The used bandwidth can be limited with
   89 <literal>Acquire::http::Dl-Limit</literal> which accepts integer values in
   90 kilobytes per second. The default value is 0 which deactivates the limit and
   91 tries to use all available bandwidth. Note that this option implicitly
   92 disables downloading from multiple servers at the same time.</para>
   93 <para>The setting <literal>Acquire::http::Pipeline-Depth</literal> can be used to
   94 enable HTTP pipelining (RFC 2616 section 8.1.2.2) which can be beneficial e.g. on
   95 high-latency connections. It specifies how many requests are sent in a pipeline.
   96 APT tries to detect and work around misbehaving webservers and proxies at runtime, but
   97 if you know that yours does not conform to the HTTP/1.1 specification, pipelining can
   98 be disabled by setting the value to 0. It is enabled by default with the value 10.</para>
   99 <para><literal>Acquire::http::AllowRedirect</literal> controls whether APT will follow
  100 redirects, which is enabled by default.</para>
  101 <para><literal>Acquire::http::User-Agent</literal> can be used to set a different
  102 User-Agent for the http download method as some proxies allow access for clients
  103 only if the client uses a known identifier.</para>
  104 <para><literal>Acquire::http::SendAccept</literal> is enabled by default and
  105 sends an <literal>Accept: text/*</literal> header field to the server for
  106 requests without file extensions to prevent the server from attempting content
  107 negotiation.</para>
  108 </refsect2>
  109 </refsect1>
  110 
  111 <refsect1><title>Examples</title>
  112 <literallayout>
  113 Acquire::http {
  114     Proxy::example.org "DIRECT";
  115     Proxy "socks5h://apt:pass@127.0.0.1:9050";
  116     Proxy-Auto-Detect "/usr/local/bin/apt-http-proxy-auto-detect";
  117     No-Cache "true";
  118     Max-Age "3600";
  119     No-Store "true";
  120     Timeout "10";
  121     Dl-Limit "42";
  122     Pipeline-Depth "0";
  123     AllowRedirect "false";
  124     User-Agent "My APT-HTTP";
  125     SendAccept "false";
  126 };
  127 </literallayout>
  128 </refsect1>
  129 
  130 <refsect1>
  131 <title>See Also</title>
  132 <para>&apt-conf; &apt-authconf; &sources-list;
  133 </para>
  134 </refsect1>
  135 
  136  &manbugs;
  137 
  138 </refentry>