diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 389 |
1 files changed, 321 insertions, 68 deletions
@@ -7,26 +7,25 @@ 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.org is added and an archive key is provided[1]. +backports.debian.org is added. -dselect is switched to expert mode to suppress superfluous help screens. +/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. -sources.list and apt_preferences are managed. Testing and unstable are pinned to -very low values by default to prevent accidental upgrades. +Ubuntu support is lagging behind but not absent either. -This module needs lsb-release installed. +This module needs: +- lsb-release installed +- the common module: git://labs.riseup.net/shared-common -Variables -========= - -$apt_clean ----------- -Sets DSelect::Clean, defaults to 'auto' on normal hosts and 'pre-auto' -in vservers, since the latter are usually more space-bound and have -better recovery mechanisms via the host: +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: +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 @@ -35,83 +34,330 @@ 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 +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) + +Variables +========= $lsbdistcodename ----------------- +---------------- + Contains the codename ("etch", "lenny", ...) of the client's release. While these values come from lsb-release by default, this -value can be set manually too, e.g. to enable forced upgrades +value can be set manually too, e.g. to enable forced upgrades. $custom_sources_list -------------------- -By default this module will use a basic apt/sources.list with a -generic debian mirror. If you need to set more specific sources, -e.g. for country proximity, proxies, etc. you can set this variable to -the location of your sources.list template. For example, setting the -following variable before including this class will pull in the -templates/apt/sources.list file: -$custom_sources_list ='template("apt/sources.list")' - -$custom_preferences --------------------- -By default this module will use a basic apt/preferences file with -unstable and testing pinned to very low values so that any package + +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 the following variable before including this class will +pull in the templates/site-apt/sources.list file: + + $custom_sources_list = template("site-apt/sources.list") + +$custom_preferences +------------------- + +Since Debian Lenny's version of APT doesn't 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. You can set this -variable to pull in a customized apt/preferences template, for -example, setting the following variable before including this class -will pull in the templates/apt/preferences file: -$custom_preferences = 'template("apt/preferences")' +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 +location (eg. $custom_preferences = "puppet:///modules/site-apt/preferences") + +Setting this variable to false before including this class will force the +apt/preferences file to be absent: + + $custom_preferences = false $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). + +$apt_proxy / $apt_proxy_port +---------------------------- + +When you include the apt::proxy_client class in your nodes, you can set the +$apt_proxy 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 $apt_proxy_port variable. + +Here's an example of setting the proxy to 'http://proxy.domain' at port 666: + + $apt_proxy = 'http://proxy.domain' + $apt_proxy_port = 666 + include apt::proxy_client + +$apt_volatile_enabled +----------------- + +If this variable is set to true the Debian Volatile sources (until +Lenny) or CODENAME-updates (such as squeeze-updates, supported since +Squeeze) are added. +By default this is false for backward compatibility with older +versions of this module. + +$apt_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. + +$apt_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. + +$apt_debian_url, $apt_security_url, $apt_backports_url, $apt_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. + +$apt_ubuntu_url +--------------- + +These variables allows to override the default APT mirror used for all +standard Ubuntu archives (including updates, security, backports). + +$apt_repos +---------- + +If this variable is set the default repositories list ("main contrib non-free") +is overriden. Classes ======= -This module contains only the apt class, which sets up all described -functionality. +apt +--- +The apt class sets up most of the documented functionality. To use +functionality that is not enabled by default, you must include one of +the following classes. -Resources -========= +apt::apticron +------------- + +When you include this class, apticron will be installed, with the following +defaults, which you are free to change before you include the class: + + $apticron_ensure_version = "present" + $apticron_email = "root" + $apticron_config = "apt/${operatingsystem}/apticron_${lsbrelease}.erb" + $apticron_diff_only = "1" + $apticron_listchanges_profile = "apticron" + $apticron_system = false + $apticron_ipaddressnum = false + $apticron_ipaddresses = false + $apticron_notifyholds = "0" + $apticron_notifynew = "0" + $apticron_customsubject = "" + +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. -File[apt_config] +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:///site-apt/${fqdn}/upgrade_initiator +- puppet:///site-apt/upgrade_initiator +- puppet:///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 ---------------- -Use this resource to depend on or add to a completed apt configuration -Exec[apt_updated] +This class, when included, installs apt-listchanges and configures it using the +following variables, the defaults are below: + + $apt_listchanges_version = "present" + $apt_listchanges_config = "apt/${operatingsystem}/listchanges_${lsbrelease}.erb" + $apt_listchanges_frontend = "pager" + $apt_listchanges_email = "root" + $apt_listchanges_confirm = "0" + $apt_listchanges_saveseen = "/var/lib/apt/listchanges.db" + $apt_listchanges_which = "both" + +apt::proxy_client ----------------- -After this point, current packages can installed via apt, usually used -like this: -Package { require => Exec[apt_updated] } +This class adds the right configuration to apt to make it fetch packages via a +proxy. The variables $apt_proxy and $apt_proxy_port need to be set (see above). + +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. + +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 /etc/apt/preferences + +Example: + + apt::preferences_snippet{ + 'irssi-plugin-otr': + release => 'lenny-backports', + priority => 999; + } apt::preseeded_package ---------------------- -This simplifies installation of packages that 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 -templates/$debian_version/locales.seeds and then include the following -in your manifest: -apt::preseeded_package { locales: } +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. + +Example: + + apt::sources_list { "company_internals.list": + source => ["puppet:///modules/site-apt/${fqdn}/company_internals.list", + "puppet:///modules/site-apt/company_internals.list"], + } apt::upgrade_package -------------------- + This simplifies upgrades for DSA security announcements or point-releases. This -will ensure that the named package is upgrade 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. +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): +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'; @@ -120,20 +366,27 @@ upgrade_package { "perl": "perl-modules": } -TODO -==== +Resources +========= + +Concatenated_file[apt_config] +----------------------------- -Enable debian-archive-keyring handling for sarge, lenny and sid. +Use this resource to depend on or add to a completed apt configuration -Enable selection of country-specific mirrors. +Exec[apt_updated] +----------------- -Currently this module updates the caches on every run. Running dselect update is -a expensive operation and should be done only on schedule by using apticron. -Sometimes -- especially when initially starting management or deploying new -packages -- a immediate update is really needed to be able to install the right -packages without errors. Thus a method should be devised to be able to specify -with high fidelity when a update should be run and when it is not needed. +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] } -[1] Of course, you should check the validity of _this_ key yourself. +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. |