systemd module¶

SystemdDependencies ¶

A unit's dependency edges, as a dict of property -> list of unit names.

Commands:

systemctl show <unit> --property=Requires,Wants,After,Before,Conflicts

Returns:

dict[str, list[str]]

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/systemd/systemd_systemd_dependencies.py.

SystemdEnabled ¶

Whether each systemd unit is enabled on boot, as a dict of unit -> bool.

Commands:

systemctl show --all --property Id --property UnitFileState '*'

Returns:

dict[str, bool]

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/systemd/systemd_systemd_enabled.py.

state_key `class-attribute` `instance-attribute` ¶

state_key = 'UnitFileState'

state_values `class-attribute` `instance-attribute` ¶

state_values = ('enabled', 'static')

SystemdFailedUnit ¶

Attributes:

Name	Type	Description
`unit`		The failed unit's full name (e.g. `httpd.service`).
`load`		The unit's load state (`loaded`, `not-found`, ...).
`active`		The unit's active state (`failed` for a failed unit).
`sub`		The unit's sub-state (`failed`, `dead`, ...).
`description`		The unit's description, the table's trailing column.

SystemdFailedUnits ¶

The failed systemd units, as a list of SystemdFailedUnit dicts.

Commands:

systemctl --failed --no-legend --no-pager

Returns:

list[SystemdFailedUnit]

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/systemd/systemd_systemd_failed_units.py.

SystemdServiceEnabled ¶

Whether a unit is enabled on boot.

Commands:

systemctl show -p UnitFileState --value <unit>

Returns:

bool

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/server/wait_for_httpd.py.

SystemdServiceState ¶

A unit's systemd ActiveState (active, inactive, ...), or None.

Commands:

systemctl show -p ActiveState --value <unit>

Returns:

str | None

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/server/wait_for_httpd.py.

SystemdStatus ¶

Whether each systemd unit is active, as a dict of unit name -> bool.

Commands:

systemctl show --all --property Id --property SubState '*'

Returns:

dict[str, bool]

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/systemd/systemd_systemd_status.py.

state_key `class-attribute` `instance-attribute` ¶

state_key = 'SubState'

state_values `class-attribute` `instance-attribute` ¶

state_values = (
    "running",
    "waiting",
    "exited",
    "listening",
    "mounted",
    "active",
    "plugged",
)

SystemdSystemState ¶

The system manager's overall health word (running, degraded, ...).

Commands:

systemctl is-system-running || true

Returns:

str

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/systemd/systemd_systemd_system_state.py.

SystemdTimer ¶

Attributes:

Name	Type	Description
`active_state`		The timer's `ActiveState` (`active`, `inactive`).
`unit_file_state`		The timer's `UnitFileState` (`enabled`, ...).
`next_elapse_usec`		The next elapse time in microseconds since the epoch, or None when systemd reports `0`/empty (no next run) or a non-integer timestamp string.
`last_trigger_usec`		The last trigger time in microseconds since the epoch, or None when the timer has never fired (`0`/empty) or systemd renders the property as a date string.

SystemdTimers ¶

The *.timer units and their schedule, as a dict of unit -> SystemdTimer.

Commands:

systemctl show '*.timer' --property=Id,ActiveState,UnitFileState,NextElapseUSecRealtime,LastTriggerUSec

Returns:

dict[str, SystemdTimer]

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/systemd/systemd_systemd_timers.py.

SystemdUnitFile ¶

Attributes:

Name	Type	Description
`state`		The unit file's state (`enabled`, `disabled`, `static`, `masked`, `generated`, `transient`, ...).
`preset`		The unit file's preset policy (`enabled`, `disabled`), or the empty string when the table prints no preset column.

SystemdUnitFiles ¶

The installed unit files and their state/preset, as a dict of unit -> SystemdUnitFile.

Commands:

systemctl list-unit-files --no-legend --no-pager

Returns:

dict[str, SystemdUnitFile]

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/systemd/systemd_systemd_unit_files.py.

SystemdUnitProperties ¶

A unit's curated systemctl show properties, as raw strings.

Commands:

systemctl show <unit> --property=Id,Description,LoadState,ActiveState,SubState,UnitFileState,FragmentPath,MainPID

Returns:

dict[str, str]

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/systemd/systemd_systemd_unit_properties.py.

SystemdVersion ¶

