diff --git a/lib/ansible/modules/network/icx/icx_config.py b/lib/ansible/modules/network/icx/icx_config.py new file mode 100644 index 00000000000..44f43b6f47a --- /dev/null +++ b/lib/ansible/modules/network/icx/icx_config.py @@ -0,0 +1,484 @@ +#!/usr/bin/python +# Copyright: 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 + +ANSIBLE_METADATA = {'metadata_version': '1.1', + 'status': ['preview'], + 'supported_by': 'community'} + +DOCUMENTATION = """ +--- +module: icx_config +version_added: "2.9" +author: "Ruckus Wireless (@Commscope)" +short_description: Manage configuration sections of Ruckus ICX 7000 series switches +description: + - Ruckus ICX configurations use a simple block indent file syntax + for segmenting configuration into sections. This module provides + an implementation for working with ICX configuration sections in + a deterministic way. +notes: + - Tested against ICX 10.1. + - For information on using ICX platform, see L(the ICX OS Platform Options guide,../network/user_guide/platform_icx.html). +options: + lines: + description: + - The ordered set of commands that should be configured in the + section. The commands must be the exact same commands as found + in the device running-config. Be sure to note the configuration + command syntax as some commands are automatically modified by the + device config parser. + type: list + aliases: ['commands'] + parents: + description: + - The ordered set of parents that uniquely identify the section or hierarchy + the commands should be checked against. If the parents argument + is omitted, the commands are checked against the set of top + level or global commands. + type: list + src: + description: + - Specifies the source path to the file that contains the configuration + or configuration template to load. The path to the source file can + either be the full path on the Ansible control host or a relative + path from the playbook or role root directory. This argument is mutually + exclusive with I(lines), I(parents). + type: str + before: + description: + - The ordered set of commands to push on to the command stack if + a change needs to be made. This allows the playbook designer + the opportunity to perform configuration commands prior to pushing + any changes without affecting how the set of commands are matched + against the system. + type: list + after: + description: + - The ordered set of commands to append to the end of the command + stack if a change needs to be made. Just like with I(before) this + allows the playbook designer to append a set of commands to be + executed after the command set. + type: list + match: + description: + - Instructs the module on the way to perform the matching of + the set of commands against the current device config. If + match is set to I(line), commands are matched line by line. If + match is set to I(strict), command lines are matched with respect + to position. If match is set to I(exact), command lines + must be an equal match. Finally, if match is set to I(none), the + module will not attempt to compare the source configuration with + the running configuration on the remote device. + type: str + choices: ['line', 'strict', 'exact', 'none'] + default: line + replace: + description: + - Instructs the module on the way to perform the configuration + on the device. If the replace argument is set to I(line) then + the modified lines are pushed to the device in configuration + mode. If the replace argument is set to I(block) then the entire + command block is pushed to the device in configuration mode if any + line is not correct. + type: str + default: line + choices: ['line', 'block'] + multiline_delimiter: + description: + - This argument is used when pushing a multiline configuration + element to the ICX device. It specifies the character to use + as the delimiting character. This only applies to the + configuration action. + type: str + default: "@" + backup: + description: + - This argument will cause the module to create a full backup of + the current C(running-config) from the remote device before any + changes are made. The backup file is written to the C(backup) + folder in the playbook root directory or role root directory, if + playbook is part of an ansible role. If the directory does not exist, + it is created. + type: bool + default: 'no' + defaults: + description: + - This argument specifies whether or not to collect all defaults + when getting the remote device running config. When enabled, + the module will get the current config by issuing the command + C(show running-config all). + type: bool + default: 'no' + running_config: + description: + - The module, by default, will connect to the remote device and + retrieve the current running-config to use as a base for comparing + against the contents of source. There are times when it is not + desirable to have the task get the current running-config for + every task in a playbook. The I(running_config) argument allows the + implementer to pass in the configuration to use as the base + config for comparison. + type: str + aliases: ['config'] + save_when: + description: + - When changes are made to the device running-configuration, the + changes are not copied to non-volatile storage by default. Using + this argument will change that before. If the argument is set to + I(always), then the running-config will always be copied to the + start-up configuration and the I(modified) flag will always be set to + True. If the argument is set to I(modified), then the running-config + will only be copied to the start-up configuration if it has changed since + the last save to configuration. If the argument is set to + I(never), the running-config will never be copied to the + configuration. If the argument is set to I(changed), then the running-config + will only be copied to the configuration if the task has made a change. + type: str + default: never + choices: ['always', 'never', 'modified', 'changed'] + diff_against: + description: + - When using the C(ansible-playbook --diff) command line argument + the module can generate diffs against different sources. + - When this option is configure as I(startup), the module will return + the diff of the running-config against the configuration. + - When this option is configured as I(intended), the module will + return the diff of the running-config against the configuration + provided in the C(intended_config) argument. + - When this option is configured as I(running), the module will + return the before and after diff of the running-config with respect + to any changes made to the device configuration. + type: str + choices: ['running', 'startup', 'intended'] + diff_ignore_lines: + description: + - Use this argument to specify one or more lines that should be + ignored during the diff. This is used for lines in the configuration + that are automatically updated by the system. This argument takes + a list of regular expressions or exact line matches. + type: list + intended_config: + description: + - The C(intended_config) provides the master configuration that + the node should conform to and is used to check the final + running-config against. This argument will not modify any settings + on the remote device and is strictly used to check the compliance + of the current device's configuration against. When specifying this + argument, the task should also modify the C(diff_against) value and + set it to I(intended). + type: str +""" + +EXAMPLES = """ +- name: configure top level configuration + icx_config: + lines: hostname {{ inventory_hostname }} + +- name: configure interface settings + icx_config: + lines: + - port-name test string + - ip address 172.31.1.1 255.255.255.0 + parents: interface ethernet 1/1/2 + +- name: configure ip helpers on multiple interfaces + icx_config: + lines: + - ip helper-address 172.26.1.10 + - ip helper-address 172.26.3.8 + parents: "{{ item }}" + with_items: + - interface ethernet 1/1/2 + - interface ethernet 1/1/3 + +- name: load new acl into device + icx_config: + lines: + - permit ip host 192.0.2.1 any log + - permit ip host 192.0.2.2 any log + - permit ip host 192.0.2.3 any log + - permit ip host 192.0.2.4 any log + parents: ip access-list extended test + before: no ip access-list extended test + match: exact + +- name: check the running-config against master config + icx_config: + diff_against: intended + intended_config: "{{ lookup('file', 'master.cfg') }}" + +- name: check the configuration against the running-config + icx_config: + diff_against: startup + diff_ignore_lines: + - ntp clock .* + +- name: for idempotency, use full-form commands + icx_config: + lines: + # - en + - enable + # parents: int eth1/0/11 + parents: interface ethernet 1/1/2 + +# Set boot image based on comparison to a group_var (version) and the version +# that is returned from the `icx_facts` module +- name: SETTING BOOT IMAGE + icx_config: + lines: + - no boot system + - boot system flash bootflash:{{new_image}} + host: "{{ inventory_hostname }}" + when: ansible_net_version != version + +- name: render template onto an ICX device + icx_config: + backup: yes + src: "{{ lookup('file', 'config.j2') }}" +""" + +RETURN = """ +updates: + description: The set of commands that will be pushed to the remote device + returned: always + type: list + sample: ['hostname foo', 'router ospf 1', 'router-id 192.0.2.1'] +commands: + description: The set of commands that will be pushed to the remote device + returned: always + type: list + sample: ['hostname foo', 'router ospf 1', 'router-id 192.0.2.1'] +backup_path: + description: The full path to the backup file + returned: when backup is yes + type: str + sample: /playbooks/ansible/backup/icx_config.2016-07-16@22:28:34 +""" + +import json +from ansible.module_utils._text import to_text +from ansible.module_utils.connection import ConnectionError +from ansible.module_utils.network.icx.icx import run_commands, get_config +from ansible.module_utils.network.icx.icx import get_defaults_flag, get_connection +from ansible.module_utils.network.icx.icx import check_args as icx_check_args +from ansible.module_utils.basic import AnsibleModule +from ansible.module_utils.network.common.config import NetworkConfig, dumps + + +def check_args(module, warnings): + icx_check_args(module, warnings) + if module.params['multiline_delimiter']: + if len(module.params['multiline_delimiter']) != 1: + module.fail_json(msg='multiline_delimiter value can only be a ' + 'single character') + + +def edit_config_or_macro(connection, commands): + if "macro name" in commands[0]: + connection.edit_macro(candidate=commands) + else: + if commands[0] != '': + connection.edit_config(candidate=commands) + + +def get_candidate_config(module): + candidate = '' + if module.params['src']: + candidate = module.params['src'] + + elif module.params['lines']: + candidate_obj = NetworkConfig(indent=1) + parents = module.params['parents'] or list() + candidate_obj.add(module.params['lines'], parents=parents) + candidate = dumps(candidate_obj, 'raw') + + return candidate + + +def get_running_config(module, current_config=None, flags=None): + running = module.params['running_config'] + if not running: + if not module.params['defaults'] and current_config: + running = current_config + else: + running = get_config(module, flags=flags) + + return running + + +def save_config(module, result): + result['changed'] = True + if not module.check_mode: + run_commands(module, 'write memory') + else: + module.warn('Skipping command `copy running-config start-up configuration` ' + 'due to check_mode. Configuration not copied to ' + 'non-volatile storage') + + +def main(): + """ main entry point for module execution + """ + argument_spec = dict( + src=dict(), + lines=dict(aliases=['commands'], type='list'), + parents=dict(type='list'), + + before=dict(type='list'), + after=dict(type='list'), + + match=dict(default='line', choices=['line', 'strict', 'exact', 'none']), + replace=dict(default='line', choices=['line', 'block']), + multiline_delimiter=dict(default='@'), + + running_config=dict(aliases=['config']), + intended_config=dict(), + + defaults=dict(type='bool', default=False), + backup=dict(type='bool', default=False), + + save_when=dict(choices=['always', 'never', 'modified', 'changed'], default='never'), + + diff_against=dict(choices=['startup', 'intended', 'running']), + diff_ignore_lines=dict(type='list'), + + ) + + mutually_exclusive = [('lines', 'src'), + ('parents', 'src')] + + required_if = [('match', 'strict', ['lines']), + ('match', 'exact', ['lines']), + ('replace', 'block', ['lines']), + ('diff_against', 'intended', ['intended_config'])] + + module = AnsibleModule(argument_spec=argument_spec, + mutually_exclusive=mutually_exclusive, + required_if=required_if, + supports_check_mode=True) + + result = {'changed': False} + + warnings = list() + check_args(module, warnings) + result['warnings'] = warnings + run_commands(module, 'skip') + diff_ignore_lines = module.params['diff_ignore_lines'] + config = None + contents = None + flags = None if module.params['defaults'] else [] + connection = get_connection(module) + + if module.params['backup'] or (module._diff and module.params['diff_against'] == 'running'): + contents = get_config(module, flags=flags) + config = NetworkConfig(indent=1, contents=contents) + if module.params['backup']: + result['__backup__'] = contents + + if any((module.params['lines'], module.params['src'])): + match = module.params['match'] + replace = module.params['replace'] + path = module.params['parents'] + + candidate = get_candidate_config(module) + running = get_running_config(module, contents, flags=flags) + try: + response = connection.get_diff(candidate=candidate, running=running, diff_match=match, diff_ignore_lines=diff_ignore_lines, path=path, + diff_replace=replace) + except ConnectionError as exc: + module.fail_json(msg=to_text(exc, errors='surrogate_then_replace')) + + config_diff = response['config_diff'] + banner_diff = response['banner_diff'] + + if config_diff or banner_diff: + commands = config_diff.split('\n') + + if module.params['before']: + commands[:0] = module.params['before'] + + if module.params['after']: + commands.extend(module.params['after']) + + result['commands'] = commands + result['updates'] = commands + result['banners'] = banner_diff + + # send the configuration commands to the device and merge + # them with the current running config + if not module.check_mode: + if commands: + edit_config_or_macro(connection, commands) + if banner_diff: + connection.edit_banner(candidate=json.dumps(banner_diff), multiline_delimiter=module.params['multiline_delimiter']) + + result['changed'] = True + + running_config = module.params['running_config'] + startup_config = None + + if module.params['save_when'] == 'always': + save_config(module, result) + elif module.params['save_when'] == 'modified': + output = run_commands(module, ['show running-config', 'show configuration']) + + running_config = NetworkConfig(indent=1, contents=output[0], ignore_lines=diff_ignore_lines) + startup_config = NetworkConfig(indent=1, contents=output[1], ignore_lines=diff_ignore_lines) + + if running_config.sha1 != startup_config.sha1: + save_config(module, result) + elif module.params['save_when'] == 'changed' and result['changed']: + save_config(module, result) + + if module._diff: + if not running_config: + output = run_commands(module, 'show running-config') + contents = output[0] + else: + contents = running_config + + # recreate the object in order to process diff_ignore_lines + running_config = NetworkConfig(indent=1, contents=contents, ignore_lines=diff_ignore_lines) + + if module.params['diff_against'] == 'running': + if module.check_mode: + module.warn("unable to perform diff against running-config due to check mode") + contents = None + else: + contents = config.config_text + + elif module.params['diff_against'] == 'startup': + if not startup_config: + output = run_commands(module, 'show configuration') + contents = output[0] + else: + contents = startup_config.config_text + + elif module.params['diff_against'] == 'intended': + contents = module.params['intended_config'] + + if contents is not None: + base_config = NetworkConfig(indent=1, contents=contents, ignore_lines=diff_ignore_lines) + + if running_config.sha1 != base_config.sha1: + if module.params['diff_against'] == 'intended': + before = running_config + after = base_config + elif module.params['diff_against'] in ('startup', 'running'): + before = base_config + after = running_config + + result.update({ + 'changed': True, + 'diff': {'before': str(before), 'after': str(after)} + }) + + module.exit_json(**result) + + +if __name__ == '__main__': + main() diff --git a/test/units/modules/network/icx/fixtures/icx_config_config.cfg b/test/units/modules/network/icx/fixtures/icx_config_config.cfg new file mode 100644 index 00000000000..e57790ea8aa --- /dev/null +++ b/test/units/modules/network/icx/fixtures/icx_config_config.cfg @@ -0,0 +1,11 @@ +! +hostname router +! +interface ethernet 1/1/4 + port-name test-interface-4 + speed-duplex 10-full +! +interface ethernet 1/1/5 + port-name port5 + ip address 172.18.20.4 255.255.255.0 +! \ No newline at end of file diff --git a/test/units/modules/network/icx/fixtures/icx_config_src.cfg b/test/units/modules/network/icx/fixtures/icx_config_src.cfg new file mode 100644 index 00000000000..a4a3468e31c --- /dev/null +++ b/test/units/modules/network/icx/fixtures/icx_config_src.cfg @@ -0,0 +1,10 @@ +! +hostname foo +! +interface ethernet 1/1/4 + disable +! +interface ethernet 1/1/5 + port-name port5 + ip address 172.18.20.4 255.255.255.0 +! diff --git a/test/units/modules/network/icx/test_icx_config.py b/test/units/modules/network/icx/test_icx_config.py new file mode 100644 index 00000000000..86b9570a151 --- /dev/null +++ b/test/units/modules/network/icx/test_icx_config.py @@ -0,0 +1,219 @@ +# Copyright: (c) 2019, 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 + +from units.compat.mock import patch, MagicMock +from ansible.modules.network.icx import icx_config +from ansible.plugins.cliconf.icx import Cliconf +from units.modules.utils import set_module_args +from .icx_module import TestICXModule, load_fixture + + +class TestICXConfigModule(TestICXModule): + + module = icx_config + + def setUp(self): + super(TestICXConfigModule, self).setUp() + + self.mock_get_config = patch('ansible.modules.network.icx.icx_config.get_config') + self.get_config = self.mock_get_config.start() + + self.mock_get_connection = patch('ansible.modules.network.icx.icx_config.get_connection') + self.get_connection = self.mock_get_connection.start() + + self.conn = self.get_connection() + self.conn.edit_config = MagicMock() + + self.mock_run_commands = patch('ansible.modules.network.icx.icx_config.run_commands') + self.run_commands = self.mock_run_commands.start() + + self.cliconf_obj = Cliconf(MagicMock()) + self.running_config = load_fixture('icx_config_config.cfg') + + def tearDown(self): + super(TestICXConfigModule, self).tearDown() + self.mock_get_config.stop() + self.mock_run_commands.stop() + self.mock_get_connection.stop() + + def load_fixtures(self, commands=None): + config_file = 'icx_config_config.cfg' + self.get_config.return_value = load_fixture(config_file) + self.get_connection.edit_config.return_value = None + + def test_icx_config_unchanged(self): + src = load_fixture('icx_config_config.cfg') + self.conn.get_diff = MagicMock(return_value=self.cliconf_obj.get_diff(src, src)) + set_module_args(dict(src=src)) + self.execute_module(changed=False) + + def test_icx_config_src(self): + src = load_fixture('icx_config_src.cfg') + set_module_args(dict(src=src)) + self.conn.get_diff = MagicMock(return_value=self.cliconf_obj.get_diff(src, self.running_config)) + commands = ['hostname foo', 'interface ethernet 1/1/4', + 'disable'] + self.execute_module(changed=True, commands=commands) + + def test_icx_config_backup(self): + set_module_args(dict(backup=True)) + result = self.execute_module() + self.assertIn('__backup__', result) + + def test_icx_config_save_always(self): + self.run_commands.return_value = "Hostname foo" + set_module_args(dict(save_when='always')) + self.execute_module(changed=True) + self.assertEqual(self.run_commands.call_count, 2) + self.assertEqual(self.get_config.call_count, 0) + self.assertEqual(self.conn.edit_config.call_count, 0) + args = self.run_commands.call_args[0][1] + self.assertIn('write memory', args) + + def test_icx_config_save_changed_false(self): + set_module_args(dict(save_when='changed')) + self.execute_module(changed=False) + self.assertEqual(self.run_commands.call_count, 1) + self.assertEqual(self.get_config.call_count, 0) + self.assertEqual(self.conn.edit_config.call_count, 0) + + def test_icx_config_lines_wo_parents(self): + lines = ['hostname foo'] + set_module_args(dict(lines=lines)) + self.conn.get_diff = MagicMock(return_value=self.cliconf_obj.get_diff('\n'.join(lines), self.running_config)) + commands = ['hostname foo'] + self.execute_module(changed=True, commands=commands) + + def test_icx_config_lines_w_parents(self): + lines = ['disable'] + parents = ['interface ethernet 1/1/4'] + set_module_args(dict(lines=lines, parents=parents)) + module = MagicMock() + module.params = {'lines': lines, 'parents': parents, 'src': None} + candidate_config = icx_config.get_candidate_config(module) + + self.conn.get_diff = MagicMock(return_value=self.cliconf_obj.get_diff(candidate_config, self.running_config)) + + commands = ['interface ethernet 1/1/4', 'disable'] + self.execute_module(changed=True, commands=commands) + + def test_icx_config_before_after_no_change(self): + lines = ['hostname router'] + set_module_args(dict(lines=lines, + before=['test1', 'test2'], + after=['test3', 'test4'])) + self.conn.get_diff = MagicMock(return_value=self.cliconf_obj.get_diff('\n'.join(lines), self.running_config)) + self.execute_module() + + def test_icx_config_config(self): + config = 'hostname localhost' + lines = ['hostname router'] + set_module_args(dict(lines=lines, config=config)) + self.conn.get_diff = MagicMock(return_value=self.cliconf_obj.get_diff('\n'.join(lines), config)) + commands = ['hostname router'] + self.execute_module(changed=True, commands=commands) + + def test_icx_config_replace_block(self): + lines = ['port-name test string', 'test string'] + parents = ['interface ethernet 1/1/4'] + set_module_args(dict(lines=lines, replace='block', parents=parents)) + + module = MagicMock() + module.params = {'lines': lines, 'parents': parents, 'src': None} + candidate_config = icx_config.get_candidate_config(module) + + self.conn.get_diff = MagicMock(return_value=self.cliconf_obj.get_diff(candidate_config, self.running_config, diff_replace='block', path=parents)) + + commands = parents + lines + self.execute_module(changed=True, commands=commands) + + def test_icx_config_match_none(self): + lines = ['hostname router'] + set_module_args(dict(lines=lines, match='none')) + self.conn.get_diff = MagicMock(return_value=self.cliconf_obj.get_diff('\n'.join(lines), self.running_config, diff_match='none')) + self.execute_module(changed=True, commands=lines) + + def test_icx_config_match_none_block(self): + lines = ['speed-duplex 10-full', 'port-name test-interface-4'] + parents = ['interface ethernet 1/1/4'] + set_module_args(dict(lines=lines, parents=parents, match='none')) + + module = MagicMock() + module.params = {'lines': lines, 'parents': parents, 'src': None} + candidate_config = icx_config.get_candidate_config(module) + self.conn.get_diff = MagicMock(return_value=self.cliconf_obj.get_diff(candidate_config, self.running_config, diff_match='none', path=parents)) + + commands = parents + lines + self.execute_module(changed=True, commands=commands, sort=False) + + def test_icx_config_match_strict(self): + lines = ['port-name test-interface-4', 'speed-duplex 10-full', + 'disable'] + parents = ['interface ethernet 1/1/4'] + set_module_args(dict(lines=lines, parents=parents, match='strict')) + + module = MagicMock() + module.params = {'lines': lines, 'parents': parents, 'src': None} + candidate_config = icx_config.get_candidate_config(module) + self.conn.get_diff = MagicMock(return_value=self.cliconf_obj.get_diff(candidate_config, self.running_config, diff_match='strict', path=parents)) + + commands = parents + ['disable'] + self.execute_module(changed=True, commands=commands, sort=False) + + def test_icx_config_match_exact(self): + lines = ['speed-duplex 10-full', 'port-name test-interface-4', + 'disable'] + parents = ['interface ethernet 1/1/4'] + set_module_args(dict(lines=lines, parents=parents, match='exact')) + + module = MagicMock() + module.params = {'lines': lines, 'parents': parents, 'src': None} + candidate_config = icx_config.get_candidate_config(module) + self.conn.get_diff = MagicMock(return_value=self.cliconf_obj.get_diff(candidate_config, self.running_config, diff_match='exact', path=parents)) + + commands = parents + lines + self.execute_module(changed=True, commands=commands, sort=False) + + def test_icx_config_src_and_lines_fails(self): + args = dict(src='foo', lines='foo') + set_module_args(args) + result = self.execute_module(failed=True) + + def test_icx_config_src_and_parents_fails(self): + args = dict(src='foo', parents='foo') + set_module_args(args) + result = self.execute_module(failed=True) + + def test_icx_config_match_exact_requires_lines(self): + args = dict(match='exact') + set_module_args(args) + result = self.execute_module(failed=True) + + def test_icx_config_match_strict_requires_lines(self): + args = dict(match='strict') + set_module_args(args) + result = self.execute_module(failed=True) + + def test_icx_config_replace_block_requires_lines(self): + args = dict(replace='block') + set_module_args(args) + result = self.execute_module(failed=True) + + def test_icx_config_replace_config_requires_src(self): + args = dict(replace='config') + set_module_args(args) + result = self.execute_module(failed=True) + + def test_icx_config_save_changed_true(self): + src = load_fixture('icx_config_src.cfg') + set_module_args(dict(src=src, save_when='changed')) + commands = ['hostname foo', 'interface ethernet 1/1/4', 'disable'] + self.conn.get_diff = MagicMock(return_value=self.cliconf_obj.get_diff(src, self.running_config)) + self.execute_module(changed=True, commands=commands) + self.assertEqual(self.run_commands.call_count, 2) + self.assertEqual(self.get_config.call_count, 1) + self.assertEqual(self.conn.edit_config.call_count, 1) + args = self.run_commands.call_args[0][1] + self.assertIn('write memory', args)