systemd¶

Collection Note

This module is part of the ansible.builtin collection. To install the collection, use:

ansible-galaxy collection install ansible.builtin

Added in version 2.2.

You need further requirements to be able to use this module, see the Requirements section for details.

Synopsis¶

Controls systemd units (services, timers, and so on) on remote hosts.
M(ansible.builtin.systemd) is renamed to M(ansible.builtin.systemd_service) to better reflect the scope of the module. M(ansible.builtin.systemd) is kept as an alias for backward compatibility.

Requirements¶

The following Python packages are needed on the host that executes this module:

A system managed by systemd.

Parameters¶

Parameter	Defaults / Choices	Comments
daemon_reexec bool		Run daemon_reexec command before doing any other operations, the systemd manager will serialize the manager state. Version Added: 2.8
daemon_reload bool		Run C(daemon-reload) before doing any other operations, to make sure systemd has read any changes. When set to V(true), runs C(daemon-reload) even if the module does not start or stop anything.
enabled bool		Whether the unit should start on boot. At least one of O(state) and O(enabled) are required. If set, requires O(name).
force bool		Whether to override existing symlinks. Version Added: 2.6
masked bool		Whether the unit should be masked or not. A masked unit is impossible to start. If set, requires O(name).
name str		Name of the unit. This parameter takes the name of exactly one unit to work with. When no extension is given, it is implied to a C(.service) as systemd. When using in a chroot environment you always need to specify the name of the unit with the extension. For example, C(crond.service).
no_block bool		Do not synchronously wait for the requested operation to finish. Enqueued job will continue without Ansible blocking on its completion. Version Added: 2.3
scope str	Default: system Choices: system, user, global	Run C(systemctl) within a given service manager scope, either as the default system scope V(system), the current user's scope V(user), or the scope of all users V(global). For systemd to work with V(user), the executing user must have its own instance of dbus started and accessible (systemd requirement). The user dbus process is normally started during normal login, but not during the run of Ansible tasks. Otherwise you will probably get a 'Failed to connect to bus: no such file or directory' error. The user must have access, normally given via setting the C(XDG_RUNTIME_DIR) variable, see the example below. Version Added: 2.7
state str	Choices: reloaded, restarted, started, stopped	V(started)/V(stopped) are idempotent actions that will not run commands unless necessary. V(restarted) will always bounce the unit. V(reloaded) will always reload and if the service is not running at the moment of the reload, it is started. If set, requires O(name).

Notes¶

Note

O(state), O(enabled), O(masked) requires O(name).
Before 2.4 you always required O(name).
Globs are not supported in name, in other words, C(postgres*.service).
The service names might vary by specific OS/distribution.
The order of execution when having multiple properties is to first enable/disable, then mask/unmask and then deal with the service state. It has been reported that C(systemctl) can behave differently depending on the order of operations if you do the same manually.

Examples¶

- name: Make sure a service unit is running
  ansible.builtin.systemd_service:
    state: started
    name: httpd

- name: Stop service cron on debian, if running
  ansible.builtin.systemd_service:
    name: cron
    state: stopped

- name: Restart service cron on centos, in all cases, also issue daemon-reload to pick up config changes
  ansible.builtin.systemd_service:
    state: restarted
    daemon_reload: true
    name: crond

- name: Reload service httpd, in all cases
  ansible.builtin.systemd_service:
    name: httpd.service
    state: reloaded

- name: Enable service httpd and ensure it is not masked
  ansible.builtin.systemd_service:
    name: httpd
    enabled: true
    masked: no

- name: Enable a timer unit for dnf-automatic
  ansible.builtin.systemd_service:
    name: dnf-automatic.timer
    state: started
    enabled: true

- name: Just force systemd to reread configs (2.4 and above)
  ansible.builtin.systemd_service:
    daemon_reload: true

- name: Just force systemd to re-execute itself (2.8 and above)
  ansible.builtin.systemd_service:
    daemon_reexec: true

- name: Run a user service when XDG_RUNTIME_DIR is not set on remote login
  ansible.builtin.systemd_service:
    name: myservice
    state: started
    scope: user
  environment:
    XDG_RUNTIME_DIR: "/run/user/{{ myuid }}"

Return Values¶

Key	Data Type	Description	Returned
status	dict	A dictionary with the key=value pairs returned from C(systemctl show).	success

Authors¶

Ansible Core Team