The systemd release and compiled-in features, as a SystemdVersionInfo dict.

Commands:

systemctl --version

Returns:

SystemdVersionInfo

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/systemd/systemd_systemd_version.py.

SystemdVersionInfo ¶

Attributes:

Name	Type	Description
`version`		The upstream systemd integer version (e.g. `255`), or None when `systemctl --version` could not be read or parsed.
`release`		The distribution release string in parentheses (e.g. `255.4-1ubuntu8.6`), or the empty string when absent.
`features`		The compiled-in feature flags line (e.g. `+PAM +AUDIT +SELINUX ...`), or the empty string when absent.

daemon_reload `async` ¶

daemon_reload(
    ctx: OpContext,
    user_mode: bool = False,
    machine: str | None = None,
    user_name: str | None = None,
    **kwargs: Any,
) -> AsyncGenerator[Command]

Reload the systemd daemon to read unit file changes.

Parameters:

Name	Type	Description	Default
`ctx`	`OpContext`	Execution context for the operation.	required
`user_mode`	`bool`	Use the per-user systemd manager (`systemctl --user`). Defaults to False.	`False`
`machine`	`str \| None`	Connect to a named machine's systemd (`--machine=<machine>`). Defaults to None.	`None`
`user_name`	`str \| None`	Connect to a specific user's systemd session. Defaults to None.	`None`
`**kwargs`	`Any`	Additional keyword arguments.	`{}`

Yields:

Name	Type	Description
`Command`	`AsyncGenerator[Command]`	A single `systemctl daemon-reload` command.

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/systemd/systemd_daemon_reload.py.

dropin `async` ¶

dropin(
    ctx: OpContext,
    unit: str,
    filename: str,
    content: str,
    present: bool = True,
    daemon_reload: bool = True,
    restart: bool = False,
    **kwargs: Any,
) -> AsyncGenerator[Command]

Add/remove/update a systemd unit drop-in configuration file.

Parameters:

Name	Type	Description	Default
`ctx`	`OpContext`	Execution context for the operation.	required
`unit`	`str`	The unit the drop-in extends (a bare name gets `.service` appended, any other systemd suffix is kept).	required
`filename`	`str`	The drop-in name; the file is `/etc/systemd/system/<unit>.d/<filename>.conf` and `.conf` is appended when missing.	required
`content`	`str`	The drop-in's text content (the `[Service]`/... override sections).	required
`present`	`bool`	Whether the drop-in file should exist. Defaults to True.	`True`
`daemon_reload`	`bool`	Reload the systemd daemon after a write/removal so the change takes effect. Defaults to True.	`True`
`restart`	`bool`	Restart the unit after a write so the new drop-in is applied to the running process. Defaults to False.	`False`
`**kwargs`	`Any`	Additional keyword arguments.	`{}`

Yields:

Name	Type	Description
`Command`	`AsyncGenerator[Command]`	The spool transfer + elevated install (and daemon-reload / restart) when the content differs, or a removal (+ daemon-reload) when `present=False` and the file exists.

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/systemd/systemd_dropin.py.

mask `async` ¶

mask(
    ctx: OpContext,
    unit: str,
    masked: bool = True,
    user_mode: bool = False,
    machine: str | None = None,
    user_name: str | None = None,
    **kwargs: Any,
) -> AsyncGenerator[Command]

Mask or unmask a systemd unit so it cannot be started.

Parameters:

Name	Type	Description	Default
`ctx`	`OpContext`	Execution context for the operation.	required
`unit`	`str`	Name of the unit (`httpd` or `httpd.service`; a bare name gets `.service` appended, any other systemd suffix is kept).	required
`masked`	`bool`	Whether the unit should be masked (`True`) or unmasked (`False`). Defaults to True.	`True`
`user_mode`	`bool`	Use the per-user systemd manager (`systemctl --user`). Defaults to False.	`False`
`machine`	`str \| None`	Connect to a named machine's systemd (`--machine=<machine>`). Defaults to None.	`None`
`user_name`	`str \| None`	Connect to a specific user's systemd session. Defaults to None.	`None`
`**kwargs`	`Any`	Additional keyword arguments.	`{}`

Yields:

Name	Type	Description
`Command`	`AsyncGenerator[Command]`	A single `systemctl mask`/`unmask` command, only when the unit's mask state differs from the request.

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/systemd/systemd_mask.py.

