systemd - Manage services.

New in version 2.2.


Controls systemd services on remote hosts.

Requirements (on host that executes module)

  • A system managed by systemd


parameter required default choices comments
  • yes
  • no
run daemon-reload before doing any other operations, to make sure systemd has read any changes.
aliases: daemon-reload
  • yes
  • no
Whether the service should start on boot. At least one of state and enabled are required.
  • yes
  • no
Whether the unit should be masked or not, a masked unit is impossible to start.
Name of the service.
aliases: unit, service
  • 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.
  • yes
  • no
run systemctl talking to the service manager of the calling user, rather than the service manager of the system.


# Example action to start service httpd, if not running
- systemd: state=started name=httpd
# Example action to stop service cron on debian, if running
- systemd: name=cron state=stopped
# Example action to 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
# Example action to reload service httpd, in all cases
- systemd: name=httpd state=reloaded
# Example action to enable service httpd and ensure it is not masked
- systemd:
    name: httpd
    enabled: yes
    masked: no
# Example action to enable a timer for dnf-automatic
- systemd:
    name: dnf-automatic.timer
    state: started
    enabled: True

Return Values

Common return values are documented here Common 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 {'ExecStart': '{ path=/usr/sbin/crond ; argv[]=/usr/sbin/crond -n $CRONDARGS ; ignore_errors=no ; start_time=[n/a] ; stop_time=[n/a] ; pid=0 ; code=(null) ; status=0/0 }', 'ConditionResult': 'yes', 'TimeoutStopUSec': '1min 30s', 'ControlGroup': '/system.slice/crond.service', 'MainPID': '595', 'GuessMainPID': 'yes', 'ExecMainCode': '0', 'InactiveExitTimestamp': 'Sun 2016-05-15 18:28:49 EDT', 'FragmentPath': '/usr/lib/systemd/system/crond.service', 'UnitFileState': 'enabled', 'ExecMainPID': '595', 'LimitSIGPENDING': '3902', 'WatchdogUSec': '0', 'ActiveState': 'active', 'Nice': '0', 'OOMScoreAdjust': '0', 'LoadState': 'loaded', 'DefaultDependencies': 'yes', 'StatusErrno': '0', 'RootDirectoryStartOnly': 'no', 'WantedBy': 'multi-user.target', 'TTYVTDisallocate': 'no', 'RestartUSec': '100ms', 'Transient': 'no', 'CPUAccounting': 'no', 'CPUSchedulingPolicy': '0', 'StartLimitInterval': '10000000', 'WatchdogTimestampMonotonic': '0', 'LimitSTACK': '18446744073709551615', 'Restart': 'no', 'RemainAfterExit': 'no', 'LimitNOFILE': '4096', 'CanReload': 'yes', 'LimitLOCKS': '18446744073709551615', 'AllowIsolate': 'no', 'IgnoreOnSnapshot': 'no', 'CanIsolate': 'no', 'ActiveEnterTimestampMonotonic': '8135942', 'NeedDaemonReload': 'no', 'TTYVHangup': 'no', 'EnvironmentFile': '/etc/sysconfig/crond (ignore_errors=no)', 'StandardInput': 'null', 'CPUSchedulingPriority': '0', 'KillSignal': '15', 'LimitFSIZE': '18446744073709551615', 'IgnoreOnIsolate': 'no', 'Requires': 'basic.target', 'LimitCPU': '18446744073709551615', 'ActiveEnterTimestamp': 'Sun 2016-05-15 18:28:49 EDT', 'ExecMainStatus': '0', 'PermissionsStartOnly': 'no', 'LimitDATA': '18446744073709551615', 'MemoryLimit': '18446744073709551615', 'StopWhenUnneeded': 'no', 'LimitMSGQUEUE': '819200', 'OnFailureIsolate': 'no', 'CanStart': 'yes', 'PrivateTmp': 'no', 'Before': 'shutdown.target multi-user.target', 'IOScheduling': '0', 'LimitAS': '18446744073709551615', 'Slice': 'system.slice', 'ExecMainExitTimestampMonotonic': '0', 'LimitRTTIME': '18446744073709551615', 'InactiveExitTimestampMonotonic': '8135942', 'NotifyAccess': 'none', 'SendSIGHUP': 'no', 'BlockIOAccounting': 'no', 'PrivateNetwork': 'no', 'MemoryAccounting': 'no', 'CanStop': 'yes', 'NoNewPrivileges': 'no', 'ExecMainStartTimestampMonotonic': '8134990', 'Type': 'simple', 'SyslogPriority': '30', 'SameProcessGroup': 'no', 'SubState': 'running', 'TimeoutStartUSec': '1min 30s', 'StartLimitBurst': '5', 'LimitNPROC': '3902', 'After': 'auditd.service systemd-user-sessions.service time-sync.target systemd-journald.socket basic.target system.slice', 'UMask': '0022', 'NonBlocking': 'no', 'DevicePolicy': 'auto', 'RefuseManualStop': 'no', 'ExecMainStartTimestamp': 'Sun 2016-05-15 18:28:49 EDT', 'StartLimitAction': 'none', 'Conflicts': 'shutdown.target', 'ConditionTimestamp': 'Sun 2016-05-15 18:28:49 EDT', 'CapabilityBoundingSet': '18446744073709551615', 'TTYReset': 'no', 'Names': 'crond.service', 'Wants': 'system.slice', 'StandardOutput': 'journal', 'MountFlags': '0', 'RefuseManualStart': 'no', 'InactiveEnterTimestampMonotonic': '0', 'KillMode': 'process', 'SyslogLevelPrefix': 'yes', 'LimitRSS': '18446744073709551615', 'StandardError': 'inherit', 'SendSIGKILL': 'yes', 'LimitRTPRIO': '0', 'IgnoreSIGPIPE': 'yes', 'Delegate': 'no', 'ExecReload': '{ path=/bin/kill ; argv[]=/bin/kill -HUP $MAINPID ; ignore_errors=no ; start_time=[n/a] ; stop_time=[n/a] ; pid=0 ; code=(null) ; status=0/0 }', 'SecureBits': '0', 'Description': 'Command Scheduler', 'LimitCORE': '18446744073709551615', 'ActiveExitTimestampMonotonic': '0', 'JobTimeoutUSec': '0', 'TimerSlackNSec': '50000', 'LimitNICE': '0', 'BlockIOWeight': '1000', 'CPUSchedulingResetOnFork': 'no', 'Result': 'success', 'CPUShares': '1024', 'ControlPID': '0', 'Id': 'crond.service', 'ConditionTimestampMonotonic': '7902742', 'LimitMEMLOCK': '65536'}



One option other than name is required.

This is a Core Module

For more information on what this means please read Core Modules

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

© 2012–2016 Michael DeHaan
© 2016 Red Hat, Inc.
Licensed under the GNU General Public License version 3.