DEBOPS.DPKG_CLEANUP(5)

NAME
debops.dpkg_cleanup - Prepare a dpkg cleanup hook using Ansible

SYNOPSIS

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

DESCRIPTION

The debops.dpkg_cleanup Ansible role is a "helper role", meant to be used by other roles via the import_role Ansible module, or through a playbook.

The role helps prepare the host to clean up and revert certain files and directories when a specific Debian/Ubuntu package is removed or purged from the system. This ensures that customizations done by other Ansible roles are correctly reverted and removed when a different role replaces a given functionality with a different service - for example a webserver is switched from nginx to apache2, an NTP server is changed, and the like. This way roles that manage the same service don't necessarily have to include code that takes care of removing parts of alternative services.

The role functions by adding a dpkg pre-invoke hook to execute a custom Bash script when a Debian package is removed or purged. The script checks if a specific package is being removed/purged and before that happens, it executes various commands that can:

•   revert files diverted by the dpkg-divert(1) command,

•   remove files or directories not covered by the deb-prerm(5) maintainer script included in the package,

•   reload or restart systemd services.

    This helps bring back the system to a state where dpkg can cleanly remove or purge the package.

GETTING STARTED

  Example inventory

The debops.dpkg_cleanup role is not designed to be used directly. It should be imported into other Ansible roles with custom configuration for each (see below). Alternatively, it can be included in the playbooks of other Ansible roles.

  Example playbook

The debops.dpkg_cleanup role does not have it's own playbook. The role is designed to be used by other Ansible roles via the import_role Ansible module, usually at the end of the task list of a given role.

In the defaults/main.yml file of the example application role, add:

application__dpkg_cleanup__dependent_packages:
  - name: 'application'
    remove_files:
      - '/path/to/custom/file'
      - '/path/to/other/file'
    restart_services:
      - 'other-service'

In the tasks/main.yml file of the application role, add:

- name: Prepare cleanup during package removal
  import_role:
    name: 'dpkg_cleanup'
  vars:
    dpkg_cleanup__dependent_packages:
      - '{{ application__dpkg_cleanup__dependent_packages }}'
  when: application__deploy_state != 'absent'
  tags: [ 'role::dpkg_cleanup', 'skip::dpkg_cleanup',
          'role::application:dpkg_cleanup' ]

This configuration will ensure that the users can modify the list of files or directories to manipulate through the Ansible inventory, if necessary.

WARNING: Keep in mind that if the debops.dpkg_cleanup role is used via the import_role Ansible module in multiple roles, due to the behaviour of this Ansible module each such instance needs to have its own dpkg_cleanup__dependent_packages variable definition. Otherwise the last instance of the role preprocessed by Ansible will define this variable for each instance without it.

DEFAULT VARIABLE DETAILS

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

  dpkg_cleanup__packages

The dpkg_cleanup__*_packages list variables (currently a single one) define what files should be removed or reverted by the pre-invoke hook script.

  Examples

Remove additional files and restart a service before the application package is removed:

application__dpkg_cleanup__dependent_packages:
  - name: 'application'
    remove_files:
      - '/path/to/custom/file'
      - '/path/to/other/file'
    restart_services:
      - 'other-service'

  Syntax

Each entry in the list is a YAML dictionary with specific parameters:

name
    Required. The name of the Debian or Ubuntu package which will trigger the cleanup script.

state
    Optional. If not specified or present, the cleanup hook and script will be created on the host. If absent, the hook and script will be removed from the host.

ansible_fact
    Optional. By default the cleanup script will remove the corresponding Ansible local fact based on the Debian or Ubuntu package name. If the fact has a different name, you can use this parameter to specify it, including the .fact suffix.

revert_files
    Optional. A single file defined as a string, or a list of files. When the cleanup script is triggered, it will check if a corresponding file with the .dpkg-divert suffix is present in the filesystem. If it is found, the script will remove the changed file without the .dpkg-divert suffix, and use the dpkg-divert(1) command to revert the original file in its place. For security, only absolute paths are allowed.

remove_files
    Optional. A single file defined as a string, or a list of files. When the cleanup script is triggered, the specified files will be removed. For security, only absolute paths are allowed.

    The role will automatically include the hook and script files, as well as the Ansible local fact script based on the name of the Debian package, so they don't need to be specified separately.

remove_directories
    Optional. A single directory defined as a string, or a list of directories. When the cleanup script is triggered, the specified directories will be removed. For security, only absolute paths are allowed.

reload_services
    Optional. A single systemd service or a list of services. When the cleanup script is triggered, it will run the systemctl reload command for each service specified in this parameter. This can be used to update runtime configuration of system services, for example remove firewall rules that were used by a service.

restart_services
    Optional. A single systemd service or a list of services. When the cleanup script is triggered, it will run the systemctl restart command for each service specified in this parameter. This can be used to update runtime configuration of system services, for example remove firewall rules that were used by a service.

AUTHOR
Maciej Delmanowski

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