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

aliases: daemon-reload
enabled
bool
    Choices:
  • no
  • yes
Whether the service should start on boot. At least one of state and enabled are required.
force
bool

(added in 2.6)
    Choices:
  • no
  • yes
Whether to override existing symlinks.
masked
bool
    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
bool

(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.
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).
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
bool
    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’, 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: yes

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

Maintenance

This module is flagged as core which means that it is maintained by the Ansible Core Team. See Module Maintenance & Support for more info.

For a list of other modules that are also maintained by the Ansible Core Team, see here.

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.