From d7c9feda05bd4bfa3002deb0ba55939c69b1d910 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Louis-Philippe=20V=C3=A9ronneau?= Date: Wed, 27 Apr 2016 14:28:47 -0400 Subject: [PATCH 1/9] README is now markdown --- README | 593 --------------------------------------------------------- 1 file changed, 593 deletions(-) delete mode 100644 README diff --git a/README b/README deleted file mode 100644 index e097a7e..0000000 --- a/README +++ /dev/null @@ -1,593 +0,0 @@ - -Overview -======== - -This module manages apt on Debian. - -It keeps dpkg's and apt's databases as well as the keyrings for securing -package download current. - -backports.debian.org is added. - -/etc/apt/sources.list and /etc/apt/preferences are managed. More -recent Debian releases are pinned to very low values by default to -prevent accidental upgrades. - -Ubuntu support is lagging behind but not absent either. - -! Upgrade Notice ! - - * The `disable_update` parameter has been removed. The main apt class - defaults to *not* run an `apt-get update` on every run anyway so this - parameter seems useless. - You can include the `apt::update` class if you want it to be run every time. - - * The `apt::upgrade_package` now doesn't automatically call an Exec['apt_updated'] - anymore, so you would need to include `apt::update` now by hand. - - * The apt::codename parameter has been removed. In its place, the - debian_codename fact may be overridden via an environment variable. This - will affect all other debian_* facts, and achieve the same result. - - FACTER_debian_codename=jessie puppet agent -t - - * If you were using custom 50unattended-upgrades.${::lsbdistcodename} in your - site_apt, these are no longer supported. You should migrate to passing - $blacklisted_packages to the apt::unattended_upgrades class. - - * the apt class has been moved to a paramterized class. if you were including - this class before, after passing some variables, you will need to move to - instantiating the class with those variables instead. For example, if you - had the following in your manifests: - - $apt_debian_url = 'http://localhost:9999/debian/' - $apt_use_next_release = true - include apt - - you will need to remove the variables, and the include and instead do - the following: - - class { 'apt': debian_url => 'http://localhost:9999/debian/', use_next_release => true } - - previously, you could manually set $lsbdistcodename which would enable forced - upgrades, but because this is a top-level facter variable, and newer puppet - versions do not let you assign variables to other namespaces, this is no - longer possible. However, there is a way to obtain this functionality, and - that is to pass the 'codename' parameter to the apt class, which will change - the sources.list and preferences files to be the codename you set, allowing - you to trigger upgrades: - - include apt::dist_upgrade - class { 'apt': codename => 'wheezy', notify => Exec['apt_dist-upgrade'] } - - * the apticron class has been moved to a parameterized class. if you were - including this class before, you will need to move to instantiating the - class instead. For example, if you had the following in your manifests: - - $apticron_email = 'foo@example.com' - $apticron_notifynew = '1' - ... any $apticron_* variables - include apticron - - you will need to remove the variables, and the include and instead do the - following: - - class { 'apt::apticron': email => 'foo@example.com', notifynew => '1' } - - * the apt::listchanges class has been moved to a paramterized class. if you - were including this class before, after passing some variables, you will need - to move to instantiating the class with those variables instead. For example, - if you had the following in your manifests: - - $apt_listchanges_email = 'foo@example.com' - ... any $apt_listchanges_* variables - include apt::listchanges - - you will need to remove the variables, and the include and instead do the - following: - - class { 'apt::listchanges': email => 'foo@example.com' } - - * the apt::proxy_client class has been moved to a paramterized class. if you - were including this class before, after passing some variables, you will need - to move to instantiating the class with those variables instead. For example, - if you had the following in your manifests: - - $apt_proxy = 'http://proxy.domain' - $apt_proxy_port = 666 - include apt::proxy_client - - you will need to remove the variables, and the include and instead do the - following: - - class { 'apt::proxy_client': proxy => 'http://proxy.domain', port => '666' } - -Requirements -============ - -This module needs: - -- the lsb-release package should be installed on the server prior to running - puppet. otherwise, all of the $::lsb* facts will be empty during runs. -- the common module: https://gitlab.com/shared-puppet-modules-group/common - -By default, on normal hosts, this module sets the configuration option -DSelect::Clean to 'auto'. On virtual servers, the value is set by default to -'pre-auto', because virtual servers are usually more space-bound and have better -recovery mechanisms via the host: - -From apt.conf(5), 0.7.2: - "Cache Clean mode; this value may be one of always, prompt, auto, - pre-auto and never. always and prompt will remove all packages - from the cache after upgrading, prompt (the default) does so - conditionally. auto removes only those packages which are no - longer downloadable (replaced with a new version for - instance). pre-auto performs this action before downloading new - packages." - -To change the default setting for DSelect::Clean, you can create a file named -"03clean" or "03clean_vserver" in your site_apt module's files directory. You -can also define this for a specific host by creating a file in a subdirectory of -the site_apt modules' files directory that is named the same as the -host. (example: site_apt/files/some.host.com/03clean, or -site_apt/files/some.host.com/03clean_vserver) - -Classes -======= - -apt ---- - -The apt class sets up most of the documented functionality. To use functionality -that is not enabled by default, you must set one of the following parameters. - -Example usage: - - class { 'apt': use_next_release => true, debian_url => 'http://localhost:9999/debian/' } - -Class parameters: - -* use_lts - - If this variable is set to true the CODENAME-lts sources (such as - squeeze-lts) are added. - - By default this is false for backward compatibility with older - versions of this module. - -* use_volatile - - If this variable is set to true the CODENAME-updates sources (such as - squeeze-updates) are added. - - By default this is false for backward compatibility with older - versions of this module. - -* include_src - - If this variable is set to true a deb-src source is added for every - added binary archive source. - - By default this is false for backward compatibility with older - versions of this module. - -* use_next_release - - If this variable is set to true the sources for the next Debian - release are added. The default pinning configuration pins it to very - low values. - - By default this is false for backward compatibility with older - versions of this module. - -* debian_url, security_url, backports_url, volatile_url - - These variables allow to override the default APT mirrors respectively - used for the standard Debian archives, the Debian security archive, - the Debian official backports and the Debian Volatile archive. - -* ubuntu_url - - These variables allows to override the default APT mirror used for all - standard Ubuntu archives (including updates, security, backports). - -* repos - - If this variable is set the default repositories list ("main contrib non-free") - is overriden. - -* custom_preferences - - For historical reasons (Debian Lenny's version of APT did not support the use - of the preferences.d directory for putting fragments of 'preferences'), this - module will manage a default generic apt/preferences file with more - recent releases pinned to very low values so that any package - installation will not accidentally pull in packages from those suites - unless you explicitly specify the version number. This file will be - complemented with all of the preferences_snippet calls (see below). - - If the default preferences template doesn't suit your needs, you can create a - template located in your site_apt module, and set custom_preferences with the - content (eg. custom_preferences => template('site_apt/preferences') ) - - Setting this variable to false before including this class will force the - apt/preferences file to be absent: - - class { 'apt': custom_preferences => false } - -* custom_sources_list - - By default this module will use a basic apt/sources.list template with - a generic Debian mirror. If you need to set more specific sources, - e.g. changing the sections included in the source, etc. you can set - this variable to the content that you desire to use instead. - - For example, setting this variable will pull in the - templates/site_apt/sources.list file: - - class { 'apt': custom_sources_list => template('site_apt/sources.list') } - -* custom_key_dir - - If you have different apt-key files that you want to get added to your - apt keyring, you can set this variable to a path in your fileserver - where individual key files can be placed. If this is set and keys - exist there, this module will 'apt-key add' each key. - - The debian-archive-keyring package is installed and kept current up to the - latest revision (this includes the backports archive keyring). - -apt::apticron -------------- - -When you instantiate this class, apticron will be installed, with the following -defaults, which you are free to change: - - $ensure_version = 'installed', - $config = "apt/${::operatingsystem}/apticron_${::lsbdistcodename}.erb", - $email = 'root', - $diff_only = '1', - $listchanges_profile = 'apticron', - $system = false, - $ipaddressnum = false, - $ipaddresses = false, - $notifyholds = '0', - $notifynew = '0', - $customsubject = '' - -Example usage: - - class { 'apt::apticron': email => 'foo@example.com', notifynew => '1' } - -apt::cron::download -------------------- - -This class sets up cron-apt so that it downloads upgradable packages, does not -actually do any upgrade and emails when the output changes. - -cron-apt defaults to run at 4 AM. You may want to set the -$apt_cron_hours variable before you include the class: its value will -be passed as the "hours" parameter of a cronjob. Example: - - # Run cron-apt every three hours - $apt_cron_hours = '*/3' - -Note that the default 4 AM cronjob won't be disabled. - -apt::cron::dist_upgrade ------------------------ - -This class sets up cron-apt so that it dist-upgrades the system and -emails when upgrades are performed. - -See apt::cron::download above if you need to run cron-apt more often -than once a day. - -apt::dist_upgrade ------------------ - -This class provides the Exec['apt_dist-upgrade'] resource that -dist-upgrade's the system. - -This exec is set as refreshonly so including this class does not -trigger any action per-se: other resources may notify it, other -classes may inherit from this one and add to its subscription list -using the plusignment ('+>') operator. A real-world example can be -seen in the apt::dist_upgrade::initiator source. - -apt::dist_upgrade::initiator ----------------------------- - -This class automatically dist-upgrade's the system when an initiator -file's content changes. The initiator file is copied from the first -available source amongst the following ones, in decreasing priority -order: - -- puppet:///modules/site_apt/${::fqdn}/upgrade_initiator -- puppet:///modules/site_apt/upgrade_initiator -- puppet:///modules/apt/upgrade_initiator - -This is useful when one does not want to setup a fully automated -upgrade process but still needs a way to manually trigger full -upgrades of any number of systems at scheduled times. - -Beware: a dist-upgrade is triggered the first time Puppet runs after -this class has been included. This is actually the single reason why -this class is not enabled by default. - -When this class is included the APT indexes are updated on every -Puppet run due to the author's lack of Puppet wizardry. - -apt::dselect ------------- - -This class, when included, installs dselect and switches it to expert mode to -suppress superfluous help screens. - -apt::listchanges ----------------- - -This class, when instantiated, installs apt-listchanges and configures it using -the following parameterized variables, which can be changed: - - version = 'present' - config = "apt/${::operatingsystem}/listchanges_${::lsbrelease}.erb" - frontend = 'pager' - email = 'root' - confirm = 0 - saveseen = '/var/lib/apt/listchanges.db' - which = 'both' - - Example usage: - class { 'apt::listchanges': email => 'foo@example.com' } - -apt::proxy_client ------------------ - -This class adds the right configuration to apt to make it fetch packages via a -proxy. The class parameters apt_proxy and apt_proxy_port need to be set: - -You can set the 'proxy' class parameter variable to the URL of the proxy that -will be used. By default, the proxy will be queried on port 3142, but you can -change the port number by setting the 'port' class parameter. - -Example: - - class { 'apt::proxy_client': proxy => 'http://proxy.domain', port => '666' } - -apt::reboot_required_notify ---------------------------- - -This class installs a daily cronjob that checks if a package upgrade -requires the system to be rebooted; if so, cron sends a notification -email to root. - -apt::unattended_upgrades ------------------------- - -If this class is included, it will install the package 'unattended-upgrades' -and configure it to daily upgrade the system. - -The class has the following parameters that you can use to change the contents -of the configuration file. The values shown here are the default values: - - * $config_content = undef - * $config_template = 'apt/50unattended-upgrades.erb' - * $mailonlyonerror = true - * $mail_recipient = 'root' - * $blacklisted_packages = [] - -Note that using $config_content actually specifies all of the configuration -contents and thus makes the other parameters useless. - -example: - - class { 'apt::unattended_upgrades': - config_template => 'site_apt/50unattended-upgrades.jessie', - blacklisted_packages => [ - 'libc6', 'libc6-dev', 'libc6-i686', 'mysql-server', 'redmine', 'nodejs', - 'bird' - ], - } - -Defines -======= - -apt::apt_conf -------------- - -Creates a file in the apt/apt.conf.d directory to easily add configuration -components. One can use either the 'source' meta-parameter to specify a list of -static files to include from the puppet fileserver or the 'content' -meta-parameter to define content inline or with the help of a template. - -Example: - - apt::apt_conf { '80download-only': - source => 'puppet:///modules/site_apt/80download-only', - } - -apt::preferences_snippet ------------------------- - -A way to add pinning information to files in /etc/apt/preferences.d/ - -Example: - - apt::preferences_snippet { - 'irssi-plugin-otr': - release => 'squeeze-backports', - priority => 999; - } - - apt::preferences_snippet { - 'unstable_fallback': - package => '*', - release => 'unstable', - priority => 1; - } - - apt::preferences_snippet { - 'ttdnsd': - pin => 'origin deb.torproject.org', - priority => 999; - } - -The names of the resources will be used as the names of the files in the -preferences.d directory, so you should ensure that resource names follow the -prescribed naming scheme. - -From apt_preferences(5): - Note that the files in the /etc/apt/preferences.d directory are parsed in - alphanumeric ascending order and need to obey the following naming - convention: The files have no or "pref" as filename extension and which - only contain alphanumeric, hyphen (-), underscore (_) and period (.) - characters - otherwise they will be silently ignored. - -apt::preseeded_package ----------------------- - -This simplifies installation of packages for which you wish to preseed the -answers to debconf. For example, if you wish to provide a preseed file for the -locales package, you would place the locales.seed file in -'site_apt/templates/${::lsbdistcodename}/locales.seeds' and then include the -following in your manifest: - - apt::preseeded_package { locales: } - -You can also specify the content of the seed via the content parameter, -for example: - - apt::preseeded_package { 'apticron': - content => 'apticron apticron/notification string root@example.com', - } - -apt::sources_list ------------------ - -Creates a file in the apt/sources.list.d directory to easily add additional apt -sources. One can use either the 'source' meta-parameter to specify a list of -static files to include from the puppet fileserver or the 'content' -meta-parameter to define content inline or with the help of a template. Ending -the resource name in '.list' is optional: it will be automatically added to the -file name if not present in the resource name. - -Example: - - apt::sources_list { 'company_internals': - source => [ "puppet:///modules/site_apt/${::fqdn}/company_internals.list", - 'puppet:///modules/site_apt/company_internals.list' ], - } - -apt::key --------- - -Deploys a secure apt OpenPGP key. This usually accompanies the -sources.list snippets above for third party repositories. For example, -you would do: - - apt::key { 'neurodebian.gpg': - ensure => present, - source => 'puppet:///modules/site_apt/neurodebian.gpg', - } - -This deploys the key in the `/etc/apt/trusted.gpg.d` directory, which -is assumed by secure apt to be binary OpenPGP keys and *not* -"ascii-armored" or "plain text" OpenPGP key material. For the latter, -use `apt::key::plain`. - -The `.gpg` extension is compulsory for `apt` to pickup the key properly. - -apt::key::plain ---------------- - -Deploys a secure apt OpenPGP key. This usually accompanies the -sources.list snippets above for third party repositories. For example, -you would do: - - apt::key::plain { 'neurodebian.asc': - source => 'puppet:///modules/site_apt/neurodebian.asc', - } - -This deploys the key in the `${apt_base_dir}/keys` directory (as -opposed to `$custom_key_dir` which deploys it in `keys.d`). The reason -this exists on top of `$custom_key_dir` is to allow a more -decentralised distribution of those keys, without having all modules -throw their keys in the same directory in the manifests. - -Note that this model does *not* currently allow keys to be removed! -Use `apt::key` instead for a more practical, revokable approach, but -that needs binary keys. - -apt::upgrade_package --------------------- - -This simplifies upgrades for DSA security announcements or point-releases. This -will ensure that the named package is upgraded to the version specified, only if -the package is installed, otherwise nothing happens. If the specified version -is 'latest' (the default), then the package is ensured to be upgraded to the -latest package revision when it becomes available. - -For example, the following upgrades the perl package to version 5.8.8-7etch1 -(if it is installed), it also upgrades the syslog-ng and perl-modules packages -to their latest (also, only if they are installed): - -upgrade_package { 'perl': - version => '5.8.8-7etch1'; - 'syslog-ng': - version => latest; - 'perl-modules': -} - -Resources -========= - -File['apt_config'] ------------------- - -Use this resource to depend on or add to a completed apt configuration - -Exec['apt_updated'] -------------------- - -After this point the APT indexes are up-to-date. -This resource is set to `refreshonly => true` so it is not run on -every puppetrun. To run this every time, you can include the `apt::update` -class. - -This resource is usually used like this to ensure current packages are -installed by Package resources: - - include apt::update - Package { require => Exec['apt_updated'] } - -Note that nodes can be updated once a day by using - - APT::Periodic::Update-Package-Lists "1"; - -in i.e. /etc/apt/apt.conf.d/80_apt_update_daily. - - -Tests -===== - -To run pupept rspec tests: - - bundle install --path vendor/bundle - bundle exec rake spec - -Using different facter/puppet versions: - - FACTER_GEM_VERSION=1.6.10 PUPPET_GEM_VERSION=2.7.23 bundle install --path vendor/bundle - bundle exec rake spec - -Licensing -========= - -This puppet module is licensed under the GPL version 3 or later. Redistribution -and modification is encouraged. - -The GPL version 3 license text can be found in the "LICENSE" file accompanying -this puppet module, or at the following URL: - -http://www.gnu.org/licenses/gpl-3.0.html From fca9b745eabb3d85ed4b53b61654ced1e5cd342f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Louis-Philippe=20V=C3=A9ronneau?= Date: Wed, 27 Apr 2016 14:29:00 -0400 Subject: [PATCH 2/9] README is now markdown --- README.md | 620 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 620 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..f9ab19a --- /dev/null +++ b/README.md @@ -0,0 +1,620 @@ +# apt module + +#### Table of Contents + +* [Overview](#overview) + * [Upgrade Notice](#upgrade-notice) +* [Requirements](#requirements) +* [Classes](#classes) + * [apt](#apt) + * [apt::apticron](#apt-apticron) + * [apt::cron::download](#apt-cron-download) + * [apt::cron::dist_upgrade](#apt-cron-dist_upgrade) + * [apt::dist_upgrade](#apt-dist_upgrade) + * [apt::dist_upgrade::initiator](#apt-dist_upgrade-initiator) + * [apt::dselect](#apt-dselect) + * [apt::listchanges](#apt-listchanges) + * [apt::proxy_client](apt-proxy_client) + * [apt::reboot_required_notify](apt-reboot_required_notify) + * [apt::unattended_upgrades](#apt-unattended_upgrades) +* [Defines](#defines) + * [apt::apt_conf](#apt-apt_conf) + * [apt::preferences_snippet](#apt-preferences_snippet) + * [apt::preseeded_package](#apt-preseeded_package) + * [apt::sources_list](#apt-sources_list) + * [apt::key](#apt-key) + * [apt::key::plain](#apt-key-plain) + * [apt::upgrade_package](#apt-upgrade_package) +* [Resources](#ressources) + * [File\['apt_config'\]](#file-apt_config) + * [Exec\['apt_updated'\]](#exec-apt_updated) +* [Tests](#tests) +* [Licensing](#licensing) + + +# Overview + +This module manages apt on Debian. + +It keeps dpkg's and apt's databases as well as the keyrings for securing +package download current. + +backports.debian.org is added. + +/etc/apt/sources.list and /etc/apt/preferences are managed. More +recent Debian releases are pinned to very low values by default to +prevent accidental upgrades. + +Ubuntu support is lagging behind but not absent either. + +## Upgrade Notice + + * The `disable_update` parameter has been removed. The main apt class + defaults to *not* run an `apt-get update` on every run anyway so this + parameter seems useless. + You can include the `apt::update` class if you want it to be run every time. + + * The `apt::upgrade_package` now doesn't automatically call an Exec['apt_updated'] + anymore, so you would need to include `apt::update` now by hand. + + * The apt::codename parameter has been removed. In its place, the + debian_codename fact may be overridden via an environment variable. This + will affect all other debian_* facts, and achieve the same result. + + FACTER_debian_codename=jessie puppet agent -t + + * If you were using custom 50unattended-upgrades.${::lsbdistcodename} in your + site_apt, these are no longer supported. You should migrate to passing + $blacklisted_packages to the apt::unattended_upgrades class. + + * the apt class has been moved to a paramterized class. if you were including + this class before, after passing some variables, you will need to move to + instantiating the class with those variables instead. For example, if you + had the following in your manifests: + + $apt_debian_url = 'http://localhost:9999/debian/' + $apt_use_next_release = true + include apt + + you will need to remove the variables, and the include and instead do + the following: + + class { 'apt': debian_url => 'http://localhost:9999/debian/', use_next_release => true } + + previously, you could manually set $lsbdistcodename which would enable forced + upgrades, but because this is a top-level facter variable, and newer puppet + versions do not let you assign variables to other namespaces, this is no + longer possible. However, there is a way to obtain this functionality, and + that is to pass the 'codename' parameter to the apt class, which will change + the sources.list and preferences files to be the codename you set, allowing + you to trigger upgrades: + + include apt::dist_upgrade + class { 'apt': codename => 'wheezy', notify => Exec['apt_dist-upgrade'] } + + * the apticron class has been moved to a parameterized class. if you were + including this class before, you will need to move to instantiating the + class instead. For example, if you had the following in your manifests: + + $apticron_email = 'foo@example.com' + $apticron_notifynew = '1' + ... any $apticron_* variables + include apticron + + you will need to remove the variables, and the include and instead do the + following: + + class { 'apt::apticron': email => 'foo@example.com', notifynew => '1' } + + * the apt::listchanges class has been moved to a paramterized class. if you + were including this class before, after passing some variables, you will need + to move to instantiating the class with those variables instead. For example, + if you had the following in your manifests: + + $apt_listchanges_email = 'foo@example.com' + ... any $apt_listchanges_* variables + include apt::listchanges + + you will need to remove the variables, and the include and instead do the + following: + + class { 'apt::listchanges': email => 'foo@example.com' } + + * the apt::proxy_client class has been moved to a paramterized class. if you + were including this class before, after passing some variables, you will need + to move to instantiating the class with those variables instead. For example, + if you had the following in your manifests: + + $apt_proxy = 'http://proxy.domain' + $apt_proxy_port = 666 + include apt::proxy_client + + you will need to remove the variables, and the include and instead do the + following: + + class { 'apt::proxy_client': proxy => 'http://proxy.domain', port => '666' } + + +# Requirements + +This module needs: + +- the lsb-release package should be installed on the server prior to running + puppet. otherwise, all of the $::lsb* facts will be empty during runs. +- the common module: https://gitlab.com/shared-puppet-modules-group/common + +By default, on normal hosts, this module sets the configuration option +DSelect::Clean to 'auto'. On virtual servers, the value is set by default to +'pre-auto', because virtual servers are usually more space-bound and have better +recovery mechanisms via the host: + +From apt.conf(5), 0.7.2: + "Cache Clean mode; this value may be one of always, prompt, auto, + pre-auto and never. always and prompt will remove all packages + from the cache after upgrading, prompt (the default) does so + conditionally. auto removes only those packages which are no + longer downloadable (replaced with a new version for + instance). pre-auto performs this action before downloading new + packages." + +To change the default setting for DSelect::Clean, you can create a file named +"03clean" or "03clean_vserver" in your site_apt module's files directory. You +can also define this for a specific host by creating a file in a subdirectory of +the site_apt modules' files directory that is named the same as the +host. (example: site_apt/files/some.host.com/03clean, or +site_apt/files/some.host.com/03clean_vserver) + + +# Classes + +## apt + +The apt class sets up most of the documented functionality. To use functionality +that is not enabled by default, you must set one of the following parameters. + +Example usage: + + class { 'apt': use_next_release => true, debian_url => 'http://localhost:9999/debian/' } + +Class parameters: + +### use_lts + + If this variable is set to true the CODENAME-lts sources (such as + squeeze-lts) are added. + + By default this is false for backward compatibility with older + versions of this module. + +### use_volatile + + If this variable is set to true the CODENAME-updates sources (such as + squeeze-updates) are added. + + By default this is false for backward compatibility with older + versions of this module. + +### include_src + + If this variable is set to true a deb-src source is added for every + added binary archive source. + + By default this is false for backward compatibility with older + versions of this module. + +### use_next_release + + If this variable is set to true the sources for the next Debian + release are added. The default pinning configuration pins it to very + low values. + + By default this is false for backward compatibility with older + versions of this module. + +### debian_url, security_url, backports_url, volatile_url + + These variables allow to override the default APT mirrors respectively + used for the standard Debian archives, the Debian security archive, + the Debian official backports and the Debian Volatile archive. + +### ubuntu_url + + These variables allows to override the default APT mirror used for all + standard Ubuntu archives (including updates, security, backports). + +### repos + + If this variable is set the default repositories list ("main contrib non-free") + is overriden. + +### custom_preferences + + For historical reasons (Debian Lenny's version of APT did not support the use + of the preferences.d directory for putting fragments of 'preferences'), this + module will manage a default generic apt/preferences file with more + recent releases pinned to very low values so that any package + installation will not accidentally pull in packages from those suites + unless you explicitly specify the version number. This file will be + complemented with all of the preferences_snippet calls (see below). + + If the default preferences template doesn't suit your needs, you can create a + template located in your site_apt module, and set custom_preferences with the + content (eg. custom_preferences => template('site_apt/preferences') ) + + Setting this variable to false before including this class will force the + apt/preferences file to be absent: + + class { 'apt': custom_preferences => false } + +### custom_sources_list + + By default this module will use a basic apt/sources.list template with + a generic Debian mirror. If you need to set more specific sources, + e.g. changing the sections included in the source, etc. you can set + this variable to the content that you desire to use instead. + + For example, setting this variable will pull in the + templates/site_apt/sources.list file: + + class { 'apt': custom_sources_list => template('site_apt/sources.list') } + +### custom_key_dir + + If you have different apt-key files that you want to get added to your + apt keyring, you can set this variable to a path in your fileserver + where individual key files can be placed. If this is set and keys + exist there, this module will 'apt-key add' each key. + + The debian-archive-keyring package is installed and kept current up to the + latest revision (this includes the backports archive keyring). + + +## apt::apticron + +When you instantiate this class, apticron will be installed, with the following +defaults, which you are free to change: + + $ensure_version = 'installed', + $config = "apt/${::operatingsystem}/apticron_${::lsbdistcodename}.erb", + $email = 'root', + $diff_only = '1', + $listchanges_profile = 'apticron', + $system = false, + $ipaddressnum = false, + $ipaddresses = false, + $notifyholds = '0', + $notifynew = '0', + $customsubject = '' + +Example usage: + + class { 'apt::apticron': email => 'foo@example.com', notifynew => '1' } + + +## apt::cron::download + +This class sets up cron-apt so that it downloads upgradable packages, does not +actually do any upgrade and emails when the output changes. + +cron-apt defaults to run at 4 AM. You may want to set the +$apt_cron_hours variable before you include the class: its value will +be passed as the "hours" parameter of a cronjob. Example: + + # Run cron-apt every three hours + $apt_cron_hours = '*/3' + +Note that the default 4 AM cronjob won't be disabled. + + +## apt::cron::dist_upgrade + +This class sets up cron-apt so that it dist-upgrades the system and +emails when upgrades are performed. + +See apt::cron::download above if you need to run cron-apt more often +than once a day. + + +## apt::dist_upgrade + +This class provides the Exec['apt_dist-upgrade'] resource that +dist-upgrade's the system. + +This exec is set as refreshonly so including this class does not +trigger any action per-se: other resources may notify it, other +classes may inherit from this one and add to its subscription list +using the plusignment ('+>') operator. A real-world example can be +seen in the apt::dist_upgrade::initiator source. + + +## apt::dist_upgrade::initiator + +This class automatically dist-upgrade's the system when an initiator +file's content changes. The initiator file is copied from the first +available source amongst the following ones, in decreasing priority +order: + +- puppet:///modules/site_apt/${::fqdn}/upgrade_initiator +- puppet:///modules/site_apt/upgrade_initiator +- puppet:///modules/apt/upgrade_initiator + +This is useful when one does not want to setup a fully automated +upgrade process but still needs a way to manually trigger full +upgrades of any number of systems at scheduled times. + +Beware: a dist-upgrade is triggered the first time Puppet runs after +this class has been included. This is actually the single reason why +this class is not enabled by default. + +When this class is included the APT indexes are updated on every +Puppet run due to the author's lack of Puppet wizardry. + + +## apt::dselect + +This class, when included, installs dselect and switches it to expert mode to +suppress superfluous help screens. + + +## apt::listchanges + +This class, when instantiated, installs apt-listchanges and configures it using +the following parameterized variables, which can be changed: + + version = 'present' + config = "apt/${::operatingsystem}/listchanges_${::lsbrelease}.erb" + frontend = 'pager' + email = 'root' + confirm = 0 + saveseen = '/var/lib/apt/listchanges.db' + which = 'both' + + Example usage: + class { 'apt::listchanges': email => 'foo@example.com' } + + +## apt::proxy_client + +This class adds the right configuration to apt to make it fetch packages via a +proxy. The class parameters apt_proxy and apt_proxy_port need to be set: + +You can set the 'proxy' class parameter variable to the URL of the proxy that +will be used. By default, the proxy will be queried on port 3142, but you can +change the port number by setting the 'port' class parameter. + +Example: + + class { 'apt::proxy_client': proxy => 'http://proxy.domain', port => '666' } + + +## apt::reboot_required_notify + +This class installs a daily cronjob that checks if a package upgrade +requires the system to be rebooted; if so, cron sends a notification +email to root. + + +## apt::unattended_upgrades + +If this class is included, it will install the package 'unattended-upgrades' +and configure it to daily upgrade the system. + +The class has the following parameters that you can use to change the contents +of the configuration file. The values shown here are the default values: + + * $config_content = undef + * $config_template = 'apt/50unattended-upgrades.erb' + * $mailonlyonerror = true + * $mail_recipient = 'root' + * $blacklisted_packages = [] + +Note that using $config_content actually specifies all of the configuration +contents and thus makes the other parameters useless. + +example: + + class { 'apt::unattended_upgrades': + config_template => 'site_apt/50unattended-upgrades.jessie', + blacklisted_packages => [ + 'libc6', 'libc6-dev', 'libc6-i686', 'mysql-server', 'redmine', 'nodejs', + 'bird' + ], + } + + +# Defines + +## apt::apt_conf + +Creates a file in the apt/apt.conf.d directory to easily add configuration +components. One can use either the 'source' meta-parameter to specify a list of +static files to include from the puppet fileserver or the 'content' +meta-parameter to define content inline or with the help of a template. + +Example: + + apt::apt_conf { '80download-only': + source => 'puppet:///modules/site_apt/80download-only', + } + + +## apt::preferences_snippet + +A way to add pinning information to files in /etc/apt/preferences.d/ + +Example: + + apt::preferences_snippet { + 'irssi-plugin-otr': + release => 'squeeze-backports', + priority => 999; + } + + apt::preferences_snippet { + 'unstable_fallback': + package => '*', + release => 'unstable', + priority => 1; + } + + apt::preferences_snippet { + 'ttdnsd': + pin => 'origin deb.torproject.org', + priority => 999; + } + +The names of the resources will be used as the names of the files in the +preferences.d directory, so you should ensure that resource names follow the +prescribed naming scheme. + +From apt_preferences(5): + Note that the files in the /etc/apt/preferences.d directory are parsed in + alphanumeric ascending order and need to obey the following naming + convention: The files have no or "pref" as filename extension and which + only contain alphanumeric, hyphen (-), underscore (_) and period (.) + characters - otherwise they will be silently ignored. + + +## apt::preseeded_package + +This simplifies installation of packages for which you wish to preseed the +answers to debconf. For example, if you wish to provide a preseed file for the +locales package, you would place the locales.seed file in +'site_apt/templates/${::lsbdistcodename}/locales.seeds' and then include the +following in your manifest: + + apt::preseeded_package { locales: } + +You can also specify the content of the seed via the content parameter, +for example: + + apt::preseeded_package { 'apticron': + content => 'apticron apticron/notification string root@example.com', + } + + +## apt::sources_list + +Creates a file in the apt/sources.list.d directory to easily add additional apt +sources. One can use either the 'source' meta-parameter to specify a list of +static files to include from the puppet fileserver or the 'content' +meta-parameter to define content inline or with the help of a template. Ending +the resource name in '.list' is optional: it will be automatically added to the +file name if not present in the resource name. + +Example: + + apt::sources_list { 'company_internals': + source => [ "puppet:///modules/site_apt/${::fqdn}/company_internals.list", + 'puppet:///modules/site_apt/company_internals.list' ], + } + + +## apt::key + +Deploys a secure apt OpenPGP key. This usually accompanies the +sources.list snippets above for third party repositories. For example, +you would do: + + apt::key { 'neurodebian.gpg': + ensure => present, + source => 'puppet:///modules/site_apt/neurodebian.gpg', + } + +This deploys the key in the `/etc/apt/trusted.gpg.d` directory, which +is assumed by secure apt to be binary OpenPGP keys and *not* +"ascii-armored" or "plain text" OpenPGP key material. For the latter, +use `apt::key::plain`. + +The `.gpg` extension is compulsory for `apt` to pickup the key properly. + + +## apt::key::plain + +Deploys a secure apt OpenPGP key. This usually accompanies the +sources.list snippets above for third party repositories. For example, +you would do: + + apt::key::plain { 'neurodebian.asc': + source => 'puppet:///modules/site_apt/neurodebian.asc', + } + +This deploys the key in the `${apt_base_dir}/keys` directory (as +opposed to `$custom_key_dir` which deploys it in `keys.d`). The reason +this exists on top of `$custom_key_dir` is to allow a more +decentralised distribution of those keys, without having all modules +throw their keys in the same directory in the manifests. + +Note that this model does *not* currently allow keys to be removed! +Use `apt::key` instead for a more practical, revokable approach, but +that needs binary keys. + + +## apt::upgrade_package + +This simplifies upgrades for DSA security announcements or point-releases. This +will ensure that the named package is upgraded to the version specified, only if +the package is installed, otherwise nothing happens. If the specified version +is 'latest' (the default), then the package is ensured to be upgraded to the +latest package revision when it becomes available. + +For example, the following upgrades the perl package to version 5.8.8-7etch1 +(if it is installed), it also upgrades the syslog-ng and perl-modules packages +to their latest (also, only if they are installed): + +upgrade_package { 'perl': + version => '5.8.8-7etch1'; + 'syslog-ng': + version => latest; + 'perl-modules': +} + + +# Resources + +## File['apt_config'] + +Use this resource to depend on or add to a completed apt configuration + +## Exec['apt_updated'] + +After this point the APT indexes are up-to-date. +This resource is set to `refreshonly => true` so it is not run on +every puppetrun. To run this every time, you can include the `apt::update` +class. + +This resource is usually used like this to ensure current packages are +installed by Package resources: + + include apt::update + Package { require => Exec['apt_updated'] } + +Note that nodes can be updated once a day by using + + APT::Periodic::Update-Package-Lists "1"; + +in i.e. /etc/apt/apt.conf.d/80_apt_update_daily. + + +# Tests + +To run pupept rspec tests: + + bundle install --path vendor/bundle + bundle exec rake spec + +Using different facter/puppet versions: + + FACTER_GEM_VERSION=1.6.10 PUPPET_GEM_VERSION=2.7.23 bundle install --path vendor/bundle + bundle exec rake spec + + +# Licensing + +This puppet module is licensed under the GPL version 3 or later. Redistribution +and modification is encouraged. + +The GPL version 3 license text can be found in the "LICENSE" file accompanying +this puppet module, or at the following URL: + +http://www.gnu.org/licenses/gpl-3.0.html From 511cd83922b7522f20dcb5ff61c0c600932cea37 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Louis-Philippe=20V=C3=A9ronneau?= Date: Wed, 27 Apr 2016 14:31:20 -0400 Subject: [PATCH 3/9] typo --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index f9ab19a..d700853 100644 --- a/README.md +++ b/README.md @@ -356,7 +356,7 @@ This class, when included, installs dselect and switches it to expert mode to suppress superfluous help screens. -## apt::listchanges +## apt::listchanges This class, when instantiated, installs apt-listchanges and configures it using the following parameterized variables, which can be changed: From cfb1eefa1dd8b651fc03524803ba21b1b1684f91 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Louis-Philippe=20V=C3=A9ronneau?= Date: Wed, 27 Apr 2016 14:33:08 -0400 Subject: [PATCH 4/9] typo (bis) --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index d700853..cac0f65 100644 --- a/README.md +++ b/README.md @@ -14,8 +14,8 @@ * [apt::dist_upgrade::initiator](#apt-dist_upgrade-initiator) * [apt::dselect](#apt-dselect) * [apt::listchanges](#apt-listchanges) - * [apt::proxy_client](apt-proxy_client) - * [apt::reboot_required_notify](apt-reboot_required_notify) + * [apt::proxy_client](#apt-proxy_client) + * [apt::reboot_required_notify](#apt-reboot_required_notify) * [apt::unattended_upgrades](#apt-unattended_upgrades) * [Defines](#defines) * [apt::apt_conf](#apt-apt_conf) From b45d09561e70bcb7429c9a2ecb481fc31ae20814 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Louis-Philippe=20V=C3=A9ronneau?= Date: Wed, 27 Apr 2016 14:38:47 -0400 Subject: [PATCH 5/9] typo (tris?) --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index cac0f65..dce6131 100644 --- a/README.md +++ b/README.md @@ -26,8 +26,8 @@ * [apt::key::plain](#apt-key-plain) * [apt::upgrade_package](#apt-upgrade_package) * [Resources](#ressources) - * [File\['apt_config'\]](#file-apt_config) - * [Exec\['apt_updated'\]](#exec-apt_updated) + * [File\['apt_config'\]](#fileapt_config) + * [Exec\['apt_updated'\]](#execapt_updated) * [Tests](#tests) * [Licensing](#licensing) @@ -529,7 +529,7 @@ use `apt::key::plain`. The `.gpg` extension is compulsory for `apt` to pickup the key properly. -## apt::key::plain +## apt ::key::plain Deploys a secure apt OpenPGP key. This usually accompanies the sources.list snippets above for third party repositories. For example, From ec3bceff10b0227ec3b9db06e6fa410b432116cb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Louis-Philippe=20V=C3=A9ronneau?= Date: Wed, 27 Apr 2016 15:00:35 -0400 Subject: [PATCH 6/9] syntax highlighting --- README.md | 270 +++++++++++++++++++++++++++--------------------------- 1 file changed, 137 insertions(+), 133 deletions(-) diff --git a/README.md b/README.md index dce6131..7151dd1 100644 --- a/README.md +++ b/README.md @@ -41,7 +41,7 @@ package download current. backports.debian.org is added. -/etc/apt/sources.list and /etc/apt/preferences are managed. More +`/etc/apt/sources.list` and `/etc/apt/preferences` are managed. More recent Debian releases are pinned to very low values by default to prevent accidental upgrades. @@ -54,18 +54,18 @@ Ubuntu support is lagging behind but not absent either. parameter seems useless. You can include the `apt::update` class if you want it to be run every time. - * The `apt::upgrade_package` now doesn't automatically call an Exec['apt_updated'] + * The `apt::upgrade_package` now doesn't automatically call an `Exec['apt_updated']` anymore, so you would need to include `apt::update` now by hand. - * The apt::codename parameter has been removed. In its place, the - debian_codename fact may be overridden via an environment variable. This - will affect all other debian_* facts, and achieve the same result. + * The `apt::codename` parameter has been removed. In its place, the + `debian_codename` fact may be overridden via an environment variable. This + will affect all other `debian_*` facts, and achieve the same result. - FACTER_debian_codename=jessie puppet agent -t + FACTER_debian_codename=jessie puppet agent -t - * If you were using custom 50unattended-upgrades.${::lsbdistcodename} in your - site_apt, these are no longer supported. You should migrate to passing - $blacklisted_packages to the apt::unattended_upgrades class. + * If you were using custom `50unattended-upgrades.${::lsbdistcodename}` in your + `site_apt`, these are no longer supported. You should migrate to passing + `$blacklisted_packages` to the `apt::unattended_upgrades` class. * the apt class has been moved to a paramterized class. if you were including this class before, after passing some variables, you will need to move to @@ -81,18 +81,18 @@ Ubuntu support is lagging behind but not absent either. class { 'apt': debian_url => 'http://localhost:9999/debian/', use_next_release => true } - previously, you could manually set $lsbdistcodename which would enable forced + previously, you could manually set `$lsbdistcodename` which would enable forced upgrades, but because this is a top-level facter variable, and newer puppet versions do not let you assign variables to other namespaces, this is no longer possible. However, there is a way to obtain this functionality, and that is to pass the 'codename' parameter to the apt class, which will change - the sources.list and preferences files to be the codename you set, allowing + the `sources.list` and `preferences` files to be the codename you set, allowing you to trigger upgrades: - include apt::dist_upgrade - class { 'apt': codename => 'wheezy', notify => Exec['apt_dist-upgrade'] } + include apt::dist_upgrade + class { 'apt': codename => 'wheezy', notify => Exec['apt_dist-upgrade'] } - * the apticron class has been moved to a parameterized class. if you were + * the `apticron` class has been moved to a parameterized class. if you were including this class before, you will need to move to instantiating the class instead. For example, if you had the following in your manifests: @@ -106,7 +106,7 @@ Ubuntu support is lagging behind but not absent either. class { 'apt::apticron': email => 'foo@example.com', notifynew => '1' } - * the apt::listchanges class has been moved to a paramterized class. if you + * the `apt::listchanges` class has been moved to a paramterized class. if you were including this class before, after passing some variables, you will need to move to instantiating the class with those variables instead. For example, if you had the following in your manifests: @@ -120,7 +120,7 @@ Ubuntu support is lagging behind but not absent either. class { 'apt::listchanges': email => 'foo@example.com' } - * the apt::proxy_client class has been moved to a paramterized class. if you + * the `apt::proxy_client` class has been moved to a paramterized class. if you were including this class before, after passing some variables, you will need to move to instantiating the class with those variables instead. For example, if you had the following in your manifests: @@ -139,12 +139,13 @@ Ubuntu support is lagging behind but not absent either. This module needs: -- the lsb-release package should be installed on the server prior to running - puppet. otherwise, all of the $::lsb* facts will be empty during runs. -- the common module: https://gitlab.com/shared-puppet-modules-group/common + * the `lsb-release` package should be installed on the server prior to running + puppet. otherwise, all of the `$::lsb*` facts will be empty during runs. + + * the [common module](https://gitlab.com/shared-puppet-modules-group/common) By default, on normal hosts, this module sets the configuration option -DSelect::Clean to 'auto'. On virtual servers, the value is set by default to +`DSelect::Clean` to 'auto'. On virtual servers, the value is set by default to 'pre-auto', because virtual servers are usually more space-bound and have better recovery mechanisms via the host: @@ -157,10 +158,10 @@ From apt.conf(5), 0.7.2: instance). pre-auto performs this action before downloading new packages." -To change the default setting for DSelect::Clean, you can create a file named -"03clean" or "03clean_vserver" in your site_apt module's files directory. You +To change the default setting for `DSelect::Clean`, you can create a file named +"03clean" or "03clean_vserver" in your `site_apt` module's files directory. You can also define this for a specific host by creating a file in a subdirectory of -the site_apt modules' files directory that is named the same as the +the `site_apt` modules' files directory that is named the same as the host. (example: site_apt/files/some.host.com/03clean, or site_apt/files/some.host.com/03clean_vserver) @@ -174,7 +175,7 @@ that is not enabled by default, you must set one of the following parameters. Example usage: - class { 'apt': use_next_release => true, debian_url => 'http://localhost:9999/debian/' } + class { 'apt': use_next_release => true, debian_url => 'http://localhost:9999/debian/' } Class parameters: @@ -230,7 +231,7 @@ Class parameters: ### custom_preferences For historical reasons (Debian Lenny's version of APT did not support the use - of the preferences.d directory for putting fragments of 'preferences'), this + of the `preferences.d` directory for putting fragments of 'preferences'), this module will manage a default generic apt/preferences file with more recent releases pinned to very low values so that any package installation will not accidentally pull in packages from those suites @@ -238,32 +239,32 @@ Class parameters: complemented with all of the preferences_snippet calls (see below). If the default preferences template doesn't suit your needs, you can create a - template located in your site_apt module, and set custom_preferences with the + template located in your `site_apt` module, and set custom_preferences with the content (eg. custom_preferences => template('site_apt/preferences') ) Setting this variable to false before including this class will force the - apt/preferences file to be absent: + `apt/preferences` file to be absent: class { 'apt': custom_preferences => false } ### custom_sources_list - By default this module will use a basic apt/sources.list template with + By default this module will use a basic `apt/sources.list` template with a generic Debian mirror. If you need to set more specific sources, e.g. changing the sections included in the source, etc. you can set this variable to the content that you desire to use instead. For example, setting this variable will pull in the - templates/site_apt/sources.list file: + `templates/site_apt/sources.list` file: - class { 'apt': custom_sources_list => template('site_apt/sources.list') } + class { 'apt': custom_sources_list => template('site_apt/sources.list') } ### custom_key_dir If you have different apt-key files that you want to get added to your apt keyring, you can set this variable to a path in your fileserver where individual key files can be placed. If this is set and keys - exist there, this module will 'apt-key add' each key. + exist there, this module will `apt-key add` each key. The debian-archive-keyring package is installed and kept current up to the latest revision (this includes the backports archive keyring). @@ -274,34 +275,34 @@ Class parameters: When you instantiate this class, apticron will be installed, with the following defaults, which you are free to change: - $ensure_version = 'installed', - $config = "apt/${::operatingsystem}/apticron_${::lsbdistcodename}.erb", - $email = 'root', - $diff_only = '1', - $listchanges_profile = 'apticron', - $system = false, - $ipaddressnum = false, - $ipaddresses = false, - $notifyholds = '0', - $notifynew = '0', - $customsubject = '' + $ensure_version = 'installed', + $config = "apt/${::operatingsystem}/apticron_${::lsbdistcodename}.erb", + $email = 'root', + $diff_only = '1', + $listchanges_profile = 'apticron', + $system = false, + $ipaddressnum = false, + $ipaddresses = false, + $notifyholds = '0', + $notifynew = '0', + $customsubject = '' Example usage: - class { 'apt::apticron': email => 'foo@example.com', notifynew => '1' } + class { 'apt::apticron': email => 'foo@example.com', notifynew => '1' } ## apt::cron::download -This class sets up cron-apt so that it downloads upgradable packages, does not +This class sets up `cron-apt` so that it downloads upgradable packages, does not actually do any upgrade and emails when the output changes. -cron-apt defaults to run at 4 AM. You may want to set the -$apt_cron_hours variable before you include the class: its value will +`cron-apt` defaults to run at 4 AM. You may want to set the +`$apt_cron_hours` variable before you include the class: its value will be passed as the "hours" parameter of a cronjob. Example: - # Run cron-apt every three hours - $apt_cron_hours = '*/3' + # Run cron-apt every three hours + $apt_cron_hours = '*/3' Note that the default 4 AM cronjob won't be disabled. @@ -311,20 +312,20 @@ Note that the default 4 AM cronjob won't be disabled. This class sets up cron-apt so that it dist-upgrades the system and emails when upgrades are performed. -See apt::cron::download above if you need to run cron-apt more often +See [apt::cron::download](#apt-cron-download) above if you need to run `cron-apt` more often than once a day. ## apt::dist_upgrade -This class provides the Exec['apt_dist-upgrade'] resource that +This class provides the `Exec['apt_dist-upgrade']` resource that dist-upgrade's the system. This exec is set as refreshonly so including this class does not trigger any action per-se: other resources may notify it, other classes may inherit from this one and add to its subscription list -using the plusignment ('+>') operator. A real-world example can be -seen in the apt::dist_upgrade::initiator source. +using the plusignment (`+>`) operator. A real-world example can be +seen in the `apt::dist_upgrade::initiator` source. ## apt::dist_upgrade::initiator @@ -334,15 +335,17 @@ file's content changes. The initiator file is copied from the first available source amongst the following ones, in decreasing priority order: -- puppet:///modules/site_apt/${::fqdn}/upgrade_initiator -- puppet:///modules/site_apt/upgrade_initiator -- puppet:///modules/apt/upgrade_initiator + * `puppet:///modules/site_apt/${::fqdn}/upgrade_initiator` + + * `puppet:///modules/site_apt/upgrade_initiator` + + * `puppet:///modules/apt/upgrade_initiator` This is useful when one does not want to setup a fully automated upgrade process but still needs a way to manually trigger full upgrades of any number of systems at scheduled times. -Beware: a dist-upgrade is triggered the first time Puppet runs after +**Beware:** a `dist-upgrade` is triggered the first time Puppet runs after this class has been included. This is actually the single reason why this class is not enabled by default. @@ -358,33 +361,34 @@ suppress superfluous help screens. ## apt::listchanges -This class, when instantiated, installs apt-listchanges and configures it using +This class, when instantiated, installs `apt-listchanges` and configures it using the following parameterized variables, which can be changed: - version = 'present' - config = "apt/${::operatingsystem}/listchanges_${::lsbrelease}.erb" - frontend = 'pager' - email = 'root' - confirm = 0 - saveseen = '/var/lib/apt/listchanges.db' - which = 'both' + version = 'present' + config = "apt/${::operatingsystem}/listchanges_${::lsbrelease}.erb" + frontend = 'pager' + email = 'root' + confirm = 0 + saveseen = '/var/lib/apt/listchanges.db' + which = 'both' - Example usage: - class { 'apt::listchanges': email => 'foo@example.com' } +Example usage: + + class { 'apt::listchanges': email => 'foo@example.com' } ## apt::proxy_client This class adds the right configuration to apt to make it fetch packages via a -proxy. The class parameters apt_proxy and apt_proxy_port need to be set: +proxy. The class parameters `apt_proxy` and `apt_proxy_port` need to be set: -You can set the 'proxy' class parameter variable to the URL of the proxy that +You can set the `proxy` class parameter variable to the URL of the proxy that will be used. By default, the proxy will be queried on port 3142, but you can -change the port number by setting the 'port' class parameter. +change the port number by setting the `port` class parameter. -Example: +Example usage: - class { 'apt::proxy_client': proxy => 'http://proxy.domain', port => '666' } + class { 'apt::proxy_client': proxy => 'http://proxy.domain', port => '666' } ## apt::reboot_required_notify @@ -396,22 +400,22 @@ email to root. ## apt::unattended_upgrades -If this class is included, it will install the package 'unattended-upgrades' +If this class is included, it will install the package `unattended-upgrades` and configure it to daily upgrade the system. The class has the following parameters that you can use to change the contents of the configuration file. The values shown here are the default values: - * $config_content = undef - * $config_template = 'apt/50unattended-upgrades.erb' - * $mailonlyonerror = true - * $mail_recipient = 'root' - * $blacklisted_packages = [] + $config_content = undef + $config_template = 'apt/50unattended-upgrades.erb' + $mailonlyonerror = true + $mail_recipient = 'root' + $blacklisted_packages = [] -Note that using $config_content actually specifies all of the configuration +Note that using `$config_content` actually specifies all of the configuration contents and thus makes the other parameters useless. -example: +Example usage: class { 'apt::unattended_upgrades': config_template => 'site_apt/50unattended-upgrades.jessie', @@ -426,42 +430,42 @@ example: ## apt::apt_conf -Creates a file in the apt/apt.conf.d directory to easily add configuration -components. One can use either the 'source' meta-parameter to specify a list of -static files to include from the puppet fileserver or the 'content' +Creates a file in the `apt/apt.conf.d` directory to easily add configuration +components. One can use either the `source` meta-parameter to specify a list of +static files to include from the puppet fileserver or the `content` meta-parameter to define content inline or with the help of a template. -Example: +Example usage: - apt::apt_conf { '80download-only': - source => 'puppet:///modules/site_apt/80download-only', - } + apt::apt_conf { '80download-only': + source => 'puppet:///modules/site_apt/80download-only', + } ## apt::preferences_snippet -A way to add pinning information to files in /etc/apt/preferences.d/ +A way to add pinning information to files in `/etc/apt/preferences.d/` Example: - apt::preferences_snippet { - 'irssi-plugin-otr': - release => 'squeeze-backports', - priority => 999; - } + apt::preferences_snippet { + 'irssi-plugin-otr': + release => 'squeeze-backports', + priority => 999; + } - apt::preferences_snippet { - 'unstable_fallback': - package => '*', - release => 'unstable', - priority => 1; - } + apt::preferences_snippet { + 'unstable_fallback': + package => '*', + release => 'unstable', + priority => 1; + } - apt::preferences_snippet { - 'ttdnsd': - pin => 'origin deb.torproject.org', - priority => 999; - } + apt::preferences_snippet { + 'ttdnsd': + pin => 'origin deb.torproject.org', + priority => 999; + } The names of the resources will be used as the names of the files in the preferences.d directory, so you should ensure that resource names follow the @@ -479,35 +483,35 @@ From apt_preferences(5): This simplifies installation of packages for which you wish to preseed the answers to debconf. For example, if you wish to provide a preseed file for the -locales package, you would place the locales.seed file in -'site_apt/templates/${::lsbdistcodename}/locales.seeds' and then include the +locales package, you would place the `locales.seed` file in +`site_apt/templates/${::lsbdistcodename}/locales.seeds` and then include the following in your manifest: - apt::preseeded_package { locales: } + apt::preseeded_package { locales: } You can also specify the content of the seed via the content parameter, for example: - apt::preseeded_package { 'apticron': - content => 'apticron apticron/notification string root@example.com', - } + apt::preseeded_package { 'apticron': + content => 'apticron apticron/notification string root@example.com', + } ## apt::sources_list -Creates a file in the apt/sources.list.d directory to easily add additional apt -sources. One can use either the 'source' meta-parameter to specify a list of -static files to include from the puppet fileserver or the 'content' +Creates a file in the `apt/sources.list.d` directory to easily add additional apt +sources. One can use either the `source` meta-parameter to specify a list of +static files to include from the puppet fileserver or the `content` meta-parameter to define content inline or with the help of a template. Ending -the resource name in '.list' is optional: it will be automatically added to the +the resource name in `.list` is optional: it will be automatically added to the file name if not present in the resource name. -Example: +Example usage: - apt::sources_list { 'company_internals': - source => [ "puppet:///modules/site_apt/${::fqdn}/company_internals.list", - 'puppet:///modules/site_apt/company_internals.list' ], - } + apt::sources_list { 'company_internals': + source => [ "puppet:///modules/site_apt/${::fqdn}/company_internals.list", + 'puppet:///modules/site_apt/company_internals.list' ], + } ## apt::key @@ -516,10 +520,10 @@ Deploys a secure apt OpenPGP key. This usually accompanies the sources.list snippets above for third party repositories. For example, you would do: - apt::key { 'neurodebian.gpg': - ensure => present, - source => 'puppet:///modules/site_apt/neurodebian.gpg', - } + apt::key { 'neurodebian.gpg': + ensure => present, + source => 'puppet:///modules/site_apt/neurodebian.gpg', + } This deploys the key in the `/etc/apt/trusted.gpg.d` directory, which is assumed by secure apt to be binary OpenPGP keys and *not* @@ -529,15 +533,15 @@ use `apt::key::plain`. The `.gpg` extension is compulsory for `apt` to pickup the key properly. -## apt ::key::plain +## apt:: key::plain Deploys a secure apt OpenPGP key. This usually accompanies the sources.list snippets above for third party repositories. For example, you would do: - apt::key::plain { 'neurodebian.asc': - source => 'puppet:///modules/site_apt/neurodebian.asc', - } + apt::key::plain { 'neurodebian.asc': + source => 'puppet:///modules/site_apt/neurodebian.asc', + } This deploys the key in the `${apt_base_dir}/keys` directory (as opposed to `$custom_key_dir` which deploys it in `keys.d`). The reason @@ -562,12 +566,12 @@ For example, the following upgrades the perl package to version 5.8.8-7etch1 (if it is installed), it also upgrades the syslog-ng and perl-modules packages to their latest (also, only if they are installed): -upgrade_package { 'perl': - version => '5.8.8-7etch1'; - 'syslog-ng': - version => latest; - 'perl-modules': -} + upgrade_package { 'perl': + version => '5.8.8-7etch1'; + 'syslog-ng': + version => latest; + 'perl-modules': + } # Resources @@ -593,7 +597,7 @@ Note that nodes can be updated once a day by using APT::Periodic::Update-Package-Lists "1"; -in i.e. /etc/apt/apt.conf.d/80_apt_update_daily. +in i.e. `/etc/apt/apt.conf.d/80_apt_update_daily`. # Tests From 3abd96bb653e16b229debafe0ac9aff8a0bcbdce Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Louis-Philippe=20V=C3=A9ronneau?= Date: Wed, 27 Apr 2016 15:12:19 -0400 Subject: [PATCH 7/9] use the same code indenting (Puppet's code guideline one) everywhere to uniform --- README.md | 129 +++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 89 insertions(+), 40 deletions(-) diff --git a/README.md b/README.md index 7151dd1..2aea453 100644 --- a/README.md +++ b/README.md @@ -79,7 +79,11 @@ Ubuntu support is lagging behind but not absent either. you will need to remove the variables, and the include and instead do the following: - class { 'apt': debian_url => 'http://localhost:9999/debian/', use_next_release => true } + class { + 'apt': + debian_url => 'http://localhost:9999/debian/', + use_next_release => true; + } previously, you could manually set `$lsbdistcodename` which would enable forced upgrades, but because this is a top-level facter variable, and newer puppet @@ -90,7 +94,11 @@ Ubuntu support is lagging behind but not absent either. you to trigger upgrades: include apt::dist_upgrade - class { 'apt': codename => 'wheezy', notify => Exec['apt_dist-upgrade'] } + class { + 'apt': + codename => 'wheezy', + notify => Exec['apt_dist-upgrade']; + } * the `apticron` class has been moved to a parameterized class. if you were including this class before, you will need to move to instantiating the @@ -104,7 +112,11 @@ Ubuntu support is lagging behind but not absent either. you will need to remove the variables, and the include and instead do the following: - class { 'apt::apticron': email => 'foo@example.com', notifynew => '1' } + class { + 'apt::apticron': + email => 'foo@example.com', + notifynew => '1'; + } * the `apt::listchanges` class has been moved to a paramterized class. if you were including this class before, after passing some variables, you will need @@ -118,7 +130,10 @@ Ubuntu support is lagging behind but not absent either. you will need to remove the variables, and the include and instead do the following: - class { 'apt::listchanges': email => 'foo@example.com' } + class { + 'apt::listchanges': + email => 'foo@example.com'; + } * the `apt::proxy_client` class has been moved to a paramterized class. if you were including this class before, after passing some variables, you will need @@ -132,7 +147,11 @@ Ubuntu support is lagging behind but not absent either. you will need to remove the variables, and the include and instead do the following: - class { 'apt::proxy_client': proxy => 'http://proxy.domain', port => '666' } + class { + 'apt::proxy_client': + proxy => 'http://proxy.domain', + port => '666'; + } # Requirements @@ -175,9 +194,13 @@ that is not enabled by default, you must set one of the following parameters. Example usage: - class { 'apt': use_next_release => true, debian_url => 'http://localhost:9999/debian/' } + class { + 'apt': + use_next_release => true, + debian_url => 'http://localhost:9999/debian/'; + } -Class parameters: +**Class parameters:** ### use_lts @@ -245,7 +268,10 @@ Class parameters: Setting this variable to false before including this class will force the `apt/preferences` file to be absent: - class { 'apt': custom_preferences => false } + class { + 'apt': + custom_preferences => false; + } ### custom_sources_list @@ -257,7 +283,10 @@ Class parameters: For example, setting this variable will pull in the `templates/site_apt/sources.list` file: - class { 'apt': custom_sources_list => template('site_apt/sources.list') } + class { + 'apt': + custom_sources_list => template('site_apt/sources.list'); + } ### custom_key_dir @@ -289,7 +318,11 @@ defaults, which you are free to change: Example usage: - class { 'apt::apticron': email => 'foo@example.com', notifynew => '1' } + class { + 'apt::apticron': + email => 'foo@example.com', + notifynew => '1'; + } ## apt::cron::download @@ -374,7 +407,10 @@ the following parameterized variables, which can be changed: Example usage: - class { 'apt::listchanges': email => 'foo@example.com' } + class { + 'apt::listchanges': + email => 'foo@example.com'; + } ## apt::proxy_client @@ -388,7 +424,11 @@ change the port number by setting the `port` class parameter. Example usage: - class { 'apt::proxy_client': proxy => 'http://proxy.domain', port => '666' } + class { + 'apt::proxy_client': + proxy => 'http://proxy.domain', + port => '666'; + } ## apt::reboot_required_notify @@ -417,12 +457,11 @@ contents and thus makes the other parameters useless. Example usage: - class { 'apt::unattended_upgrades': - config_template => 'site_apt/50unattended-upgrades.jessie', - blacklisted_packages => [ - 'libc6', 'libc6-dev', 'libc6-i686', 'mysql-server', 'redmine', 'nodejs', - 'bird' - ], + class { + 'apt::unattended_upgrades': + config_template => 'site_apt/50unattended-upgrades.jessie', + blacklisted_packages => [ 'libc6', 'libc6-dev', 'libc6-i686', + 'mysql-server', 'redmine', 'nodejs', 'bird' ]; } @@ -437,8 +476,9 @@ meta-parameter to define content inline or with the help of a template. Example usage: - apt::apt_conf { '80download-only': - source => 'puppet:///modules/site_apt/80download-only', + apt::apt_conf { + '80download-only': + source => 'puppet:///modules/site_apt/80download-only'; } @@ -450,20 +490,20 @@ Example: apt::preferences_snippet { 'irssi-plugin-otr': - release => 'squeeze-backports', + release => 'squeeze-backports', priority => 999; } apt::preferences_snippet { 'unstable_fallback': - package => '*', - release => 'unstable', + package => '*', + release => 'unstable', priority => 1; } apt::preferences_snippet { 'ttdnsd': - pin => 'origin deb.torproject.org', + pin => 'origin deb.torproject.org', priority => 999; } @@ -492,8 +532,9 @@ following in your manifest: You can also specify the content of the seed via the content parameter, for example: - apt::preseeded_package { 'apticron': - content => 'apticron apticron/notification string root@example.com', + apt::preseeded_package { + 'apticron': + content => 'apticron apticron/notification string root@example.com'; } @@ -508,9 +549,10 @@ file name if not present in the resource name. Example usage: - apt::sources_list { 'company_internals': - source => [ "puppet:///modules/site_apt/${::fqdn}/company_internals.list", - 'puppet:///modules/site_apt/company_internals.list' ], + apt::sources_list { + 'company_internals': + source => [ "puppet:///modules/site_apt/${::fqdn}/company_internals.list", + 'puppet:///modules/site_apt/company_internals.list' ]; } @@ -520,9 +562,10 @@ Deploys a secure apt OpenPGP key. This usually accompanies the sources.list snippets above for third party repositories. For example, you would do: - apt::key { 'neurodebian.gpg': - ensure => present, - source => 'puppet:///modules/site_apt/neurodebian.gpg', + apt::key { + 'neurodebian.gpg': + ensure => present, + source => 'puppet:///modules/site_apt/neurodebian.gpg'; } This deploys the key in the `/etc/apt/trusted.gpg.d` directory, which @@ -539,8 +582,9 @@ Deploys a secure apt OpenPGP key. This usually accompanies the sources.list snippets above for third party repositories. For example, you would do: - apt::key::plain { 'neurodebian.asc': - source => 'puppet:///modules/site_apt/neurodebian.asc', + apt::key::plain { + 'neurodebian.asc': + source => 'puppet:///modules/site_apt/neurodebian.asc'; } This deploys the key in the `${apt_base_dir}/keys` directory (as @@ -566,11 +610,14 @@ For example, the following upgrades the perl package to version 5.8.8-7etch1 (if it is installed), it also upgrades the syslog-ng and perl-modules packages to their latest (also, only if they are installed): - upgrade_package { 'perl': - version => '5.8.8-7etch1'; - 'syslog-ng': - version => latest; - 'perl-modules': + upgrade_package { + 'perl': + version => '5.8.8-7etch1'; + + 'syslog-ng': + version => latest; + + 'perl-modules': } @@ -591,7 +638,9 @@ This resource is usually used like this to ensure current packages are installed by Package resources: include apt::update - Package { require => Exec['apt_updated'] } + Package { + require => Exec['apt_updated'] + } Note that nodes can be updated once a day by using From bb823a23f84e2fea55bf8b8c3eb47028d0378305 Mon Sep 17 00:00:00 2001 From: Gabriel Filion Date: Mon, 27 Jun 2016 23:47:14 +0200 Subject: [PATCH 8/9] extraneous space in subsection title --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 2aea453..851f7aa 100644 --- a/README.md +++ b/README.md @@ -576,7 +576,7 @@ use `apt::key::plain`. The `.gpg` extension is compulsory for `apt` to pickup the key properly. -## apt:: key::plain +## apt::key::plain Deploys a secure apt OpenPGP key. This usually accompanies the sources.list snippets above for third party repositories. For example, From 5d95c3f5e7d0543d28792a96bb3cd927b265ec71 Mon Sep 17 00:00:00 2001 From: Gabriel Filion Date: Mon, 27 Jun 2016 23:47:43 +0200 Subject: [PATCH 9/9] README: make examples more compact also, use commas instead of semi-colon at the end of resources to use a coding style that makes things more extensible. --- README.md | 102 +++++++++++++++++++++++------------------------------- 1 file changed, 43 insertions(+), 59 deletions(-) diff --git a/README.md b/README.md index 851f7aa..5f6a109 100644 --- a/README.md +++ b/README.md @@ -194,10 +194,9 @@ that is not enabled by default, you must set one of the following parameters. Example usage: - class { - 'apt': - use_next_release => true, - debian_url => 'http://localhost:9999/debian/'; + class { 'apt': + use_next_release => true, + debian_url => 'http://localhost:9999/debian/', } **Class parameters:** @@ -268,9 +267,8 @@ Example usage: Setting this variable to false before including this class will force the `apt/preferences` file to be absent: - class { - 'apt': - custom_preferences => false; + class { 'apt': + custom_preferences => false, } ### custom_sources_list @@ -283,9 +281,8 @@ Example usage: For example, setting this variable will pull in the `templates/site_apt/sources.list` file: - class { - 'apt': - custom_sources_list => template('site_apt/sources.list'); + class { 'apt': + custom_sources_list => template('site_apt/sources.list'), } ### custom_key_dir @@ -318,10 +315,9 @@ defaults, which you are free to change: Example usage: - class { - 'apt::apticron': - email => 'foo@example.com', - notifynew => '1'; + class { 'apt::apticron': + email => 'foo@example.com', + notifynew => '1', } @@ -407,9 +403,8 @@ the following parameterized variables, which can be changed: Example usage: - class { - 'apt::listchanges': - email => 'foo@example.com'; + class { 'apt::listchanges': + email => 'foo@example.com', } @@ -424,10 +419,9 @@ change the port number by setting the `port` class parameter. Example usage: - class { - 'apt::proxy_client': - proxy => 'http://proxy.domain', - port => '666'; + class { 'apt::proxy_client': + proxy => 'http://proxy.domain', + port => '666', } @@ -457,11 +451,10 @@ contents and thus makes the other parameters useless. Example usage: - class { - 'apt::unattended_upgrades': - config_template => 'site_apt/50unattended-upgrades.jessie', - blacklisted_packages => [ 'libc6', 'libc6-dev', 'libc6-i686', - 'mysql-server', 'redmine', 'nodejs', 'bird' ]; + class { 'apt::unattended_upgrades': + config_template => 'site_apt/50unattended-upgrades.jessie', + blacklisted_packages => [ 'libc6', 'libc6-dev', 'libc6-i686', + 'mysql-server', 'redmine', 'nodejs', 'bird' ], } @@ -476,9 +469,8 @@ meta-parameter to define content inline or with the help of a template. Example usage: - apt::apt_conf { - '80download-only': - source => 'puppet:///modules/site_apt/80download-only'; + apt::apt_conf { '80download-only': + source => 'puppet:///modules/site_apt/80download-only', } @@ -486,25 +478,22 @@ Example usage: A way to add pinning information to files in `/etc/apt/preferences.d/` -Example: +Examples: - apt::preferences_snippet { - 'irssi-plugin-otr': - release => 'squeeze-backports', - priority => 999; + apt::preferences_snippet { 'irssi-plugin-otr': + release => 'squeeze-backports', + priority => 999, } - apt::preferences_snippet { - 'unstable_fallback': - package => '*', - release => 'unstable', - priority => 1; + apt::preferences_snippet { 'unstable_fallback': + package => '*', + release => 'unstable', + priority => 1, } - apt::preferences_snippet { - 'ttdnsd': - pin => 'origin deb.torproject.org', - priority => 999; + apt::preferences_snippet { 'ttdnsd': + pin => 'origin deb.torproject.org', + priority => 999, } The names of the resources will be used as the names of the files in the @@ -532,9 +521,8 @@ following in your manifest: You can also specify the content of the seed via the content parameter, for example: - apt::preseeded_package { - 'apticron': - content => 'apticron apticron/notification string root@example.com'; + apt::preseeded_package { 'apticron': + content => 'apticron apticron/notification string root@example.com', } @@ -549,10 +537,9 @@ file name if not present in the resource name. Example usage: - apt::sources_list { - 'company_internals': - source => [ "puppet:///modules/site_apt/${::fqdn}/company_internals.list", - 'puppet:///modules/site_apt/company_internals.list' ]; + apt::sources_list { 'company_internals': + source => [ "puppet:///modules/site_apt/${::fqdn}/company_internals.list", + 'puppet:///modules/site_apt/company_internals.list' ]; } @@ -582,9 +569,8 @@ Deploys a secure apt OpenPGP key. This usually accompanies the sources.list snippets above for third party repositories. For example, you would do: - apt::key::plain { - 'neurodebian.asc': - source => 'puppet:///modules/site_apt/neurodebian.asc'; + apt::key::plain { 'neurodebian.asc': + source => 'puppet:///modules/site_apt/neurodebian.asc'; } This deploys the key in the `${apt_base_dir}/keys` directory (as @@ -612,12 +598,10 @@ to their latest (also, only if they are installed): upgrade_package { 'perl': - version => '5.8.8-7etch1'; - - 'syslog-ng': - version => latest; - - 'perl-modules': + version => '5.8.8-7etch1'; + 'syslog-ng': + version => latest; + 'perl-modules': }