+### Add GPG keys
+
+**Warning:** Using short key IDs presents a serious security issue, potentially leaving you open to collision attacks. We recommend you always use full fingerprints to identify your GPG keys. This module allows short keys, but issues a security warning if you use them.
+
+Declare the `apt::key` defined type:
+
+```puppet
+apt::key { 'puppetlabs':
+ id => '6F6B15509CF8E59E6E469F327F438280EF8D349F',
+ server => 'pgp.mit.edu',
+ options => 'http-proxy="http://proxyuser:proxypass@example.org:3128"',
+}
+```
+
+### Prioritize backports
+
+```puppet
+class { 'apt::backports':
+ pin => 500,
+}
+```
+
+By default, the `apt::backports` class drops a pin file for backports, pinning it to a priority of 200. This is lower than the normal default of 500, so packages with `ensure => latest` don't get upgraded from backports without your explicit permission.
+
+If you raise the priority through the `pin` parameter to 500, normal policy goes into effect and Apt installs or upgrades to the newest version. This means that if a package is available from backports, it and its dependencies are pulled in from backports unless you explicitly set the `ensure` attribute of the `package` resource to `installed`/`present` or a specific version.
+
+### Update the list of packages
+
+By default, Puppet runs `apt-get update` on the first Puppet run after you include the `apt` class, and anytime `notify => Exec['apt_update']` occurs; i.e., whenever config files get updated or other relevant changes occur. If you set `update['frequency']` to 'always', the update runs on every Puppet run. You can also set `update['frequency']` to 'daily' or 'weekly':
+
+```puppet
+class { 'apt':
+ update => {
+ frequency => 'daily',
+ },
+}
+```
+When `Exec['apt_update']` is triggered, it generates a `Notice` message. Because the default [logging level for agents](https://docs.puppet.com/puppet/latest/configuration.html#loglevel) is `notice`, this causes the repository update to appear in logs and agent reports. Some tools, such as [The Foreman](https://www.theforeman.org), report the update notice as a significant change. To eliminate these updates from reports, set the [loglevel](https://docs.puppet.com/puppet/latest/metaparameter.html#loglevel) metaparameter for `Exec['apt_update']` above the agent logging level:
+
+```puppet
+class { 'apt':
+ update => {
+ frequency => 'daily',
+ loglevel => 'debug',
+ },
+}
+```
+
+### Pin a specific release
+
+```puppet
+apt::pin { 'karmic': priority => 700 }
+apt::pin { 'karmic-updates': priority => 700 }
+apt::pin { 'karmic-security': priority => 700 }
+```
+
+You can also specify more complex pins using distribution properties:
+
+```puppet
+apt::pin { 'stable':
+ priority => -10,
+ originator => 'Debian',
+ release_version => '3.0',
+ component => 'main',
+ label => 'Debian'
+}
+```
+
+To pin multiple packages, pass them to the `packages` parameter as an array or a space-delimited string.
+
+### Add a Personal Package Archive (PPA) repository
+
+```puppet
+apt::ppa { 'ppa:drizzle-developers/ppa': }
+```
+
+### Add an Apt source to `/etc/apt/sources.list.d/`
+
+```puppet
+apt::source { 'debian_unstable':
+ comment => 'This is the iWeb Debian unstable mirror',
+ location => 'http://debian.mirror.iweb.ca/debian/',
+ release => 'unstable',
+ repos => 'main contrib non-free',
+ pin => '-10',
+ key => {
+ 'id' => 'A1BD8E9D78F7FE5C3E65D8AF8B48AD6246925553',
+ 'server' => 'subkeys.pgp.net',
+ },
+ include => {
+ 'src' => true,
+ 'deb' => true,
+ },
+}
+```
+
+To use the Puppet Apt repository as a source:
+
+```puppet
+apt::source { 'puppetlabs':
+ location => 'http://apt.puppetlabs.com',
+ repos => 'main',
+ key => {
+ 'id' => '6F6B15509CF8E59E6E469F327F438280EF8D349F',
+ 'server' => 'pgp.mit.edu',
+ },
+}
+```
+
+### Configure Apt from Hiera
+
+Instead of specifying your sources directly as resources, you can instead just include the `apt` class, which will pick up the values automatically from hiera.
+
+```yaml