preset `async` ¶

preset(
    ctx: OpContext,
    unit: str | None = None,
    all_units: bool = False,
    user_mode: bool = False,
    machine: str | None = None,
    user_name: str | None = None,
    **kwargs: Any,
) -> AsyncGenerator[Command]

Apply a unit's preset policy (enable/disable per the vendor preset).

Parameters:

Name	Type	Description	Default
`ctx`	`OpContext`	Execution context for the operation.	required
`unit`	`str \| None`	The unit to preset (a bare name gets `.service` appended). Required unless `all_units=True`. Defaults to None.	`None`
`all_units`	`bool`	Apply presets to every unit (`systemctl preset-all`) instead of a single unit. Defaults to False.	`False`
`user_mode`	`bool`	Use the per-user systemd manager (`systemctl --user`). Defaults to False.	`False`
`machine`	`str \| None`	Connect to a named machine's systemd (`--machine=<machine>`). Defaults to None.	`None`
`user_name`	`str \| None`	Connect to a specific user's systemd session. Defaults to None.	`None`
`**kwargs`	`Any`	Additional keyword arguments.	`{}`

Yields:

Name	Type	Description
`Command`	`AsyncGenerator[Command]`	A `systemctl preset <unit>` command only when the unit's state differs from its preset policy, or a stateless `systemctl preset-all` when `all_units=True`.

Raises:

CommandNotFoundError, HostConnectionError, ValueError

Examples:

Examples can be found in examples/modules/systemd/systemd_preset.py.

reset_failed `async` ¶

reset_failed(
    ctx: OpContext,
    unit: str,
    user_mode: bool = False,
    machine: str | None = None,
    user_name: str | None = None,
    **kwargs: Any,
) -> AsyncGenerator[Command]

Clear a systemd unit's failed state with reset-failed.

Parameters:

Name	Type	Description	Default
`ctx`	`OpContext`	Execution context for the operation.	required
`unit`	`str`	Name of the unit (a bare name gets `.service` appended, any other systemd suffix is kept).	required
`user_mode`	`bool`	Use the per-user systemd manager (`systemctl --user`). Defaults to False.	`False`
`machine`	`str \| None`	Connect to a named machine's systemd (`--machine=<machine>`). Defaults to None.	`None`
`user_name`	`str \| None`	Connect to a specific user's systemd session. Defaults to None.	`None`
`**kwargs`	`Any`	Additional keyword arguments.	`{}`

Yields:

Name	Type	Description
`Command`	`AsyncGenerator[Command]`	A single `systemctl reset-failed` command, only when the unit's `ActiveState` is `failed`.

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/systemd/systemd_reset_failed.py.

service `async` ¶

service(
    ctx: OpContext,
    service: str,
    running: bool = True,
    restarted: bool = False,
    reloaded: bool = False,
    enabled: bool | None = None,
    daemon_reload: bool = False,
    reset_failed: bool = False,
    soft_reload: bool = False,
    now: bool = False,
    user_mode: bool = False,
    machine: str | None = None,
    user_name: str | None = None,
    **kwargs: Any,
) -> AsyncGenerator[Command]

Manage the state of a systemd unit.

Parameters:

Name	Type	Description	Default
`ctx`	`OpContext`	Execution context for the operation.	required
`service`	`str`	Name of the unit (`httpd` or `httpd.service`; a bare name gets `.service` appended, any other systemd suffix such as `.timer` is kept).	required
`running`	`bool`	Whether the unit should be running. Defaults to True.	`True`
`restarted`	`bool`	Whether to restart the unit (only if it is already running). Defaults to False.	`False`
`reloaded`	`bool`	Whether to reload the unit (only if it is already running). Defaults to False.	`False`
`enabled`	`bool \| None`	Whether the unit should be enabled on boot; `None` leaves the boot setting alone. Defaults to None.	`None`
`daemon_reload`	`bool`	Reload the systemd daemon to read updated unit files before anything else. Defaults to False.	`False`
`reset_failed`	`bool`	Clear a `failed` state with `reset-failed` before starting/restarting. Defaults to False.	`False`
`soft_reload`	`bool`	When `reloaded` is set, use `reload-or-try-restart` instead of `reload` so a unit without a reload handler is restarted instead. Defaults to False.	`False`
`now`	`bool`	When `enabled` changes, add `--now` so the enable/disable also starts/stops the unit immediately. Defaults to False.	`False`
`user_mode`	`bool`	Use the per-user systemd manager (`systemctl --user`). Defaults to False.	`False`
`machine`	`str \| None`	Connect to a named machine's systemd (`--machine=<machine>`). Defaults to None.	`None`
`user_name`	`str \| None`	Connect to a specific user's systemd session (`--machine=<user>@<machine>` or `<user>@.host`). Defaults to None.	`None`
`**kwargs`	`Any`	Additional keyword arguments.	`{}`

