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(-) 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 From bd3b46ac07e36bb995c99ade2e6d045c9f06f4fc Mon Sep 17 00:00:00 2001 From: Gabriel Filion Date: Mon, 25 Oct 2010 13:58:14 -0400 Subject: Change "brought to you" into "managed" in headers File headers are there to indicate that the files should not be touched directly on the server. By changing the first sentence to "This file is managed by Puppet", we reinforce the idea that it is already taken care of by something else. Signed-off-by: Gabriel Filion --- files/02show_upgraded | 2 +- files/03clean | 2 +- files/preferences | 2 +- templates/20proxy.erb | 2 +- templates/Debian/sources.list.deb-src.erb | 2 +- templates/Debian/sources.list.erb | 2 +- templates/Debian/sources.list.volatile.erb | 2 +- templates/Ubuntu/sources.list.backports.erb | 2 +- templates/Ubuntu/sources.list.deb-src.erb | 2 +- templates/Ubuntu/sources.list.erb | 2 +- 10 files changed, 10 insertions(+), 10 deletions(-) diff --git a/files/02show_upgraded b/files/02show_upgraded index eb046b2..8ef5d8d 100644 --- a/files/02show_upgraded +++ b/files/02show_upgraded @@ -1,4 +1,4 @@ -# This file is brought to you by Puppet +# This file is managed by Puppet # all local modifications will be overwritten APT::Get::Show-Upgraded true; diff --git a/files/03clean b/files/03clean index d878375..29acece 100644 --- a/files/03clean +++ b/files/03clean @@ -1,4 +1,4 @@ -# This file is brought to you by Puppet +# This file is managed by Puppet # all local modifications will be overwritten DSelect::Clean auto; diff --git a/files/preferences b/files/preferences index 7495131..ddf82fe 100644 --- a/files/preferences +++ b/files/preferences @@ -1,4 +1,4 @@ -# This file is brought to you by Puppet +# This file is managed by Puppet # all local modifications will be overwritten Package: * diff --git a/templates/20proxy.erb b/templates/20proxy.erb index 8f57e73..602e08f 100644 --- a/templates/20proxy.erb +++ b/templates/20proxy.erb @@ -1,4 +1,4 @@ -# This file is brought to you by Puppet +# This file is managed by Puppet # all local modifications will be overwritten Acquire::http { Proxy "<%= real_apt_proxy %>:<%= real_apt_proxy_port %>"; }; diff --git a/templates/Debian/sources.list.deb-src.erb b/templates/Debian/sources.list.deb-src.erb index e167ab6..954e25f 100644 --- a/templates/Debian/sources.list.deb-src.erb +++ b/templates/Debian/sources.list.deb-src.erb @@ -1,4 +1,4 @@ -# This file is brought to you by puppet +# This file is managed by puppet # all local modifications will be overwritten # basic <%= lsbdistcodename %> diff --git a/templates/Debian/sources.list.erb b/templates/Debian/sources.list.erb index 12d1027..aa26415 100644 --- a/templates/Debian/sources.list.erb +++ b/templates/Debian/sources.list.erb @@ -1,4 +1,4 @@ -# This file is brought to you by puppet +# This file is managed by puppet # all local modifications will be overwritten # basic <%= lsbdistcodename %> diff --git a/templates/Debian/sources.list.volatile.erb b/templates/Debian/sources.list.volatile.erb index d8527b6..4a0d9ab 100644 --- a/templates/Debian/sources.list.volatile.erb +++ b/templates/Debian/sources.list.volatile.erb @@ -1,4 +1,4 @@ -# This file is brought to you by puppet +# This file is managed by puppet # all local modifications will be overwritten <% if (lsbdistcodename == "sid" || lsbdistcodename == "unstable" || lsbdistcodename == "squeeze") -%> diff --git a/templates/Ubuntu/sources.list.backports.erb b/templates/Ubuntu/sources.list.backports.erb index 2bb0ad2..8347268 100644 --- a/templates/Ubuntu/sources.list.backports.erb +++ b/templates/Ubuntu/sources.list.backports.erb @@ -1,4 +1,4 @@ -# This file is brought to you by puppet +# This file is managed by puppet # all local modifications will be overwritten # backports diff --git a/templates/Ubuntu/sources.list.deb-src.erb b/templates/Ubuntu/sources.list.deb-src.erb index 22f103b..5d85983 100644 --- a/templates/Ubuntu/sources.list.deb-src.erb +++ b/templates/Ubuntu/sources.list.deb-src.erb @@ -1,4 +1,4 @@ -# This file is brought to you by puppet +# This file is managed by puppet # all local modifications will be overwritten # basic <%= lsbdistcodename %> diff --git a/templates/Ubuntu/sources.list.erb b/templates/Ubuntu/sources.list.erb index 2719934..a90c08a 100644 --- a/templates/Ubuntu/sources.list.erb +++ b/templates/Ubuntu/sources.list.erb @@ -1,4 +1,4 @@ -# This file is brought to you by puppet +# This file is managed by puppet # all local modifications will be overwritten # basic <%= lsbdistcodename %> -- cgit v1.2.3 From b5c504e19ef3f798d752bc43aa121496bff8d9aa Mon Sep 17 00:00:00 2001 From: Gabriel Filion Date: Mon, 25 Oct 2010 14:36:19 -0400 Subject: Correct some errors in the README Signed-off-by: Gabriel Filion --- README | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/README b/README index 2a2aa6f..355ee72 100644 --- a/README +++ b/README @@ -151,9 +151,9 @@ 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. +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: @@ -195,16 +195,16 @@ example for preseeding installation of the 'mysql' package with a template: 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. +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": - content => ["puppet:///modules/site-apt/${fqdn}/company_internals.list", - "puppet:///modules/site-apt/company_internals.list"], + source => ["puppet:///modules/site-apt/${fqdn}/company_internals.list", + "puppet:///modules/site-apt/company_internals.list"], } apt::upgrade_package -- cgit v1.2.3 From 90c45cfe446588345eb5d9061ea359d121db2dc3 Mon Sep 17 00:00:00 2001 From: mh Date: Thu, 28 Oct 2010 22:05:37 +0200 Subject: put the file at the right place & fix typos --- files/preferences_snippet.erb | 4 ---- manifests/preferences_snippet.pp | 12 +++++++----- templates/preferences_snippet.erb | 4 ++++ 3 files changed, 11 insertions(+), 9 deletions(-) delete mode 100644 files/preferences_snippet.erb create mode 100644 templates/preferences_snippet.erb diff --git a/files/preferences_snippet.erb b/files/preferences_snippet.erb deleted file mode 100644 index 4dfb701..0000000 --- a/files/preferences_snippet.erb +++ /dev/null @@ -1,4 +0,0 @@ -Package: <%= name %> -Pin: release a=<%= release %> -Pin-Priority: <%= priority %> - diff --git a/manifests/preferences_snippet.pp b/manifests/preferences_snippet.pp index 9da7a8e..fd2956d 100644 --- a/manifests/preferences_snippet.pp +++ b/manifests/preferences_snippet.pp @@ -21,13 +21,15 @@ define apt::preferences_snippet( # snippets, but since the preferences.d directory cannot be used in Debian # lenny, we can't generalize without going into ugly special-casing. case $source { - '' => - File["${apt::preferences::apt_preferences_dir/${name}"] { + '': { + File["${apt::preferences::apt_preferences_dir}/${name}"] { content => template("apt/preferences_snippet.erb") - }, - default => - File["${apt::preferences::apt_preferences_dir/${name}"] { + } + } + default: { + File["${apt::preferences::apt_preferences_dir}/${name}"] { source => $source } + } } } diff --git a/templates/preferences_snippet.erb b/templates/preferences_snippet.erb new file mode 100644 index 0000000..4dfb701 --- /dev/null +++ b/templates/preferences_snippet.erb @@ -0,0 +1,4 @@ +Package: <%= name %> +Pin: release a=<%= release %> +Pin-Priority: <%= priority %> + -- cgit v1.2.3 From 5de6431b89b696ce17874952dceb5968108449a9 Mon Sep 17 00:00:00 2001 From: mh Date: Thu, 28 Oct 2010 22:18:30 +0200 Subject: remove comments as lenny apt doesn't like them I got errors like: E: Syntax error /etc/apt/apt.conf.d/03clean:4: Extra junk after value Removing these comments fixed these problems. --- files/02show_upgraded | 3 --- files/03clean | 3 --- 2 files changed, 6 deletions(-) diff --git a/files/02show_upgraded b/files/02show_upgraded index 8ef5d8d..870a3a9 100644 --- a/files/02show_upgraded +++ b/files/02show_upgraded @@ -1,4 +1 @@ -# This file is managed by Puppet -# all local modifications will be overwritten - APT::Get::Show-Upgraded true; diff --git a/files/03clean b/files/03clean index 29acece..335823d 100644 --- a/files/03clean +++ b/files/03clean @@ -1,4 +1 @@ -# This file is managed by Puppet -# all local modifications will be overwritten - DSelect::Clean auto; -- cgit v1.2.3 From 4cff5ef63e6df3f7ac22834ea902b1f410e3d6ed Mon Sep 17 00:00:00 2001 From: mh Date: Thu, 28 Oct 2010 22:24:57 +0200 Subject: Revert "remove comments as lenny apt doesn't like them" This reverts commit 5de6431b89b696ce17874952dceb5968108449a9. Actually the comments are just the wrong way... --- files/02show_upgraded | 3 +++ files/03clean | 3 +++ 2 files changed, 6 insertions(+) diff --git a/files/02show_upgraded b/files/02show_upgraded index 870a3a9..8ef5d8d 100644 --- a/files/02show_upgraded +++ b/files/02show_upgraded @@ -1 +1,4 @@ +# This file is managed by Puppet +# all local modifications will be overwritten + APT::Get::Show-Upgraded true; diff --git a/files/03clean b/files/03clean index 335823d..29acece 100644 --- a/files/03clean +++ b/files/03clean @@ -1 +1,4 @@ +# This file is managed by Puppet +# all local modifications will be overwritten + DSelect::Clean auto; -- cgit v1.2.3 From ebb46ca2002d0ef9aeb15160065fa3511ced30c1 Mon Sep 17 00:00:00 2001 From: mh Date: Thu, 28 Oct 2010 22:27:28 +0200 Subject: fixing comments apt preferences actually want // to comment, while sources are fine to be commented with # ... --- files/02show_upgraded | 4 ++-- files/03clean | 4 ++-- files/preferences | 4 ++-- templates/20proxy.erb | 4 ++-- 4 files changed, 8 insertions(+), 8 deletions(-) diff --git a/files/02show_upgraded b/files/02show_upgraded index 8ef5d8d..bb127d4 100644 --- a/files/02show_upgraded +++ b/files/02show_upgraded @@ -1,4 +1,4 @@ -# This file is managed by Puppet -# all local modifications will be overwritten +// This file is managed by Puppet +// all local modifications will be overwritten APT::Get::Show-Upgraded true; diff --git a/files/03clean b/files/03clean index 29acece..3d20924 100644 --- a/files/03clean +++ b/files/03clean @@ -1,4 +1,4 @@ -# This file is managed by Puppet -# all local modifications will be overwritten +// This file is managed by Puppet +// all local modifications will be overwritten DSelect::Clean auto; diff --git a/files/preferences b/files/preferences index ddf82fe..eea7f86 100644 --- a/files/preferences +++ b/files/preferences @@ -1,5 +1,5 @@ -# This file is managed by Puppet -# all local modifications will be overwritten +// This file is managed by Puppet +// all local modifications will be overwritten Package: * Pin: release a=unstable diff --git a/templates/20proxy.erb b/templates/20proxy.erb index 602e08f..3e1ae5d 100644 --- a/templates/20proxy.erb +++ b/templates/20proxy.erb @@ -1,4 +1,4 @@ -# This file is managed by Puppet -# all local modifications will be overwritten +// This file is managed by Puppet +// all local modifications will be overwritten Acquire::http { Proxy "<%= real_apt_proxy %>:<%= real_apt_proxy_port %>"; }; -- cgit v1.2.3 From 5d54dfdd88d1e87681b317db16b20ad20b8c88f7 Mon Sep 17 00:00:00 2001 From: mh Date: Thu, 28 Oct 2010 22:44:13 +0200 Subject: unfortunately no comments are allowed in that file --- files/preferences | 3 --- 1 file changed, 3 deletions(-) diff --git a/files/preferences b/files/preferences index eea7f86..e893b7e 100644 --- a/files/preferences +++ b/files/preferences @@ -1,6 +1,3 @@ -// This file is managed by Puppet -// all local modifications will be overwritten - Package: * Pin: release a=unstable Pin-Priority: 1 -- cgit v1.2.3