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: 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 -- cgit v1.2.3