From c475effeedbf643de5d2967eee001b496d52a033 Mon Sep 17 00:00:00 2001 From: Amin Vakil Date: Tue, 11 Aug 2020 20:24:41 +0430 Subject: [PATCH] New module: shutdown (#700) * New module: shutdown * Add symlink to plugin * Fix Signed-off-by: Amin Vakil * 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 | 1 + plugins/action/system/shutdown.py | 211 ++++++++++++++++++ plugins/modules/shutdown.py | 1 + plugins/modules/system/shutdown.py | 68 ++++++ tests/integration/targets/shutdown/aliases | 1 + .../targets/shutdown/tasks/main.yml | 84 +++++++ 6 files changed, 366 insertions(+) create mode 120000 plugins/action/shutdown.py create mode 100644 plugins/action/system/shutdown.py create mode 120000 plugins/modules/shutdown.py create mode 100644 plugins/modules/system/shutdown.py create mode 100644 tests/integration/targets/shutdown/aliases create mode 100644 tests/integration/targets/shutdown/tasks/main.yml diff --git a/plugins/action/shutdown.py b/plugins/action/shutdown.py new file mode 120000 index 0000000000..260ca8ece4 --- /dev/null +++ b/plugins/action/shutdown.py @@ -0,0 +1 @@ +./system/shutdown.py \ No newline at end of file diff --git a/plugins/action/system/shutdown.py b/plugins/action/system/shutdown.py new file mode 100644 index 0000000000..e36397ffe7 --- /dev/null +++ b/plugins/action/system/shutdown.py @@ -0,0 +1,211 @@ +# Copyright: (c) 2020, Amin Vakil +# Copyright: (c) 2016-2018, Matt Davis +# Copyright: (c) 2018, Sam Doran +# 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 diff --git a/plugins/modules/shutdown.py b/plugins/modules/shutdown.py new file mode 120000 index 0000000000..260ca8ece4 --- /dev/null +++ b/plugins/modules/shutdown.py @@ -0,0 +1 @@ +./system/shutdown.py \ No newline at end of file diff --git a/plugins/modules/system/shutdown.py b/plugins/modules/system/shutdown.py new file mode 100644 index 0000000000..ccb02a2da0 --- /dev/null +++ b/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 +''' diff --git a/tests/integration/targets/shutdown/aliases b/tests/integration/targets/shutdown/aliases new file mode 100644 index 0000000000..a6dafcf8cd --- /dev/null +++ b/tests/integration/targets/shutdown/aliases @@ -0,0 +1 @@ +shippable/posix/group1 diff --git a/tests/integration/targets/shutdown/tasks/main.yml b/tests/integration/targets/shutdown/tasks/main.yml new file mode 100644 index 0000000000..c167e08899 --- /dev/null +++ b/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