Yields:

Name	Type	Description
`Command`	`AsyncGenerator[Command]`	Generated systemctl commands.

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/systemd/systemd_service.py.

sysusers `async` ¶

sysusers(
    ctx: OpContext,
    filename: str,
    content: str,
    present: bool = True,
    **kwargs: Any,
) -> AsyncGenerator[Command]

Add/remove/update a sysusers.d configuration file.

Parameters:

Name	Type	Description	Default
`ctx`	`OpContext`	Execution context for the operation.	required
`filename`	`str`	The config name; the file is `/etc/sysusers.d/<filename>.conf` and `.conf` is appended when missing.	required
`content`	`str`	The sysusers.d text content (the type/name/id/... rows).	required
`present`	`bool`	Whether the config file should exist. Defaults to True.	`True`
`**kwargs`	`Any`	Additional keyword arguments.	`{}`

Yields:

Name	Type	Description
`Command`	`AsyncGenerator[Command]`	The spool transfer + elevated install + `systemd-sysusers` when the content differs, or a removal when `present=False` and the file exists.

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/systemd/systemd_sysusers.py.

tmpfiles `async` ¶

tmpfiles(
    ctx: OpContext,
    filename: str,
    content: str,
    present: bool = True,
    **kwargs: Any,
) -> AsyncGenerator[Command]

Add/remove/update a tmpfiles.d configuration file.

Parameters:

Name	Type	Description	Default
`ctx`	`OpContext`	Execution context for the operation.	required
`filename`	`str`	The config name; the file is `/etc/tmpfiles.d/<filename>.conf` and `.conf` is appended when missing.	required
`content`	`str`	The tmpfiles.d text content (the type/path/mode/... rows).	required
`present`	`bool`	Whether the config file should exist. Defaults to True.	`True`
`**kwargs`	`Any`	Additional keyword arguments.	`{}`

Yields:

Name	Type	Description
`Command`	`AsyncGenerator[Command]`	The spool transfer + elevated install + `systemd-tmpfiles --create` when the content differs, or a removal when `present=False` and the file exists.

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/systemd/systemd_tmpfiles.py.

unit_name ¶

unit_name(service: str) -> str

Normalize a service name to a full systemd unit name.

httpd becomes httpd.service; a name already carrying a systemd unit suffix (logrotate.timer, httpd.service) is returned as is. Both the facts and the operations key on the normalized name, so the test framework's simulated state must use full unit names too.

systemd module¶

SystemdDependencies ¶

SystemdEnabled ¶

state_key class-attribute instance-attribute ¶

state_values class-attribute instance-attribute ¶

SystemdFailedUnit ¶

SystemdFailedUnits ¶

SystemdServiceEnabled ¶

SystemdServiceState ¶

SystemdStatus ¶

state_key class-attribute instance-attribute ¶

state_values class-attribute instance-attribute ¶

SystemdSystemState ¶

SystemdTimer ¶

SystemdTimers ¶

SystemdUnitFile ¶

SystemdUnitFiles ¶

SystemdUnitProperties ¶

SystemdVersion ¶

SystemdVersionInfo ¶

daemon_reload async ¶

dropin async ¶

mask async ¶

preset async ¶

reset_failed async ¶

service async ¶

sysusers async ¶

tmpfiles async ¶

unit_name ¶

state_key `class-attribute` `instance-attribute` ¶

state_values `class-attribute` `instance-attribute` ¶

state_key `class-attribute` `instance-attribute` ¶

state_values `class-attribute` `instance-attribute` ¶

daemon_reload `async` ¶

dropin `async` ¶

mask `async` ¶

preset `async` ¶

reset_failed `async` ¶

service `async` ¶

sysusers `async` ¶

tmpfiles `async` ¶