unixadm.common

 

filter

bcrypt_hash

Returns a bcrypt hash of a given string. Optionally, a salt, a prefix and the logarithmic work factor (number of rounds) can be specified.

Example
'{{"Hello world"|unixadm.common.bcrypt_hash(salt=mysalt, rounds=12, prefix="2a")}}'

prefix

Prepends each element of a list with a given string.

Example:
'{{["foo", "bar", "baz"]|unixadm.common.prefix("my_")}}'

suffix

Appends a given string to each element of a list.

Example
'{{["foo", "bar", "baz"]|unixadm.common.suffix("zinga")}}'

delete_keys

Removes a set of keys from a dict.

Example
'{{
  dict(foo="bar", baz="yatta", wee="woo")|
  unixadm.common.delete_keys(["foo", "bar"])
}}'

get_keys_by_value

Select all keys from a dict with a given value.

Example
'{{somedict|unixadm.common.get_keys_by_value(["foo", "bar"])}}'

multimap

Like map(key) but works with multiple keys.

Example
'{{somedict|unixadm.common.multimap(["foo", "bar"])}}'

from_ini

Parses a given string in ini-format into a dict.

Example
---
- slurp: src=/path/to/inifile
  register: t_ini

- debug: var=mydict
  vars:
    mydict: '{{t_ini.content|b64decode|from_ini(default_section="default")}}'
...

inventory

virtual_groups - group hosts by pattern

Synopsis

group hosts by pattern

Parameters
Parameter Choices/Defaults Description
children
(string)		 dict of groups with corresponding children group patterns
groups
(string)		 dict of groups with corresponding host patterns
plugin
(string)
required		 virtual_groups
unixadm.common.virtual_groups		 Name of the plugin
Examples
---
plugin: 'unixadm.common.virtual_groups'
groups:
  mywebservers:
    - '^web\d+\.'
  mydbservers:
    - '^mysql\d+\.'
    - '^pgsql\d+\.'
children:
  myservers:
    - '^mywebservers$'
    - '^mydbservers$'
...

lookup

first_exists - return first file or directory found

Synopsis

Returns the first file or directory found

Parameters
Parameter Choices/Defaults Description
_terms
(string)
required		 list of paths to examine
Examples
---
- name: "copy either contents of directoryA or directoryB to dest"
  copy:
    src: '{{lookup("unixadm.common.first_exists",
      ["/tmp/directoryA", "/tmp/directoryB"]
    )}}'
    dest: /usr/local/share/foo/
    recursive: yes
...
Return values
Key Returned Description
_raw Success path to item

stat - return the file's or directory's stat

Synopsis

Returns the file's or directory's stats

Parameters
Parameter Choices/Defaults Description
_terms
(string)
required		 path
Examples
---
- name: "get file size"
  debug:
    msg: '{{myfilestats.st_size}}'
  vars:
    myfilestats: '{{lookup("unixadm.common.stat", "/foo/bar")}}'
...
Return values
Key Returned Description
_raw Success stat dict

version - return this collection's version

Synopsis

Returns this collection's version

Examples
---
- assert:
    that: "lookup('unixadm.common.version') is version_compare('0.0.1', '>=')"
Return values
Key Returned Description
_raw Success version string

modules

swap - activates or deactivates a swap device

Synopsis

This module activates or deactivates a swap device

Parameters
Parameter Choices/Defaults Description
dev
(string)
required		 device name
state
(string)		 present
absent
status		 enable (present) or disable (absent) swap or show (status) swap state

network_scripts - generate network-scripts from dict

Synopsis

this module generates the network-scripts config from a given dict

