module-apt/README

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.

This module needs:

- the lsb module: git://labs.riseup.net/shared-lsb

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)

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.

$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 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. 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:

  $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.

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
=======

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.

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.

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 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
-----------------

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::preferences_snippet {
    'unstable_fallback':
      package => '*',
      release => 'unstable',
      priority => 1;
  }

  apt::preferences_snippet {
    'ttdnsd':
      pin => 'origin deb.torproject.org',
      priority => 999;
  }

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.

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 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.


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