Merge pull request #287 from oc243/master

[puppet-modules/puppetlabs-apt.git] / README.md

diff --git a/README.md b/README.md
index 581277bde051039e1a6a8c0f93b843f6920d2e64..cbaab7247232d8baac139ac76175972e0d456c96 100644 (file)
--- a/README.md
+++ b/README.md
@@ -3,12 +3,6 @@ apt
 
 [![Build Status](https://travis-ci.org/puppetlabs/puppetlabs-apt.png?branch=master)](https://travis-ci.org/puppetlabs/puppetlabs-apt)
 
-## Description
-
-Provides helpful definitions for dealing with Apt.
-
-=======
-
 Overview
 --------
 
@@ -19,12 +13,15 @@ Module Description
 
 APT automates obtaining and installing software packages on \*nix systems.
 
+***Note:** While this module allows the use of short keys, we STRONGLY RECOMMEND that you DO NOT USE short keys, as they pose a serious security issue in that they open you up to collision attacks.*
+
 Setup
 -----
 
 **What APT affects:**
 
 * package/service/configuration files for APT
+    * NOTE: Setting the `purge_preferences` or `purge_preferences_d` parameters to 'true' will destroy any existing configuration that was not declared with puppet. The default for these parameters is 'false'.
 * your system's `sources.list` file and `sources.list.d` directory
     * NOTE: Setting the `purge_sources_list` and `purge_sources_list_d` parameters to 'true' will destroy any existing content that was not declared with Puppet. The default for these parameters is 'false'.
 * system repositories
@@ -57,12 +54,13 @@ The parameters for `apt` are not required in general and are predominantly for d
       purge_sources_list   => false,
       purge_sources_list_d => false,
       purge_preferences_d  => false,
-      update_timeout       => undef
+      update_timeout       => undef,
+      fancy_progress       => undef
     }
 
 Puppet will manage your system's `sources.list` file and `sources.list.d` directory but will do its best to respect existing content.
 
-If you declare your apt class with `purge_sources_list` and `purge_sources_list_d` set to 'true', Puppet will unapologetically purge any existing content it finds that wasn't declared with Puppet.
+If you declare your apt class with `purge_sources_list`, `purge_sources_list_d`, `purge_preferences` and `purge_preferences_d` set to 'true', Puppet will unapologetically purge any existing content it finds that wasn't declared with Puppet.
 
 ### apt::builddep
 
@@ -273,6 +271,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
 -----------
 
@@ -319,3 +321,4 @@ A lot of great people have contributed to this module. A somewhat current list f
 * William Van Hevelingen <blkperl@cat.pdx.edu> <wvan13@gmail.com>
 * Zach Leslie <zach@puppetlabs.com>
 * Daniele Sluijters <github@daenney.net>
+* Daniel Paulus <daniel@inuits.eu>