Documentation

systemd - Manage services

New in version 2.2.

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_reload
    Choices:
  • no ←
  • yes
run daemon-reload before doing any other operations, to make sure systemd has read any changes.

aliases: daemon-reload
enabled
    Choices:
  • no
  • yes
Whether the service should start on boot. At least one of state and enabled are required.
masked
    Choices:
  • no
  • yes
Whether the unit should be masked or not, a masked unit is impossible to start.
name
Name of the service. When using in a chroot environment you always need to specify the full name i.e. (crond.service).

aliases: service, unit
no_block
(added in 2.3)
    Choices:
  • no ←
  • yes
Do not synchronously wait for the requested operation to finish. Enqueued job will continue without Ansible blocking on its completion.
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
    Choices:
  • no ←
  • yes
run systemctl talking to the service manager of the calling user, rather than the service manager of the system.

Notes

Note

  • Since 2.4, one of the following options is required ‘state’, ‘enabled’, ‘masked’, ‘daemon_reload’, and all except ‘daemon_reload’ also require ‘name’.
  • Before 2.4 you always required ‘name’.

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: True

- name: just force systemd to reread configs (2.4 and above)
  systemd: daemon_reload=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`

 
ActiveEnterTimestamp

 
ActiveEnterTimestampMonotonic

 
ActiveExitTimestampMonotonic

 
ActiveState

 
After

 
AllowIsolate

 
Before

 
BlockIOAccounting

 
BlockIOWeight

 
CPUAccounting

 
CPUSchedulingPolicy

 
CPUSchedulingPriority

 
CPUSchedulingResetOnFork

 
CPUShares

 
CanIsolate

 
CanReload

 
CanStart

 
CanStop

 
CapabilityBoundingSet

 
ConditionResult

 
ConditionTimestamp

 
ConditionTimestampMonotonic

 
Conflicts

 
ControlGroup

 
ControlPID

 
DefaultDependencies

 
Delegate

 
Description

 
DevicePolicy

 
EnvironmentFile

 
ExecMainCode

 
ExecMainExitTimestampMonotonic

 
ExecMainPID

 
ExecMainStartTimestamp

 
ExecMainStartTimestampMonotonic

 
ExecMainStatus

 
ExecReload

 
ExecStart

 
FragmentPath

 
GuessMainPID

 
IOScheduling

 
Id

 
IgnoreOnIsolate

 
IgnoreOnSnapshot

 
IgnoreSIGPIPE

 
InactiveEnterTimestampMonotonic

 
InactiveExitTimestamp

 
InactiveExitTimestampMonotonic

 
JobTimeoutUSec

 
KillMode

 
KillSignal

 
LimitAS

 
LimitCORE

 
LimitCPU

 
LimitDATA

 
LimitFSIZE

 
LimitLOCKS

 
LimitMEMLOCK

 
LimitMSGQUEUE

 
LimitNICE

 
LimitNOFILE

 
LimitNPROC

 
LimitRSS

 
LimitRTPRIO

 
LimitRTTIME

 
LimitSIGPENDING

 
LimitSTACK

 
LoadState

 
MainPID

 
MemoryAccounting

 
MemoryLimit

 
MountFlags

 
Names

 
NeedDaemonReload

 
Nice

 
NoNewPrivileges

 
NonBlocking

 
NotifyAccess

 
OOMScoreAdjust

 
OnFailureIsolate

 
PermissionsStartOnly

 
PrivateNetwork

 
PrivateTmp

 
RefuseManualStart

 
RefuseManualStop

 
RemainAfterExit

 
Requires

 
Restart

 
RestartUSec

 
Result

 
RootDirectoryStartOnly

 
SameProcessGroup

 
SecureBits

 
SendSIGHUP

 
SendSIGKILL

 
Slice

 
StandardError

 
StandardInput

 
StandardOutput

 
StartLimitAction

 
StartLimitBurst

 
StartLimitInterval

 
StatusErrno

 
StopWhenUnneeded

 
SubState

 
SyslogLevelPrefix

 
SyslogPriority

 
TTYReset

 
TTYVHangup

 
TTYVTDisallocate

 
TimeoutStartUSec

 
TimeoutStopUSec

 
TimerSlackNSec

 
Transient

 
Type

 
UMask

 
UnitFileState

 
WantedBy

 
Wants

 
WatchdogTimestampMonotonic

 
WatchdogUSec



Status

This module is flagged as stableinterface which means that the maintainers for this module guarantee that no backward incompatible interface changes will be made.

Support

For more information about Red Hat’s support of this module, please refer to this Knowledge Base article

Author

  • Ansible Core Team

Hint

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