systemd – Manage services — Ansible Documentation

- AnsibleFest
- Products
- Community
- Webinars & Training
- Blog

Documentation

# systemd – Manage services

- Synopsis
- Requirements
- Parameters
- Notes
- Examples
- Return Values
- Status

## Synopsis

- Controls systemd services on remote hosts.

## Requirements

The below requirements are needed on the host that executes this module.

- A system managed by systemd.

## Parameters

Parameter | Choices/Defaults | Comments
--- | --- | ---
daemon_reexec boolean added in 2.8 | Choices: no ← yes | Run daemon_reexec command before doing any other operations, the systemd manager will serialize the manager state. aliases: daemon-reexec
daemon_reload boolean | Choices: no ← yes | Run daemon-reload before doing any other operations, to make sure systemd has read any changes. When set to `yes`, runs daemon-reload even if the module does not start or stop anything. aliases: daemon-reload
enabled boolean | Choices: no yes | Whether the service should start on boot. At least one of state and enabled are required.
force boolean added in 2.6 | Choices: no yes | Whether to override existing symlinks.
masked boolean | Choices: no yes | Whether the unit should be masked or not, a masked unit is impossible to start.
name - |  | Name of the service. This parameter takes the name of exactly one service to work with. When using in a chroot environment you always need to specify the full name i.e. (crond.service). aliases: service, unit
no_block boolean | Choices: no ← yes | Do not synchronously wait for the requested operation to finish. Enqueued job will continue without Ansible blocking on its completion.
scope - added in 2.7 | Choices: system user global | run systemctl within a given service manager scope, either as the default system scope (system), the current user's scope (user), or the scope of all users (global). For systemd to work with 'user', the executing user must have its own instance of dbus started (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.
state - | Choices: reloaded restarted started stopped | `started`/`stopped` are idempotent actions that will not run commands unless necessary. `restarted` will always bounce the service. `reloaded` will always reload.
user boolean | Choices: no ← yes | (deprecated) run ``systemctl`` talking to the service manager of the calling user, rather than the service manager of the system. This option is deprecated and will eventually be removed in 2.11. The ``scope`` option should be used instead.

## Notes

Note

- Since 2.4, one of the following options is required ‘state’, ‘enabled’, ‘masked’, ‘daemon_reload’, (‘daemon_reexec’ since 2.8), and all except ‘daemon_reload’ (and ‘daemon_reexec’ since 2.8) also require ‘name’.
- Before 2.4 you always required ‘name’.
- Globs are not supported in name, i.e `postgres*.service`.

## Examples

    - name: Make sure a service is running
      systemd:
        state: started
        name: httpd

    - name: stop service cron on debian, if running
      systemd:
        name: cron
        state: stopped

    - name: restart service cron on centos, in all cases, also issue daemon-reload to pick up config changes
      systemd:
        state: restarted
        daemon_reload: yes
        name: crond

    - name: reload service httpd, in all cases
      systemd:
        name: httpd
        state: reloaded

    - name: enable service httpd and ensure it is not masked
      systemd:
        name: httpd
        enabled: yes
        masked: no

    - name: enable a timer for dnf-automatic
      systemd:
        name: dnf-automatic.timer
        state: started
        enabled: yes

    - name: just force systemd to reread configs (2.4 and above)
      systemd:
        daemon_reload: yes

    - name: just force systemd to re-execute itself (2.8 and above)
      systemd:
        daemon_reexec: yes

## Return Values

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

