summaryrefslogtreecommitdiff
path: root/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'README.md')
-rw-r--r--README.md673
1 files changed, 673 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..2aea453
--- /dev/null
+++ b/README.md
@@ -0,0 +1,673 @@
+# 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'\]](#fileapt_config)
+ * [Exec\['apt_updated'\]](#execapt_updated)
+* [Tests](#tests)
+* [Licensing](#licensing)
+
+
+# Overview<a name="overview"></a>
+
+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<a name="upgrade-notice"></a>
+
+ * 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<a name="requirements"></a>
+
+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<a name="classes"></a>
+
+## apt<a name="apt"></a>
+
+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<a name="apt-apticron"></a>
+
+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<a name="apt-cron-download"></a>
+
+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<a name="apt-cron-dist_upgrade"></a>
+
+This class sets up cron-apt so that it dist-upgrades the system and
+emails when upgrades are performed.
+
+See [apt::cron::download](#apt-cron-download) above if you need to run `cron-apt` more often
+than once a day.
+
+
+## apt::dist_upgrade<a name="apt-dist_upgrade"></a>
+
+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<a name="apt-dist_upgrade-initiator"></a>
+
+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<a name="apt-dselect"></a>
+
+This class, when included, installs dselect and switches it to expert mode to
+suppress superfluous help screens.
+
+
+## apt::listchanges<a name="apt-listchanges"></a>
+
+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<a name="apt-proxy_client"></a>
+
+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 usage:
+
+ class {
+ 'apt::proxy_client':
+ proxy => 'http://proxy.domain',
+ port => '666';
+ }
+
+
+## apt::reboot_required_notify<a name="apt-reboot_required_notify"></a>
+
+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<a name="apt-unattended_upgrades"></a>
+
+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 usage:
+
+ class {
+ 'apt::unattended_upgrades':
+ config_template => 'site_apt/50unattended-upgrades.jessie',
+ blacklisted_packages => [ 'libc6', 'libc6-dev', 'libc6-i686',
+ 'mysql-server', 'redmine', 'nodejs', 'bird' ];
+ }
+
+
+# Defines<a name="defines"></a>
+
+## apt::apt_conf<a name="apt-apt_conf"></a>
+
+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 usage:
+
+ apt::apt_conf {
+ '80download-only':
+ source => 'puppet:///modules/site_apt/80download-only';
+ }
+
+
+## apt::preferences_snippet<a name="apt-preferences_snippet"></a>
+
+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<a name="apt-preseeded_package"></a>
+
+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<a name="apt-sources_list"></a>
+
+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 usage:
+
+ apt::sources_list {
+ 'company_internals':
+ source => [ "puppet:///modules/site_apt/${::fqdn}/company_internals.list",
+ 'puppet:///modules/site_apt/company_internals.list' ];
+ }
+
+
+## apt::key<a name="apt-key"></a>
+
+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<a name="apt-key-plain"></a>
+
+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<a name="apt-upgrade_package"></a>
+
+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<a name="ressources"></a>
+
+## File['apt_config']<a name="file-apt-config"></a>
+
+Use this resource to depend on or add to a completed apt configuration
+
+## Exec['apt_updated']<a name="exec-apt-updated"></a>
+
+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<a name="test"></a>
+
+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<a name="licensing"></a>
+
+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