X-Git-Url: https://review.fuel-infra.org/gitweb?a=blobdiff_plain;ds=sidebyside;f=README.md;fp=README.md;h=78e43b16fa2ad1861a294944b82ad3c4a10e7669;hb=6c1fd8e819cc8ffb44ac187bb0fa7051d2958cc6;hp=a62b7b512660154a5e11bb3d7983140d72ca7369;hpb=0cfcadeee5cc86c577756adf812822214af4d37f;p=puppet-modules%2Fpuppetlabs-apt.git 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