5 1. [Module Description - What the module does and why it is useful](#module-description)
6 1. [Setup - The basics of getting started with apt](#setup)
7 * [What apt affects](#what-apt-affects)
8 * [Beginning with apt](#beginning-with-apt)
9 1. [Usage - Configuration options and additional functionality](#usage)
10 * [Add GPG keys](#add-gpg-keys)
11 * [Prioritize backports](#prioritize-backports)
12 * [Update the list of packages](#update-the-list-of-packages)
13 * [Pin a specific release](#pin-a-specific-release)
14 * [Add a Personal Package Archive repository](#add-a-personal-package-archive-repository)
15 * [Configure Apt from Hiera](#configure-apt-from-hiera)
16 * [Replace the default sources.list file](#replace-the-default-sourceslist-file)
17 1. [Reference - An under-the-hood peek at what the module is doing and how](#reference)
18 1. [Limitations - OS compatibility, etc.](#limitations)
19 1. [Development - Guide for contributing to the module](#development)
21 <a id="module-description"></a>
25 The apt module lets you use Puppet to manage APT (Advanced Package Tool) sources, keys, and other configuration options.
27 APT is a package manager available on Debian, Ubuntu, and several other operating systems. The apt module provides a series of classes, defines, types, and facts to help you automate APT package management.
29 **Note**: Prior to Puppet 7, for this module to correctly autodetect which version of
30 Debian/Ubuntu (or derivative) you're running, you need to make sure the `lsb-release` package is
31 installed. With Puppet 7 the `lsb-release` package is not needed.
37 <a id="what-apt-affects"></a>
41 * Your system's `preferences` file and `preferences.d` directory
42 * Your system's `sources.list` file and `sources.list.d` directory
43 * Your system's `apt.conf.d` directory
47 **Note:** This module offers `purge` parameters which, if set to `true`, **destroy** any configuration on the node's `sources.list(.d)`, `preferences(.d)` and `apt.conf.d` that you haven't declared through Puppet. The default for these parameters is `false`.
49 <a id="beginning-with-apt"></a>
51 ### Beginning with apt
53 To use the apt module with default parameters, declare the `apt` class.
59 **Note:** The main `apt` class is required by all other classes, types, and defined types in this module. You must declare it whenever you use the module.
65 <a id="add-gpg-keys"></a>
69 **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.
71 Declare the `apt::key` defined type:
74 apt::key { 'puppetlabs':
75 id => '6F6B15509CF8E59E6E469F327F438280EF8D349F',
76 server => 'pgp.mit.edu',
77 options => 'http-proxy="http://proxyuser:proxypass@example.org:3128"',
81 <a id="prioritize-backports"></a>
83 ### Prioritize backports
86 class { 'apt::backports':
91 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.
93 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.
95 <a id="update-the-list-of-packages"></a>
97 ### Update the list of packages
99 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':
104 frequency => 'daily',
109 When `Exec['apt_update']` is triggered, it generates a `notice`-level message. Because the default [logging level for agents](https://puppet.com/docs/puppet/latest/configuration.html#loglevel) is `notice`, this causes the repository update to appear in agent logs. To silence these updates from the default log output, set the [loglevel](https://puppet.com/docs/puppet/latest/metaparameter.html#loglevel) metaparameter for `Exec['apt_update']` above the agent logging level:
114 frequency => 'daily',
120 > **NOTE:** Every `Exec['apt_update']` run will generate a corrective change, even if the apt caches are not updated. For example, setting an update frequency of `always` can result in every Puppet run resulting in a corrective change. This is a known issue. For details, see [MODULES-10763](https://tickets.puppetlabs.com/browse/MODULES-10763).
122 <a id="pin-a-specific-release"></a>
124 ### Pin a specific release
127 apt::pin { 'karmic': priority => 700 }
128 apt::pin { 'karmic-updates': priority => 700 }
129 apt::pin { 'karmic-security': priority => 700 }
132 You can also specify more complex pins using distribution properties:
137 originator => 'Debian',
138 release_version => '3.0',
144 To pin multiple packages, pass them to the `packages` parameter as an array or a space-delimited string.
146 <a id="add-a-personal-package-archive-repository"></a>
148 ### Add a Personal Package Archive (PPA) repository
151 apt::ppa { 'ppa:drizzle-developers/ppa': }
154 ### Add an Apt source to `/etc/apt/sources.list.d/`
157 apt::source { 'debian_unstable':
158 comment => 'This is the iWeb Debian unstable mirror',
159 location => 'http://debian.mirror.iweb.ca/debian/',
160 release => 'unstable',
161 repos => 'main contrib non-free',
164 'id' => 'A1BD8E9D78F7FE5C3E65D8AF8B48AD6246925553',
165 'server' => 'subkeys.pgp.net',
174 To use the Puppet Apt repository as a source:
177 apt::source { 'puppetlabs':
178 location => 'http://apt.puppetlabs.com',
181 'id' => '6F6B15509CF8E59E6E469F327F438280EF8D349F',
182 'server' => 'pgp.mit.edu',
187 <a id="configure-apt-from-hiera"></a>
189 ### Configure Apt from Hiera
191 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.
196 comment: 'This is the iWeb Debian unstable mirror'
197 location: 'http://debian.mirror.iweb.ca/debian/'
199 repos: 'main contrib non-free'
202 id: 'A1BD8E9D78F7FE5C3E65D8AF8B48AD6246925553'
203 server: 'subkeys.pgp.net'
209 location: 'http://apt.puppetlabs.com'
212 id: '6F6B15509CF8E59E6E469F327F438280EF8D349F'
213 server: 'pgp.mit.edu'
216 <a id="replace-the-default-sourceslist-file"></a>
218 ### Replace the default `sources.list` file
220 The following example replaces the default `/etc/apt/sources.list`. Along with this code, be sure to use the `purge` parameter, or you might get duplicate source warnings when running Apt.
223 apt::source { "archive.ubuntu.com-${facts['os']['distro']['codename']}":
224 location => 'http://archive.ubuntu.com/ubuntu',
225 key => '630239CC130E1A7FD81A27B140976EAF437D05B5',
226 repos => 'main universe multiverse restricted',
229 apt::source { "archive.ubuntu.com-${facts['os']['distro']['codename']}-security":
230 location => 'http://archive.ubuntu.com/ubuntu',
231 key => '630239CC130E1A7FD81A27B140976EAF437D05B5',
232 repos => 'main universe multiverse restricted',
233 release => "${facts['os']['distro']['codename']}-security"
236 apt::source { "archive.ubuntu.com-${facts['os']['distro']['codename']}-updates":
237 location => 'http://archive.ubuntu.com/ubuntu',
238 key => '630239CC130E1A7FD81A27B140976EAF437D05B5',
239 repos => 'main universe multiverse restricted',
240 release => "${facts['os']['distro']['codename']}-updates"
243 apt::source { "archive.ubuntu.com-${facts['os']['distro']['codename']}-backports":
244 location => 'http://archive.ubuntu.com/ubuntu',
245 key => '630239CC130E1A7FD81A27B140976EAF437D05B5',
246 repos => 'main universe multiverse restricted',
247 release => "${facts['os']['distro']['codename']}-backports"
251 ### Manage login configuration settings for an APT source or proxy in `/etc/apt/auth.conf`
253 Starting with APT version 1.5, you can define login configuration settings, such as
254 username and password, for APT sources or proxies that require authentication
255 in the `/etc/apt/auth.conf` file. This is preferable to embedding login
256 information directly in `source.list` entries, which are usually world-readable.
258 The `/etc/apt/auth.conf` file follows the format of netrc (used by ftp or
259 curl) and has restrictive file permissions. See [here](https://manpages.debian.org/testing/apt/apt_auth.conf.5.en.html) for details.
261 Use the optional `apt::auth_conf_entries` parameter to specify an array of hashes containing login configuration settings. These hashes may only contain the `machine`, `login` and `password` keys.
265 auth_conf_entries => [
267 'machine' => 'apt-proxy.example.net',
268 'login' => 'proxylogin',
269 'password' => 'proxypassword',
272 'machine' => 'apt.example.com/ubuntu',
274 'password' => 'supersecret',
280 <a id="reference"></a>
286 * `apt_updates`: The number of installed packages with available updates from `upgrade`.
288 * `apt_dist_updates`: The number of installed packages with available updates from `dist-upgrade`.
290 * `apt_security_updates`: The number of installed packages with available security updates from `upgrade`.
292 * `apt_security_dist_updates`: The number of installed packages with available security updates from `dist-upgrade`.
294 * `apt_package_updates`: The names of all installed packages with available updates from `upgrade`. In Facter 2.0 and later this data is formatted as an array; in earlier versions it is a comma-delimited string.
296 * `apt_package_dist_updates`: The names of all installed packages with available updates from `dist-upgrade`. In Facter 2.0 and later this data is formatted as an array; in earlier versions it is a comma-delimited string.
298 * `apt_update_last_success`: The date, in epochtime, of the most recent successful `apt-get update` run (based on the mtime of /var/lib/apt/periodic/update-success-stamp).
300 * `apt_reboot_required`: Determines if a reboot is necessary after updates have been installed.
304 See [REFERENCE.md](https://github.com/puppetlabs/puppetlabs-apt/blob/main/REFERENCE.md) for all other reference documentation.
306 <a id="limitations"></a>
310 This module is not designed to be split across [run stages](https://docs.puppetlabs.com/puppet/latest/reference/lang_run_stages.html).
312 For an extensive list of supported operating systems, see [metadata.json](https://github.com/puppetlabs/puppetlabs-apt/blob/main/metadata.json)
314 ### Adding new sources or PPAs
316 If you are adding a new source or PPA and trying to install packages from the new source or PPA on the same Puppet run, your `package` resource should depend on `Class['apt::update']`, as well as depending on the `Apt::Source` or the `Apt::Ppa`. You can also add [collectors](https://docs.puppetlabs.com/puppet/latest/reference/lang_collectors.html) to ensure that all packages happen after `apt::update`, but this can lead to dependency cycles and has implications for [virtual resources](https://docs.puppetlabs.com/puppet/latest/reference/lang_collectors.html#behavior). Before running the command below, ensure that all packages have the provider set to apt.
319 Class['apt::update'] -> Package <| provider == 'apt' |>
324 Acceptance tests for this module leverage [puppet_litmus](https://github.com/puppetlabs/puppet_litmus).
325 To run the acceptance tests follow the instructions [here](https://puppetlabs.github.io/litmus/Running-acceptance-tests.html).
326 You can also find a tutorial and walkthrough of using Litmus and the PDK on [YouTube](https://www.youtube.com/watch?v=FYfR7ZEGHoE).
328 If you run into an issue with this module, or if you would like to request a feature, please [file a ticket](https://tickets.puppetlabs.com/browse/MODULES/).
329 Every Monday the Puppet IA Content Team has [office hours](https://puppet.com/community/office-hours) in the [Puppet Community Slack](http://slack.puppet.com/), alternating between an EMEA friendly time (1300 UTC) and an Americas friendly time (0900 Pacific, 1700 UTC).
331 If you have problems getting this module up and running, please [contact Support](http://puppetlabs.com/services/customer-support).
333 If you submit a change to this module, be sure to regenerate the reference documentation as follows:
336 puppet strings generate --format markdown --out REFERENCE.md