systemd - Manage services.

New in version 2.2.

Synopsis

  • Controls systemd services on remote hosts.

Requirements (on host that executes module)

  • A system managed by systemd

Options

parameter required default choices comments
daemon_reload
 no
  • yes
  • no
run daemon-reload before doing any other operations, to make sure systemd has read any changes.
aliases: daemon-reload
enabled
 no
  • yes
  • no
Whether the service should start on boot. At least one of state and enabled are required.
masked
 no
  • yes
  • no
Whether the unit should be masked or not, a masked unit is impossible to start.
name
 no
Name of the service. When using in a chroot environment you always need to specify the full name i.e. (crond.service).
aliases: unit, service
no_block
(added in 2.3)
 no
  • yes
  • no
Do not synchronously wait for the requested operation to finish. Enqueued job will continue without Ansible blocking on its completion.
state
 no
  • started
  • stopped
  • restarted
  • reloaded
started/stopped are idempotent actions that will not run commands unless necessary. restarted will always bounce the service. reloaded will always reload.
user
 no
  • yes
  • no
run systemctl talking to the service manager of the calling user, rather than the service manager of the system.

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 Return Values, the following are the fields unique to this module:

name description returned type sample
status
A dictionary with the key=value pairs returned from `systemctl show`
 success complex
contains:
name description returned type sample
ExecStart
ConditionResult
TimeoutStopUSec
ControlGroup
MainPID
GuessMainPID
ExecMainCode
InactiveExitTimestamp
FragmentPath
UnitFileState
ExecMainPID
LimitSIGPENDING
WatchdogUSec
ActiveState
Nice
OOMScoreAdjust
LoadState
DefaultDependencies
StatusErrno
RootDirectoryStartOnly
WantedBy
TTYVTDisallocate
RestartUSec
Transient
CPUAccounting
CPUSchedulingPolicy
StartLimitInterval
WatchdogTimestampMonotonic
LimitSTACK
Restart
RemainAfterExit
LimitNOFILE
CanReload
LimitLOCKS
AllowIsolate
IgnoreOnSnapshot
CanIsolate
ActiveEnterTimestampMonotonic
NeedDaemonReload
TTYVHangup
EnvironmentFile
StandardInput
CPUSchedulingPriority
KillSignal
LimitFSIZE
IgnoreOnIsolate
Requires
LimitCPU
ActiveEnterTimestamp
ExecMainStatus
PermissionsStartOnly
LimitDATA
MemoryLimit
StopWhenUnneeded
LimitMSGQUEUE
OnFailureIsolate
CanStart
PrivateTmp
Before
IOScheduling
LimitAS
Slice
ExecMainExitTimestampMonotonic
LimitRTTIME
InactiveExitTimestampMonotonic
NotifyAccess
SendSIGHUP
BlockIOAccounting
PrivateNetwork
MemoryAccounting
CanStop
NoNewPrivileges
ExecMainStartTimestampMonotonic
Type
SyslogPriority
SameProcessGroup
SubState
TimeoutStartUSec
StartLimitBurst
LimitNPROC
After
UMask
NonBlocking
DevicePolicy
RefuseManualStop
ExecMainStartTimestamp
StartLimitAction
Conflicts
ConditionTimestamp
CapabilityBoundingSet
TTYReset
Names
Wants
StandardOutput
MountFlags
RefuseManualStart
InactiveEnterTimestampMonotonic
KillMode
SyslogLevelPrefix
LimitRSS
StandardError
SendSIGKILL
LimitRTPRIO
IgnoreSIGPIPE
Delegate
ExecReload
SecureBits
Description
LimitCORE
ActiveExitTimestampMonotonic
JobTimeoutUSec
TimerSlackNSec
LimitNICE
BlockIOWeight
CPUSchedulingResetOnFork
Result
CPUShares
ControlPID
Id
ConditionTimestampMonotonic
LimitMEMLOCK

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’.

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.

Maintenance Info

For more information about Red Hat’s this support of this module, please refer to this knowledge base article<https://access.redhat.com/articles/rhel-top-support-policies>

For help in developing on modules, should you be so inclined, please read Community Information & Contributing, Testing Ansible and Developing Modules.

© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.4/systemd_module.html