123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593 |
- 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 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.
- * disable_update
- Disable "apt-get update" which is normally triggered by apt::upgrade_package
- and apt::dist_upgrade.
- 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.
- * 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.
- When this class is included the APT indexes are updated on every
- Puppet run due to the author's lack of Puppet wizardry.
- 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 usually used like this to ensure current packages are
- installed by Package resources:
- include apt::update
- Package { require => Exec['apt_updated'] }
- Please note that the apt::upgrade_package define automatically uses
- this resource so you don't have to manage this yourself if you need to
- make sure APT indexes are up-to-date before a package upgrade is
- attempted, but don't want "apt-get update" to happen on every Puppet
- run.
- 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
|