X-Git-Url: https://review.fuel-infra.org/gitweb?a=blobdiff_plain;f=README.md;h=20c465dbfa1eec47e5ef0ccdfc21609635c8554b;hb=ed52e513db21eca180c4ac80cce0cfe116549653;hp=e2271b847f2cf14ed3ba58e780541df3ce32c98d;hpb=ab6f6d31468ae865d1ff8ba7ec108802d5b27625;p=puppet-modules%2Fpuppetlabs-apt.git

diff --git a/README.md b/README.md
index e2271b8..20c465d 100644
--- a/README.md
+++ b/README.md
@@ -138,6 +138,45 @@ If you wish to pin a number of packages you may specify the packages as a space
 delimited string using the `packages` attribute or pass in an array of package
 names.
 
+### apt::hold
+
+When you wish to hold a package in Puppet is should be done by passing in
+'held' as the ensure attribute to the package resource. However, a lot of
+public modules do not take this into account and generally do not work well
+with an ensure of 'held'.
+
+There is an additional issue that when Puppet is told to hold a package, it
+will hold it at the current version installed, there is no way to tell it in
+one go to install a specific version and then hold that version without using
+an exec resource that wraps `dpkg --set-selections` or `apt-mark`.
+
+At first glance this could also be solved by just passing the version required
+to the ensure attribute but that only means that Puppet will install that
+version once it processes that package. It does not inform apt that we want
+this package to be held. In other words; if another package somehow wants to
+upgrade this one (because of a version requirement in a dependency), apt
+should not allow it.
+
+In order to solve this you can use apt::hold. It's implemented by creating
+a preferences file with a priority of 1001, meaning that under normal
+circumstances this preference will always win. Because the priority is > 1000
+apt will interpret this as 'this should be the version installed and I am
+allowed to downgrade the current package if needed'.
+
+With this you can now set a package's ensure attribute to 'latest' but still
+get the version specified by apt::hold. You can do it like this:
+
+    apt::hold { 'vim':
+      version => '2:7.3.547-7',
+    }
+
+Since you might just want to hold Vim at version 7.3 and not care about the
+rest you can also pass in a version with a glob:
+
+    apt::hold { 'vim':
+      version => '2:7.3.*',
+    }
+
 ### apt::ppa
 
 Adds a ppa repository using `add-apt-repository`.
@@ -176,6 +215,27 @@ If you would like to configure your system so the source is the Puppet Labs APT
       key_server => 'pgp.mit.edu',
     }
 
+
+#### Hiera example
+<pre>
+apt::sources:
+  'debian_unstable':
+      location: 'http://debian.mirror.iweb.ca/debian/'
+      release: 'unstable'
+      repos: 'main contrib non-free'
+      required_packages: 'debian-keyring debian-archive-keyring'
+      key: '55BE302B'
+      key_server: 'subkeys.pgp.net'
+      pin: '-10'
+      include_src: 'true'
+
+  'puppetlabs':
+      location: 'http://apt.puppetlabs.com'
+      repos: 'main'
+      key: '4BD6EC30'
+      key_server: 'pgp.mit.edu'
+</pre>
+
 ### Testing
 
 The APT module is mostly a collection of defined resource types, which provide reusable logic that can be leveraged to manage APT. It does provide smoke tests for testing functionality on a target system, as well as spec tests for checking a compiled catalog against an expected set of resources.
@@ -213,6 +273,10 @@ Implementation
 
 Adds the necessary components to get backports for Ubuntu and Debian. The release name defaults to `$lsbdistcodename`. Setting this manually can cause undefined behavior (read: universe exploding).
 
+By default this class drops a Pin-file for Backports pinning it to a priority of 200, lower than the normal Debian archive which gets a priority of 500 to ensure your packages with `ensure => latest` don't get magically upgraded from Backports without your explicit say-so.
+
+If you raise the priority through the `pin_priority` parameter to *500*, identical to the rest of the Debian mirrors, normal policy goes into effect and the newest version wins/becomes the candidate apt will want to install or upgrade to. This means that if a package is available from Backports it and its dependencies will be pulled in from Backports unless you explicitly set the `ensure` attribute of the `package` resource to `installed`/`present` or a specific version.
+
 Limitations
 -----------
 
@@ -243,6 +307,7 @@ A lot of great people have contributed to this module. A somewhat current list f
 * Branan Purvine-Riley <branan@puppetlabs.com>
 * Christian G. Warden <cwarden@xerus.org>
 * Dan Bode <bodepd@gmail.com> <dan@puppetlabs.com>
+* Daniel Tremblay <github@danieltremblay.ca>
 * Garrett Honeycutt <github@garretthoneycutt.com>
 * Jeff Wallace <jeff@evolvingweb.ca> <jeff@tjwallace.ca>
 * Ken Barber <ken@bob.sh>
@@ -257,3 +322,4 @@ A lot of great people have contributed to this module. A somewhat current list f
 * Spencer Krum <spencer@puppetlabs.com>
 * William Van Hevelingen <blkperl@cat.pdx.edu> <wvan13@gmail.com>
 * Zach Leslie <zach@puppetlabs.com>
+* Daniele Sluijters <github@daenney.net>