summaryrefslogtreecommitdiff
path: root/README
diff options
context:
space:
mode:
Diffstat (limited to 'README')
-rw-r--r--README222
1 files changed, 154 insertions, 68 deletions
diff --git a/README b/README
index 12ec3fa..2cbf246 100644
--- a/README
+++ b/README
@@ -9,11 +9,9 @@ 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.
+/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.
@@ -22,17 +20,12 @@ This module needs:
- lsb-release installed
- the common module: git://labs.riseup.net/shared-common
+By default, this module sets the configuration option DSelect::Clean to 'auto'.
+It is the recommended value on normal hosts. On virtual servers, the
+recommended value is 'pre-auto', since virtual servers are usually more
+space-bound and have better recovery mechanisms via the host:
-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:
+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
@@ -41,49 +34,82 @@ 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" in a 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)
+
+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.
-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")'
-
+
+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
--------------------
-By default this module will use a basic apt/preferences file with
-more recent releases pinned to very low values so that any package
+
+Since Debian stable'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 file named 'preferences' in a site-apt module's files
+directory. You can also create a host-specific file:
+
+ site-apt
+ - files/
+ - server.domain.com/
+ - preferences
+ preferences
-Also, if you need the preferences file to be absent, set this variable to false:
+Setting this variable to false before including this class will force the
+apt/preferences file to be absent:
-$custom_preferences = 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
+exist there, this module will 'apt-key add' each key.
-$apt_unattended_upgrades
-------------------------
+$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.
-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.
+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
-----------------
@@ -134,7 +160,9 @@ Classes
apt
---
-The apt class sets up all documented functionality but cron-apt.
+The apt class sets up most of the documented functionality. To use
+functionality that is not enabled by default, you must inlucde one of
+the following classes.
apt::cron::download
-------------------
@@ -148,9 +176,41 @@ apt::cron::dist-upgrade
This class sets up cron-apt so that it dist-upgrades the system and
email when upgrades are performed.
+apt::dselect
+------------
+
+This class, when included, installs dselect and switches it to expert mode to
+suppress superfluous help screens.
+
+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::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
------------------------
@@ -164,41 +224,51 @@ Example:
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
+
+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
-templates/$debian_version/locales.seeds and then include the following
+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::preseeded_package { locales: }
+
+You can also specify 'content' to define this file via a template. Here's an
+example for preseeding installation of the 'mysql' package with a template:
+
+ apt::preseeded_package { "mysql":
+ content => template("site-apt/mysql.seed.erb"),
+ }
+
+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 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):
+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';
@@ -207,13 +277,29 @@ upgrade_package { "perl":
"perl-modules":
}
+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 be installed via apt. It is usually used
+like this:
+
+Package { require => Exec[apt_updated] }
+
TODO
====
-Enable debian-archive-keyring handling for sarge, lenny and sid.
+Currently this module updates the caches on every run. Running apt-get update is
+an expensive operation and should be done only on schedule by using
+apticron or cron-apt.
-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