Join AnsibleFest at Red Hat Summit!

community.general.systemd_info module – Gather systemd unit info

Note

This module is part of the community.general collection (version 10.5.0).

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.systemd_info.

New in community.general 10.4.0

Synopsis

  • This module gathers info about systemd units (services, targets, sockets, mounts, timers).

  • Timer units are supported since community.general 10.5.0.

  • It runs systemctl list-units (or processes selected units) and collects properties for each unit using systemctl show.

  • In case a unit has multiple properties with the same name, only the value of the first one will be collected.

  • Even if a unit has a units.loadstate of not-found or masked, it is returned, but only with the minimal properties (units.name, units.loadstate, units.activestate, units.substate).

  • When unitname and extra_properties are used, the module first checks if the unit exists, then check if properties exist. If not, the module fails.

  • When unitname is used with wildcard expressions, the module checks for units that match the indicated expressions, if units are not present for all the indicated expressions, the module fails.

Parameters

Parameter

Comments

extra_properties

list / elements=string

Additional properties to retrieve (appended to the default ones).

Note that all property names are converted to lower-case.

Default: []

unitname

list / elements=string

List of unit names to process.

It supports .service, .target, .socket, .mount and .timer units type.

.timer units are supported since community.general 10.5.0.

Each name must correspond to the full name of the systemd unit or to a wildcard expression like 'ssh*' and '*.service'.

Wildcard expressions in unitname are supported since community.general 10.5.0.

Default: []

Attributes

Attribute

Support

Description

check_mode

Support: full

This action does not modify state.

Can run in check_mode and return changed status prediction without modifying target.

diff_mode

Support: N/A

This action does not modify state.

Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode.

Examples

---
# Gather info for all systemd services, targets, sockets, mount and timer
- name: Gather all systemd unit info
  community.general.systemd_info:
  register: results

# Gather info for selected units with extra properties.
- name: Gather info for selected unit(s)
  community.general.systemd_info:
    unitname:
      - systemd-journald.service
      - systemd-journald.socket
      - sshd-keygen.target
      - -.mount
    extra_properties:
      - Description
    register: results

# Gather info using wildcards/expression
- name: Gather info of units that start with 'systemd-'
  community.general.systemd_info:
    unitname:
      - 'systemd-*'
  register: results

# Gather info for systemd-tmpfiles-clean.timer with extra properties
- name: Gather info of systemd-tmpfiles-clean.timer and extra AccuracyUSec
  community.general.systemd_info:
    unitname:
      - systemd-tmpfiles-clean.timer
    extra_properties:
      - AccuracyUSec
  register: results

Return Values

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

Key

Description

units

dictionary

Dictionary of systemd unit info keyed by unit name.

Additional fields will be returned depending on the value of extra_properties.

Returned: success

Sample: {"-.mount": {"activestate": "active", "description": "Root Mount", "loadstate": "loaded", "name": "-.mount", "options": "rw,relatime,seclabel,attr2,inode64,logbufs=8,logbsize=32k,noquota", "substate": "mounted", "type": "xfs", "what": "/dev/mapper/cs-root", "where": "/"}, "sshd-keygen.target": {"activestate": "active", "description": "sshd-keygen.target", "fragmentpath": "/usr/lib/systemd/system/sshd-keygen.target", "loadstate": "loaded", "name": "sshd-keygen.target", "substate": "active", "unitfilepreset": "disabled", "unitfilestate": "static"}, "systemd-journald.service": {"activestate": "active", "description": "Journal Service", "execmainpid": "613", "fragmentpath": "/usr/lib/systemd/system/systemd-journald.service", "loadstate": "loaded", "mainpid": "613", "name": "systemd-journald.service", "substate": "running", "unitfilepreset": "disabled", "unitfilestate": "static"}, "systemd-journald.socket": {"activestate": "active", "description": "Journal Socket", "fragmentpath": "/usr/lib/systemd/system/systemd-journald.socket", "loadstate": "loaded", "name": "systemd-journald.socket", "substate": "running", "unitfilepreset": "disabled", "unitfilestate": "static"}}

activestate

string

The current active state of the unit.

The most common values are active, inactive, and failed, but other values are possible as well.

Returned: always

Sample: "active"

execmainpid

string

PID of the ExecStart process of the unit.

Returned: only for .service units.

Sample: "799"

fragmentpath

string

Path to the unit’s fragment file.

Returned: always except for .mount units.

Sample: "/usr/lib/systemd/system/systemd-journald.service"

loadstate

string

The state of the unit’s configuration load.

The most common values are loaded, not-found, and masked, but other values are possible as well.

Returned: always

Sample: "loaded"

mainpid

string

PID of the main process of the unit.

Returned: only for .service units.

Sample: "798"

name

string

Unit full name.

Returned: always

Sample: "systemd-journald.service"

options

string

The mount options.

Returned: only for .mount units.

Sample: "rw,relatime,noquota"

substate

string

The detailed sub state of the unit.

The most common values are running, dead, exited, failed, listening, active, and mounted, but other values are possible as well.

Returned: always

Sample: "running"

type

string

The filesystem type of the mounted device.

Returned: only for .mount units.

Sample: "ext4"

unitfilepreset

string

The preset configuration state for the unit file.

The most common values are enabled, disabled, and static, but other values are possible as well.

Returned: always except for .mount units.

Sample: "disabled"

unitfilestate

string

The actual configuration state for the unit file.

The most common values are enabled, disabled, and static, but other values are possible as well.

Returned: always except for .mount units.

Sample: "enabled"

what

string

The device that is mounted.

Returned: only for .mount units.

Sample: "/dev/sda1"

where

string

The mount point where the device is mounted.

Returned: only for .mount units.

Sample: "/"

Authors

  • Marco Noce (@NomakCooper)