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.

dselect is switched to expert mode to suppress superfluous help screens.

sources.list and 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:

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

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

$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.
If you need to set more specific sources, e.g. for 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
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")'

Also, if you need the preferences file to be absent, set this variable to false:

$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

$apt_unattended_upgrades
------------------------

If this variable is set to true apt::unattended_upgrades is included,
which will install the package unattended-upgrades and configure it to
daily upgrade the system.

$apt_volatile_enabled
-----------------

If this variable is set to true the Debian Volatile sources 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 all documented functionality but cron-apt.

apt::cron::download
-------------------

This class sets up cron-apt so that it downloads upgradable packages,
does not actually do any upgrade and email when the output changes.

apt::cron::dist-upgrade
-----------------------

This class sets up cron-apt so that it dist-upgrades the system and
email when upgrades are performed.

Defines
=======

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

Resources
=========

Concatenated_file[apt_config]
-----------------------------
Use this resource to depend on or add to a completed apt configuration

Exec[apt_updated]
-----------------
After this point, current packages can installed via apt, usually used
like this: 

Package { require => Exec[apt_updated] }

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

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.  

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":
}

TODO
====

Enable debian-archive-keyring handling for sarge, lenny and sid.

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.