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`

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



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.

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