cisco_ios

Table of Contents

1. Module Description - What the module does and why it is useful
2. Setup - The basics of getting started with cisco_ios
   • Setup requirements
   • Beginning with cisco_ios
3. Usage - Configuration options and additional functionality
4. Reference - An under-the-hood peek at what the module is doing and how
5. Limitations - OS compatibility, etc.
6. Development - Guide for contributing to the module

Module Description

The Cisco IOS module allows for the configuration of Cisco Catalyst devices running IOS.

This module automatically installs the Telnet-SSH ruby library for communication purposes.

Any changes made by this module affect the current running-config. These changes will lost on device reboot unless they are backed up to startup-config. This module provides a Puppet task to save running-config to startup-config.

Setup

Setup Requirements

This module requires a user that can access the device via SSH and that has the enable mode privilege.

Beginning with cisco_ios

To get started, create or edit /etc/puppetlabs/puppet/device.conf, add a section for the device (this will become the device's certname), specify a type of cisco_ios, and specify a url to a credentials file. For example:

[cisco.example.com]
type cisco_ios
url file:////etc/puppetlabs/puppet/devices/cisco.example.com.conf`

Next, create a credentials file, following the HOCON documentation regarding quoted/unquoted strings, with connection information for the device. For example:

address = 10.0.10.20
username = admin
port = 22
password = "P@$$w0rd"
enable_password = "3n4bleP@$$w0rd"

Note that the enable_password key must be supplied even if the user has the enable mode privilege. Enter any value here.

Test your setup. For example:

puppet device --verbose --target cisco.example.com

Signing Certificates

The first run of puppet device for a device will generate a certificate request:

Info: Creating a new SSL key for cisco.example.com
Info: Caching certificate for ca
Info: csr_attributes file loading from /opt/puppetlabs/puppet/cache/devices/cisco.example.com/csr_attributes.yaml
Info: Creating a new SSL certificate request for cisco.example.com
Info: Certificate Request fingerprint (SHA256): ...
Info: Caching certificate for ca

Unless autosign is enabled, the following (depending upon waitforcert) will be output:

Notice: Did not receive certificate
Notice: Did not receive certificate
Notice: Did not receive certificate
...

Or:

Exiting; no certificate found and waitforcert is disabled

On the master, execute the following to sign the certificate for the device:

puppet cert sign cisco.example.com

This will output that the certificate for the device has been signed:

Signing Certificate Request for:
  "cisco.example.com" (SHA256) ...
Notice: Signed certificate request for cisco.example.com
Notice: Removing file Puppet::SSL::CertificateRequest cisco.example.com at '/etc/puppetlabs/puppet/ssl/ca/requests/cisco.example.com.pem'

Usage

See the Cisco IOS module wiki for up-to-date usage information.

Create a manifest with the changes you want to apply. For example:

    ntp_server { '1.2.3.4':
      ensure => 'present',
      key => 94,
      prefer => true,
      minpoll => 4,
      maxpoll => 14,
      source_interface => 'Vlan 42',
    }

Run Puppet device apply to apply the changes:

puppet device --target cisco.example.com --apply manifest.pp

Run Puppet device resource to obtain the current values:

puppet device --resource --target cisco.example.com ntp_server

Reference

Please see the netdev_stdlib docs https://github.com/puppetlabs/netdev_stdlib/blob/master/README.md

Classes

• cisco_ios:
• cisco_ios::install: Private class

Resource types

• banner: Set the banner on the device.
• ios_config: Execute an arbitrary configuration against the cisco_ios device with or without a check for idempotency.

cisco_ios

The cisco_ios class.

cisco_ios::install

Private class.

banner

Set various banners on the device, for example motd.

attributes

The following attributes are available in the banner type.

name

namevar

The friendly name for banner settings, it is set to default.

Default value: default.

motd

The MOTD banner.

ios_config

Execute an arbitrary configuration against the cisco_ios device with or without a check for idempotency

attributes

The following attributes are available in the ios_config type.

name

namevar

The friendly name for this ios command.

command

The ios command to run.

command_mode

Valid values: CONF_T.

The command line mode to be in, when executing the command

Default value: CONF_T.

idempotent_regex

Expected string, when running a regex against the 'show running-config'.

idempotent_regex_options

Array of one or more options which control how the pattern can match.

Allowed values: ['ignorecase', 'extended', 'multiline', 'fixedencoding', 'noencoding']

negate_idempotent_regex

Boolean

Negate the regex used with idempotent_regex.

Default value: false.

stp_global

Manages the Cisco Spanning-tree Global configuration resource.

Properties

The following properties are available in the stp_global type.

enable

Data type: Optional[Boolean]

Enable or disable STP functionality [true|false]

bridge_assurance

Data type: Optional[Boolean]

Bridge Assurance on all network ports

loopguard

Data type: Optional[Boolean]

Bridge Assurance on all network ports

mode

Data type: Optional[Enum["mst","pvst","rapid-pvst"]]

Operating Mode

mst_forward_time

Data type: Optional[Integer]

Forward delay for the spanning tree

mst_hello_time

Data type: Optional[Integer]

Hello interval for the spanning tree

mst_inst_vlan_map

Data type: Optional[Array[Tuple[Integer,String]]]

An array of [mst_inst, vlan_range] pairs.

mst_max_age

Data type: Optional[Integer[6,40]]

Max age interval for the spanning tree

mst_max_hops

Data type: Optional[Integer[1,255]]

Max hops value for the spanning tree

mst_name

Data type: Optional[String]

Configuration name.

mst_priority

Data type: Optional[Array[Tuple[String,Integer]]]

An array of [mst_inst_list, priority] pairs.

mst_revision

Data type: Optional[Integer]

Configuration revision number.

pathcost

Data type: Optional[Enum["long","short"]]

Method to calculate default port path cost

vlan_forward_time

Data type: Optional[Array[Tuple[String,Integer]]]

An array of [vlan_inst_list, forward_time] pairs.

vlan_hello_time

Data type: Optional[Array[Tuple[String,Integer]]]

An array of [vlan_inst_list, hello_time] pairs.

vlan_max_age

Data type: Optional[Array[Tuple[String,Integer]]]

An array of [vlan_inst_list, max_age] pairs.

vlan_priority

Data type: Optional[Array[Tuple[String,Integer]]]

An array of [vlan_inst_list, priority] pairs.

Parameters

The following parameters are available in the stp_global type.

name

namevar

Data type: String

ID of the stp global config. Valid values are default.

Default value: default

Limitations

The following devices have been tested against this module — with the type compatibilities listed.

Note that this is not an exhaustive list of supported devices, but rather the results found from execution across a cross section of the devices that we use for internal testing.

Devices used in testing

Resources vs Device type

Cells marked with the * have deviations. See the section below for details.

Deviations

network_interface

2960

The switch does not support the MTU on a per-interface basis. It does not support the following attributes: link

• mtu

3750

The switch does not support the MTU on a per-interface basis. It does not support the following attributes: link

• mtu

network_trunk

2960

This device does not have native trunking. It does not support the following attributes: link

• ensure
• encapsulation

ntp_server

3750

Does not support the following attributes: link

• minpoll
• maxpoll

4948

Does not support the following attributes: link

• minpoll
• maxpoll

4507

Does not support the following attributes: link

• minpoll
• maxpoll

port_channel

3750

4507

This device does not have native trunking. It does not support the following attributes: link

• flowcontrol_send

radius_global

The IOS operating system does not support:

• enable

radius_server

3750

6503

The IOS operating system needs to support the new "radius server" command, we do not use "radius-server" link

stp_global

3750

2960

4507

4948

This device does not support bridge assurance link

tacacs_server

2960

3750

The IOS operating system uses the deprecated "tacacs_server" syntax, we cannot use 'unset' functionality for individiual fields link

tacacs_global

The IOS operating system does not support:

• enable
• retransmit_count

Anomalies in Cisco CLI

ntp_server

It has been noted that NTP Server configuration may allow multiple entries of the same NTP Server address with different Source Interfaces

For example:

ntp server 1.2.3.4 key 42
ntp server 1.2.3.4 key 94 source Vlan42
ntp server 1.2.3.4 key 50 source Loopback42

While Puppet Resource will obtain all entries, Puppet Apply compares against the first entry found with the same name.

Workaround

Send an ensure 'absent' manifest to remove all ntp servers of the same name, before rebuilding the ntp server configuration:

    ntp_server { '1.2.3.4':
      ensure => 'absent',
    }

followed by:

    ntp_server { '1.2.3.4':
      ensure => 'present',
      key => 94,
      prefer => true,
      minpoll => 4,
      maxpoll => 14,
      source_interface => 'Vlan 42',
    }

Any edits can be made by referencing the same ntp_server name and source_interface.

Development

Contributions are welcome, especially if they can be of use to other users.

Checkout the repo by forking and creating your feature branch.

Prior to development, copy the types from the netdev standard library to the /lib/puppet/types directory.

See the command guide for IOS.

Type

Add new types to the type directory. We use the Resource API format Use the bundled ios_config example for guidance. Here is a simple example:

  require 'puppet/resource_api'

  Puppet::ResourceApi.register_type(
    name: 'new_thing',
    docs: 'Configure the new thing of the device',
    features: ['remote_resource'],
    attributes: {
      ensure:       {
        type:       'Enum[present, absent]',
        desc:       'Whether the new thing should be present or absent on the target system.',
        default:    'present',
      },
      name:         {
        type:      'String',
        desc:      'The name of the new thing',
        behaviour: :namevar,
      },
      # Other fields in resource API format
    },
  )

Provider

Add a provider — see existing examples. Parsing logic is contained in ios.rb. Regular expressions for parsing, getting and setting values, are contained within command.yaml.

Modes

If the new provider requires accessing a CLI "mode", for example, Interface (config-if), add this as a new mode state to device.rb and an associated prompt to command.yaml.

Testing

There are 2 levels of testing found under spec.

Unit Testing

Unit tests test the parsing and command generation logic executed locally. Specs typically iterate over read_tests and update_tests, which contain testing values within test_data.yaml.

Execute with bundle exec rake spec.

Acceptance Testing

Acceptance tests are executed on actual devices.

Use test values and make sure that these are non-destructive.

Typically, the following flow is used:

• Remove any existing entry
• Add test
• Edit test — with as many values as possible
• Remove test

Any other logic or values that can be tested should be added, as appropriate.

Executing

Ensure that the IP address/hostname, username, password and enable password are specified as environment variables from your execution environment, for example:

export DEVICE_IP=10.0.10.20
export DEVICE_USER=admin
export DEVICE_PASSWORD="devicePa$$w0rd"
export DEVICE_ENABLE_PASSWORD="enablePa$$w0rd"

Execute the acceptance test suite with the following command:

BEAKER_provision=yes PUPPET_INSTALL_TYPE=pe BEAKER_set=vmpooler bundle exec rspec spec/acceptance/

Change log

All notable changes to this project will be documented in this file. The format is based on Keep a Changelog and this project adheres to Semantic Versioning.

0.2.0 (2018-06-15)

Full Changelog

Added

• (FM-6989) Support Tacacs server deprecated CLI #220 (willmeek)

Fixed

• (maint) Adding changelog generator #217 (tphoney)
• (FM-7074) Add list of tested IOS versions to OperatingSystem metadata #216 (willmeek)
• (FM-7069) hocon vs yaml #215 (tkishel)
• (FM-7068) run pdk update, fix blacksmith #213 (tphoney)

* This Changelog was automatically generated by github_changelog_generator