Documentation

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

    # 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 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'}


    Notes

    Note

    • One option other than name is required.

    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

    This module is maintained by those with core commit privileges

    For more information on what this means please read Module Support

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