Parameters
Parameter Choices/Defaults Description
config
(string)
required		 config dict with the interface name as key.
The interface name decides the network device type, e.g
+ starting with 'br' or 'rawbr' is a bridge
+ starting with 'bond' is a bond
+ starting with 'sit' is a sit (simple internet transition) tunnel
+ starting with 'wg' is a wireguard interface
+ containing a dot is a vlan interface
+ containing a colon is a virtual interface
+ eth, enp.. whatever is an ethernet interface
the dict's value is the interface configuration
+ name - nickname, defaults to the interface name
+ ipv4 - address/prefix or 'dhcp'
+ ipv6 - address/prefix or 'dhcpv6' or 'auto' for router advertisement
+ ipv6_privacy - boolean, enable privacy extensions
+ ipv6_pd - boolean, use prefix delegation
+ ipv6_secondaries - list of secondary ipv6 addresses
+ mac - mac address, defaults to mac address taken from ansible facts
+ rewrite_mac - rewrite this interface's mac address to this value
+ onboot - boolean, start interface on boot
+ peerdns - enable or disable peer dns (dhcp/dhcpv6 only)
+ slaves - list of slave interfaces (bond only)
+ bonding_opts - bonding options, defaults to "mode=0" (bond only)
+ interfaces - list of bridge members (bridge only)
+ ethtool_opts - ethtool options (ethernet only)
+ arpcheck - boolean, check using arping if ip address is already taken
+ peer - tunnel peer address (sit only)
+ scope - address scope (ethernet only)
Examples
- name: "generate network config"
  network_scripts:
    config:
      'eth0':
        name: 'dialup'
        ipv4: 'dhcp'
        ipv6: 'dhcpv6'
        ipv6_privacy: true
        ipv6_pd: true
        peerdns: false
        mac: '00:11:22:33:44:55'
        rewrite_mac: '00:22:44:66:88:aa'
      'bond0':
        ipv4: '10.0.0.1/24'
        ipv6: 'fc00::1/64'
        ipv6_secondaries:
          - 'fc00::2'
          - 'fc00::3'
        slaves:
          - eth1
          - eth2
      'br0':
        ipv4: '10.1.0.1/24'
        interfaces:
          - eth3
          - eth4
      'lo:mysub'
        ipv4: '10.2.0.1/32'
      'bond1':
        slaves:
          - eth4
          - eth5
      'br1':
        slaves:
          - bond1
      'br1.1337':
        ipv4: '10.3.0.1/24'
        arpcheck: false
      'sit1':
        ipv6: 'fc01::1/64'
        peer: '192.0.2.1'
      'wg0'
        ipv4: '10.4.0.1/30'
        ipv6: 'fc04::1/64'
        listen_port: 12345
        privatekey: '6N7Sm8oWwWMNO6KS4bX95Ew/PAuI3mnjwzG0Ii7d9m0='
        psk: 'Iy+0sqf8ZksfG1TRwsOKAlcYdtc7DZZtGDVHyyv1tao='
        peer: 'gQBdyfAPzI+YTG6jXh9N130JHQcVY68OjphlpvNKD1E='
        peer_endpoint: '10.100.1.2:12345'
        keepalive: 30
        allowed_ips:
          - '10.4.0.2/32'
          - 'fc04::/64'

  register: t_network_config

- name: "restart network"
  service: name=network state=restarted
  when: t_network_config is changed

genksfloppy - build a floppy image containing a kickstart file

Synopsis

This module builds a floppy image containing the kickstart file

Parameters
Parameter Choices/Defaults Description
ks
(string)		 the kickstart as a text
ks_file
(string)		 the path to a file that should be used as kickstart

dnf_module - enable or disable a dnf module

Synopsis

enables or disables a given dnf module

Parameters
Parameter Choices/Defaults Description
name
(string)
required		 the module name
profiles
(string)		 the module's profiles
state
(string)		 present
absent		 enabled (present) or disabled (absent)
stream
(string)		 the module's version stream

dnf_versionlock - sets or removes a dnf versionlock

Synopsis

this module sets or removes a dnf versionlock

