aboutsummaryrefslogtreecommitdiff
path: root/README
diff options
context:
space:
mode:
authorGabriel Filion <lelutin@gmail.com>2010-10-25 13:54:37 -0400
committerGabriel Filion <lelutin@gmail.com>2010-10-25 14:19:58 -0400
commit8efc70cab8b87fea46868396210568081e1ecfca (patch)
treeb0e35d59e489cbe0898b70bb15b7cbebb1b60706 /README
parent92aa5a51e95d74604a40318558aa98f70fcf7720 (diff)
downloadpuppet-apt-8efc70cab8b87fea46868396210568081e1ecfca.tar.gz
puppet-apt-8efc70cab8b87fea46868396210568081e1ecfca.tar.bz2
Update the README
Include new classes and defines and move things around for a little bit of consistency. Also remove the now unused variables. Signed-off-by: Gabriel Filion <lelutin@gmail.com>
Diffstat (limited to 'README')
-rw-r--r--README244
1 files changed, 169 insertions, 75 deletions
diff --git a/README b/README
index a6e37ce..2a2aa6f 100644
--- a/README
+++ b/README
@@ -9,24 +9,18 @@ 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. Testing and unstable are pinned to
-very low values by default to prevent accidental upgrades.
+/etc/apt/sources.list and /etc/apt/preferences are managed. Testing and
+unstable are pinned to very low values by default to prevent accidental
+upgrades.
This module needs lsb-release installed.
+By default, this module sets the cofiguration 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
@@ -35,60 +29,138 @@ 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.
+
+$main_apt_source
+----------------
+
+If the default sources.list template (see next variable) suits your needs but
+you simply need to change the URL to the apt source used, set this variable to
+the URL that is desired. The default value for this variable is
+"http://ftp.debian.org/debian/" for Debian and
+"http://de.archive.ubuntu.com/ubuntu/" for Ubuntu.
+
+Here's an example for setting a local source near Montreal, Quebec, Canada:
+
+ $apt_main_source = "ftp://debian.mirror.iweb.ca/debian/"
$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
-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:
+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 or removing backports, 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 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 basic apt/preferences file with unstable and testing
+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 you are not using the 'stable' branch or if the default preferences file
+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:
-$custom_preferences = false
+ site-apt
+ - files/
+ - server.domain.com/
+ - preferences
+ preferences
+
+You can set 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.
-$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
Classes
=======
-This module contains only the apt class, which sets up all described
-functionality.
+Most of the functionality is provided by the 'apt' class, but some
+functionality is not inclulded by default. To use it, you must inlucde one of
+the following classes:
+
+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 'sources' to specify a list of static files to
+include from the puppet fileserver or 'content' 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
------------------------
@@ -102,41 +174,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/apt.conf.d directory to easily add additional apt
+sources. One can use either 'sources' to specify a list of static files to
+include from the puppet fileserver or 'content' to define content inline or
+with the help of a template.
+
+Example:
+
+ apt::sources_list { "company_internals.list":
+ content => ["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';
@@ -145,15 +227,27 @@ upgrade_package { "perl":
"perl-modules":
}
-TODO
-====
+Resources
+=========
-Enable debian-archive-keyring handling for sarge, lenny and sid.
+Concatenated_file[apt_config]
+-----------------------------
-Enable selection of country-specific mirrors.
+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
+====
-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.
+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.
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