From: Eimhin Laverty Date: Tue, 4 Sep 2018 13:38:25 +0000 (+0100) Subject: (FM-7318) - Added Puppet Strings formatting to documentation X-Git-Tag: 6.1.0~11^2 X-Git-Url: https://review.fuel-infra.org/gitweb?a=commitdiff_plain;h=6c1fd8e819cc8ffb44ac187bb0fa7051d2958cc6;hp=0cfcadeee5cc86c577756adf812822214af4d37f;p=puppet-modules%2Fpuppetlabs-apt.git (FM-7318) - Added Puppet Strings formatting to documentation --- diff --git a/README.md b/README.md index a62b7b5..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) @@ -260,32 +255,6 @@ class { 'apt': ## Reference -### Classes - -#### Public Classes - -* [`apt`](#class-apt) -* [`apt::backports`](#class-aptbackports) - -#### Private Classes - -* `apt::params`: Provides defaults for the apt module parameters. -* `apt::update`: Updates the list of available packages using `apt-get update`. - -### Defined Types - -* [`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) -* [`apt::proxy`](#defined-type-aptproxy) - -### Types - -* [`apt_key`](#type-apt_key) - ### Facts * `apt_updates`: The number of installed packages with available updates from `upgrade`. @@ -304,264 +273,9 @@ class { 'apt': * `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 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: - - * `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: {}. - -* `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: {}. - -* `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'. - -#### 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`. - -#### Defined Type: `apt::proxy` - -Configures Apt to connect to a proxy server. - -##### Parameters - -All parameters are optional. - -* `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`. +### More Information -* `ensure`: *Optional.* Specifies whether the proxy should exist. Valid options: 'file', 'present', and 'absent'. Default: undef. Prefer 'file' over 'present'. +See [REFERENCE.md](https://github.com/puppetlabs/puppetlabs-motd/blob/master/REFERENCE.md) for all other reference documentation. ## Limitations diff --git a/REFERENCE.md b/REFERENCE.md new file mode 100644 index 0000000..ded9ade --- /dev/null +++ b/REFERENCE.md @@ -0,0 +1,862 @@ +# Reference + + +## Table of Contents + +**Classes** + +_Public Classes_ + +* [`apt`](#apt): Main class, includes all other classes. +* [`apt::backports`](#aptbackports): Manages backports. + +_Private Classes_ + +* `apt::params`: Provides defaults for the Apt module parameters. +* `apt::update`: Updates the list of available packages using apt-get update. + +**Defined types** + +* [`apt::conf`](#aptconf): Specifies a custom Apt configuration file. +* [`apt::key`](#aptkey): Manages the GPG keys that Apt uses to authenticate packages. +* [`apt::pin`](#aptpin): Manages Apt pins. Does not trigger an apt-get update run. +* [`apt::ppa`](#aptppa): Manages PPA repositories using `add-apt-repository`. Not supported on Debian. +* [`apt::setting`](#aptsetting): Manages Apt configuration files. +* [`apt::source`](#aptsource): Manages the Apt sources in /etc/apt/sources.list.d/. + +**Resource types** + +_Public Resource types_ + + +_Private Resource types_ + +* `apt_key`: This type provides Puppet with the capabilities to manage GPG keys needed by apt to perform package validation. Apt has it's own GPG keyring + +**Tasks** + +* [`init`](#init): Allows you to perform apt functions + +## Classes + +### apt + +Main class, includes all other classes. + +* **See also** +https://docs.puppetlabs.com/references/latest/function.html#createresources +for the create resource function + +#### Parameters + +The following parameters are available in the `apt` class. + +##### `provider` + +Data type: `String` + +Specifies the provider that should be used by apt::update. + +Default value: $apt::params::provider + +##### `keyserver` + +Data type: `String` + +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 value: $apt::params::keyserver + +##### `ppa_options` + +Data type: `Optional[String]` + +Supplies options to be passed to the `add-apt-repository` command. + +Default value: $apt::params::ppa_options + +##### `ppa_package` + +Data type: `Optional[String]` + +Names the package that provides the `apt-add-repository` command. + +Default value: $apt::params::ppa_package + +##### `backports` + +Data type: `Optional[Hash]` + +Specifies some of the default parameters used by apt::backports. Valid options: a hash made up from the following keys: + +Options: + +* **:location** `String`: See apt::backports for documentation. +* **:repos** `String`: See apt::backports for documentation. +* **:key** `String`: See apt::backports for documentation. + +Default value: $apt::params::backports + +##### `confs` + +Data type: `Hash` + +Creates new `apt::conf` resources. Valid options: a hash to be passed to the create_resources function linked above. + +Default value: $apt::params::confs + +##### `update` + +Data type: `Hash` + +Configures various update settings. Valid options: a hash made up from the following keys: + +Options: + +* **:frequency** `String`: 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'. +* **:loglevel** `Integer`: Specifies the log level of logs outputted to the console. Default: undef. +* **:timeout** `Integer`: Specifies how long to wait for the update to complete before canceling it. Valid options: an integer, in seconds. Default: undef. +* **:tries** `Integer`: Specifies how many times to retry the update after receiving a DNS or HTTP error. Default: undef. + +Default value: $apt::params::update + +##### `purge` + +Data type: `Hash` + +Specifies whether to purge any existing settings that aren't managed by Puppet. Valid options: a hash made up from the following keys: + +Options: + +* **:sources.list** `Boolean`: Specifies whether to purge any unmanaged entries from sources.list. Default false. +* **:sources.list.d** `Boolean`: Specifies whether to purge any unmanaged entries from sources.list.d. Default false. +* **:preferences** `Boolean`: Specifies whether to purge any unmanaged entries from preferences. Default false. +* **:preferences.d.** `Boolean`: Specifies whether to purge any unmanaged entries from preferences.d. Default false. + +Default value: $apt::params::purge + +##### `proxy` + +Data type: `Apt::Proxy` + +Configures Apt to connect to a proxy server. Valid options: a hash matching the locally defined type apt::proxy. + +Default value: $apt::params::proxy + +##### `sources` + +Data type: `Hash` + +Creates new `apt::source` resources. Valid options: a hash to be passed to the create_resources function linked above. + +Default value: $apt::params::sources + +##### `keys` + +Data type: `Hash` + +Creates new `apt::key` resources. Valid options: a hash to be passed to the create_resources function linked above. + +Default value: $apt::params::keys + +##### `ppas` + +Data type: `Hash` + +Creates new `apt::ppa` resources. Valid options: a hash to be passed to the create_resources function linked above. + +Default value: $apt::params::ppas + +##### `pins` + +Data type: `Hash` + +Creates new `apt::pin` resources. Valid options: a hash to be passed to the create_resources function linked above. + +Default value: $apt::params::pins + +##### `settings` + +Data type: `Hash` + +Creates new `apt::setting` resources. Valid options: a hash to be passed to the create_resources function linked above. + +Default value: $apt::params::settings + +##### `auth_conf_entries` + +Data type: `Array[Apt::Auth_conf_entry]` + +An optional array of login configuration settings (hashes) that are 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 value: $apt::params::auth_conf_entries + +##### `root` + +Data type: `String` + +Specifies root directory of Apt executable. + +Default value: $apt::params::root + +##### `sources_list` + +Data type: `String` + +Specifies the path of the sources_list file to use. + +Default value: $apt::params::sources_list + +##### `sources_list_d` + +Data type: `String` + +Specifies the path of the sources_list.d file to use. + +Default value: $apt::params::sources_list_d + +##### `conf_d` + +Data type: `String` + +Specifies the path of the conf.d file to use. + +Default value: $apt::params::conf_d + +##### `preferences` + +Data type: `String` + +Specifies the path of the preferences file to use. + +Default value: $apt::params::preferences + +##### `preferences_d` + +Data type: `String` + +Specifies the path of the preferences.d file to use. + +Default value: $apt::params::preferences_d + +##### `config_files` + +Data type: `Hash` + +A hash made up of the various configuration files used by Apt. + +Default value: $apt::params::config_files + +##### `update_defaults` + +Data type: `Hash` + + + +Default value: $apt::params::update_defaults + +##### `purge_defaults` + +Data type: `Hash` + + + +Default value: $apt::params::purge_defaults + +##### `proxy_defaults` + +Data type: `Hash` + + + +Default value: $apt::params::proxy_defaults + +##### `include_defaults` + +Data type: `Hash` + + + +Default value: $apt::params::include_defaults + +##### `source_key_defaults` + +Data type: `Hash` + + + +Default value: $apt::params::source_key_defaults + +### apt::backports + +Manages backports. + +#### Examples + +##### Set up a backport for linuxmint qiana + +```puppet +apt::backports { 'qiana': + location => 'http://us.archive.ubuntu.com/ubuntu', + release => 'trusty-backports', + repos => 'main universe multiverse restricted', + key => { + id => '630239CC130E1A7FD81A27B140976EAF437D05B5', + server => 'hkps.pool.sks-keyservers.net', + }, +} +``` + +#### Parameters + +The following parameters are available in the `apt::backports` class. + +##### `location` + +Data type: `Optional[String]` + +Specifies an Apt repository containing the backports to manage. Valid options: a string containing a URL. Default value for Debian and +Ubuntu varies: + +- Debian: 'http://deb.debian.org/debian' + +- Ubuntu: 'http://archive.ubuntu.com/ubuntu' + +Default value: `undef` + +##### `release` + +Data type: `Optional[String]` + +Specifies a distribution of the Apt repository containing the backports to manage. 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. + +Default value: `undef` + +##### `repos` + +Data type: `Optional[String]` + +Specifies a component of the Apt repository containing the backports to manage. Used in populating the `source.list` configuration file. +Default value for Debian and Ubuntu varies: + +- Debian: 'main contrib non-free' + +- Ubuntu: 'main universe multiverse restricted' + +Default value: `undef` + +##### `key` + +Data type: `Optional[Variant[String, Hash]]` + +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. Default value +for Debian and Ubuntu varies: + +- Debian: 'A1BD8E9D78F7FE5C3E65D8AF8B48AD6246925553' + +- Ubuntu: '630239CC130E1A7FD81A27B140976EAF437D05B5' + +Default value: `undef` + +##### `pin` + +Data type: `Optional[Variant[Integer, String, Hash]]` + +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 value: 200 + +## Defined types + +### apt::conf + +Specifies a custom Apt configuration file. + +#### Parameters + +The following parameters are available in the `apt::conf` defined type. + +##### `content` + +Data type: `Optional[String]` + +Required unless `ensure` is set to 'absent'. Directly supplies content for the configuration file. + +Default value: `undef` + +##### `ensure` + +Data type: `Enum['present', 'absent']` + +Specifies whether the configuration file should exist. Valid options: 'present' and 'absent'. + +Default value: present + +##### `priority` + +Data type: `Variant[String, Integer]` + +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 or an integer. + +Default value: 50 + +##### `notify_update` + +Data type: `Optional[Boolean]` + +Specifies whether to trigger an `apt-get update` run. + +Default value: `undef` + +### apt::key + +Manages the GPG keys that Apt uses to authenticate packages. + +* **Note** The apt::key defined type makes use of the apt_key type, but includes extra functionality to help prevent duplicate keys. + +#### Examples + +##### Declare Apt key for apt.puppetlabs.com source + +```puppet +apt::key { 'puppetlabs': + id => '6F6B15509CF8E59E6E469F327F438280EF8D349F', + server => 'hkps.pool.sks-keyservers.net', + options => 'http-proxy="http://proxyuser:proxypass@example.org:3128"', +} +``` + +#### Parameters + +The following parameters are available in the `apt::key` defined type. + +##### `id` + +Data type: `String` + +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 value: $title + +##### `ensure` + +Data type: `Enum['present', 'absent']` + +Specifies whether the key should exist. Valid options: 'present' and 'absent'. + +Default value: present + +##### `content` + +Data type: `Optional[String]` + +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. + +Default value: `undef` + +##### `source` + +Data type: `Optional[String]` + +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 value: `undef` + +##### `server` + +Data type: `String` + +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 value: $::apt::keyserver + +##### `options` + +Data type: `Optional[String]` + +Passes additional options to `apt-key adv --keyserver-options`. + +Default value: `undef` + +### apt::pin + +Manages Apt pins. Does not trigger an apt-get update run. + +* **See also** +http://linux.die.net/man/5/apt_preferences +for context on these parameters + +#### Parameters + +The following parameters are available in the `apt::pin` defined type. + +##### `ensure` + +Data type: `Optional[Enum['file', 'present', 'absent']]` + +Specifies whether the pin should exist. Valid options: 'file', 'present', and 'absent'. + +Default value: present + +##### `explanation` + +Data type: `Optional[String]` + +Supplies a comment to explain the pin. Default: "${caller_module_name}: ${name}". + +Default value: `undef` + +##### `order` + +Data type: `Variant[Integer]` + +Determines the order in which Apt processes the pin file. Files with lower order numbers are loaded first. + +Default value: 50 + +##### `packages` + +Data type: `Variant[String, Array]` + +Specifies which package(s) to pin. + +Default value: '*' + +##### `priority` + +Data type: `Variant[Numeric, String]` + +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 value: 0 + +##### `release` + +Data type: `Optional[String]` + +Tells APT to prefer packages that support the specified release. Typical values include 'stable', 'testing', and 'unstable'. + +Default value: '' + +##### `release_version` + +Data type: `Optional[String]` + +Tells APT to prefer packages that support the specified operating system release version (such as Debian release version 7). + +Default value: '' + +##### `component` + +Data type: `Optional[String]` + +Names the licensing component associated with the packages in the directory tree of the Release file. + +Default value: '' + +##### `originator` + +Data type: `Optional[String]` + +Names the originator of the packages in the directory tree of the Release file. + +Default value: '' + +##### `label` + +Data type: `Optional[String]` + +Names the label of the packages in the directory tree of the Release file. + +Default value: '' + +##### `origin` + +Data type: `Optional[String]` + + + +Default value: '' + +##### `version` + +Data type: `Optional[String]` + + + +Default value: '' + +##### `codename` + +Data type: `Optional[String]` + + + +Default value: '' + +### apt::ppa + +Manages PPA repositories using `add-apt-repository`. Not supported on Debian. + +#### Examples + +##### Example declaration of an Apt PPA + +```puppet +apt::ppa{ 'ppa:openstack-ppa/bleeding-edge': } +``` + +#### Parameters + +The following parameters are available in the `apt::ppa` defined type. + +##### `ensure` + +Data type: `String` + +Specifies whether the PPA should exist. Valid options: 'present' and 'absent'. + +Default value: 'present' + +##### `options` + +Data type: `Optional[String]` + +Supplies options to be passed to the `add-apt-repository` command. Default: '-y'. + +Default value: $::apt::ppa_options + +##### `release` + +Data type: `Optional[String]` + +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 value: $facts['lsbdistcodename'] + +##### `package_name` + +Data type: `Optional[String]` + +Names the package that provides the `apt-add-repository` command. Default: 'software-properties-common'. + +Default value: $::apt::ppa_package + +##### `package_manage` + +Data type: `Boolean` + +Specifies whether Puppet should manage the package that provides `apt-add-repository`. + +Default value: `false` + +### apt::setting + +Manages Apt configuration files. + +* **See also** +https://docs.puppetlabs.com/references/latest/type.html#file-attributes +for more information on source and content parameters + +#### Parameters + +The following parameters are available in the `apt::setting` defined type. + +##### `priority` + +Data type: `Variant[String, Integer, Array]` + +Determines the order in which Apt processes the configuration file. Files with higher priority numbers are loaded first. + +Default value: 50 + +##### `ensure` + +Data type: `Optional[Enum['file', 'present', 'absent']]` + +Specifies whether the file should exist. Valid options: 'present', 'absent', and 'file'. + +Default value: file + +##### `source` + +Data type: `Optional[String]` + +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 link above for Puppet's native file type source attribute. + +Default value: `undef` + +##### `content` + +Data type: `Optional[String]` + +Required, unless `source` is set. Directly supplies content for the configuration file. Cannot be used in combination with `source`. Valid +options: see link above for Puppet's native file type content attribute. + +Default value: `undef` + +##### `notify_update` + +Data type: `Boolean` + +Specifies whether to trigger an `apt-get update` run. + +Default value: `true` + +### apt::source + +Manages the Apt sources in /etc/apt/sources.list.d/. + +#### Examples + +##### Install the puppetlabs apt source + +```puppet +apt::source { 'puppetlabs': + location => 'http://apt.puppetlabs.com', + repos => 'main', + key => { + id => '6F6B15509CF8E59E6E469F327F438280EF8D349F', + server => 'hkps.pool.sks-keyservers.net', + }, +} +``` + +#### Parameters + +The following parameters are available in the `apt::source` defined type. + +##### `location` + +Data type: `Optional[String]` + +Required, unless ensure is set to 'absent'. Specifies an Apt repository. Valid options: a string containing a repository URL. + +Default value: `undef` + +##### `comment` + +Data type: `String` + +Supplies a comment for adding to the Apt source file. + +Default value: $name + +##### `ensure` + +Data type: `String` + +Specifies whether the Apt source file should exist. Valid options: 'present' and 'absent'. + +Default value: present + +##### `release` + +Data type: `Optional[String]` + +Specifies a distribution of the Apt repository. + +Default value: `undef` + +##### `repos` + +Data type: `String` + +Specifies a component of the Apt repository. + +Default value: 'main' + +##### `include` + +Data type: `Optional[Variant[Hash]]` + +Configures include options. Valid options: a hash of available keys. + +Options: + +* **:deb** `Boolean`: Specifies whether to request the distribution's compiled binaries. Default true. +* **:src** `Boolean`: Specifies whether to request the distribution's uncompiled source code. Default false. + +Default value: {} + +##### `key` + +Data type: `Optional[Variant[String, Hash]]` + +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 value: `undef` + +##### `pin` + +Data type: `Optional[Variant[Hash, Numeric, String]]` + +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 value: `undef` + +##### `architecture` + +Data type: `Optional[String]` + +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). + +Default value: `undef` + +##### `allow_unsigned` + +Data type: `Boolean` + +Specifies whether to authenticate packages from this release, even if the Release file is not signed or the signature can't be checked. + +Default value: `false` + +##### `notify_update` + +Data type: `Boolean` + +Specifies whether to trigger an `apt-get update` run. + +Default value: `true` + +## Resource types + +## Tasks + +### init + +Allows you to perform apt functions + +**Supports noop?** false + +#### Parameters + +##### `action` + +Data type: `Enum[update, upgrade]` + +Action to perform + diff --git a/lib/facter/apt_updates.rb b/lib/facter/apt_updates.rb index cf7d12f..7a701c1 100644 --- a/lib/facter/apt_updates.rb +++ b/lib/facter/apt_updates.rb @@ -1,6 +1,9 @@ apt_package_updates = nil apt_dist_updates = nil +# Executes the upgrading of packages +# @param +# upgrade_option Type of upgrade passed into apt-get command arguments i.e. 'upgrade' or 'dist-upgrade' def get_updates(upgrade_option) apt_updates = nil if File.executable?('/usr/bin/apt-get') diff --git a/lib/puppet/provider/apt_key/apt_key.rb b/lib/puppet/provider/apt_key/apt_key.rb index fc0d206..1e54f3c 100644 --- a/lib/puppet/provider/apt_key/apt_key.rb +++ b/lib/puppet/provider/apt_key/apt_key.rb @@ -11,6 +11,8 @@ if RUBY_VERSION == '1.8.7' end Puppet::Type.type(:apt_key).provide(:apt_key) do + desc 'apt-key provider for apt_key resource' + confine osfamily: :debian defaultfor osfamily: :debian commands apt_key: 'apt-key' diff --git a/lib/puppet/type/apt_key.rb b/lib/puppet/type/apt_key.rb index d8b224f..c44aca0 100644 --- a/lib/puppet/type/apt_key.rb +++ b/lib/puppet/type/apt_key.rb @@ -6,14 +6,17 @@ Puppet::Type.newtype(:apt_key) do by apt to perform package validation. Apt has it's own GPG keyring that can be manipulated through the `apt-key` command. - apt_key { '6F6B15509CF8E59E6E469F327F438280EF8D349F': - source => 'http://apt.puppetlabs.com/pubkey.gpg' - } + @example Basic usage + apt_key { '6F6B15509CF8E59E6E469F327F438280EF8D349F': + source => 'http://apt.puppetlabs.com/pubkey.gpg' + } - **Autorequires**: + **Autorequires** If Puppet is given the location of a key file which looks like an absolute path this type will autorequire that file. + + @api private MANIFEST ensurable diff --git a/manifests/backports.pp b/manifests/backports.pp index 6a7e87c..a93e14f 100644 --- a/manifests/backports.pp +++ b/manifests/backports.pp @@ -1,4 +1,50 @@ -# Defining backports for the apt class +# @summary Manages backports. +# +# @example Set up a backport for linuxmint qiana +# apt::backports { 'qiana': +# location => 'http://us.archive.ubuntu.com/ubuntu', +# release => 'trusty-backports', +# repos => 'main universe multiverse restricted', +# key => { +# id => '630239CC130E1A7FD81A27B140976EAF437D05B5', +# server => 'hkps.pool.sks-keyservers.net', +# }, +# } +# +# @param location +# Specifies an Apt repository containing the backports to manage. Valid options: a string containing a URL. Default value for Debian and +# Ubuntu varies: +# +# - Debian: 'http://deb.debian.org/debian' +# +# - Ubuntu: 'http://archive.ubuntu.com/ubuntu' +# +# @param release +# Specifies a distribution of the Apt repository containing the backports to manage. 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. +# +# @param repos +# Specifies a component of the Apt repository containing the backports to manage. Used in populating the `source.list` configuration file. +# Default value for Debian and Ubuntu varies: +# +# - Debian: 'main contrib non-free' +# +# - Ubuntu: 'main universe multiverse restricted' +# +# @param 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. Default value +# for Debian and Ubuntu varies: +# +# - Debian: 'A1BD8E9D78F7FE5C3E65D8AF8B48AD6246925553' +# +# - Ubuntu: '630239CC130E1A7FD81A27B140976EAF437D05B5' +# +# @param pin +# 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. +# class apt::backports ( Optional[String] $location = undef, Optional[String] $release = undef, diff --git a/manifests/conf.pp b/manifests/conf.pp index b791f85..c27f0c1 100644 --- a/manifests/conf.pp +++ b/manifests/conf.pp @@ -1,4 +1,18 @@ -# Defining apt config +# @summary Specifies a custom Apt configuration file. +# +# @param content +# Required unless `ensure` is set to 'absent'. Directly supplies content for the configuration file. +# +# @param ensure +# Specifies whether the configuration file should exist. Valid options: 'present' and 'absent'. +# +# @param priority +# 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 or an integer. +# +# @param notify_update +# Specifies whether to trigger an `apt-get update` run. +# define apt::conf ( Optional[String] $content = undef, Enum['present', 'absent'] $ensure = present, diff --git a/manifests/init.pp b/manifests/init.pp index 8aa8c6b..ff0d931 100644 --- a/manifests/init.pp +++ b/manifests/init.pp @@ -1,6 +1,112 @@ -# == Class: apt +# @summary Main class, includes all other classes. # -# Manage APT (Advanced Packaging Tool) +# @see https://docs.puppetlabs.com/references/latest/function.html#createresources for the create resource function +# +# @param provider +# Specifies the provider that should be used by apt::update. +# +# @param keyserver +# Specifies a keyserver to provide the GPG key. Valid options: a string containing a domain name or a full URL (http://, https://, or +# hkp://). +# +# @param ppa_options +# Supplies options to be passed to the `add-apt-repository` command. +# +# @param ppa_package +# Names the package that provides the `apt-add-repository` command. +# +# @param backports +# Specifies some of the default parameters used by apt::backports. Valid options: a hash made up from the following keys: +# +# @option backports [String] :location +# See apt::backports for documentation. +# +# @option backports [String] :repos +# See apt::backports for documentation. +# +# @option backports [String] :key +# See apt::backports for documentation. +# +# @param confs +# Creates new `apt::conf` resources. Valid options: a hash to be passed to the create_resources function linked above. +# +# @param update +# Configures various update settings. Valid options: a hash made up from the following keys: +# +# @option update [String] :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'. +# +# @option update [Integer] :loglevel +# Specifies the log level of logs outputted to the console. Default: undef. +# +# @option update [Integer] :timeout +# Specifies how long to wait for the update to complete before canceling it. Valid options: an integer, in seconds. Default: undef. +# +# @option update [Integer] :tries +# Specifies how many times to retry the update after receiving a DNS or HTTP error. Default: undef. +# +# @param purge +# Specifies whether to purge any existing settings that aren't managed by Puppet. Valid options: a hash made up from the following keys: +# +# @option purge [Boolean] :sources.list +# Specifies whether to purge any unmanaged entries from sources.list. Default false. +# +# @option purge [Boolean] :sources.list.d +# Specifies whether to purge any unmanaged entries from sources.list.d. Default false. +# +# @option purge [Boolean] :preferences +# Specifies whether to purge any unmanaged entries from preferences. Default false. +# +# @option purge [Boolean] :preferences.d. +# Specifies whether to purge any unmanaged entries from preferences.d. Default false. +# +# @param proxy +# Configures Apt to connect to a proxy server. Valid options: a hash matching the locally defined type apt::proxy. +# +# @param sources +# Creates new `apt::source` resources. Valid options: a hash to be passed to the create_resources function linked above. +# +# @param keys +# Creates new `apt::key` resources. Valid options: a hash to be passed to the create_resources function linked above. +# +# @param ppas +# Creates new `apt::ppa` resources. Valid options: a hash to be passed to the create_resources function linked above. +# +# @param pins +# Creates new `apt::pin` resources. Valid options: a hash to be passed to the create_resources function linked above. +# +# @param settings +# Creates new `apt::setting` resources. Valid options: a hash to be passed to the create_resources function linked above. +# +# @param auth_conf_entries +# An optional array of login configuration settings (hashes) that are 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. +# +# @param root +# Specifies root directory of Apt executable. +# +# @param sources_list +# Specifies the path of the sources_list file to use. +# +# @param sources_list_d +# Specifies the path of the sources_list.d file to use. +# +# @param conf_d +# Specifies the path of the conf.d file to use. +# +# @param preferences +# Specifies the path of the preferences file to use. +# +# @param preferences_d +# Specifies the path of the preferences.d file to use. +# +# @param config_files +# A hash made up of the various configuration files used by Apt. # class apt ( Hash $update_defaults = $apt::params::update_defaults, @@ -30,7 +136,7 @@ class apt ( String $preferences = $apt::params::preferences, String $preferences_d = $apt::params::preferences_d, Hash $config_files = $apt::params::config_files, - Hash $source_key_defaults = $apt::params::source_key_defaults + Hash $source_key_defaults = $apt::params::source_key_defaults, ) inherits apt::params { if $facts['osfamily'] != 'Debian' { diff --git a/manifests/key.pp b/manifests/key.pp index 1933b3f..cb95b4d 100644 --- a/manifests/key.pp +++ b/manifests/key.pp @@ -1,4 +1,36 @@ -# == Define: apt::key +# @summary Manages the GPG keys that Apt uses to authenticate packages. +# +# @note +# The apt::key defined type makes use of the apt_key type, but includes extra functionality to help prevent duplicate keys. +# +# @example Declare Apt key for apt.puppetlabs.com source +# apt::key { 'puppetlabs': +# id => '6F6B15509CF8E59E6E469F327F438280EF8D349F', +# server => 'hkps.pool.sks-keyservers.net', +# options => 'http-proxy="http://proxyuser:proxypass@example.org:3128"', +# } +# +# @param 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). +# +# @param ensure +# Specifies whether the key should exist. Valid options: 'present' and 'absent'. +# +# @param 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. +# +# @param 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. +# +# @param 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://). +# +# @param options +# Passes additional options to `apt-key adv --keyserver-options`. +# define apt::key ( String $id = $title, Enum['present', 'absent'] $ensure = present, diff --git a/manifests/params.pp b/manifests/params.pp index 479ac12..196bb0e 100644 --- a/manifests/params.pp +++ b/manifests/params.pp @@ -1,4 +1,7 @@ -# Setting params for the module +# @summary Provides defaults for the Apt module parameters. +# +# @api private +# class apt::params { if $::osfamily != 'Debian' { diff --git a/manifests/pin.pp b/manifests/pin.pp index 831d75f..9310653 100644 --- a/manifests/pin.pp +++ b/manifests/pin.pp @@ -1,6 +1,38 @@ -# pin.pp -# pin a release in apt, useful for unstable repositories - +# @summary Manages Apt pins. Does not trigger an apt-get update run. +# +# @see http://linux.die.net/man/5/apt_preferences for context on these parameters +# +# @param ensure +# Specifies whether the pin should exist. Valid options: 'file', 'present', and 'absent'. +# +# @param explanation +# Supplies a comment to explain the pin. Default: "${caller_module_name}: ${name}". +# +# @param order +# Determines the order in which Apt processes the pin file. Files with lower order numbers are loaded first. +# +# @param packages +# Specifies which package(s) to pin. +# +# @param 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. +# +# @param release +# Tells APT to prefer packages that support the specified release. Typical values include 'stable', 'testing', and 'unstable'. +# +# @param release_version +# Tells APT to prefer packages that support the specified operating system release version (such as Debian release version 7). +# +# @param component +# Names the licensing component associated with the packages in the directory tree of the Release file. +# +# @param originator +# Names the originator of the packages in the directory tree of the Release file. +# +# @param label +# Names the label of the packages in the directory tree of the Release file. +# define apt::pin( Optional[Enum['file', 'present', 'absent']] $ensure = present, Optional[String] $explanation = undef, diff --git a/manifests/ppa.pp b/manifests/ppa.pp index 2ed841b..bdc3593 100644 --- a/manifests/ppa.pp +++ b/manifests/ppa.pp @@ -1,4 +1,24 @@ -# ppa.pp +# @summary Manages PPA repositories using `add-apt-repository`. Not supported on Debian. +# +# @example Example declaration of an Apt PPA +# apt::ppa{ 'ppa:openstack-ppa/bleeding-edge': } +# +# @param ensure +# Specifies whether the PPA should exist. Valid options: 'present' and 'absent'. +# +# @param options +# Supplies options to be passed to the `add-apt-repository` command. Default: '-y'. +# +# @param 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. +# +# @param package_name +# Names the package that provides the `apt-add-repository` command. Default: 'software-properties-common'. +# +# @param package_manage +# Specifies whether Puppet should manage the package that provides `apt-add-repository`. +# define apt::ppa( String $ensure = 'present', Optional[String] $options = $::apt::ppa_options, diff --git a/manifests/setting.pp b/manifests/setting.pp index a7b11c4..e743a5c 100644 --- a/manifests/setting.pp +++ b/manifests/setting.pp @@ -1,4 +1,24 @@ -# Defining apt settings +# @summary Manages Apt configuration files. +# +# @see https://docs.puppetlabs.com/references/latest/type.html#file-attributes for more information on source and content parameters +# +# @param priority +# Determines the order in which Apt processes the configuration file. Files with higher priority numbers are loaded first. +# +# @param ensure +# Specifies whether the file should exist. Valid options: 'present', 'absent', and 'file'. +# +# @param 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 link above for Puppet's native file type source attribute. +# +# @param content +# Required, unless `source` is set. Directly supplies content for the configuration file. Cannot be used in combination with `source`. Valid +# options: see link above for Puppet's native file type content attribute. +# +# @param notify_update +# Specifies whether to trigger an `apt-get update` run. +# define apt::setting ( Variant[String, Integer, Array] $priority = 50, Optional[Enum['file', 'present', 'absent']] $ensure = file, diff --git a/manifests/source.pp b/manifests/source.pp index 724f5f3..9ccad35 100644 --- a/manifests/source.pp +++ b/manifests/source.pp @@ -1,5 +1,59 @@ -# source.pp -# add an apt source +# @summary Manages the Apt sources in /etc/apt/sources.list.d/. +# +# @example Install the puppetlabs apt source +# apt::source { 'puppetlabs': +# location => 'http://apt.puppetlabs.com', +# repos => 'main', +# key => { +# id => '6F6B15509CF8E59E6E469F327F438280EF8D349F', +# server => 'hkps.pool.sks-keyservers.net', +# }, +# } +# +# @param location +# Required, unless ensure is set to 'absent'. Specifies an Apt repository. Valid options: a string containing a repository URL. +# +# @param comment +# Supplies a comment for adding to the Apt source file. +# +# @param ensure +# Specifies whether the Apt source file should exist. Valid options: 'present' and 'absent'. +# +# @param release +# Specifies a distribution of the Apt repository. +# +# @param repos +# Specifies a component of the Apt repository. +# +# @param include +# Configures include options. Valid options: a hash of available keys. +# +# @option include [Boolean] :deb +# Specifies whether to request the distribution's compiled binaries. Default true. +# +# @option include [Boolean] :src +# Specifies whether to request the distribution's uncompiled source code. Default false. +# +# @param 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. +# +# @param 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. +# +# @param 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). +# +# @param 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. +# +# @param notify_update +# Specifies whether to trigger an `apt-get update` run. +# define apt::source( Optional[String] $location = undef, String $comment = $name, diff --git a/manifests/update.pp b/manifests/update.pp index 4b05c21..1ea16af 100644 --- a/manifests/update.pp +++ b/manifests/update.pp @@ -1,4 +1,7 @@ -# Defining apt update +# @summary Updates the list of available packages using apt-get update. +# +# @api private +# class apt::update { assert_private() diff --git a/spec/acceptance/apt_key_provider_spec.rb b/spec/acceptance/apt_key_provider_spec.rb index aa78001..de3be33 100644 --- a/spec/acceptance/apt_key_provider_spec.rb +++ b/spec/acceptance/apt_key_provider_spec.rb @@ -27,7 +27,7 @@ end def install_key(key) retry_on_error_matching do - shell("apt-key adv --keyserver hkps.pool.sks-keyservers.net --recv-keys #{key}") + shell("apt-key adv --keyserver pgp.mit.edu --recv-keys #{key}") end end @@ -384,7 +384,7 @@ hkps_pool_pp = <<-MANIFEST apt_key { 'puppetlabs': id => '#{PUPPETLABS_GPG_KEY_LONG_ID}', ensure => 'present', - server => 'hkps.pool.sks-keyservers.net', + server => 'pgp.mit.edu', } MANIFEST @@ -392,7 +392,7 @@ hkp_pool_pp = <<-MANIFEST apt_key { 'puppetlabs': id => '#{PUPPETLABS_GPG_KEY_FINGERPRINT}', ensure => 'present', - server => 'hkp://hkps.pool.sks-keyservers.net:80', + server => 'hkp://pgp.mit.edu:80', } MANIFEST @@ -653,7 +653,7 @@ describe 'apt_key' do end describe 'server =>' do - context 'with hkps.pool.sks-keyservers.net' do + context 'with pgp.mit.edu' do it 'works' do # Apply the manifest (Retry if timeout error is received from key pool) retry_on_error_matching do @@ -665,7 +665,7 @@ describe 'apt_key' do end end - context 'with hkp://hkps.pool.sks-keyservers.net:80' do + context 'with hkp://pgp.mit.edu:80' do it 'works' do retry_on_error_matching do apply_manifest(hkp_pool_pp, catch_failures: true) diff --git a/types/auth_conf_entry.pp b/types/auth_conf_entry.pp index 40648d1..c046276 100644 --- a/types/auth_conf_entry.pp +++ b/types/auth_conf_entry.pp @@ -1 +1,20 @@ -type Apt::Auth_conf_entry = Struct[{ machine => String[1], login => String, password => String }] +# @summary Login configuration settings that are recorded in the file `/etc/apt/auth.conf`. +# +# @see https://manpages.debian.org/testing/apt/apt_auth.conf.5.en.html for more information +# +# @param machine +# Hostname of machine to connect to. +# +# @param login +# Specifies the username to connect with. +# +# @param password +# Specifies the password to connect with. +# +type Apt::Auth_conf_entry = Struct[ + { + machine => String[1], + login => String, + password => String + } +] diff --git a/types/proxy.pp b/types/proxy.pp index 297bf1b..0aae395 100644 --- a/types/proxy.pp +++ b/types/proxy.pp @@ -1,3 +1,20 @@ +# @summary Configures Apt to connect to a proxy server. +# +# @param ensure +# Specifies whether the proxy should exist. Valid options: 'file', 'present', and 'absent'. Prefer 'file' over 'present'. +# +# @param host +# Specifies a proxy host to be stored in `/etc/apt/apt.conf.d/01proxy`. Valid options: a string containing a hostname. +# +# @param port +# Specifies a proxy port to be stored in `/etc/apt/apt.conf.d/01proxy`. Valid options: an integer containing a port number. +# +# @param https +# Specifies whether to enable https proxies. +# +# @param direct +# Specifies whether or not to use a `DIRECT` https proxy if http proxy is used but https is not. +# type Apt::Proxy = Struct[ { ensure => Optional[Enum['file', 'present', 'absent']],