New module: shutdown (#700)

* New module: shutdown

* Add symlink to plugin

* Fix

Signed-off-by: Amin Vakil <info@aminvakil.com>

* Fix

* Fix

* Add seealso

* Fix seealso

* Add future-import, metaclass boilerplate

* Change pre_shutdown_delay to delay

* Cleanup before executing shutdown

* Fix

* Remove unused connect_timeout paramater

* Improve documentation

* Remove deprecated function and calling it

* Remove double calling delay function

* Remove unneeded call in check delay function

* Make check mode more realistic

* Remove extra blank line

* Remove unnecessary imports and fix copyright year

* Add shutdown_command and integration test

* Fix integration test

* Don't fail on local AND enabled check_mode

* Add copyright

* Skip ubuntu1804 as systemd-sysv is not installed on container

* Ignore ubuntu 18 on task

* Readd integration tests

* Do not run integration test on ubuntu 18

* Improve integration test and add delay, msg testing

* Fix ubuntu 18 integration test

* Remove unnecessary condition

plugins/action/shutdown.py

@@ -0,0 +1 @@
+./system/shutdown.py

plugins/action/system/shutdown.py

@@ -0,0 +1,211 @@
+# Copyright: (c) 2020, Amin Vakil <info@aminvakil.com>
+# Copyright: (c) 2016-2018, Matt Davis <mdavis@ansible.com>
+# Copyright: (c) 2018, Sam Doran <sdoran@redhat.com>
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+from ansible.errors import AnsibleError, AnsibleConnectionFailure
+from ansible.module_utils._text import to_native, to_text
+from ansible.module_utils.common.collections import is_string
+from ansible.plugins.action import ActionBase
+from ansible.utils.display import Display
+
+display = Display()
+
+
+class TimedOutException(Exception):
+    pass
+
+
+class ActionModule(ActionBase):
+    TRANSFERS_FILES = False
+    _VALID_ARGS = frozenset((
+        'msg',
+        'delay',
+        'search_paths'
+    ))
+
+    DEFAULT_CONNECT_TIMEOUT = None
+    DEFAULT_PRE_SHUTDOWN_DELAY = 0
+    DEFAULT_SHUTDOWN_MESSAGE = 'Shut down initiated by Ansible'
+    DEFAULT_SHUTDOWN_COMMAND = 'shutdown'
+    DEFAULT_SHUTDOWN_COMMAND_ARGS = '-h {delay_min} "{message}"'
+    DEFAULT_SUDOABLE = True
+
+    SHUTDOWN_COMMANDS = {
+        'alpine': 'poweroff',
+        'vmkernel': 'halt',
+    }
+
+    SHUTDOWN_COMMAND_ARGS = {
+        'alpine': '',
+        'void': '-h +{delay_min} "{message}"',
+        'freebsd': '-h +{delay_sec}s "{message}"',
+        'linux': DEFAULT_SHUTDOWN_COMMAND_ARGS,
+        'macosx': '-h +{delay_min} "{message}"',
+        'openbsd': '-h +{delay_min} "{message}"',
+        'solaris': '-y -g {delay_sec} -i 5 "{message}"',
+        'sunos': '-y -g {delay_sec} -i 5 "{message}"',
+        'vmkernel': '-d {delay_sec}',
+        'aix': '-Fh',
+    }
+
+    def __init__(self, *args, **kwargs):
+        super(ActionModule, self).__init__(*args, **kwargs)
+
+    @property
+    def delay(self):
+        return self._check_delay('delay', self.DEFAULT_PRE_SHUTDOWN_DELAY)
+
+    def _check_delay(self, key, default):
+        """Ensure that the value is positive or zero"""
+        value = int(self._task.args.get(key, default))
+        if value < 0:
+            value = 0
+        return value
+
+    def _get_value_from_facts(self, variable_name, distribution, default_value):
+        """Get dist+version specific args first, then distribution, then family, lastly use default"""
+        attr = getattr(self, variable_name)
+        value = attr.get(
+            distribution['name'] + distribution['version'],
+            attr.get(
+                distribution['name'],
+                attr.get(
+                    distribution['family'],
+                    getattr(self, default_value))))
+        return value
+
+    def get_shutdown_command_args(self, distribution):
+        args = self._get_value_from_facts('SHUTDOWN_COMMAND_ARGS', distribution, 'DEFAULT_SHUTDOWN_COMMAND_ARGS')
+        # Convert seconds to minutes. If less that 60, set it to 0.
+        delay_sec = self.delay
+        shutdown_message = self._task.args.get('msg', self.DEFAULT_SHUTDOWN_MESSAGE)
+        return args.format(delay_sec=delay_sec, delay_min=delay_sec // 60, message=shutdown_message)
+
+    def get_distribution(self, task_vars):
+        # FIXME: only execute the module if we don't already have the facts we need
+        distribution = {}
+        display.debug('{action}: running setup module to get distribution'.format(action=self._task.action))
+        module_output = self._execute_module(
+            task_vars=task_vars,
+            module_name='ansible.legacy.setup',
+            module_args={'gather_subset': 'min'})
+        try:
+            if module_output.get('failed', False):
+                raise AnsibleError('Failed to determine system distribution. {0}, {1}'.format(
+                    to_native(module_output['module_stdout']).strip(),
+                    to_native(module_output['module_stderr']).strip()))
+            distribution['name'] = module_output['ansible_facts']['ansible_distribution'].lower()
+            distribution['version'] = to_text(module_output['ansible_facts']['ansible_distribution_version'].split('.')[0])
+            distribution['family'] = to_text(module_output['ansible_facts']['ansible_os_family'].lower())
+            display.debug("{action}: distribution: {dist}".format(action=self._task.action, dist=distribution))
+            return distribution
+        except KeyError as ke:
+            raise AnsibleError('Failed to get distribution information. Missing "{0}" in output.'.format(ke.args[0]))
+
+    def get_shutdown_command(self, task_vars, distribution):
+        shutdown_bin = self._get_value_from_facts('SHUTDOWN_COMMANDS', distribution, 'DEFAULT_SHUTDOWN_COMMAND')
+        default_search_paths = ['/sbin', '/usr/sbin', '/usr/local/sbin']
+        search_paths = self._task.args.get('search_paths', default_search_paths)
+
+        # FIXME: switch all this to user arg spec validation methods when they are available
+        # Convert bare strings to a list
+        if is_string(search_paths):
+            search_paths = [search_paths]
+
+        # Error if we didn't get a list
+        err_msg = "'search_paths' must be a string or flat list of strings, got {0}"
+        try:
+            incorrect_type = any(not is_string(x) for x in search_paths)
+            if not isinstance(search_paths, list) or incorrect_type:
+                raise TypeError
+        except TypeError:
+            raise AnsibleError(err_msg.format(search_paths))
+
+        display.debug('{action}: running find module looking in {paths} to get path for "{command}"'.format(
+            action=self._task.action,
+            command=shutdown_bin,
+            paths=search_paths))
+        find_result = self._execute_module(
+            task_vars=task_vars,
+            # prevent collection search by calling with ansible.legacy (still allows library/ override of find)
+            module_name='ansible.legacy.find',
+            module_args={
+                'paths': search_paths,
+                'patterns': [shutdown_bin],
+                'file_type': 'any'
+            }
+        )
+
+        full_path = [x['path'] for x in find_result['files']]
+        if not full_path:
+            raise AnsibleError('Unable to find command "{0}" in search paths: {1}'.format(shutdown_bin, search_paths))
+        self._shutdown_command = full_path[0]
+        return self._shutdown_command
+
+    def perform_shutdown(self, task_vars, distribution):
+        result = {}
+        shutdown_result = {}
+        shutdown_command = self.get_shutdown_command(task_vars, distribution)
+        shutdown_command_args = self.get_shutdown_command_args(distribution)
+        shutdown_command_exec = '{0} {1}'.format(shutdown_command, shutdown_command_args)
+
+        self.cleanup(force=True)
+        try:
+            display.vvv("{action}: shutting down server...".format(action=self._task.action))
+            display.debug("{action}: shutting down server with command '{command}'".format(action=self._task.action, command=shutdown_command_exec))
+            if self._play_context.check_mode:
+                shutdown_result['rc'] = 0
+            else:
+                shutdown_result = self._low_level_execute_command(shutdown_command_exec, sudoable=self.DEFAULT_SUDOABLE)
+        except AnsibleConnectionFailure as e:
+            # If the connection is closed too quickly due to the system being shutdown, carry on
+            display.debug('{action}: AnsibleConnectionFailure caught and handled: {error}'.format(action=self._task.action, error=to_text(e)))
+            shutdown_result['rc'] = 0
+
+        if shutdown_result['rc'] != 0:
+            result['failed'] = True
+            result['shutdown'] = False
+            result['msg'] = "Shutdown command failed. Error was {stdout}, {stderr}".format(
+                stdout=to_native(shutdown_result['stdout'].strip()),
+                stderr=to_native(shutdown_result['stderr'].strip()))
+            return result
+
+        result['failed'] = False
+        result['shutdown_command'] = shutdown_command_exec
+        return result
+
+    def run(self, tmp=None, task_vars=None):
+        self._supports_check_mode = True
+        self._supports_async = True
+
+        # If running with local connection, fail so we don't shutdown ourself
+        if self._connection.transport == 'local' and (not self._play_context.check_mode):
+            msg = 'Running {0} with local connection would shutdown the control node.'.format(self._task.action)
+            return {'changed': False, 'elapsed': 0, 'shutdown': False, 'failed': True, 'msg': msg}
+
+        if task_vars is None:
+            task_vars = {}
+
+        result = super(ActionModule, self).run(tmp, task_vars)
+
+        if result.get('skipped', False) or result.get('failed', False):
+            return result
+
+        distribution = self.get_distribution(task_vars)
+
+        # Initiate shutdown
+        shutdown_result = self.perform_shutdown(task_vars, distribution)
+
+        if shutdown_result['failed']:
+            result = shutdown_result
+            return result
+
+        result['shutdown'] = True
+        result['changed'] = True
+        result['shutdown_command'] = shutdown_result['shutdown_command']
+
+        return result

plugins/modules/shutdown.py

@@ -0,0 +1 @@
+./system/shutdown.py

plugins/modules/system/shutdown.py

@@ -0,0 +1,68 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+# Copyright: (c) 2020, Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+
+DOCUMENTATION = r'''
+module: shutdown
+short_description: Shut down a machine
+notes:
+  - C(PATH) is ignored on the remote node when searching for the C(shutdown) command. Use I(search_paths)
+    to specify locations to search if the default paths do not work.
+description:
+    - Shut downs a machine.
+version_added: "1.1.0"
+options:
+  delay:
+    description:
+      - 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 will be set to 0.
+      - On Solaris and FreeBSD, this will be seconds.
+    type: int
+    default: 0
+  msg:
+    description:
+      - Message to display to users before shutdown.
+    type: str
+    default: Shut down initiated by Ansible
+  search_paths:
+    description:
+      - Paths to search on the remote machine for the C(shutdown) command.
+      - I(Only) these paths will be searched for the C(shutdown) command. C(PATH) is ignored in the remote node when searching for the C(shutdown) command.
+    type: list
+    elements: path
+    default: ['/sbin', '/usr/sbin', '/usr/local/sbin']
+
+seealso:
+- module: ansible.builtin.reboot
+author:
+    - Matt Davis (@nitzmahone)
+    - Sam Doran (@samdoran)
+    - Amin Vakil (@aminvakil)
+'''
+
+EXAMPLES = r'''
+- 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 = r'''
+shutdown:
+  description: C(true) if the machine has been shut down.
+  returned: always
+  type: bool
+  sample: true
+'''

tests/integration/targets/shutdown/aliases

@@ -0,0 +1 @@
+shippable/posix/group1

tests/integration/targets/shutdown/tasks/main.yml

@@ -0,0 +1,84 @@
+---
+- name: Install systemd-sysv on ubuntu 18
+  apt:
+    name: systemd-sysv
+    state: present
+  when: ansible_distribution == 'Ubuntu' and ansible_distribution_major_version is version('18', '>=')
+  register: systemd_sysv_install
+
+- name: Execute shutdown with custom message and delay
+  community.general.shutdown:
+    delay: 100
+    msg: "Custom Message"
+  register: shutdown_result
+  check_mode: yes
+
+- name: Execute shutdown with minus delay
+  community.general.shutdown:
+    delay: -100
+  register: shutdown_result_minus
+  check_mode: yes
+
+- name: Verify Custom Message except Alpine, AIX
+  assert:
+    that:
+      - '"Custom Message" in shutdown_result["shutdown_command"]'
+      - '"Shut down initiated by Ansible" in shutdown_result_minus["shutdown_command"]'
+      - '"Custom Message" not in shutdown_result_minus["shutdown_command"]'
+  when: ansible_os_family not in ['Alpine', 'AIX']
+
+- name: Verify shutdown command is present except Alpine, VMKernel
+  assert:
+    that: '"shutdown" in shutdown_result["shutdown_command"]'
+  when: ansible_os_family != 'Alpine' and ansible_system != 'VMKernel'
+
+- name: Verify shutdown command is present in Alpine
+  assert:
+    that: '"poweroff" in shutdown_result["shutdown_command"]'
+  when: ansible_os_family == 'Alpine'
+
+- name: Verify shutdown command is present in VMKernel
+  assert:
+    that: '"halt" in shutdown_result["shutdown_command"]'
+  when: ansible_system == 'VMKernel'
+
+- name: Verify shutdown delay is present in minutes in Linux
+  assert:
+    that:
+      - '"-h 1" in shutdown_result["shutdown_command"]'
+      - '"-h 0" in shutdown_result_minus["shutdown_command"]'
+  when: ansible_system == 'Linux' and ansible_os_family != 'Alpine'
+
+- name: Verify shutdown delay is present in minutes in Void, MacOSX, OpenBSD
+  assert:
+    that:
+      - '"-h +1" in shutdown_result["shutdown_command"]'
+      - '"-h +0" in shutdown_result_minus["shutdown_command"]'
+  when: ansible_system in ['Void', 'MacOSX', 'OpenBSD']
+
+- name: Verify shutdown delay is present in seconds in FreeBSD
+  assert:
+    that:
+      - '"-h +100s" in shutdown_result["shutdown_command"]'
+      - '"-h +0s" in shutdown_result_minus["shutdown_command"]'
+  when: ansible_system == 'FreeBSD'
+
+- name: Verify shutdown delay is present in seconds in Solaris, SunOS
+  assert:
+    that:
+      - '"-g 100" in shutdown_result["shutdown_command"]'
+      - '"-g 0" in shutdown_result_minus["shutdown_command"]'
+  when: ansible_system in ['Solaris', 'SunOS']
+
+- name: Verify shutdown delay is present in seconds, VMKernel
+  assert:
+    that:
+      - '"-d 100" in shutdown_result["shutdown_command"]'
+      - '"-d 0" in shutdown_result_minus["shutdown_command"]'
+  when: ansible_system == 'VMKernel'
+
+- name: Remove systemd_sysv in ubuntu 18 in case it has been installed in test
+  apt:
+    name: systemd-sysv
+    state: absent
+  when: systemd_sysv_install is changed