community.general.dpkg_divert (8.5.0) — module

Install collection

Install with ansible-galaxy collection install community.general:==8.5.0

Add to requirements.yml

  collections:
    - name: community.general
      version: 8.5.0

Description

A diversion is for C(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 O(divert) it, that is 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 C(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 O(holder) and/or its O(divert) location.

Requirements

• dpkg-divert >= 1.15.0 (Debian family)

Usage examples

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

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

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

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

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

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

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

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

Inputs

    
path:
    description:
    - 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 O(path).
    required: true
    type: path

force:
    default: false
    description:
    - When O(rename=true) and O(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 O(rename=false).
    type: bool

state:
    choices:
    - absent
    - present
    default: present
    description:
    - When O(state=absent), remove the diversion of the specified O(path); when O(state=present),
      create the diversion if it does not exist, or update its package O(holder) or O(divert)
      location, if it already exists.
    type: str

divert:
    description:
    - The location where the versions of file will be diverted.
    - Default is to add suffix C(.distrib) to the file path.
    - This parameter is ignored when O(state=absent).
    type: path

holder:
    description:
    - 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 O(state=absent).
    type: str

rename:
    default: false
    description:
    - Actually move the file aside (when O(state=present)) or back (when O(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 O(force=true), renaming fails if the destination file already exists (this
      lock being a dpkg-divert feature, and bypassing it being a module feature).
    type: bool

Outputs

commands:
  description: The dpkg-divert commands ran internally by the module.
  elements: str
  returned: on_success
  sample: /usr/bin/dpkg-divert --no-rename --remove /etc/foobarrc
  type: list
diversion:
  contains:
    divert:
      description: The location of the diverted file.
      type: str
    holder:
      description: The package holding the diversion.
      type: str
    path:
      description: The path of the file to divert/undivert.
      type: str
    state:
      description: The state of the diversion.
      type: str
  description: The status of the diversion after task execution.
  returned: always
  sample:
    divert: /etc/foobarrc.distrib
    holder: LOCAL
    path: /etc/foobarrc
    state: present
  type: dict
messages:
  description: The dpkg-divert relevant messages (stdout or stderr).
  elements: str
  returned: on_success
  sample: Removing 'local diversion of /etc/foobarrc to /etc/foobarrc.distrib'
  type: list