X-Git-Url: https://review.fuel-infra.org/gitweb?a=blobdiff_plain;f=README.md;h=cbaab7247232d8baac139ac76175972e0d456c96;hb=0da464de351241db7d9772977b9670eddc80d84f;hp=6e2642f4c7184db44c843424f828ac556f727a73;hpb=519babcfb68dc5e224ab8da4848220b6c69707c4;p=puppet-modules%2Fpuppetlabs-apt.git
diff --git a/README.md b/README.md
index 6e2642f..cbaab72 100644
--- a/README.md
+++ b/README.md
@@ -3,12 +3,6 @@ apt
[](https://travis-ci.org/puppetlabs/puppetlabs-apt)
-## Description
-
-Provides helpful definitions for dealing with Apt.
-
-=======
-
Overview
--------
@@ -19,17 +13,19 @@ 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
* authentication keys
-* wget (optional)
### Beginning with APT
@@ -58,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
@@ -81,9 +78,31 @@ Forces a package to be installed from a specific release. This class is particu
require => Apt::Source['debian_unstable'],
}
+### apt_key
+
+A native Puppet type and provider for managing GPG keys for APT is provided by
+this module.
+
+ apt_key { 'puppetlabs':
+ ensure => 'present',
+ id => '4BD6EC30',
+ }
+
+You can additionally set the following attributes:
+
+ * `source`: HTTP, HTTPS or FTP location of a GPG key or path to a file on the
+ target host;
+ * `content`: Instead of pointing to a file, pass the key in as a string;
+ * `server`: The GPG key server to use. It defaults to *keyserver.ubuntu.com*;
+ * `keyserver_options`: Additional options to pass to `--keyserver`.
+
+Because it is a native type it can be used in and queried for with MCollective.
+
### apt::key
-Adds a key to the list of keys used by APT to authenticate packages.
+Adds a key to the list of keys used by APT to authenticate packages. This type
+uses the aforementioned `apt_key` native type. As such it no longer requires
+the wget command that the old implementation depended on.
apt::key { 'puppetlabs':
key => '4BD6EC30',
@@ -95,8 +114,6 @@ Adds a key to the list of keys used by APT to authenticate packages.
key_source => 'http://pkg.jenkins-ci.org/debian/jenkins-ci.org.key',
}
-Note that use of `key_source` requires wget to be installed and working.
-
### apt::pin
Adds an apt pin for a certain release.
@@ -196,6 +213,27 @@ If you would like to configure your system so the source is the Puppet Labs APT
key_server => 'pgp.mit.edu',
}
+
+#### Hiera example
+
+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'
+
+
### 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.
@@ -233,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
-----------
@@ -263,6 +305,7 @@ A lot of great people have contributed to this module. A somewhat current list f
* Branan Purvine-Riley
* Christian G. Warden
* Dan Bode
+* Daniel Tremblay
* Garrett Honeycutt
* Jeff Wallace
* Ken Barber
@@ -278,3 +321,4 @@ A lot of great people have contributed to this module. A somewhat current list f
* William Van Hevelingen
* Zach Leslie
* Daniele Sluijters
+* Daniel Paulus