X-Git-Url: https://review.fuel-infra.org/gitweb?a=blobdiff_plain;f=README.md;h=ef9989412ddf6b78beb0a0ab15d68aca3b53e17c;hb=e99d83c2d6bdd45a9111eab0306da105c1f2acca;hp=56687f2e448686ea04569219446b1c53fb4ede97;hpb=2889b8abfe83c29bfdb377edb0985805a6816097;p=puppet-modules%2Fpuppetlabs-apt.git diff --git a/README.md b/README.md index 56687f2..ef99894 100644 --- a/README.md +++ b/README.md @@ -226,6 +226,38 @@ apt::source { "archive.ubuntu.com-${lsbdistcodename}-backports": } ``` +### Manage login configuration settings for an APT source or proxy in `/etc/apt/auth.conf` + +Starting with APT version 1.5, you can define login configuration settings, such as +username and password, for APT sources or proxies that require authentication +in the `/etc/apt/auth.conf` file. This is preferable to embedding login +information directly in `source.list` entries, which are usually world-readable. + +The `/etc/apt/auth.conf` file follows the format of netrc (used by ftp or +curl) and has restrictive file permissions. See +https://manpages.debian.org/testing/apt/apt_auth.conf.5.en.html for details. + +Use the optional `apt::auth_conf_entries` parameter to specify an array of +hashes containing login configuration settings. These hashes may only contain +the `machine`, `login` and `password` keys. + +```puppet +class { 'apt': + auth_conf_entries => [ + { + 'machine' => 'apt-proxy.example.net', + 'login' => 'proxylogin', + 'password' => 'proxypassword', + }, + { + 'machine' => 'apt.example.com/ubuntu', + 'login' => 'reader', + 'password' => 'supersecret', + }, + ], +} +``` + ## Reference ### Classes @@ -248,6 +280,7 @@ apt::source { "archive.ubuntu.com-${lsbdistcodename}-backports": * [`apt::ppa`](#defined-type-aptppa) * [`apt::setting`](#defined-type-aptsetting) * [`apt::source`](#defined-type-aptsource) +* [`apt::proxy`](#defined-type-aptproxy) ### Types @@ -289,17 +322,7 @@ All parameters are optional unless specified. * `ppas`: Creates new `apt::ppa` resources. Valid options: a hash to be passed to the [`create_resources` function](https://docs.puppetlabs.com/references/latest/function.html#createresources). Default: {}. -* `proxy`: Configures Apt to connect to a proxy server. Valid options: a hash made up from the following keys: - - * `host`: Specifies a proxy host to be stored in `/etc/apt/apt.conf.d/01proxy`. Valid options: a string containing a hostname. Default: undef. - - * `port`: Specifies a proxy port to be stored in `/etc/apt/apt.conf.d/01proxy`. Valid options: an integer containing a port number. Default: 8080. - - * `https`: Specifies whether to enable https proxies. Valid options: `true` and `false`. Default: `false`. - - * `ensure`: Optional parameter. Valid options: 'file', 'present', and 'absent'. Default: `undef`. Prefer 'file' over 'present'. - - * `direct`: Specifies whether or not to use a 'DIRECT' https proxy if http proxy is used but https is not. Valid options: `true` and `false`. Default: `false`. +* `proxy`: Configures Apt to connect to a proxy server. Valid options: a hash matching the locally defined type [`apt::proxy`](#defined-type-aptproxy). * `purge`: Specifies whether to purge any existing settings that aren't managed by Puppet. Valid options: a hash made up from the following keys: @@ -313,6 +336,8 @@ All parameters are optional unless specified. * `settings`: Creates new `apt::setting` resources. Valid options: a hash to be passed to the [`create_resources` function](https://docs.puppetlabs.com/references/latest/function.html#createresources). Default: {}. +* `auth_conf_entries`: An optional array of login configuration settings (hashes) that will be recorded in the file `/etc/apt/auth.conf`. This file has a netrc-like format (similar to what curl uses) and contains the login configuration for APT sources and proxies that require authentication. See https://manpages.debian.org/testing/apt/apt_auth.conf.5.en.html for details. If specified each hash must contain the keys `machine`, `login` and `password` and no others. Default: []. + * `sources`: Creates new `apt::source` resources. Valid options: a hash to be passed to the [`create_resources` function](https://docs.puppetlabs.com/references/latest/function.html#createresources). Default: {}. * `pins`: Creates new `apt::pin` resources. Valid options: a hash to be passed to the [`create_resources` function](https://docs.puppetlabs.com/references/latest/function.html#createresources). Default: {}. @@ -512,20 +537,38 @@ Manages the GPG keys that Apt uses to authenticate packages. All parameters are optional. -* `content`: Supplies the entire GPG key. Useful in case the key can't be fetched from a remote location and using a file resource is inconvenient. Cannot be used in combination with `source`. Valid options: a string. Default: undef. +* `content`: Supplies the entire GPG key. Useful in case the key can't be fetched from a remote location and using a file resource is inconvenient. Cannot be used in combination with `source`. Valid options: a string. Default: `undef`. -* `options`: Passes additional options to `apt-key adv --keyserver-options`. Valid options: a string. Default: undef. +* `options`: Passes additional options to `apt-key adv --keyserver-options`. Valid options: a string. Default: `undef`. -* `server`: Specifies a keyserver to provide Puppet's GPG key. Valid options: a string containing a domain name or a full URL. Default: 'keyserver.ubuntu.com'. +* `server`: Specifies a keyserver to provide Puppet's GPG key. Valid options: a string containing a domain name or a full URL. Default: `keyserver.ubuntu.com`. -* `source`: Specifies the location of an existing GPG key file to copy. Cannot be used in combination with `content`. Valid options: a string containing a URL (ftp://, http://, or https://) or an absolute path. Default: undef. +* `source`: Specifies the location of an existing GPG key file to copy. Cannot be used in combination with `content`. Valid options: a string containing a URL (ftp://, http://, or https://) or an absolute path. Default: `undef`. -## Limitations +#### Defined Type: `apt::proxy` + +Configures Apt to connect to a proxy server. + +##### Parameters + +All parameters are optional. -This module is tested and officially supported on Debian 8 and 9 and Ubuntu 14.04, and 16.04. Testing on other platforms has been light and cannot be guaranteed. +* `host`: *Optional.* Specifies a proxy host to be stored in `/etc/apt/apt.conf.d/01proxy`. Valid options: a string containing a hostname. Default: `undef`. + +* `port`: *Optional.* Specifies a proxy port to be stored in `/etc/apt/apt.conf.d/01proxy`. Valid options: an integer containing a port number. Default: `8080`. + +* `https`: *Optional.* Specifies whether to enable https proxies. Valid options: `true` and `false`. Default: `false`. + +* `direct`: *Optional.* Specifies whether or not to use a `DIRECT` https proxy if http proxy is used but https is not. Valid options: `true` and `false`. Default: `false`. + +* `ensure`: *Optional.* Specifies whether the proxy should exist. Valid options: 'file', 'present', and 'absent'. Default: undef. Prefer 'file' over 'present'. + +## Limitations This module is not designed to be split across [run stages](https://docs.puppetlabs.com/puppet/latest/reference/lang_run_stages.html). +For an extensive list of supported operating systems, see [metadata.json](https://github.com/puppetlabs/puppetlabs-apt/blob/master/metadata.json) + ### Adding new sources or PPAs If you are adding a new source or PPA and trying to install packages from the new source or PPA on the same Puppet run, your `package` resource should depend on `Class['apt::update']`, in addition to depending on the `Apt::Source` or the `Apt::Ppa`. You can also add [collectors](https://docs.puppetlabs.com/puppet/latest/reference/lang_collectors.html) to ensure that all packages happen after `apt::update`, but this can lead to dependency cycles and has implications for [virtual resources](https://docs.puppetlabs.com/puppet/latest/reference/lang_collectors.html#behavior).