DEBOPS.UNATTENDED_UPGRADES(5)

NAME
debops.unattended_upgrades - Configure unattended upgrades on Debian-based hosts

SYNOPSIS

debops service/unattended_upgrades [--limit group,host,...] [--diff] [--check] [--tags tag1,tag2,...] [--skip-tags tag1,tag2,...] [<ansible-playbook options>] ...

DESCRIPTION

The unattended-upgrades package manages automatic, unattended upgrades <https://wiki.debian.org/UnattendedUpgrades> of the Debian-based hosts. You can specify what package origins are included in the unattended upgrades, as well as specify what packages should be exempt from the upgrades, among other things.

GETTING STARTED

  Initial configuration

The unattended-upgrades package will be configured differently depending on whether or not a DNS domain is configured on the host:

•   if the ansible_domain variable is not empty (domain is present), only packages released through the security repository of a given OS distribution will be upgraded automatically. E-mail messages with the information about the unattended upgrades will be sent to the root@{{ ansible_domain }} mail account.

•   if the ansible_domain variable is empty, role assumes that the host is a workstation or a laptop (end-user device) and will configure the unattended-upgrades package to upgrade packages from all official repositories of the given OS distribution (main, updates, backports, security). The e-mail messages about the upgrades won't be generated.

    You can control the above behaviour using unattended_upgrades__release and unattended_upgrades__mail_to default variables.

  Example inventory

debops.unattended_upgrades is included by default in the common.yml DebOps playbook; you don't need to do anything to have it installed.

If you want to disable the unattended-upgrades service on a host or set of hosts, you can do this by the setting variable:

unattended_upgrades__enabled: False

in Ansible's inventory. The unattended-upgrades package won't be installed. If it is already present on the host, it won't be removed, but its configuration will be reset to the distribution defaults.

  Example playbook

Here's an example playbook that can be used to enable and manage the unattended-upgrades service on a set of hosts:

---
- name: Manage unattended APT upgrades
  collections: [ 'debops.debops', 'debops.roles01',
                 'debops.roles02', 'debops.roles03' ]
  hosts: [ 'debops_all_hosts', 'debops_service_unattended_upgrades' ]
  become: True
  environment: '{{ inventory__environment | d({})
                   | combine(inventory__group_environment | d({}))
                   | combine(inventory__host_environment  | d({})) }}'
  roles:
    - role: unattended_upgrades
      tags: [ 'role::unattended_upgrades', 'skip::unattended_upgrades' ]

  Use as a role dependency

The debops.unattended_upgrades Ansible role can be used by other Ansible roles as a dependency, to allow unattended upgrades of packages from other repositories than the official ones, or allow automatic blacklisting of important packages by a given Ansible role. To do this, you can specify debops.unattended_upgrades role as a dependency and use two custom variables:

unattended_upgrades__dependent_origins
    This is a list of package origins which should be considered for unattended upgrades of packages.

unattended_upgrades__dependent_blacklist
    This is a list of APT packages which should be exempt from unattended upgrades.

    Configuration passed to the role through above variables will be stored on the remote host in Ansible local facts. This prevents idempotency loops and allows users to use debops.unattended_upgrades in different playbooks without issues. This method works on the host with unattended upgrades disabled through Ansible inventory.

DEFAULT VARIABLE DETAILS

Some of debops.unattended_upgrades default variables have more extensive configuration than simple strings or lists, here you can find documentation and examples for them.

  unattended_upgrades__blacklist

The unattended_upgrades__blacklist and similar lists allow you to specify packages which shouldn't be upgraded automatically. The lists can be nested. You can specify them as simple package names or dictionaries with specific keys:

name
    Required, string or list specifying a package name to include in the blacklist.

state
    Required. Choices:

present
    The specified package(s) will be added in the blacklist.

absent
    The specified package(s) will be removed in the blacklist.

  Examples

Include specified packages in the upgrade blacklist on all hosts:

unattended_upgrades__blacklist:
  - 'zsh'
  - name: 'postgresql'
    state: '{{ "present" if (ansible_hostname in [ "database", "db" ]) else "absent" }}'
  - name: [ '^linux-.*', 'vim' ]
    state: '{{ "present"
              if (ansible_local|d() and ansible_local.tags|d()
                  and "production" in ansible_local.tags)
              else "absent" }}'

  unattended_upgrades__origins

The unattended_upgrades__origins and unattended_upgrades__dependent_origins lists define origin patterns of repositories that will be considered for unattended package upgrades. The lists can be nested. You can specify them as simple origin patterns or dictionaries with specific keys:

origin
    Required, string or list of origin patterns.

    Alternatively, origins also works.

state
    Required. Choices:

present
    The specified origin patterns will be considered for unattended package upgrades.

absent
    The specified origin patterns will be not considered for unattended package upgrades.

  Origins syntax

Lines below have the format format is keyword=value,.... A package will be upgraded only if the values in its metadata match all the supplied keywords in a line. (In other words, omitted keywords are wild cards.) The keywords originate from the Release file, but several aliases are accepted. The accepted keywords are:

a,archive,suite (eg, "stable")
c,component     (eg, "main", "crontrib", "non-free")
l,label         (eg, "Debian", "Debian-Security")
o,origin        (eg, "Debian", "Unofficial Multimedia Packages")
n,codename      (eg, "jessie", "jessie-updates")
  site          (eg, "http.debian.net")

The available values on the system are printed by the command "apt-cache policy", and can be debugged by running "unattended-upgrades -d" and looking at the log file.

Within lines unattended-upgrades allows 2 macros whose values are derived from /etc/debian_version:

${distro_id}            Installed origin.
${distro_codename}      Installed codename (eg, "jessie")

Codename based matching: This will follow the migration of a release through different archives (e. g. from testing to stable and later oldstable):

"o=Debian,n=jessie";
"o=Debian,n=jessie-updates";
"o=Debian,n=jessie-proposed-updates";
"o=Debian,n=jessie,l=Debian-Security";

Archive or Suite based matching: Note that this will silently match a different release after migration to the specified archive (e. g. testing becomes the new stable):

"o=Debian,a=stable";
"o=Debian,a=stable-updates";
"o=Debian,a=proposed-updates";
"origin=Debian,codename=${distro_codename},label=Debian-Security";

  Examples

Include specified origin patterns for all hosts:

unattended_upgrades__origins:
  - 'o=packages.gitlab.com/gitlab/gitlab-ce,n=${distro_codename},l=gitlab-ce'
  - origin: 'site=download.owncloud.org'
  - origin: [ 'site=download.example.org', 'o=Example Testing Packages' ]
    state: '{{ "present" if (ansible_hostname in [ "testing", "staging" ]) else "absent" }}'

AUTHOR
Maciej Delmanowski, Robin Schneider

COPYRIGHT
2014-2022, Maciej Delmanowski, Nick Janetakis, Robin Schneider and others