README.md

   1 # apt
   2
   3 #### Table of Contents
   4
   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)
  20
  21 <a id="module-description"></a>
  22
  23 ## Module Description
  24
  25 The apt module lets you use Puppet to manage APT (Advanced Package Tool) sources, keys, and other configuration options.
  26
  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.
  28
  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.
  32
  33 <a id="setup"></a>
  34
  35 ## Setup
  36
  37 <a id="what-apt-affects"></a>
  38
  39 ### What apt affects
  40
  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
  44 * System repositories
  45 * Authentication keys
  46
  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`.
  48
  49 <a id="beginning-with-apt"></a>
  50
  51 ### Beginning with apt
  52
  53 To use the apt module with default parameters, declare the `apt` class.
  54
  55 ```puppet
  56 include apt
  57 ```
  58
  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.
  60
  61 <a id="usage"></a>
  62
  63 ## Usage
  64
  65 <a id="add-gpg-keys"></a>
  66
  67 ### Add GPG keys
  68
  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.
  70
  71 Declare the `apt::key` defined type:
  72
  73 ```puppet
  74 apt::key { 'puppetlabs':
  75   id      => '6F6B15509CF8E59E6E469F327F438280EF8D349F',
  76   server  => 'pgp.mit.edu',
  77   options => 'http-proxy="http://proxyuser:proxypass@example.org:3128"',
  78 }
  79 ```
  80
  81 <a id="prioritize-backports"></a>
  82
  83 ### Prioritize backports
  84
  85 ```puppet
  86 class { 'apt::backports':
  87   pin => 500,
  88 }
  89 ```
  90
  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.
  92
  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.
  94
  95 <a id="update-the-list-of-packages"></a>
  96
  97 ### Update the list of packages
  98
  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':
 100
 101 ```puppet
 102 class { 'apt':
 103   update => {
 104     frequency => 'daily',
 105   },
 106 }
 107 ```
 108
 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:
 110
 111 ```puppet
 112 class { 'apt':
 113   update => {
 114     frequency => 'daily',
 115     loglevel  => 'debug',
 116   },
 117 }
 118 ```
 119
 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).
 121
 122 <a id="pin-a-specific-release"></a>
 123
 124 ### Pin a specific release
 125
 126 ```puppet
 127 apt::pin { 'karmic': priority => 700 }
 128 apt::pin { 'karmic-updates': priority => 700 }
 129 apt::pin { 'karmic-security': priority => 700 }
 130 ```
 131
 132 You can also specify more complex pins using distribution properties:
 133
 134 ```puppet
 135 apt::pin { 'stable':
 136   priority        => -10,
 137   originator      => 'Debian',
 138   release_version => '3.0',
 139   component       => 'main',
 140   label           => 'Debian'
 141 }
 142 ```
 143
 144 To pin multiple packages, pass them to the `packages` parameter as an array or a space-delimited string.
 145
 146 <a id="add-a-personal-package-archive-repository"></a>
 147
 148 ### Add a Personal Package Archive (PPA) repository
 149
 150 ```puppet
 151 apt::ppa { 'ppa:drizzle-developers/ppa': }
 152 ```
 153
 154 ### Add an Apt source to `/etc/apt/sources.list.d/`
 155
 156 ```puppet
 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',
 162   pin      => '-10',
 163   key      => {
 164     'id'     => 'A1BD8E9D78F7FE5C3E65D8AF8B48AD6246925553',
 165     'server' => 'subkeys.pgp.net',
 166   },
 167   include  => {
 168     'src' => true,
 169     'deb' => true,
 170   },
 171 }
 172 ```
 173
 174 To use the Puppet Apt repository as a source:
 175
 176 ```puppet
 177 apt::source { 'puppetlabs':
 178   location => 'http://apt.puppetlabs.com',
 179   repos    => 'main',
 180   key      => {
 181     'id'     => '6F6B15509CF8E59E6E469F327F438280EF8D349F',
 182     'server' => 'pgp.mit.edu',
 183   },
 184 }
 185 ```
 186
 187 <a id="configure-apt-from-hiera"></a>
 188
 189 ### Configure Apt from Hiera
 190
 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.
 192
 193 ```yaml
 194 apt::sources:
 195   'debian_unstable':
 196     comment: 'This is the iWeb Debian unstable mirror'
 197     location: 'http://debian.mirror.iweb.ca/debian/'
 198     release: 'unstable'
 199     repos: 'main contrib non-free'
 200     pin: '-10'
 201     key:
 202       id: 'A1BD8E9D78F7FE5C3E65D8AF8B48AD6246925553'
 203       server: 'subkeys.pgp.net'
 204     include:
 205       src: true
 206       deb: true
 207
 208   'puppetlabs':
 209     location: 'http://apt.puppetlabs.com'
 210     repos: 'main'
 211     key:
 212       id: '6F6B15509CF8E59E6E469F327F438280EF8D349F'
 213       server: 'pgp.mit.edu'
 214 ```
 215
 216 <a id="replace-the-default-sourceslist-file"></a>
 217
 218 ### Replace the default `sources.list` file
 219
 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.
 221
 222 ```puppet
 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',
 227 }
 228
 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"
 234 }
 235
 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"
 241 }
 242
 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"
 248 }
 249 ```
 250
 251 ### Manage login configuration settings for an APT source or proxy in `/etc/apt/auth.conf`
 252
 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.
 257
 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.
 260
 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.
 262
 263 ```puppet
 264 class { 'apt':
 265   auth_conf_entries => [
 266     {
 267       'machine'  => 'apt-proxy.example.net',
 268       'login'    => 'proxylogin',
 269       'password' => 'proxypassword',
 270     },
 271     {
 272       'machine'  => 'apt.example.com/ubuntu',
 273       'login'    => 'reader',
 274       'password' => 'supersecret',
 275     },
 276   ],
 277 }
 278 ```
 279
 280 <a id="reference"></a>
 281
 282 ## Reference
 283
 284 ### Facts
 285
 286 * `apt_updates`: The number of installed packages with available updates from `upgrade`.
 287
 288 * `apt_dist_updates`: The number of installed packages with available updates from `dist-upgrade`.
 289
 290 * `apt_security_updates`: The number of installed packages with available security updates from `upgrade`.
 291
 292 * `apt_security_dist_updates`: The number of installed packages with available security updates from `dist-upgrade`.
 293
 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.
 295
 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.
 297
 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).
 299
 300 * `apt_reboot_required`: Determines if a reboot is necessary after updates have been installed.
 301
 302 ### More Information
 303
 304 See [REFERENCE.md](https://github.com/puppetlabs/puppetlabs-apt/blob/main/REFERENCE.md) for all other reference documentation.
 305
 306 <a id="limitations"></a>
 307
 308 ## Limitations
 309
 310 This module is not designed to be split across [run stages](https://docs.puppetlabs.com/puppet/latest/reference/lang_run_stages.html).
 311
 312 For an extensive list of supported operating systems, see [metadata.json](https://github.com/puppetlabs/puppetlabs-apt/blob/main/metadata.json)
 313
 314 ### Adding new sources or PPAs
 315
 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.
 317
 318 ```puppet
 319 Class['apt::update'] -> Package <| provider == 'apt' |>
 320 ```
 321
 322 ## Development
 323
 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).
 327
 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).
 330
 331 If you have problems getting this module up and running, please [contact Support](http://puppetlabs.com/services/customer-support).
 332
 333 If you submit a change to this module, be sure to regenerate the reference documentation as follows:
 334
 335 ```bash
 336 puppet strings generate --format markdown --out REFERENCE.md
 337 ```