Key | Returned | Description
--- | --- | ---
status complex | success | A dictionary with the key=value pairs returned from `systemctl show` Sample: {'ActiveEnterTimestamp': 'Sun 2016-05-15 18:28:49 EDT', 'ActiveEnterTimestampMonotonic': '8135942', 'ActiveExitTimestampMonotonic': '0', 'ActiveState': 'active', 'After': 'auditd.service systemd-user-sessions.service time-sync.target systemd-journald.socket basic.target system.slice', 'AllowIsolate': 'no', 'Before': 'shutdown.target multi-user.target', 'BlockIOAccounting': 'no', 'BlockIOWeight': '1000', 'CPUAccounting': 'no', 'CPUSchedulingPolicy': '0', 'CPUSchedulingPriority': '0', 'CPUSchedulingResetOnFork': 'no', 'CPUShares': '1024', 'CanIsolate': 'no', 'CanReload': 'yes', 'CanStart': 'yes', 'CanStop': 'yes', 'CapabilityBoundingSet': '18446744073709551615', 'ConditionResult': 'yes', 'ConditionTimestamp': 'Sun 2016-05-15 18:28:49 EDT', 'ConditionTimestampMonotonic': '7902742', 'Conflicts': 'shutdown.target', 'ControlGroup': '/system.slice/crond.service', 'ControlPID': '0', 'DefaultDependencies': 'yes', 'Delegate': 'no', 'Description': 'Command Scheduler', 'DevicePolicy': 'auto', 'EnvironmentFile': '/etc/sysconfig/crond (ignore_errors=no)', 'ExecMainCode': '0', 'ExecMainExitTimestampMonotonic': '0', 'ExecMainPID': '595', 'ExecMainStartTimestamp': 'Sun 2016-05-15 18:28:49 EDT', 'ExecMainStartTimestampMonotonic': '8134990', 'ExecMainStatus': '0', 'ExecReload': '{ path=/bin/kill ; argv[]=/bin/kill -HUP $MAINPID ; ignore_errors=no ; start_time=[n/a] ; stop_time=[n/a] ; pid=0 ; code=(null) ; status=0/0 }', 'ExecStart': '{ path=/usr/sbin/crond ; argv[]=/usr/sbin/crond -n $CRONDARGS ; ignore_errors=no ; start_time=[n/a] ; stop_time=[n/a] ; pid=0 ; code=(null) ; status=0/0 }', 'FragmentPath': '/usr/lib/systemd/system/crond.service', 'GuessMainPID': 'yes', 'IOScheduling': '0', 'Id': 'crond.service', 'IgnoreOnIsolate': 'no', 'IgnoreOnSnapshot': 'no', 'IgnoreSIGPIPE': 'yes', 'InactiveEnterTimestampMonotonic': '0', 'InactiveExitTimestamp': 'Sun 2016-05-15 18:28:49 EDT', 'InactiveExitTimestampMonotonic': '8135942', 'JobTimeoutUSec': '0', 'KillMode': 'process', 'KillSignal': '15', 'LimitAS': '18446744073709551615', 'LimitCORE': '18446744073709551615', 'LimitCPU': '18446744073709551615', 'LimitDATA': '18446744073709551615', 'LimitFSIZE': '18446744073709551615', 'LimitLOCKS': '18446744073709551615', 'LimitMEMLOCK': '65536', 'LimitMSGQUEUE': '819200', 'LimitNICE': '0', 'LimitNOFILE': '4096', 'LimitNPROC': '3902', 'LimitRSS': '18446744073709551615', 'LimitRTPRIO': '0', 'LimitRTTIME': '18446744073709551615', 'LimitSIGPENDING': '3902', 'LimitSTACK': '18446744073709551615', 'LoadState': 'loaded', 'MainPID': '595', 'MemoryAccounting': 'no', 'MemoryLimit': '18446744073709551615', 'MountFlags': '0', 'Names': 'crond.service', 'NeedDaemonReload': 'no', 'Nice': '0', 'NoNewPrivileges': 'no', 'NonBlocking': 'no', 'NotifyAccess': 'none', 'OOMScoreAdjust': '0', 'OnFailureIsolate': 'no', 'PermissionsStartOnly': 'no', 'PrivateNetwork': 'no', 'PrivateTmp': 'no', 'RefuseManualStart': 'no', 'RefuseManualStop': 'no', 'RemainAfterExit': 'no', 'Requires': 'basic.target', 'Restart': 'no', 'RestartUSec': '100ms', 'Result': 'success', 'RootDirectoryStartOnly': 'no', 'SameProcessGroup': 'no', 'SecureBits': '0', 'SendSIGHUP': 'no', 'SendSIGKILL': 'yes', 'Slice': 'system.slice', 'StandardError': 'inherit', 'StandardInput': 'null', 'StandardOutput': 'journal', 'StartLimitAction': 'none', 'StartLimitBurst': '5', 'StartLimitInterval': '10000000', 'StatusErrno': '0', 'StopWhenUnneeded': 'no', 'SubState': 'running', 'SyslogLevelPrefix': 'yes', 'SyslogPriority': '30', 'TTYReset': 'no', 'TTYVHangup': 'no', 'TTYVTDisallocate': 'no', 'TimeoutStartUSec': '1min 30s', 'TimeoutStopUSec': '1min 30s', 'TimerSlackNSec': '50000', 'Transient': 'no', 'Type': 'simple', 'UMask': '0022', 'UnitFileState': 'enabled', 'WantedBy': 'multi-user.target', 'Wants': 'system.slice', 'WatchdogTimestampMonotonic': '0', 'WatchdogUSec': '0'}

## Status

- This module is guaranteed to have backward compatible interface changes going forward. [stableinterface]
- This module is maintained by the Ansible Core Team. [core]

### Red Hat Support

More information about Red Hat’s support of this module is available from this Red Hat Knowledge Base article.

### Authors

- Ansible Core Team

Hint

If you notice any issues in this documentation, you can edit this document to improve it.