From 8efc70cab8b87fea46868396210568081e1ecfca Mon Sep 17 00:00:00 2001 From: Gabriel Filion Date: Mon, 25 Oct 2010 13:54:37 -0400 Subject: 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 --- README | 244 +++++++++++++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 169 insertions(+), 75 deletions(-) (limited to 'README') 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 -- cgit v1.2.3