community.general.shutdown module – Shut down a machine

Note

This module is part of the community.general collection (version 10.7.5).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install community.general.

To use it in a playbook, specify: community.general.shutdown.

New in community.general 1.1.0

Synopsis

  • Shut downs a machine.

Note

This module has a corresponding action plugin.

Parameters

Parameter

Comments

delay

integer

Seconds to wait before shutdown. Passed as a parameter to the shutdown command.

On Linux, macOS and OpenBSD, this is converted to minutes and rounded down. If less than 60, it is set to 0.

On Solaris and FreeBSD, this represents seconds.

Default: 0

msg

string

Message to display to users before shutdown.

Default: "Shut down initiated by Ansible"

search_paths

list / elements=path

Paths to search on the remote machine for the shutdown command.

Only these paths are searched for the shutdown command. PATH is ignored in the remote node when searching for the shutdown command.

Default: ["/sbin", "/usr/sbin", "/usr/local/sbin"]

Attributes

Attribute

Support

Description

action

Support: full

Indicates this has a corresponding action plugin so some parts of the options can be executed on the controller.

async

Support: full

Supports being used with the async keyword.

check_mode

Support: full

Can run in check_mode and return changed status prediction without modifying target.

diff_mode

Support: none

Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode.

Notes

Note

  • PATH is ignored on the remote node when searching for the shutdown command. Use search_paths to specify locations to search if the default paths do not work.

  • The msg and delay options are not supported when a shutdown command is not found in search_paths, instead the module attempts to shutdown the system by calling systemctl shutdown.

See Also

See also

ansible.builtin.reboot

Reboot a machine.

Examples

- name: Unconditionally shut down the machine with all defaults
  community.general.shutdown:

- name: Delay shutting down the remote node
  community.general.shutdown:
    delay: 60

- name: Shut down a machine with shutdown command in unusual place
  community.general.shutdown:
    search_paths:
      - '/lib/molly-guard'

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key

Description

shutdown

boolean

true if the machine has been shut down.

Returned: always

Sample: true

Authors

  • Matt Davis (@nitzmahone)

  • Sam Doran (@samdoran)

  • Amin Vakil (@aminvakil)