community.general.dpkg_divert – Override a debian package’s version of a file

Note

This plugin is part of the community.general collection (version 3.8.1).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install community.general.

To use it in a playbook, specify: community.general.dpkg_divert.

New in version 0.2.0: of community.general

Synopsis

  • A diversion is for dpkg the knowledge that only a given package (or the local administrator) is allowed to install a file at a given location. Other packages shipping their own version of this file will be forced to divert it, i.e. to install it at another location. It allows one to keep changes in a file provided by a debian package by preventing its overwrite at package upgrade.
  • This module manages diversions of debian packages files using the dpkg-divert commandline tool. It can either create or remove a diversion for a given file, but also update an existing diversion to modify its holder and/or its divert location.

Requirements

The below requirements are needed on the host that executes this module.

  • dpkg-divert >= 1.15.0 (Debian family)

Parameters

Parameter Choices/Defaults Comments
divert
path
The location where the versions of file will be diverted.
Default is to add suffix .distrib to the file path.
This parameter is ignored when state=absent.
force
boolean
    Choices:
  • no
  • yes
When rename=true and force=true, renaming is performed even if the target of the renaming exists, i.e. the existing contents of the file at this location will be lost.
This parameter is ignored when rename=false.
holder
string
The name of the package whose copy of file is not diverted, also known as the diversion holder or the package the diversion belongs to.
The actual package does not have to be installed or even to exist for its name to be valid. If not specified, the diversion is hold by 'LOCAL', that is reserved by/for dpkg for local diversions.
This parameter is ignored when state=absent.
path
path / required
The original and absolute path of the file to be diverted or undiverted. This path is unique, i.e. it is not possible to get two diversions for the same path.
rename
boolean
    Choices:
  • no
  • yes
Actually move the file aside (when state=present) or back (when state=absent), but only when changing the state of the diversion. This parameter has no effect when attempting to add a diversion that already exists or when removing an unexisting one.
Unless force=true, renaming fails if the destination file already exists (this lock being a dpkg-divert feature, and bypassing it being a module feature).
state
string
    Choices:
  • absent
  • present
When state=absent, remove the diversion of the specified path; when state=present, create the diversion if it does not exist, or update its package holder or divert location, if it already exists.

Notes

Note

  • This module supports check_mode and diff.

Examples

- name: Divert /usr/bin/busybox to /usr/bin/busybox.distrib and keep file in place
  community.general.dpkg_divert:
    path: /usr/bin/busybox

- name: Divert /usr/bin/busybox by package 'branding'
  community.general.dpkg_divert:
    path: /usr/bin/busybox
    holder: branding

- name: Divert and rename busybox to busybox.dpkg-divert
  community.general.dpkg_divert:
    path: /usr/bin/busybox
    divert: /usr/bin/busybox.dpkg-divert
    rename: yes

- name: Remove the busybox diversion and move the diverted file back
  community.general.dpkg_divert:
    path: /usr/bin/busybox
    state: absent
    rename: yes
    force: yes

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key Returned Description
commands
list / elements=string
on_success
The dpkg-divert commands ran internally by the module.

Sample:
[ "/usr/bin/dpkg-divert --no-rename --remove /etc/foobarrc", "/usr/bin/dpkg-divert --package ansible --no-rename --add /etc/foobarrc" ]
diversion
dictionary
always
The status of the diversion after task execution.

Sample:
{ "divert": "/etc/foobarrc.distrib", "holder": "LOCAL", "path": "/etc/foobarrc" "state": "present" }
divert
string
success
The location of the diverted file.

holder
string
success
The package holding the diversion.

path
string
success
The path of the file to divert/undivert.

state
string
success
The state of the diversion.

messages
list / elements=string
on_success
The dpkg-divert relevant messages (stdout or stderr).

Sample:
[ "Removing 'local diversion of /etc/foobarrc to /etc/foobarrc.distrib'", "Adding 'diversion of /etc/foobarrc to /etc/foobarrc.distrib by ansible'" ]


Authors

  • quidame (@quidame)

© 2012–2018 Michael DeHaan
© 2018–2021 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/latest/collections/community/general/dpkg_divert_module.html