Move net_* modules into specific sub-topics (#26234)

As we continue to expand the number of modules we must ensure they are
sensibly grouped.

lib/ansible/modules/network/system/net_banner.py

@@ -0,0 +1,99 @@
+#!/usr/bin/python
+#
+# This file is part of Ansible
+#
+# Ansible is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# Ansible is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+#
+
+ANSIBLE_METADATA = {'metadata_version': '1.0',
+                    'status': ['preview'],
+                    'supported_by': 'community'}
+
+
+DOCUMENTATION = """
+---
+module: net_banner
+version_added: "2.4"
+author: "Ricardo Carrillo Cruz (@rcarrillocruz)"
+short_description: Manage multiline banners on network devices
+description:
+  - This will configure both login and motd banners on network devices.
+    It allows playbooks to add or remote
+    banner text from the active running configuration.
+options:
+  banner:
+    description:
+      - Specifies which banner that should be
+        configured on the remote device.
+    required: true
+    choices: ['login', 'motd']
+  text:
+    description:
+      - The banner text that should be
+        present in the remote device running configuration.  This argument
+        accepts a multiline string, with no empty lines. Requires I(state=present).
+    default: null
+  state:
+    description:
+      - Specifies whether or not the configuration is
+        present in the current devices active running configuration.
+    default: present
+    choices: ['present', 'absent']
+"""
+
+EXAMPLES = """
+- name: configure the login banner
+  net_banner:
+    banner: login
+    text: |
+      this is my login banner
+      that contains a multiline
+      string
+    state: present
+
+- name: remove the motd banner
+  net_banner:
+    banner: motd
+    state: absent
+
+- name: Configure banner from file
+  net_banner:
+    banner:  motd
+    text: "{{ lookup('file', './config_partial/raw_banner.cfg') }}"
+    state: present
+
+"""
+
+RETURN = """
+commands:
+  description: The list of configuration mode commands to send to the device
+  returned: always
+  type: list
+  sample:
+    - banner login
+    - this is my login banner
+    - that contains a multiline
+    - string
+
+rpc:
+  description: load-configuration RPC send to the device
+  returned: when configuration is changed on device
+  type: string
+  sample: >
+          <system>
+            <login>
+                <message>this is my login banner</message>
+            </login>
+          </system>"
+"""

lib/ansible/modules/network/system/net_command.py

@@ -0,0 +1,131 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+
+# (c) 2017, Ansible by Red Hat, inc
+#
+# This file is part of Ansible by Red Hat
+#
+# Ansible is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# Ansible is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+#
+
+ANSIBLE_METADATA = {'metadata_version': '1.0',
+                    'status': ['preview'],
+                    'supported_by': 'core'}
+
+DOCUMENTATION = """
+---
+module: net_command
+version_added: "2.4"
+author: "Trishna Guha (@trishnag)"
+short_description: Run arbitrary commands on a network device
+description:
+  - Sends an arbitrary set of commands to network node and returns the results
+    read from the device.  This module includes an
+    argument that will cause the module to wait for a specific condition
+    before returning or timing out if the condition is not met.
+options:
+  commands:
+    description:
+      - The commands to send to the remote network device over the
+        configured provider.  The resulting output from the command
+        is returned.  If the I(wait_for) argument is provided, the
+        module is not returned until the condition is satisfied or
+        the number of I(retries) has been exceeded.
+    required: true
+  wait_for:
+    description:
+      - Specifies what to evaluate from the output of the command
+        and what conditionals to apply.  This argument will cause
+        the task to wait for a particular conditional to be true
+        before moving forward.   If the conditional is not true
+        by the configured retries, the task fails.  See examples.
+    required: false
+    default: null
+    aliases: ['waitfor']
+    version_added: "2.2"
+  match:
+    description:
+      - The I(match) argument is used in conjunction with the
+        I(wait_for) argument to specify the match policy.  Valid
+        values are C(all) or C(any).  If the value is set to C(all)
+        then all conditionals in the I(wait_for) must be satisfied.  If
+        the value is set to C(any) then only one of the values must be
+        satisfied.
+    required: false
+    default: all
+    choices: ['any', 'all']
+    version_added: "2.2"
+  retries:
+    description:
+      - Specifies the number of retries a command should be tried
+        before it is considered failed.  The command is run on the
+        target device every retry and evaluated against the I(wait_for)
+        conditionals.
+    required: false
+    default: 10
+  interval:
+    description:
+      - Configures the interval in seconds to wait between retries
+        of the command.  If the command does not pass the specified
+        conditional, the interval indicates how to long to wait before
+        trying the command again.
+    required: false
+    default: 1
+"""
+
+EXAMPLES = """
+- name: run show version on remote devices
+  net_command:
+    commands: show version
+- name: run show version and check to see if output contains Network vendor name
+  net_command:
+    commands: show version
+    wait_for: result[0] contains Network vendor name
+- name: run multiple commands on remote nodes
+  net_command:
+    commands:
+      - show version
+      - show interfaces
+- name: run multiple commands and evaluate the output
+  net_command:
+    commands:
+      - show version
+      - show interfaces
+    wait_for:
+      - result[0] contains Network vendor name
+      - result[1] contains Loopback0
+- name: run commands and specify the output format
+  net_command:
+    commands:
+      - command: show version
+        output: json
+"""
+
+RETURN = """
+stdout:
+  description: The set of responses from the commands
+  returned: always apart from low level errors (such as action plugin)
+  type: list
+  sample: ['...', '...']
+stdout_lines:
+  description: The value of stdout split into a list
+  returned: always apart from low level errors (such as action plugin)
+  type: list
+  sample: [['...', '...'], ['...'], ['...']]
+failed_conditions:
+  description: The list of conditionals that have failed
+  returned: failed
+  type: list
+  sample: ['...', '...']
+"""

lib/ansible/modules/network/system/net_system.py

@@ -0,0 +1,123 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+
+# (c) 2017, Ansible by Red Hat, inc
+#
+# This file is part of Ansible by Red Hat
+#
+# Ansible is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# Ansible is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+#
+
+ANSIBLE_METADATA = {'metadata_version': '1.0',
+                    'status': ['preview'],
+                    'supported_by': 'core'}
+
+
+DOCUMENTATION = """
+---
+module: net_system
+version_added: "2.4"
+author: "Ricardo Carrillo Cruz (@rcarrillocruz)"
+short_description: Manage the system attributes on network devices
+description:
+  - This module provides declarative management of node system attributes
+    on network devices.  It provides an option to configure host system
+    parameters or remove those parameters from the device active
+    configuration.
+options:
+  hostname:
+    description:
+      - Configure the device hostname parameter. This option takes an ASCII string value.
+  domain_name:
+    description:
+      - Configure the IP domain name
+        on the remote device to the provided value. Value
+        should be in the dotted name form and will be
+        appended to the C(hostname) to create a fully-qualified
+        domain name.
+  domain_search:
+    description:
+      - Provides the list of domain suffixes to
+        append to the hostname for the purpose of doing name resolution.
+        This argument accepts a list of names and will be reconciled
+        with the current active configuration on the running node.
+  lookup_source:
+    description:
+      - Provides one or more source
+        interfaces to use for performing DNS lookups.  The interface
+        provided in C(lookup_source) must be a valid interface configured
+        on the device.
+  name_servers:
+    description:
+      - List of DNS name servers by IP address to use to perform name resolution
+        lookups.  This argument accepts either a list of DNS servers See
+        examples.
+  state:
+    description:
+      - State of the configuration
+        values in the device's current active configuration.  When set
+        to I(present), the values should be configured in the device active
+        configuration and when set to I(absent) the values should not be
+        in the device active configuration
+    default: present
+    choices: ['present', 'absent']
+"""
+
+EXAMPLES = """
+- name: configure hostname and domain name
+  net_system:
+    hostname: ios01
+    domain_name: test.example.com
+    domain-search:
+      - ansible.com
+      - redhat.com
+      - cisco.com
+
+- name: remove configuration
+  net_system:
+    state: absent
+
+- name: configure DNS lookup sources
+  net_system:
+    lookup_source: MgmtEth0/0/CPU0/0
+
+- name: configure name servers
+  net_system:
+    name_servers:
+      - 8.8.8.8
+      - 8.8.4.4
+"""
+
+RETURN = """
+commands:
+  description: The list of configuration mode commands to send to the device
+  returned: always
+  type: list
+  sample:
+    - hostname ios01
+    - ip domain name test.example.com
+
+rpc:
+  description: load-configuration RPC send to the device
+  returned: C(rpc) is returned only for junos device
+            when configuration is changed on device
+  type: string
+  sample: >
+            <interfaces>
+                <interface>
+                    <name>ge-0/0/0</name>
+                    <description>test interface</description>
+                </interface>
+            </interfaces>
+"""

lib/ansible/modules/network/system/net_user.py

@@ -0,0 +1,138 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+
+# (c) 2017, Ansible by Red Hat, inc
+#
+# This file is part of Ansible by Red Hat
+#
+# Ansible is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# Ansible is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+#
+
+ANSIBLE_METADATA = {'metadata_version': '1.0',
+                    'status': ['preview'],
+                    'supported_by': 'core'}
+
+DOCUMENTATION = """
+---
+module: net_user
+version_added: "2.4"
+author: "Trishna Guha (@trishnag)"
+short_description: Manage the collection of local users on network device
+description:
+  - This module provides declarative management of the local usernames
+    configured on network devices. It allows playbooks to manage
+    either individual usernames or the collection of usernames in the
+    current running config. It also supports purging usernames from the
+    configuration that are not explicitly defined.
+options:
+  collection:
+    description:
+      - The set of username objects to be configured on the remote
+        network device. The list entries can either be the username
+        or a hash of username and properties. This argument is mutually
+        exclusive with the C(name) argument.
+  name:
+    description:
+      - The username to be configured on the remote network device.
+        This argument accepts a string value and is mutually exclusive
+        with the C(collection) argument.
+        Please note that this option is not same as C(provider username).
+  password:
+    description:
+      - The password to be configured on the remote network device. The
+        password needs to be provided in clear and it will be encrypted
+        on the device.
+        Please note that this option is not same as C(provider password).
+  update_password:
+    description:
+      - Since passwords are encrypted in the device running config, this
+        argument will instruct the module when to change the password.  When
+        set to C(always), the password will always be updated in the device
+        and when set to C(on_create) the password will be updated only if
+        the username is created.
+    default: always
+    choices: ['on_create', 'always']
+  privilege:
+    description:
+      - The C(privilege) argument configures the privilege level of the
+        user when logged into the system. This argument accepts integer
+        values in the range of 1 to 15.
+  role:
+    description:
+      - Configures the role for the username in the
+        device running configuration. The argument accepts a string value
+        defining the role name. This argument does not check if the role
+        has been configured on the device.
+  sshkey:
+    description:
+      - Specifies the SSH public key to configure
+        for the given username. This argument accepts a valid SSH key value.
+  nopassword:
+    description:
+      - Defines the username without assigning
+        a password. This will allow the user to login to the system
+        without being authenticated by a password.
+    type: bool
+  purge:
+    description:
+      - Instructs the module to consider the
+        resource definition absolute. It will remove any previously
+        configured usernames on the device with the exception of the
+        `admin` user (the current defined set of users).
+    type: bool
+    default: false
+  state:
+    description:
+      - Configures the state of the username definition
+        as it relates to the device operational configuration. When set
+        to I(present), the username(s) should be configured in the device active
+        configuration and when set to I(absent) the username(s) should not be
+        in the device active configuration
+    default: present
+    choices: ['present', 'absent']
+"""
+
+EXAMPLES = """
+- name: create a new user
+  net_user:
+    name: ansible
+    sshkey: "{{ lookup('file', '~/.ssh/id_rsa.pub') }}"
+    state: present
+- name: remove all users except admin
+  net_user:
+    purge: yes
+- name: set multiple users to privilege level 15
+  net_user:
+    collection:
+      - name: netop
+      - name: netend
+    privilege: 15
+    state: present
+- name: Change Password for User netop
+  net_user:
+    name: netop
+    password: "{{ new_password }}"
+    update_password: always
+    state: present
+"""
+
+RETURN = """
+commands:
+  description: The list of configuration mode commands to send to the device
+  returned: always
+  type: list
+  sample:
+    - username ansible secret password
+    - username admin secret admin
+"""