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.