diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/CMakeLists.txt | 1 | ||||
| -rw-r--r-- | doc/apt-verbatim.ent | 6 | ||||
| -rw-r--r-- | doc/apt_auth.conf.5.xml | 132 | ||||
| -rw-r--r-- | doc/examples/configure-index | 6 | ||||
| -rw-r--r-- | doc/sources.list.5.xml | 61 |
5 files changed, 187 insertions, 19 deletions
diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt index a1491428f..d7241eb5e 100644 --- a/doc/CMakeLists.txt +++ b/doc/CMakeLists.txt @@ -66,6 +66,7 @@ endif() add_docbook(apt-man MANPAGE ALL DOCUMENTS apt.8.xml + apt_auth.conf.5.xml apt-cache.8.xml apt-cdrom.8.xml apt.conf.5.xml diff --git a/doc/apt-verbatim.ent b/doc/apt-verbatim.ent index b555c5de5..be599d393 100644 --- a/doc/apt-verbatim.ent +++ b/doc/apt-verbatim.ent @@ -15,6 +15,12 @@ </citerefentry>" > +<!ENTITY apt-authconf "<citerefentry> + <refentrytitle><filename>apt_auth.conf</filename></refentrytitle> + <manvolnum>5</manvolnum> + </citerefentry>" +> + <!ENTITY apt-get "<citerefentry> <refentrytitle><command>apt-get</command></refentrytitle> <manvolnum>8</manvolnum> diff --git a/doc/apt_auth.conf.5.xml b/doc/apt_auth.conf.5.xml new file mode 100644 index 000000000..8a1882604 --- /dev/null +++ b/doc/apt_auth.conf.5.xml @@ -0,0 +1,132 @@ +<?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-07-07T00:00:00Z</date> + </refentryinfo> + + <refmeta> + <refentrytitle>apt_auth.conf</refentrytitle> + <manvolnum>5</manvolnum> + <refmiscinfo class="manual">APT</refmiscinfo> + </refmeta> + + <!-- Man page title --> + <refnamediv> + <refname>apt_auth.conf</refname> + <refpurpose>Login configuration file for APT sources and proxies</refpurpose> + </refnamediv> + +<refsect1><title>Description</title> +<para>APT configuration files like &sources-list; or &apt-conf; need to be accessible +for everyone using apt tools on the system to have access to all package-related +information like the available packages in a repository. Login information +needed to connect to a proxy or to download data from a repository on the other +hand shouldn't always be accessible by everyone and can hence not be placed in a +file with world-readable file permissions.</para> + +<para>The APT auth.conf file <filename>/etc/apt/auth.conf</filename> can be used to store +login information in a netrc-like format with restrictive file permissions.</para> +</refsect1> + +<refsect1><title>netrc-like format</title> +<para>The format defined here is similar to the format of the <filename>~/.netrc</filename> +file used by <citerefentry><refentrytitle><command>ftp</command></refentrytitle><manvolnum>1</manvolnum></citerefentry> +and similar programs interacting with servers. +It is a simple token-based format with the following tokens being recognized; +Unknown tokens will be ignored. Tokens may be separated by spaces, tabs or newlines.</para> + +<variablelist> +<varlistentry> +<term><literal>machine</literal> <replaceable>hostname</replaceable>[:<replaceable>port</replaceable>][/<replaceable>path</replaceable>]</term> +<listitem><para>Entries are looked up by searching for the +<emphasis><literal>machine</literal></emphasis> token matching the +hostname of the URI apt needs login information for. Extending the netrc-format +a portnumber can be specified. If no port is given the token matches for all ports. +Similar the path is optional and only needed and useful if multiple repositories with +different login information reside on the same server. A machine token with a path +matches if the path in the URI starts with the path given in the token. +Once a match is made, the subsequent tokens are processed, stopping when the +end of file is reached or another <emphasis><literal>machine</literal></emphasis> +token is encountered.</para></listitem> +</varlistentry> + +<varlistentry> +<term><literal>login</literal> <replaceable>name</replaceable></term> +<listitem><para>The username to be used.</para></listitem> +</varlistentry> + +<varlistentry> +<term><literal>password</literal> <replaceable>string</replaceable></term> +<listitem><para>The password to be used.</para></listitem> +</varlistentry> + +</variablelist> + +</refsect1> + +<refsect1><title>Example</title> +<para>Supplying login information for a user named <literal>apt</literal> +with the password <literal>debian</literal> for the &sources-list; entry +<literallayout>deb http://example.org/debian &debian-stable-codename; main</literallayout> +could be done in the entry directly: +<literallayout>deb http://apt:debian@example.org/debian &debian-stable-codename; main</literallayout> +Alternatively an entry like the following in the auth.conf file could be used: +<literallayout>machine example.org +login apt +password debian</literallayout> +Or alternatively within a single line: +<literallayout>machine example.org login apt password debian</literallayout> +If you need to be more specific all of these lines will also apply to the example entry:</para> +<literallayout>machine example.org/deb login apt password debian +machine example.org/debian login apt password debian +machine example.org/debian/ login apt password debian +</literallayout> +On the other hand neither of the following lines apply: +<literallayout>machine example.org:80 login apt password debian +machine example.org/deb/ login apt password debian +machine example.org/ubuntu login apt password debian +machine example.orga login apt password debian +machine example.net login apt password debian +</literallayout> +</refsect1> + +<refsect1><title>Notes</title> +<para>Basic support for this feature is present since version 0.7.25, but was +undocumented for years. The documentation was added in version 1.5 changing +also the implementation slightly. For maximum backward compatibility you should +avoid multiple <literal>machine</literal> tokens with the same hostname, but if +you need multiple they should all have a path specified in the +<literal>machine</literal> token.</para> +</refsect1> + +<refsect1> +<title>Files</title> + <variablelist> + <varlistentry><term><filename>/etc/apt/auth.conf</filename></term> + <listitem><para>Login information for APT sources and proxies in a netrc-like format. + Configuration Item: <literal>Dir::Etc::netrc</literal>.</para></listitem> + </varlistentry> + </variablelist> +</refsect1> + +<refsect1> +<title>See Also</title> +<para>&apt-conf; &sources-list; +</para> +</refsect1> + + &manbugs; + +</refentry> diff --git a/doc/examples/configure-index b/doc/examples/configure-index index 244d7c1c3..61a749495 100644 --- a/doc/examples/configure-index +++ b/doc/examples/configure-index @@ -107,7 +107,11 @@ APT IndexTargets::ReleaseInfo "<BOOL>"; IndexTargets::format "<STRING>"; - Update::InteractiveReleaseInfoChanges "<BOOL>"; + Update + { + InteractiveReleaseInfoChanges "<BOOL>"; + SourceListWarnings "<BOOL>"; + }; }; Cache diff --git a/doc/sources.list.5.xml b/doc/sources.list.5.xml index dd057eb32..c4df9aa58 100644 --- a/doc/sources.list.5.xml +++ b/doc/sources.list.5.xml @@ -350,6 +350,40 @@ deb-src [ option1=value1 option2=value2 ] uri suite [component1] [component2] [. <para>The currently recognized URI types are: <variablelist> + <varlistentry><term><command>http</command></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>. + 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 + communication with the remote server (or proxy) is not encrypted so a + sufficiently capable attacker can observe and record login as well as all + other interactions. The attacker can <emphasis>not</emphasis> modify the + communication through as APTs data security model is independent of the + chosen transport method. See &apt-secure; for details.</para></listitem> + </varlistentry> + + <varlistentry><term><command>https</command></term> + <listitem><para> + 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 + difference is that the communication between apt and server (or proxy) is + encrypted. Note that the encryption does not prevent an attacker from + knowing which server (or proxy) apt is communicating with and deeper + analyses can potentially still reveal which data was downloaded. If this is + a concern the Tor-based schemes mentioned further below might be a suitable + alternative.</para></listitem> + </varlistentry> + + <varlistentry><term><command>file</command></term> <listitem><para> The file scheme allows an arbitrary directory in the file system to be @@ -359,27 +393,19 @@ deb-src [ option1=value1 option2=value2 ] uri suite [component1] [component2] [. <varlistentry><term><command>cdrom</command></term> <listitem><para> - The cdrom scheme allows APT to use a local CD-ROM drive with media + The cdrom scheme allows APT to use a local CD-ROM, DVD or USB drive with media swapping. Use the &apt-cdrom; program to create cdrom entries in the source list.</para></listitem> </varlistentry> - <varlistentry><term><command>http</command></term> - <listitem><para> - The http scheme specifies an HTTP server for the archive. If an environment - variable <envar>http_proxy</envar> is set with the format - http://server:port/, the proxy server specified in - <envar>http_proxy</envar> will be used. Users of authenticated - HTTP/1.1 proxies may use a string of the format - http://user:pass@server:port/. - Note that this is an insecure method of authentication.</para></listitem> - </varlistentry> - <varlistentry><term><command>ftp</command></term> <listitem><para> - The ftp scheme specifies an FTP server for the archive. APT's FTP behavior - is highly configurable; for more information see the - &apt-conf; manual page. Please note that an FTP proxy can be specified + The ftp scheme specifies an FTP server for an archive. Use of FTP is on the + decline in favour of <literal>http</literal> and <literal>https</literal> + and many archives either never offered or are retiring FTP access. If you + still need this method many configuration options for it are available in + the <literal>Acquire::ftp</literal> scope and detailed in &apt-conf;.</para> + <para>Please note that an FTP proxy can be specified by using the <envar>ftp_proxy</envar> environment variable. It is possible to specify an HTTP proxy (HTTP proxy servers often understand FTP URLs) using this environment variable and <emphasis>only</emphasis> this @@ -407,9 +433,8 @@ deb-src [ option1=value1 option2=value2 ] uri suite [component1] [component2] [. <listitem><para> APT can be extended with more methods shipped in other optional packages, which should follow the naming scheme <package>apt-transport-<replaceable>method</replaceable></package>. - For instance, the APT team also maintains the package <package>apt-transport-https</package>, - which provides access methods for HTTPS URIs with features similar to the http method. - Methods for using e.g. debtorrent are also available - see &apt-transport-debtorrent;. + For instance, the APT team also maintains the package <package>apt-transport-tor</package>, + which provides access methods for HTTP and HTTPS URIs routed via the Tor network. </para></listitem> </varlistentry> </variablelist> |