From 5599ab14f6f0582b7eca6ba4636a0f672eb52afc Mon Sep 17 00:00:00 2001 From: John Barker Date: Thu, 4 Aug 2016 12:18:06 +0100 Subject: [PATCH] Cumulus - consistent docs formatting --- network/cumulus/cl_bond.py | 71 +++++++++++++++----------- network/cumulus/cl_bridge.py | 44 ++++++++-------- network/cumulus/cl_img_install.py | 10 ++-- network/cumulus/cl_interface.py | 55 ++++++++++---------- network/cumulus/cl_interface_policy.py | 7 +-- network/cumulus/cl_license.py | 18 ++++--- network/cumulus/cl_ports.py | 10 ++-- 7 files changed, 116 insertions(+), 99 deletions(-) diff --git a/network/cumulus/cl_bond.py b/network/cumulus/cl_bond.py index 89725810f1b..5221699b58d 100644 --- a/network/cumulus/cl_bond.py +++ b/network/cumulus/cl_bond.py @@ -25,70 +25,79 @@ description: - Configures a bond interface on Cumulus Linux To configure a bridge port use the cl_bridge module. To configure any other type of interface use the cl_interface module. Follow the guidelines for bonding found in the - Cumulus User Guide at http://docs.cumulusnetworks.com + Cumulus User Guide at U(http://docs.cumulusnetworks.com). options: name: description: - - name of the interface + - Name of the interface. required: true alias_name: description: - - add a port description + - Description of the port. ipv4: description: - - list of IPv4 addresses to configure on the interface. - use X.X.X.X/YY syntax. + - List of IPv4 addresses to configure on the interface. + In the form I(X.X.X.X/YY). ipv6: description: - - list of IPv6 addresses to configure on the interface. - use X:X:X::X/YYY syntax + - List of IPv6 addresses to configure on the interface. + In the form I(X:X:X::X/YYY). addr_method: description: - - configures the port to use DHCP. - To enable this feature use the option 'dhcp' + - Configures the port to use DHCP. + To enable this feature use the option I(dhcp). choices: ['dhcp'] mtu: description: - - set MTU. Configure Jumbo Frame by setting MTU to 9000. + - Set MTU. Configure Jumbo Frame by setting MTU to I(9000). virtual_ip: description: - - define IPv4 virtual IP used by the Cumulus Linux VRR feature + - Define IPv4 virtual IP used by the Cumulus Linux VRR feature. virtual_mac: description: - - define Ethernet mac associated with Cumulus Linux VRR feature + - Define Ethernet mac associated with Cumulus Linux VRR feature. vids: description: - - in vlan aware mode, lists vlans defined under the interface + - In vlan-aware mode, lists VLANs defined under the interface. mstpctl_bpduguard: description: - - Enables BPDU Guard on a port in vlan-aware mode + - Enables BPDU Guard on a port in vlan-aware mode. + choices: + - true + - false mstpctl_portnetwork: description: - - Enables bridge assurance in vlan-aware mode + - Enables bridge assurance in vlan-aware mode. + choices: + - true + - false mstpctl_portadminedge: description: - - Enables admin edge port + - Enables admin edge port. + choices: + - true + - false clag_id: description: - - specify a unique clag_id for every dual connected bond on each + - Specify a unique clag_id for every dual connected bond on each peer switch. The value must be between 1 and 65535 and must be the same on both peer switches in order for the bond to be considered - dual-connected + dual-connected. pvid: description: - - in vlan aware mode, defines vlan that is the untagged vlan + - In vlan-aware mode, defines vlan that is the untagged vlan. miimon: description: - - mii link monitoring interval + - The mii link monitoring interval. default: 100 mode: description: - - bond mode. as of Cumulus Linux 2.5 only LACP bond mode is - supported + - The bond mode, as of Cumulus Linux 2.5 only LACP bond mode is + supported. default: '802.3ad' min_links: description: - - minimum number of links + - Minimum number of links. default: 1 lacp_bypass_allow: description: @@ -98,7 +107,7 @@ options: - Period for enabling LACP bypass. Max value is 900. lacp_bypass_priority: description: - - List of ports and priorities. Example "swp1=10, swp2=20" + - List of ports and priorities. Example I("swp1=10, swp2=20"). lacp_bypass_all_active: description: - Activate all interfaces for bypass. @@ -106,27 +115,27 @@ options: of using bypass_priority. lacp_rate: description: - - lacp rate + - The lacp rate. default: 1 slaves: description: - - bond members + - Bond members. required: True xmit_hash_policy: description: - - transmit load balancing algorithm. As of Cumulus Linux 2.5 only - layer3+4 policy is supported + - Transmit load balancing algorithm. As of Cumulus Linux 2.5 only + I(layer3+4) policy is supported. default: layer3+4 location: description: - - interface directory location + - Interface directory location. default: - - /etc/network/interfaces.d + - '/etc/network/interfaces.d' requirements: [ Alternate Debian network interface manager - \ ifupdown2 @ github.com/CumulusNetworks/ifupdown2 ] notes: - - because the module writes the interface directory location. Ensure that + - As this module writes the interface directory location, ensure that ``/etc/network/interfaces`` has a 'source /etc/network/interfaces.d/\*' or whatever path is mentioned in the ``location`` attribute. diff --git a/network/cumulus/cl_bridge.py b/network/cumulus/cl_bridge.py index c0bf2d523a7..44822b9453e 100644 --- a/network/cumulus/cl_bridge.py +++ b/network/cumulus/cl_bridge.py @@ -25,70 +25,72 @@ description: - Configures a bridge interface on Cumulus Linux To configure a bond port use the cl_bond module. To configure any other type of interface use the cl_interface module. Follow the guidelines for bridging found in the - Cumulus User Guide at http://docs.cumulusnetworks.com + Cumulus User Guide at U(http://docs.cumulusnetworks.com) options: name: description: - - name of the interface + - Name of the interface. required: true alias_name: description: - - add a port description + - Description of the port. ipv4: description: - - list of IPv4 addresses to configure on the interface. - use X.X.X.X/YY syntax. + - List of IPv4 addresses to configure on the interface. + In the form I(X.X.X.X/YY). ipv6: description: - - list of IPv6 addresses to configure on the interface. - use X:X:X::X/YYY syntax + - List of IPv6 addresses to configure on the interface. + In the form I(X:X:X::X/YYY). addr_method: description: - - configures the port to use DHCP. - To enable this feature use the option 'dhcp' + - Configures the port to use DHCP. + To enable this feature use the option I(dhcp). choices: ['dhcp'] mtu: description: - - set MTU. Configure Jumbo Frame by setting MTU to 9000. + - Set MTU. Configure Jumbo Frame by setting MTU to I(9000). virtual_ip: description: - - define IPv4 virtual IP used by the Cumulus Linux VRR feature + - Define IPv4 virtual IP used by the Cumulus Linux VRR feature. virtual_mac: description: - - define Ethernet mac associated with Cumulus Linux VRR feature + - Define Ethernet mac associated with Cumulus Linux VRR feature. vids: description: - - in vlan aware mode, lists vlans defined under the interface + - In vlan-aware mode, lists VLANs defined under the interface. pvid: description: - - in vlan aware mode, defines vlan that is the untagged vlan + - In vlan-aware mode, defines vlan that is the untagged vlan. stp: description: - - enables spanning tree. As of Cumulus Linux 2.5 the default + - Enables spanning tree Protocol. As of Cumulus Linux 2.5 the default bridging mode, only per vlan RSTP or 802.1d is supported. For the vlan aware mode, only common instance STP is supported default: 'yes' + choices: ['yes', 'no'] ports: description: - - list of bridge members + - List of bridge members. required: True vlan_aware: description: - - enables vlan aware mode. + - Enables vlan-aware mode. + choices: ['yes', 'no'] mstpctl_treeprio: description: - - set spanning tree root priority. Must be a multiple of 4096 + - Set spanning tree root priority. Must be a multiple of 4096. location: description: - - interface directory location + - Interface directory location. default: - - /etc/network/interfaces.d + - '/etc/network/interfaces.d' requirements: [ Alternate Debian network interface manager ifupdown2 @ github.com/CumulusNetworks/ifupdown2 ] notes: - - because the module writes the interface directory location. Ensure that + - As this module writes the interface directory location, ensure that ``/etc/network/interfaces`` has a 'source /etc/network/interfaces.d/\*' or whatever path is mentioned in the ``location`` attribute. diff --git a/network/cumulus/cl_img_install.py b/network/cumulus/cl_img_install.py index cb36abcb970..00e4f9034c2 100644 --- a/network/cumulus/cl_img_install.py +++ b/network/cumulus/cl_img_install.py @@ -23,19 +23,19 @@ author: "Cumulus Networks (@CumulusLinux)" short_description: Install a different Cumulus Linux version. description: - install a different version of Cumulus Linux in the inactive slot. For - more details go the Image Management User Guide @ - http://docs.cumulusnetworks.com/ + more details go the Image Management User Guide at + U(http://docs.cumulusnetworks.com/). options: src: description: - - full path to the Cumulus Linux binary image. Can be a local path, + - The full path to the Cumulus Linux binary image. Can be a local path, http or https URL. If the code version is in the name of the file, the module will assume this is the version of code you wish to install. required: true version: description: - - inform the module of the exact version one is installing. This + - Inform the module of the exact version one is installing. This overrides the automatic check of version in the file name. For example, if the binary file name is called CumulusLinux-2.2.3.bin, and version is set to '2.5.0', then the module will assume it is @@ -46,7 +46,7 @@ options: switch_slot: description: - Switch slots after installing the image. - To run the installed code, reboot the switch + To run the installed code, reboot the switch. choices: ['yes', 'no'] default: 'no' required: false diff --git a/network/cumulus/cl_interface.py b/network/cumulus/cl_interface.py index d8dd3bf9e83..f5b84c127a9 100644 --- a/network/cumulus/cl_interface.py +++ b/network/cumulus/cl_interface.py @@ -28,82 +28,83 @@ description: bond ports use the cl_bond module. When configuring bridge related features like the "vid" option, please follow the guidelines for configuring "vlan aware" bridging. For more details review the Layer2 - Interface Guide at http://docs.cumulusnetworks.com + Interface Guide at U(http://docs.cumulusnetworks.com) options: name: description: - - name of the interface + - Name of the interface. required: true alias_name: description: - - add a port description + - Description of the port. ipv4: description: - - list of IPv4 addresses to configure on the interface. - use X.X.X.X/YY syntax. + - List of IPv4 addresses to configure on the interface. + In the form I(X.X.X.X/YY). ipv6: description: - - list of IPv6 addresses to configure on the interface. - use X:X:X::X/YYY syntax + - List of IPv6 addresses to configure on the interface. + In the form I(X:X:X::X/YYY). addr_method: description: - - can be loopback for loopback interfaces or dhcp for dhcp - interfaces. + - Address method. + choices: + - loopback + - dhcp speed: description: - - set speed of the swp(front panel) or management(eth0) interface. - speed is in MB + - Set speed of the swp(front panel) or management(eth0) interface. + speed is in MB. mtu: description: - - set MTU. Configure Jumbo Frame by setting MTU to 9000. - + - Set MTU. Configure Jumbo Frame by setting MTU to I(9000). virtual_ip: description: - - define IPv4 virtual IP used by the Cumulus VRR feature + - Define IPv4 virtual IP used by the Cumulus Linux VRR feature. virtual_mac: description: - - define Ethernet mac associated with Cumulus VRR feature + - Define Ethernet mac associated with Cumulus Linux VRR feature. vids: description: - - in vlan aware mode, lists vlans defined under the interface + - In vlan-aware mode, lists VLANs defined under the interface. mstpctl_bpduguard: description: - - Enables BPDU Guard on a port in vlan-aware mode + - Enables BPDU Guard on a port in vlan-aware mode. mstpctl_portnetwork: description: - - Enables bridge assurance in vlan-aware mode + - Enables bridge assurance in vlan-aware mode. mstpctl_portadminedge: description: - - Enables admin edge port + - Enables admin edge port. clagd_enable: description: - Enables the clagd daemon. This command should only be applied to - the clag peerlink interface + the clag peerlink interface. clagd_priority: description: - Integer that changes the role the switch has in the clag domain. The lower priority switch will assume the primary role. The number - can be between 0 and 65535 + can be between 0 and 65535. clagd_peer_ip: description: - - IP address of the directly connected peer switch interface + - IP address of the directly connected peer switch interface. clagd_sys_mac: description: - Clagd system mac address. Recommended to use the range starting - with 44:38:39:ff. Needs to be the same between 2 Clag switches + with 44:38:39:ff. Needs to be the same between 2 Clag switches. pvid: description: - - in vlan aware mode, defines vlan that is the untagged vlan + - In vlan-aware mode, defines vlan that is the untagged vlan. location: description: - - interface directory location + - Interface directory location default: - - /etc/network/interfaces.d + - '/etc/network/interfaces.d' requirements: [ Alternate Debian network interface manager - \ ifupdown2 @ github.com/CumulusNetworks/ifupdown2 ] notes: - - because the module writes the interface directory location. Ensure that + - As this module writes the interface directory location, ensure that ``/etc/network/interfaces`` has a 'source /etc/network/interfaces.d/\*' or whatever path is mentioned in the ``location`` attribute. diff --git a/network/cumulus/cl_interface_policy.py b/network/cumulus/cl_interface_policy.py index 307c477ccfa..ae99cb1bf02 100644 --- a/network/cumulus/cl_interface_policy.py +++ b/network/cumulus/cl_interface_policy.py @@ -29,17 +29,18 @@ description: the switch, but not found in the "allowed" list, this interface will be unconfigured. By default this is `/etc/network/interface.d` For more details go the Configuring Interfaces at - http://docs.cumulusnetworks.com + U(http://docs.cumulusnetworks.com). notes: - lo must be included in the allowed list. - eth0 must be in allowed list if out of band management is done options: allowed: description: - - list of ports to run initial run at 10G + - List of ports to run initial run at 10G. + required: true location: description: - - folder to store interface files. + - Directory to store interface files. default: '/etc/network/interfaces.d/' ''' diff --git a/network/cumulus/cl_license.py b/network/cumulus/cl_license.py index deafed5e49a..7690d8ac1ce 100644 --- a/network/cumulus/cl_license.py +++ b/network/cumulus/cl_license.py @@ -24,14 +24,14 @@ short_description: Install Cumulus Linux license description: - Installs a Cumulus Linux license. The module reports no change of status when a license is installed. - For more details go the Cumulus Linux License Documentation @ - http://docs.cumulusnetwork.com and the Licensing KB Site @ - https://support.cumulusnetworks.com/hc/en-us/sections/200507688 + For more details go the Cumulus Linux License Documentation at + U(http://docs.cumulusnetwork.com) and the Licensing KB Site at + U(https://support.cumulusnetworks.com/hc/en-us/sections/200507688) notes: - - to activate a license for the FIRST time, the switchd service must be + - To activate a license for the FIRST time, the switchd service must be restarted. This action is disruptive. The license renewal process occurs via the Cumulus Networks Customer Portal - - http://customers.cumulusnetworks.com. + U(http://customers.cumulusnetworks.com). - A non-EULA license is REQUIRED for automation. Manually install the license on a test switch, using the command "cl-license -i " to confirm the license is a Non-EULA license. @@ -39,15 +39,19 @@ notes: options: src: description: - - full path to the license. Can be local path or http url + - The full path to the license. Can be local path or HTTP URL. + required: true force: description: - - force installation of a license. Typically not needed. + - Force installation of a license. Typically not needed. It is recommended to manually run this command via the ansible command. A reload of switchd is not required. Running the force option in a playbook will break the idempotent state machine of the module and cause the switchd notification to kick in all the time, causing a disruption. + choices: + - yes + - no ''' EXAMPLES = ''' diff --git a/network/cumulus/cl_ports.py b/network/cumulus/cl_ports.py index 677ce18d5ca..02728203400 100644 --- a/network/cumulus/cl_ports.py +++ b/network/cumulus/cl_ports.py @@ -27,20 +27,20 @@ description: to not include ports that do not exist on the switch. Carefully read the original ports.conf file for any exceptions or limitations. For more details go the Configure Switch Port Attribute Documentation at - http://docs.cumulusnetworks.com + U(http://docs.cumulusnetworks.com). options: speed_10g: description: - - list of ports to run initial run at 10G + - List of ports to run initial run at 10G. speed_40g: description: - - list of ports to run initial run at 40G + - List of ports to run initial run at 40G. speed_4_by_10g: description: - - list of 40G ports that will be unganged to run as 4 10G ports. + - List of 40G ports that will be unganged to run as 4 10G ports. speed_40g_div_4: description: - - list of 10G ports that will be ganged to form a 40G port + - List of 10G ports that will be ganged to form a 40G port. ''' EXAMPLES = ''' Example playbook entries using the cl_ports module to manage the switch