ansible.builtin.systemd_service module – Manage systemd units
Note
This module is part of ansible-core and included in all Ansible installations. In most cases, you can use the short module name systemd_service even without specifying the collections keyword. However, we recommend you use the Fully Qualified Collection Name (FQCN) ansible.builtin.systemd_service for easy linking to the module documentation and to avoid conflicting with other collections that may have the same module name.
Synopsis
- Controls systemd units (services, timers, and so on) on remote hosts.
- ansible.builtin.systemd is renamed to ansible.builtin.systemd_service to better reflect the scope of the module. ansible.builtin.systemd is kept as an alias for backward compatibility.
Aliases: systemd
Requirements
The below requirements are needed on the host that executes this module.
- A system managed by systemd.
Parameters
Parameter | Comments |
|---|---|
daemon_reexec aliases: daemon-reexec boolean added in Ansible 2.8 | Run daemon_reexec command before doing any other operations, the systemd manager will serialize the manager state. Choices:
|
daemon_reload aliases: daemon-reload boolean | Run daemon-reload before doing any other operations, to make sure systemd has read any changes. When set to Choices:
|
enabled boolean | Whether the unit should start on boot. At least one of state and enabled are required. If set, requires Choices:
|
force boolean | Whether to override existing symlinks. Choices:
|
masked boolean | Whether the unit should be masked or not. A masked unit is impossible to start. If set, requires Choices:
|
name aliases: service, unit string | 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 When using in a chroot environment you always need to specify the name of the unit with the extension. For example, |
no_block boolean | Do not synchronously wait for the requested operation to finish. Enqueued job will continue without Ansible blocking on its completion. Choices:
|
scope string added in Ansible 2.7 | Run systemctl within a given service manager scope, either as the default system scope For systemd to work with ‘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 Choices:
|
state string |
If set, requires Choices:
|
Attributes
Attribute | Support | Description |
|---|---|---|
check_mode | Support: full | Can run in check_mode and return changed status prediction without modifying target, if not supported the action will be skipped. |
diff_mode | Support: none | Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode |
platform | Platform: posix | Target OS/families that can be operated against |
Notes
Note
-
state,enabled,maskedrequiresname. - Before 2.4 you always required
name. - Globs are not supported in name, in other words,
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 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
Common return values are documented here, the following are the fields unique to this module:
Key | Description |
|---|---|
status dictionary | A dictionary with the key=value pairs returned from Returned: success Sample: |
Collection links
© 2012–2018 Michael DeHaan
© 2018–2024 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/latest/collections/ansible/builtin/systemd_service_module.html