From 956145444e1a3b7f5e660f71904711f4ea5bd262 Mon Sep 17 00:00:00 2001 From: David Kalnischkies Date: Wed, 22 Nov 2017 19:39:31 +0100 Subject: 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. --- doc/CMakeLists.txt | 1 + doc/apt-transport-http.1.xml | 138 +++++++++++++++++++++++++++++++++++++++++++ doc/apt-verbatim.ent | 11 ++++ doc/apt.conf.5.xml | 64 -------------------- doc/po4a.conf | 1 + doc/sources.list.5.xml | 16 +++-- 6 files changed, 158 insertions(+), 73 deletions(-) create mode 100644 doc/apt-transport-http.1.xml (limited to 'doc') 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 @@ + + %aptent; + %aptverbatiment; + %aptvendor; +]> + + + + + &apt-author.team; + &apt-email; + &apt-product; + + 2017-11-22T00:00:00Z + + + + apt-transport-http + 1 + APT + + + + + apt-transport-http + APT transport for downloading via the Hypertext Transfer Protocol (HTTP) + + +Description +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. +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 not 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;. + + +Options +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. + +Proxy Configuration +The environment variable http_proxy is supported for system wide configuration. +Proxies specific to apt can be configured via the option Acquire::http::Proxy. +Proxies which should be used only for certain hosts can be specified via +Acquire::http::Proxy::host. Even more finegrained control +can be achieved via proxy autodetection detailed further below. +All these options use the URI format scheme://[[user][:pass]@]host[:port]/. +Supported URI schemes are socks5h (SOCKS5 with remote DNS resolution), http and https. +Authentification details can be supplied via &apt-authconf; instead of including it in the URI directly. +The various APT configuration options support the special value DIRECT meaning that +no proxy should be used. The environment variable no_proxy with the same propose is also supported. +Further more there are three settings provided for cache control with HTTP/1.1 compliant proxy caches: +Acquire::http::No-Cache tells the proxy not to use its +cached response under any circumstances. +Acquire::http::Max-Age sets the allowed maximum age (in +seconds) of an index file in the cache of the proxy. +Acquire::http::No-Store 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. + + +Automatic Proxy Configuration +Acquire::http::Proxy-Auto-Detect 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 DIRECT 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 Acquire::http::Proxy::host. +See the &squid-deb-proxy-client; and &auto-apt-proxy; packages for example implementations. +This option takes precedence over the legacy option name Acquire::http::ProxyAutoDetect. + + +Connection Configuration +The option Acquire::http::Timeout sets the timeout timer used by the method; +this value applies to the connection as well as the data timeout. +The used bandwidth can be limited with +Acquire::http::Dl-Limit 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. +The setting Acquire::http::Pipeline-Depth 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. +Acquire::http::AllowRedirect controls whether APT will follow +redirects, which is enabled by default. +Acquire::http::User-Agent 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. +Acquire::http::SendAccept is enabled by default and +sends a Accept: text/* header field to the server for +requests without file extensions to prevent the server from attempting content +negotiation. + + + +Examples + +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"; +}; + + + + +See Also +&apt-conf; &apt-authconf; &sources-list; + + + + &manbugs; + + 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 @@ " > + + apt-transport-http + 1 + " +> sources.list @@ -148,6 +153,12 @@ " > + + auto-apt-proxy + 1 + " +> + debsign 1 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. - - http::Proxy sets the default proxy to use for HTTP - URIs. 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. If no one of the above settings is specified, - http_proxy environment variable - will be used. - - Three settings are provided for cache control with HTTP/1.1 compliant - proxy caches. - No-Cache tells the proxy not to use its cached - response under any circumstances. - Max-Age sets the allowed maximum age (in seconds) of - an index file in the cache of the proxy. - No-Store 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. - - The option timeout sets the timeout timer used by the method; - this value applies to the connection as well as the data timeout. - - The setting Acquire::http::Pipeline-Depth 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. - - Acquire::http::AllowRedirect controls whether APT will follow - redirects, which is enabled by default. - - The used bandwidth can be limited with - Acquire::http::Dl-Limit 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. - - Acquire::http::User-Agent 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. - - Acquire::http::Proxy-Auto-Detect 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 http://proxy:port/ - or the word DIRECT 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 Acquire::http::Proxy::HOST. - - See the &squid-deb-proxy-client; package for an example implementation that - uses avahi. - - This option takes precedence over the legacy option name - ProxyAutoDetect. - - - - - The Cache-control, Timeout, 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] [. The currently recognized URI types are: - http + http (&apt-transport-http;) The http scheme specifies an HTTP server for an archive and is the most - commonly used method, with many options in the - Acquire::http 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 http_proxy in the - format (assuming an HTTP proxy requiring authentication) - http://user:pass@server:port/. + 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 + http_proxy in the format (assuming an HTTP proxy requiring + authentication) http://user:pass@server:port/. The authentication details for proxies can also be supplied via &apt-authconf;. Note that these forms of authentication are insecure as the whole -- cgit v1.2.3 From c28682430a27f75ceb8cc8dff78b3a560fd68399 Mon Sep 17 00:00:00 2001 From: David Kalnischkies Date: Thu, 23 Nov 2017 00:58:00 +0100 Subject: document https options in new apt-transport-https manpage Same reasoning as with the previous commit for http with the added benefit of moving the hard to discover and untranslated example config into a manpage which could be translated. --- doc/CMakeLists.txt | 1 + doc/apt-transport-https.1.xml | 133 +++++++++++++++++++++ doc/apt-verbatim.ent | 6 + doc/apt.conf.5.xml | 33 +---- doc/examples/CMakeLists.txt | 2 +- doc/examples/apt-https-method-example.conf | 186 ----------------------------- doc/examples/configure-index | 3 - doc/po4a.conf | 1 + doc/sources.list.5.xml | 2 +- 9 files changed, 148 insertions(+), 219 deletions(-) create mode 100644 doc/apt-transport-https.1.xml delete mode 100644 doc/examples/apt-https-method-example.conf (limited to 'doc') diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt index df88eb809..cb2fe892c 100644 --- a/doc/CMakeLists.txt +++ b/doc/CMakeLists.txt @@ -85,6 +85,7 @@ add_docbook(apt-man MANPAGE ALL apt-secure.8.xml apt-sortpkgs.1.xml apt-transport-http.1.xml + apt-transport-https.1.xml sources.list.5.xml DEPENDS ${ENTITIES} TRANSLATED_ENTITIES ${TRANSLATED_ENTITIES} diff --git a/doc/apt-transport-https.1.xml b/doc/apt-transport-https.1.xml new file mode 100644 index 000000000..97137fc2c --- /dev/null +++ b/doc/apt-transport-https.1.xml @@ -0,0 +1,133 @@ + + %aptent; + %aptverbatiment; + %aptvendor; +]> + + + + + &apt-author.team; + &apt-email; + &apt-product; + + 2017-11-22T00:00:00Z + + + + apt-transport-https + 1 + APT + + + + + apt-transport-https + APT transport for downloading via the HTTP Secure protocol (HTTPS) + + +Description +This APT transport allows the use of repositories accessed via the +HTTP Secure protocol (HTTPS) also referred to as HTTP over TLS. It is available +by default since apt 1.5 and was before that available in a apt-transport-https +package. Note that a transport is never called directly by +a user but used by APT tools based on user configuration. +HTTP is by itself an unencrypted transport protocol (compare &apt-transport-http;), +which, as indicated by the appended S is wrapped in an encrypted layer known as +Transport Layer Security (TLS) which provides end-to-end encryption. +A sufficiently capable attacker can still observe the communication partners +and deeper analyse of the encrypted communcation might still reveal important details. +An overview over available alternative transport methods is given in &sources-list;. + + +Options +The HTTPS protocol is based on the HTTP protocol and as such this implementation +has the same relation meaning that all options supported by &apt-transport-http; are also +available via Acquire::https and will default to the same values specified +for Acquire::http. This manpage will only document the options +unique to https. + +Server credentials +By default all certificates trusted by the system (see +ca-certificates package) are used for the verification of +the server certificate. An alternative certificate authority (CA) can be +configured with the Acquire::https::CAInfo option and its +host-specific option Acquire::https::CAInfo::host. +The option specifies a file is made of the concatenation of the CA certificates +(in PEM format) creating the chain used for the verification of the path +from the root (self signed one). If the remote server provides the +whole chain during the exchange, the file need only contain the root +certificate. Otherwise, the whole chain is required. If you need to support +multiple authorities, the only way is to concatenate everything. +A custom certificate revocation list (CRL) can be configured with the options +Acquire::https::CRLFile and +Acquire::https::CRLFile::host respectively. +Like the previous option a file in PEM format needs to be specified. + + +Disabling security +When authenticating the server, if the certificate verification fails +for some reason (expired, revoked, man in the middle, …), the connection fails. +This is obviously what you want in all cases and what the default value (true) +of the option Acquire::https::Verify-Peer and its host-specific +variant provides. If you know exactly what you are doing, +setting this option to "false" allows you to skip peer certificate verification and +make the exchange succeed. Again, this option is for debugging or testing purpose +only as it removes all security provided by the use of HTTPS. +Similarly the option Acquire::https::Verify-Host and its +host-specific variant can be used to deactivate a security feature: The certificate +provided by the server includes the identity of the server which should match the +DNS name used to access it. By default, as requested by RFC 2818, the name of the +mirror is checked against the identity found in the certificate. This default behavior +is safe and should not be changed, but if you know that the server you are using has a +DNS name which does not match the identity in its certificate, you can set the option to +"false", which will prevent the comparison to be done. + + +Client authentication +Beside the password based authentication available (see &apt-authconf;) HTTPS supports +authentication based on client certificates as well via Acquire::https::SSLCert +and Acquire::https::SSLKey. They respectively should be set to the filename of +the X.509 client certificate and the associated (unencrypted) private key, both in PEM format. +In practice the use of the host-specific variants of both options is highly recommended. + + + + +Examples + +Acquire::https { + Proxy::example.org "DIRECT"; + Proxy "socks5h://apt:pass@localhost:9050"; + Proxy-Auto-Detect "/usr/local/bin/apt-https-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-HTTPS"; + SendAccept "false"; + + CAInfo "/path/to/ca/certs.pem"; + CRLFile "/path/to/all/crl.pem"; + Verify-Peer "true"; + Verify-Host::broken.example.org "false"; + SSLCert::example.org "/path/to/client/cert.pem"; + SSLKey::example.org "/path/to/client/key.pem" +}; + + + + +See Also +&apt-transport-http; &apt-conf; &apt-authconf; &sources-list; + + + + &manbugs; + + diff --git a/doc/apt-verbatim.ent b/doc/apt-verbatim.ent index 1af7b174d..8d0a56b6c 100644 --- a/doc/apt-verbatim.ent +++ b/doc/apt-verbatim.ent @@ -87,6 +87,12 @@ " > + + apt-transport-https + 1 + " +> + sources.list 5 diff --git a/doc/apt.conf.5.xml b/doc/apt.conf.5.xml index 30714e66b..e0be6a37d 100644 --- a/doc/apt.conf.5.xml +++ b/doc/apt.conf.5.xml @@ -409,34 +409,11 @@ APT::Compressor::rev { be symlinked when possible instead of copying. True is the default. - - - The Cache-control, Timeout, - AllowRedirect, Dl-Limit and - proxy options work for HTTPS URIs in the same way - as for the http method, and default to the same - values if they are not explicitly set. The - Pipeline-Depth option is not yet supported. - - - CaInfo suboption specifies place of file that - holds info about trusted certificates. - <host>::CaInfo is the corresponding per-host option. - Verify-Peer boolean suboption determines whether or not the - server's host certificate should be verified against trusted certificates. - <host>::Verify-Peer is the corresponding per-host option. - Verify-Host boolean suboption determines whether or not the - server's hostname should be verified. - <host>::Verify-Host is the corresponding per-host option. - SslCert determines what certificate to use for client - authentication. <host>::SslCert is the corresponding per-host option. - SslKey determines what private key to use for client - authentication. <host>::SslKey is the corresponding per-host option. - SslForceVersion overrides default SSL version to use. - It can contain either of the strings 'TLSv1' or - 'SSLv3'. - <host>::SslForceVersion is the corresponding per-host option. - + + The options in these scopes configure APTs acquire transports for the protocols + HTTP and HTTPS and are documented in the &apt-transport-http; and &apt-transport-https; + manpages respectively. + diff --git a/doc/examples/CMakeLists.txt b/doc/examples/CMakeLists.txt index 1998867db..8d9ea068f 100644 --- a/doc/examples/CMakeLists.txt +++ b/doc/examples/CMakeLists.txt @@ -1,4 +1,4 @@ -install(FILES apt.conf apt-https-method-example.conf configure-index preferences +install(FILES apt.conf configure-index preferences DESTINATION ${CMAKE_INSTALL_DOCDIR}/examples) install(FILES apt-ftparchive.conf ftp-archive.conf DESTINATION ${CMAKE_INSTALL_DOCDIR}/../apt-utils/examples) diff --git a/doc/examples/apt-https-method-example.conf b/doc/examples/apt-https-method-example.conf deleted file mode 100644 index 3152ef1e2..000000000 --- a/doc/examples/apt-https-method-example.conf +++ /dev/null @@ -1,186 +0,0 @@ -/* This file is a sample configuration for apt https method. Configuration - parameters found in this example file are expected to be used in main - apt.conf file, just like other configuration parameters for different - methods (ftp, file, ...). - - This example file starts with a common setup that voluntarily exhibits - all available configurations knobs with simple comments. Extended - comments on the behavior of the option is provided at the end for - better readability. As a matter of fact, a common configuration file - will certainly contain far less elements and benefit of default values - for many parameters. - - Because some configuration parameters for apt https method in following - examples apply to specific (fictional) repositories, the associated - sources.list file is provided here: - - ... - - deb https://secure.dom1.tld/debian unstable main contrib non-free - deb-src https://secure.dom1.tld/debian unstable main contrib non-free - - deb https://secure.dom2.tld/debian unstable main contrib non-free - deb-src https://secure.dom2.tld/debian unstable main contrib non-free - - ... - - - Some notes on the servers: - - - secure.dom1.tld is freely accessible using https (no client - authentication is required). - - secure.dom1.tld certificate is part of a multi level PKI, and we - want to specifically check the issuer of its certificate. We do - not have the constraint for secure.dom2.tld - - secure.dom2.tld requires client authentication by certificate - to access its content. - - The certificate presented by both server have (as expected) a CN that - matches their respective DNS names. - - We have CRL available for both dom1.tld and dom2.tld PKI, and intend - to use them. - - It sometimes happens that we had other more generic https available - repository to our list. We want the checks to be performed against - a common list of anchors (like the one provided by ca-certificates - package for instance) - - The sample configuration below basically covers those simple needs. -*/ - - -// Verify peer certificate and also matching between certificate name -// and server name as provided in sources.list (default values) -Acquire::https::Verify-Peer "true"; -Acquire::https::Verify-Host "true"; - -// Except otherwise specified, use that list of anchors -Acquire::https::CaInfo "/etc/ssl/certs/ca-certificates.pem"; - -// Use a specific anchor and associated CRL. Enforce issuer of -// server certificate using its cert. -Acquire::https::secure.dom1.tld::CaInfo "/etc/apt/certs/ca-dom1-crt.pem"; -Acquire::https::secure.dom1.tld::CrlFile "/etc/apt/certs/ca-dom1-crl.pem"; -Acquire::https::secure.dom1.tld::IssuerCert "/etc/apt/certs/secure.dom1-issuer-crt.pem"; - -// Like previous for anchor and CRL, but also provide our -// certificate and keys for client authentication. -Acquire::https::secure.dom2.tld::CaInfo "/etc/apt/certs/ca-dom2-crt.pem"; -Acquire::https::secure.dom2.tld::CrlFile "/etc/apt/certs/ca-dom2-crl.pem"; -Acquire::https::secure.dom2.tld::SslCert "/etc/apt/certs/my-crt.pem"; -Acquire::https::secure.dom2.tld::SslKey "/etc/apt/certs/my-key.pem"; - -// No need to downgrade, TLS will be proposed by default. Uncomment -// to have SSLv3 proposed. -// Acquire::https::mirror.ipv6.ssi.corp::SslForceVersion "SSLv3"; - -// No need for more debug if every is fine (default). Uncomment -// me to get additional information. -// Debug::Acquire::https "true"; - - -/* - Options with extended comments: - - Acquire::https[::repo.domain.tld]::CaInfo "/path/to/ca/certs.pem"; - - A string providing the path of a file containing the list of trusted - CA certificates used to verify the server certificate. The pointed - file is made of the concatenation of the CA certificates (in - PEM format) creating the chain used for the verification of the path - from the root (self signed one). If the remote server provides the - whole chain during the exchange, the file need only contain the root - certificate. Otherwise, the whole chain is required. - - If you need to support multiple authorities, the only way is to - concatenate everything. - - If None is provided, the default CA bundle used by GnuTLS (apt https - method is linked against libcurl-gnutls) is used. At the time of - writing, /etc/ssl/certs/ca-certificates.crt. - - If no specific hostname is provided, the file is used by default - for all https targets. If a specific mirror is provided, it is - used for the https entries in the sources.list file that use that - repository (with the same name). - - Acquire::https[::repo.domain.tld]::CrlFile "/path/to/all/crl.pem"; - - Like previous knob but for passing the list of CRL files (in PEM - format) to be used to verify revocation status. Again, if the - option is defined with no specific mirror (probably makes little - sense), this CRL information is used for all defined https entries - in sources.list file. In a mirror specific context, it only applies - to that mirror. - - Acquire::https[::repo.domain.tld]::IssuerCert "/path/to/issuer/cert.pem"; - - Allows one to constrain the issuer of the server certificate (for all - https mirrors or a specific one) to a specific issuer. If the - server certificate has not been issued by this certificate, - connection fails. - - Acquire::https[::repo.domain.tld]::Verify-Peer "true"; - - When authenticating the server, if the certificate verification fails - for some reason (expired, revoked, man in the middle, lack of anchor, - ...), the connection fails. This is obviously what you want in all - cases and what the default value (true) of this option provides. - - If you know EXACTLY what you are doing, setting this option to "false" - allow you to skip peer certificate verification and make the exchange - succeed. Again, this option is for debugging or testing purpose only. - It removes ALL the security provided by the use of SSL.TLS to secure - the HTTP exchanges. - - Acquire::https[::repo.domain.tld]::Verify-Host "true"; - - The certificate provided by the server during the TLS/SSL exchange - provides the identity of the server which should match the DNS name - used to access it. By default, as requested by RFC 2818, the name - of the mirror is checked against the identity found in the - certificate. This default behavior is safe and should not be - changed. If you know that the server you are using has a DNS name - which does not match the identity in its certificate, you can - [report that issue to its administrator or] set the option to - "false", which will prevent the comparison to be done. - - The options can be set globally or on a per-mirror basis. If set - globally, the DNS name used is the one found in the sources.list - file in the https URI. - - Acquire::https[::repo.domain.tld]::SslCert "/path/to/client/cert.pem"; - Acquire::https[::repo.domain.tld]::SslKey "/path/to/client/key.pem"; - - These two options provides support for client authentication using - certificates. They respectively accept the X.509 client certificate - in PEM format and the associated client key in PEM format (non - encrypted form). - - The options can be set globally (which rarely makes sense) or on a - per-mirror basis. - - Acquire::https[::repo.domain.tld]::SslForceVersion "TLSv1"; - - This option can be use to select the version which will be proposed - to the server. "SSLv3" and "TLSv1" are supported. SSLv2, which is - considered insecure anyway is not supported (by gnutls, which is - used by libcurl against which apt https method is linked). - - When the option is set to "SSLv3" to have apt propose SSLv3 (and - associated sets of ciphersuites) instead of TLSv1 (the default) - when performing the exchange. This prevents the server to select - TLSv1 and use associated ciphersuites. You should probably not use - this option except if you know exactly what you are doing. - - Note that the default setting does not guarantee that the server - will not select SSLv3 (for ciphersuites and SSL/TLS version as - selection is always done by the server, in the end). It only means - that apt will not advertise TLS support. - - Debug::Acquire::https "true"; - - This option can be used to show debug information. Because it is - quite verbose, it is mainly useful to debug problems in case of - failure to connect to a server for some reason. The default value - is "false". - -*/ diff --git a/doc/examples/configure-index b/doc/examples/configure-index index 153637ebc..9088bd844 100644 --- a/doc/examples/configure-index +++ b/doc/examples/configure-index @@ -274,9 +274,6 @@ Acquire // - cache-control values // - Dl-Limit, Timeout, ... values // if not set explicit for https - // - // see /usr/share/doc/apt/examples/apt-https-method-example.conf.gz - // for more examples https { Verify-Peer "false"; diff --git a/doc/po4a.conf b/doc/po4a.conf index 4b8d33f52..f1fe4cb0c 100644 --- a/doc/po4a.conf +++ b/doc/po4a.conf @@ -28,6 +28,7 @@ [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: manpage] apt-transport-https.1.xml $lang:$lang/apt-transport-https.$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 3f81dd515..5572b8da3 100644 --- a/doc/sources.list.5.xml +++ b/doc/sources.list.5.xml @@ -371,7 +371,7 @@ deb-src [ option1=value1 option2=value2 ] uri suite [component1] [component2] [. chosen transport method. See &apt-secure; for details. - https + https (&apt-transport-https;) The https scheme specifies an HTTPS server for an archive and is very similar in use and available options to the http scheme. The main -- cgit v1.2.3 From ef9677831f62a1554a888ebc7b162517d7881116 Mon Sep 17 00:00:00 2001 From: David Kalnischkies Date: Sat, 12 Aug 2017 16:21:13 +0200 Subject: allow a method to request auxiliary files If a method needs a file to operate like e.g. mirror needs to get a list of mirrors before it can redirect the the actual requests to them. That could easily be solved by moving the logic into libapt directly, but by allowing a method to request other methods to do something we can keep this logic contained in the method and allow e.g. also methods which perform binary patching or similar things. Previously they would need to implement their own acquire system inside the existing one which in all likelyhood will not support the same features and methods nor operate with similar security compared to what we have already running 'above' the requesting method. That said, to avoid methods producing conflicts with "proper" files we are downloading a new directory is introduced to keep the auxiliary files in. [The message magic number 351 is a tribute to the german Grundgesetz article 35 paragraph 1 which defines that all authorities of the state(s) help each other on request.] --- doc/method.dbk | 23 +++++++++++++++++++++-- 1 file changed, 21 insertions(+), 2 deletions(-) (limited to 'doc') diff --git a/doc/method.dbk b/doc/method.dbk index e5e035a2b..410d6898c 100644 --- a/doc/method.dbk +++ b/doc/method.dbk @@ -267,6 +267,11 @@ an informational string provided for visual debugging. +351 Aux Request - Method requests an auxiliary file + + + + 400 URI Failure - URI has failed to acquire @@ -309,9 +314,9 @@ Authorization is User/Pass Only the 6xx series of status codes is sent TO the method. Furthermore the -method may not emit status codes in the 6xx range. The Codes 402 and 403 +method may not emit status codes in the 6xx range. The Codes 351, 402 and 403 require that the method continue reading all other 6xx codes until the proper -602/603 code is received. This means the method must be capable of handling an +600/602/603 code is received. This means the method must be capable of handling an unlimited number of 600 messages. @@ -567,6 +572,20 @@ Size, Last-Modified, Filename, MD5-Hash +351 Aux Request + + +Indicates a request for an auxiliary file to be downloaded by the acquire system +(via another method) and made available for the requesting method. The requestor +will get a 600 URI Acquire with the URI it requested and the +filename will either be an existing file if the request was success or if the +acquire failed for some reason the file will not exist. +Fields: URI (of the file causing the need for the auxiliary file), MaximumSize, +Aux-ShortDesc, Aux-Description, Aux-URI + + + + 400 URI Failure -- cgit v1.2.3 From e4ed47f10844cf7ad933f7a9b64583869592f139 Mon Sep 17 00:00:00 2001 From: David Kalnischkies Date: Sat, 9 Dec 2017 12:32:32 +0100 Subject: add apt-transport-mirror manpage The mirror method is undocumented since 0.7.24, now with the reimplementation it is high time to get something written about it. --- doc/CMakeLists.txt | 1 + doc/apt-transport-mirror.1.xml | 150 +++++++++++++++++++++++++++++++++++++++++ doc/po4a.conf | 1 + 3 files changed, 152 insertions(+) create mode 100644 doc/apt-transport-mirror.1.xml (limited to 'doc') diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt index cb2fe892c..7cca4cf81 100644 --- a/doc/CMakeLists.txt +++ b/doc/CMakeLists.txt @@ -86,6 +86,7 @@ add_docbook(apt-man MANPAGE ALL apt-sortpkgs.1.xml apt-transport-http.1.xml apt-transport-https.1.xml + apt-transport-mirror.1.xml sources.list.5.xml DEPENDS ${ENTITIES} TRANSLATED_ENTITIES ${TRANSLATED_ENTITIES} diff --git a/doc/apt-transport-mirror.1.xml b/doc/apt-transport-mirror.1.xml new file mode 100644 index 000000000..72001fad5 --- /dev/null +++ b/doc/apt-transport-mirror.1.xml @@ -0,0 +1,150 @@ + + %aptent; + %aptverbatiment; + %aptvendor; +]> + + + + + &apt-author.team; + &apt-email; + &apt-product; + + 2017-12-09T00:00:00Z + + + + apt-transport-mirror + 1 + APT + + + + + apt-transport-mirror + APT transport for more automated mirror selection + + +Description +This APT transport isn't implementing a protocol to access local or remote repositories +on its own, but acquires a mirrorlist and redirects all requests to the mirror(s) picked from +this list access via other transports like &apt-transport-http;. The basic functionality is +available since apt 0.7.24, but was undocumented until apt 1.6 which contained a complete +rework of the transport and its supported features. Note that a transport is never called directly +by a user but used by APT tools based on user configuration. +If the acquisition of a file via a mirror fails the method ensures that automatically +another possible mirror of the list is tried until either the file is retrieved or no mirror is +left in the list handling transparently server downtimes and similar problems. +The security implications of the transport are based on the security considerations +associated with the transport used to acquire the mirrorlist and the transports involved in +accessing the chosen mirror(s) by the transport. + + +Options +This transport has no configuration options at present. The mirror selection is +based entirely on the mirrors offered in the mirrorlist and the files apt needs to +acquire. + +Mirrorlist format +A mirrorlist contains at least one line each specifying an URI for a mirror. +Empty lines and those starting with a hash key (#) are ignored. +An URI always starts with a URI scheme which defines the transport used for this +mirror. If the URI e.g. starts with http: the responsible transport +is &apt-transport-http; which might have specific requirements for the format of +the remaining part of the URI. +An URI can optionally be separated from metadata about the mirror by a tab. +Multiple datapoints in the provided metadata can itself be separated by spaces for tabs. +(This is an advanced feature only available with apt >= 1.6. Earlier apt versions will +fail to parse mirrorlists using this feature) +Since apt 1.6 the usage of compressed mirrorlists is also supported. +Note that the filename of the mirrorlist must specify the compression algorithm used, +there is no auto-detection based on file content performed. + + +Mirror selection by metadata +As specified in the format a mirror can have additional metadata attached to +prevent a mirror from being selected for acquiring a file not matching this metadata. +This way the mirrorlist can e.g. contain partial mirrors serving only certain +architectures and apt will automatically choose a different mirror for files requiring +an unlisted architecture. Supported are limits for the architecture (arch), +codename of the release (codename), component of the repository +the file is in (component), language the file applies to (lang), +suite name of the release (suite) and type of the file (type). + + +Fallback order for mirrors +If no priority is given via the metadata key priority for a +mirror the order in which mirrors are contacted is random. If a certain set of mirrors +should be tried first before any of another set is tried a priority can be explicitly +set. The mirrors with the lowest number are tried first. Mirrors which have no explicit +priority set default to the highest possible number and are therefore tried last. The +choice between mirrors with the same priority is again random. + + +Allowed transports in a mirrorlist +The availability and choice of transports in a mirrorlist is limited by how the apt +client is accessing the mirrorlist. If a local transport like file +or copy is used the mirrorlist can also include local sources while a +mirrorlist accessed via http can not. Additionally, a mirrorlist can +not contain a mirrorlist or other wrapping transports (like apt-transport-tor). +See the documentation of these transports on how to use them with the mirror method. +Note that apt versions before 1.6 do not support any other transport than http. + + + +Examples +Basic example +A basic mirrorlist example supported by all apt versions with a mirror method +(>= 0.7.24) in which the client will pick any of the three mirrors: + +http://ftp.de.debian.org/debian/ +http://ftp.us.debian.org/debian/ +http://deb.debian.org/debian/ + +Assuming a file with this content is stored as /etc/apt/mirrorlist.txt +on your machine it can be used like this in &sources-list; (since apt 1.6): + +deb mirror+file:/etc/apt/mirrorlist.txt &debian-stable-codename; main + +All versions of the mirror method support a mirrorlist accessible via http, so assuming +it is available at http://apt.example.org/mirror.lst the sources.list entry +from above could be written instead as: + +deb mirror://apt.example.org/mirror.lst &debian-stable-codename; main + +Note that since apt 1.6 the use of mirror+http should +be preferred over mirror for uniformity. The functionality is the same. + +Example with metadata-enhanced mirror selection +As explained in the format definition apt versions before 1.6 do not support this and +will fail parsing the mirrorlist. The example mirrorlist is proposefully complicated to show some +aspects of the selection. The following setup is assumed: The first mirror is local mirror +accessible via the file method, but potentially incomplete. The second mirror has a great +connection, but is a partial mirror in sofar as it only contains files related +to the architectures amd64 and all. The remaining mirrors +are average mirrors which should be contacted only if the earlier ones didn't work. + + +file:/srv/local/debian/mirror/ priority:1 type:index +http://partial.example.org/mirror/ priority:2 arch:amd64 arch:all type:deb +http://ftp.us.debian.org/debian/ type:deb +http://ftp.de.debian.org/debian/ type:deb +https://deb.debian.org/debian/ + +In this setup with this mirrorlist the first mirror will be used to download all +index files assuming the mirrorlist itself is accessed via a local transport like +file. If it isn't, the mirror is otherwise inaccessible or does not +contain the requested file another mirror will be used to acquire the file, which one +depending on the type of the file: An index file will be served by the last +mirror in the list, while a package of architecture amd64 is served by +the second and those of e.g. architecture i386 by one of the last three. + + + + + &manbugs; + + diff --git a/doc/po4a.conf b/doc/po4a.conf index f1fe4cb0c..587215abc 100644 --- a/doc/po4a.conf +++ b/doc/po4a.conf @@ -29,6 +29,7 @@ [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: manpage] apt-transport-https.1.xml $lang:$lang/apt-transport-https.$lang.1.xml add_$lang:xml.add +[type: manpage] apt-transport-mirror.1.xml $lang:$lang/apt-transport-mirror.$lang.1.xml add_$lang:xml.add [type: docbook] guide.dbk $lang:$lang/guide.$lang.dbk # add_$lang::$lang/addendum/docbook_$lang.add -- cgit v1.2.3