X-Git-Url: https://review.fuel-infra.org/gitweb?a=blobdiff_plain;f=README.md;h=78e43b16fa2ad1861a294944b82ad3c4a10e7669;hb=17b9a4481378fb50b5c3745824ae07ddbdd8e3fa;hp=73272c2ffaa6e2e2ae3ca415aa0ce9130238fb8b;hpb=37b710bbc19d0b962a0d9f740a30a6c3fb8aff9c;p=puppet-modules%2Fpuppetlabs-apt.git diff --git a/README.md b/README.md index 73272c2..78e43b1 100644 --- a/README.md +++ b/README.md @@ -16,11 +16,6 @@ * [Configure Apt from Hiera](#configure-apt-from-hiera) * [Replace the default sources.list file](#replace-the-default-sourceslist-file) 1. [Reference - An under-the-hood peek at what the module is doing and how](#reference) - * [Classes](#classes) - * [Defined types](#defined-types) - * [Types](#types) - * [Facts](#facts) - * [Tasks](#tasks) 1. [Limitations - OS compatibility, etc.](#limitations) 1. [Development - Guide for contributing to the module](#development) @@ -226,32 +221,39 @@ apt::source { "archive.ubuntu.com-${lsbdistcodename}-backports": } ``` -## Reference - -### Classes - -#### Public Classes - -* [`apt`](#class-apt) -* [`apt::backports`](#class-aptbackports) - -#### Private Classes +### Manage login configuration settings for an APT source or proxy in `/etc/apt/auth.conf` -* `apt::params`: Provides defaults for the apt module parameters. -* `apt::update`: Updates the list of available packages using `apt-get update`. +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. -### Defined Types +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. -* [`apt::conf`](#defined-type-aptconf) -* [`apt::key`](#defined-type-aptkey) -* [`apt::pin`](#defined-type-aptpin) -* [`apt::ppa`](#defined-type-aptppa) -* [`apt::setting`](#defined-type-aptsetting) -* [`apt::source`](#defined-type-aptsource) +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. -### Types +```puppet +class { 'apt': + auth_conf_entries => [ + { + 'machine' => 'apt-proxy.example.net', + 'login' => 'proxylogin', + 'password' => 'proxypassword', + }, + { + 'machine' => 'apt.example.com/ubuntu', + 'login' => 'reader', + 'password' => 'supersecret', + }, + ], +} +``` -* [`apt_key`](#type-apt_key) +## Reference ### Facts @@ -271,264 +273,19 @@ apt::source { "archive.ubuntu.com-${lsbdistcodename}-backports": * `apt_reboot_required`: Determines if a reboot is necessary after updates have been installed. -### Tasks - -The Apt module has an example task that allows a user to run apt-get update or upgrade. Please refer to to the [PE documentation](https://puppet.com/docs/pe/2017.3/orchestrator/running_tasks.html) or [Bolt documentation](https://puppet.com/docs/bolt/latest/bolt.html) on how to execute a task. - -#### Class: `apt` - -Main class, includes all other classes. - -##### Parameters - -All parameters are optional unless specified. - -* `confs`: Creates new `apt::conf` resources. Valid options: a hash to be passed to the [`create_resources` function](https://docs.puppetlabs.com/references/latest/function.html#createresources). Default: {}. - -* `keys`: Creates new `apt::key` resources. Valid options: a hash to be passed to the [`create_resources` function](https://docs.puppetlabs.com/references/latest/function.html#createresources). Default: {}. - -* `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`. - -* `purge`: Specifies whether to purge any existing settings that aren't managed by Puppet. Valid options: a hash made up from the following keys: - - * `sources.list`: Specifies whether to purge any unmanaged entries from `sources.list`. Valid options: `true` and `false`. Default: `false`. - - * `sources.list.d`: Specifies whether to purge any unmanaged entries from `sources.list.d`. Valid options: `true` and `false`. Default: `false`. - - * `preferences`: Specifies whether to purge any unmanaged entries from `preferences`. Valid options: `true` and `false`. Default: `false`. - - * `preferences.d`: Specifies whether to purge any unmanaged entries from `preferences.d`. Valid options: `true` and `false`. Default: `false`. - -* `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: {}. - -* `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: {}. - -* `update`: Configures various update settings. Valid options: a hash made up from the following keys: - - * `frequency`: Specifies how often to run `apt-get update`. If the exec resource `apt_update` is notified, `apt-get update` runs regardless of this value. Valid options: 'always' (at every Puppet run); 'daily' (if the value of `apt_update_last_success` is less than current epoch time minus 86400); 'weekly' (if the value of `apt_update_last_success` is less than current epoch time minus 604800); and 'reluctantly' (only if the exec resource `apt_update` is notified). Default: 'reluctantly'. - - * `timeout`: Specifies how long to wait for the update to complete before canceling it. Valid options: an integer, in seconds. Default: 300. - - * `tries`: Specifies how many times to retry the update after receiving a DNS or HTTP error. Valid options: an integer. Default: 1. - -#### Class: `apt::backports` - -Manages backports. - -##### Parameters - -All parameters are optional on Debian and Ubuntu and required on other operating systems, except where specified. - -* `key`: Specifies a key to authenticate the backports. Valid options: a string to be passed to the `id` parameter of the `apt::key` defined type, or a hash of `parameter => value` pairs to be passed to `apt::key`'s `id`, `server`, `content`, `source`, and/or `options` parameters. Defaults: - - * Debian: 'A1BD8E9D78F7FE5C3E65D8AF8B48AD6246925553' - * Ubuntu: '630239CC130E1A7FD81A27B140976EAF437D05B5' - -* `location`: Specifies an Apt repository containing the backports to manage. Valid options: a string containing a URL. Defaults: - - * Debian: 'http://deb.debian.org/debian' - * Ubuntu: 'http://archive.ubuntu.com/ubuntu' - -* `pin`: *Optional.* Specifies a pin priority for the backports. Valid options: a number or string to be passed to the `id` parameter of the `apt::pin` defined type, or a hash of `parameter => value` pairs to be passed to `apt::pin`'s corresponding parameters. Default: '200'. - -* `release`: Specifies a distribution of the Apt repository containing the backports to manage. Valid options: a string containing the release, used in populating the `source.list` configuration file. Default: on Debian and Ubuntu, '${lsbdistcodename}-backports'. We recommend keeping this default, except on other operating systems. - -* `repos`: Specifies a component of the Apt repository containing the backports to manage. Valid options: A string containing the repos to include, used in populating the `source.list` configuration file. Defaults: - - * Debian: 'main contrib non-free' - * Ubuntu: 'main universe multiverse restricted' - -#### Defined Type: `apt::conf` - -Specifies a custom Apt configuration file. - -##### Parameters - -All parameters are optional unless specified. - - -* `content`: *Required, unless `ensure` is set to 'absent'.* Directly supplies content for the configuration file. Valid options: a string. Default: undef. - -* `ensure`: Specifies whether the configuration file should exist. Valid options: 'present' and 'absent'. Default: 'present'. - -* `priority`: *Optional.* Determines the order in which Apt processes the configuration file. Files with lower priority numbers are loaded first. Valid options: a string containing an integer. Default: '50'. - -* `notify_update`: *Optional.* Specifies whether to trigger an `apt-get update` run. Valid options: `true` and `false`. Default: `true`. - -#### Defined type: `apt::key` - -Manages the GPG keys that Apt uses to authenticate packages. - -The `apt::key` defined type makes use of the `apt_key` type, but includes extra functionality to help prevent duplicate keys. - -##### Parameters (all 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. Valid options: a string. Default: undef. - -* `ensure`: Specifies whether the key should exist. Valid options: 'present' and 'absent'. Default: 'present'. - -* `id`: Specifies a GPG key to authenticate Apt package signatures. Valid options: a string containing a key ID (8 or 16 hexadecimal characters, optionally prefixed with "0x") or a full key fingerprint (40 hexadecimal characters). Default: $title. - -* `options`: Passes additional options to `apt-key adv --keyserver-options`. Valid options: a string. Default: undef. - -* `source`: Specifies the location of an existing GPG key file to copy. Valid options: a string containing a URL (ftp://, http://, or https://) or an absolute path. Default: undef. - -* `server`: Specifies a keyserver to provide the GPG key. Valid options: a string containing a domain name or a full URL (http://, https://, or hkp://). Default: 'keyserver.ubuntu.com'. +### More Information -#### Defined type: `apt::pin` - -Manages Apt pins. Does not trigger an `apt-get update` run. - -**Note:** For context on these parameters, we recommend reading the man page ['apt_preferences(5)'](http://linux.die.net/man/5/apt_preferences) - -##### Parameters - -All parameters are optional unless specified. - -* `codename`: Specifies the distribution (lsbdistcodename) of the Apt repository. Valid options: a string. Default: ''. - -* `component`: Names the licensing component associated with the packages in the directory tree of the Release file. Valid options: a string. Default: ''. - -* `ensure`: Specifies whether the pin should exist. Valid options: 'file', 'present', and 'absent'. Default: 'present'. - -* `explanation`: Supplies a comment to explain the pin. Valid options: a string. Default: "${caller_module_name}: ${name}". - -* `label`: Names the label of the packages in the directory tree of the Release file. Valid options: a string (most commonly, 'debian'). Default: ''. - -* `order`: Determines the order in which Apt processes the pin file. Files with lower order numbers are loaded first. Valid options: an integer. Default: 50. - -* `origin`: Tells Apt to prefer packages from the specified server. Valid options: a string containing a hostname. Default: ''. - -* `originator`: Names the originator of the packages in the directory tree of the Release file. Valid options: a string (most commonly, 'debian'). Default: ''. - -* `packages`: Specifies which package(s) to pin. Valid options: a string or an array. Default: `*`. - -* `priority`: Sets the priority of the package. If multiple versions of a given package are available, `apt-get` installs the one with the highest priority number (subject to dependency constraints). Valid options: an integer. Default: 0. - -* `release`: Tells Apt to prefer packages that support the specified release. Typical values include 'stable', 'testing', and 'unstable' Valid options: a string. Default: ''. - -* `release_version`: Tells Apt to prefer packages that support the specified operating system release version (such as Debian release version 7). Valid options: a string. Default: ''. - -* `version`: Tells Apt to prefer a specified package version or version range. Valid options: a string. Default: ''. - -#### Defined Type: `apt::ppa` - -Manages PPA repositories using `add-apt-repository`. Not supported on Debian. - -##### Parameters - -All parameters are optional unless specified. - -* `ensure`: Specifies whether the PPA should exist. Valid options: 'present' and 'absent'. Default: 'present'. - -* `options`: Supplies options to be passed to the `add-apt-repository` command. Valid options: a string. Defaults: - - * Lucid: undef - * All others: '-y' - -* `package_manage`: Specifies whether Puppet should manage the package that provides `apt-add-repository`. Valid options: `true` and `false`. Default: `false`. - -* `package_name`: Names the package that provides the `apt-add-repository` command. Valid options: a string. Defaults: - - * Lucid and Precise: 'python-software-properties' - * Trusty and newer: 'software-properties-common' - * All others: 'python-software-properties' - -* `release`: *Optional if lsb-release is installed (unless you're using a different release than indicated by lsb-release, e.g., Linux Mint).* Specifies the operating system of your node. Valid options: a string containing a valid LSB distribution codename. Default: "$lsbdistcodename". - -#### Defined Type: `apt::setting` - -Manages Apt configuration files. - -##### Parameters - -All parameters are optional unless specified. - -* `content`: *Required, unless `source` is set.* Directly supplies content for the configuration file. Cannot be used in combination with `source`. Valid options: see the `content` attribute of [Puppet's native `file` type](https://docs.puppetlabs.com/references/latest/type.html#file-attribute-content). Default: undef. - -* `ensure`: Specifies whether the file should exist. Valid options: 'present', 'absent', and 'file'. Default: 'file'. - -* `notify_update`: *Optional.* Specifies whether to trigger an `apt-get update` run. Valid options: `true` and `false`. Default: `true`. - -* `priority`: *Optional.* Determines the order in which Apt processes the configuration file. Files with higher priority numbers are loaded first. Valid options: an integer or zero-padded integer. Default: 50. - -* `source`: *Required, unless `content` is set.* Specifies a source file to supply the content of the configuration file. Cannot be used in combination with `content`. Valid options: see the `source` attribute of [Puppet's native `file` type](https://docs.puppetlabs.com/references/latest/type.html#file-attribute-source). Default: undef. - -#### Defined Type: `apt::source` - -Manages the Apt sources in `/etc/apt/sources.list.d/`. - -##### Parameters - -All parameters are optional unless specified. - -* `allow_unsigned`: Specifies whether to authenticate packages from this release, even if the Release file is not signed or the signature can't be checked. Valid options: `true` and `false`. Default: `false`. - -* `architecture`: Tells Apt to only download information for specified architectures. Valid options: a string containing one or more architecture names, separated by commas (e.g., 'i386' or 'i386,alpha,powerpc'). Default: undef (if unspecified, Apt downloads information for all architectures defined in the Apt::Architectures option). - -* `comment`: Supplies a comment for adding to the Apt source file. Valid options: a string. Default: $name. - -* `ensure`: Specifies whether the Apt source file should exist. Valid options: 'present' and 'absent'. Default: 'present'. - -* `key`: Creates a declaration of the apt::key defined type. Valid options: a string to be passed to the `id` parameter of the `apt::key` defined type, or a hash of `parameter => value` pairs to be passed to `apt::key`'s `id`, `server`, `content`, `source`, and/or `options` parameters. Default: undef. - -* `include`: Configures include options. Valid options: a hash of available keys. Default: {}. Available keys are: - - * `deb` - Specifies whether to request the distribution's compiled binaries. Valid options: `true` and `false`. Default: `true`. - - * `src` - Specifies whether to request the distribution's uncompiled source code. Valid options: `true` and `false`. Default: `false`. - -* `location`: *Required, unless `ensure` is set to 'absent'.* Specifies an Apt repository. Valid options: a string containing a repository URL. Default: undef. - -* `pin`: Creates a declaration of the apt::pin defined type. Valid options: a number or string to be passed to the `id` parameter of the `apt::pin` defined type, or a hash of `parameter => value` pairs to be passed to `apt::pin`'s corresponding parameters. Default: undef. - -* `release`: Specifies a distribution of the Apt repository. Valid options: a string. Default: "$lsbdistcodename". - - * `repos`: Specifies a component of the Apt repository. Valid options: a string. Default: 'main'. - -* `notify_update`: *Optional.* Specifies whether to trigger an `apt-get update` run. Valid options: `true` and `false`. Default: `true`. - -#### Type: `apt_key` - -Manages the GPG keys that Apt uses to authenticate packages. - -**Note:** In most cases, we recommend using the `apt::key` defined type. It makes use of the `apt_key` type, but includes extra functionality to help prevent duplicate keys. - -##### Parameters - -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. - -* `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'. - -* `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. +See [REFERENCE.md](https://github.com/puppetlabs/puppetlabs-motd/blob/master/REFERENCE.md) for all other reference documentation. ## Limitations -This module is tested and officially supported on Debian 6 and 7 and Ubuntu 10.04, 12.04, and 14.04. Testing on other platforms has been light and cannot be guaranteed. - 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). +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). Before running the command below, ensure that all packages have the provider set to apt. ```puppet Class['apt::update'] -> Package <| provider == 'apt' |>