Parameters
Parameter Choices/Defaults Description
name
(string)
required		 package name(s)
state
(string)		 present
absent		 set ("present)" or remove ("absent") a versionlock
version
(string)		 force locked version to given string (V-R or E:V-R)
Examples
---
- name: "set versionlock to currently installed version"
  dnf_versionlock:
    name: bash

- name: "set versionlock to a specific version"
  dnf_versionlock:
    name: bash
    version: 4.2.46-34.el7

- name: "remove versionlocks"
  dnf_versionlock:
    name:
      - bash
      - tcsh
      - zsh
    state: absent

yum_config_manager - enable/disable yum/dnf repositories

Synopsis

this module disables or enables yum/dnf repositories

Parameters
Parameter Choices/Defaults Description
name
(string)
required		 name(s) of the repositor(y ies)
state
(string)		 present
absent		 disable ("absent") or enable ("present") given repositor(y ies)

sysfsctl - get or set sysfs values

Synopsis

This module gets or sets values from/to sysfs

Parameters
Parameter Choices/Defaults Description
key
(string)
required		 sysfs key to operate on
state
(string)		 get
set		 read (get) or write (set) value
value
(string)		 value to set sysfs key to

subguid - Add/modify/remove user/group to/in/from /etc/subuid or /etc/subgid

Synopsis

This module adds, modifies or removes a user or a group to, in or from /etc/subuid or /etc/subgid.

Parameters
Parameter Choices/Defaults Description
count
(string)		 amount of uids/gids to reserve
name
(string)
required		 user or group name
operate_on
(string)		 operate on either /etc/subuid or /etc/subgid
state
(string)		 present
absent		 add/modify (present) or remove (absent) user or group
Examples
- name: "add joe with 1024 uids to /etc/subuid"
  subguid:
    name: joe
    operate_on: subuid
    count: 1024

- name: "remove john from /etc/subgid"
  subguid:
    name: john
    operate_on: subgid
    state: absent

yum_versionlock - sets or removes a yum versionlock

Synopsis

this module sets or removes a yum versionlock

Parameters
Parameter Choices/Defaults Description
name
(string)
required		 package name(s)
state
(string)		 present
absent		 set ("present)" or remove ("absent") a versionlock
version
(string)		 force locked version to given string (V-R or E:V-R)
Examples
---
- name: "set versionlock to currently installed version"
  yum_versionlock:
    name: bash

- name: "set versionlock to a specific version"
  yum_versionlock:
    name: bash
    version: 4.2.46-34.el7

- name: "remove versionlocks"
  yum_versionlock:
    name:
      - bash
      - tcsh
      - zsh
    state: absent

findcerts - search directories for certificates and keys

Synopsis

This module searches given directories for certificate and key files and returns the certificate data as well as the corresponding key file path.

Parameters
Parameter Choices/Defaults Description
cert_path
(string)		 ['/etc/pki/tls/certs'] directory/directories to look for certificate files
key_path
(string)		 ['/etc/pki/tls/private'] directory/directories to look for key files
skip_combined
(bool)		 True ignore combined certificate/key files
skip_expired
(bool)		 True ignore expired certificates
subject
(string)		 filter by subject
Examples
---
- name: "get all valid certificates for this host"
  unixadm.common.findcerts:
    subject: '{{ansible_fqdn}}'
    skip_combined: no
  register: t_certs

kill - send signal to process or get process' pid

Synopsis

send signal to a process or a pid or get the pid of a process

Parameters
Parameter Choices/Defaults Description
pattern
(string)		 pattern of the process name, must not be used together with pid=
pid
(string)		 pid of the process, must not be used together with name=
signal
(string)		 signal to send to the process (signal names are allowed)
Examples
---
- name: "send sigterm to smokeping.fcgi"
  unixadm.common.kill:
    pattern: smokeping.fcgi
    signal: term

network_route - add or delete interface routes

Synopsis

this module manages interface routes for network-script-based systems

Parameters
Parameter Choices/Defaults Description
apply
(string)		 True
False		 apply route changes
gateway
(string)		 the gateway for reaching the network
interface
(string)
required		 the interface name
network
(string)
required		 the network to route
can be specified as 'address' (for routing a single address) or either as 'network/prefix' or as 'network/netmask'.
state
(string)		 present
absent		 add/remove route
Examples
- name: "add interface route"
  common.unixadm.network_route:
    interface: eth1
    network: '172.16.255.0/24'
    gateway: '192.168.1.1'

- name: "remove interface route but do not apply changes"
  common.unixadm.network_route:
    interface: eth1
    network: '172.16.255.0/24'
    gateway: '192.168.1.1'
    apply: no
    state: absent