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.4.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, mount).

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

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

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, and .mount units type.

Each name must correspond to the full name of the systemd unit.

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 and mount
- 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

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)