{"id":15022657,"url":"https://github.com/puppetlabs/cisco_ios","last_synced_at":"2025-04-05T14:05:07.231Z","repository":{"id":32555979,"uuid":"116127289","full_name":"puppetlabs/cisco_ios","owner":"puppetlabs","description":"Cisco IOS Catalyst module","archived":false,"fork":false,"pushed_at":"2025-02-04T02:43:03.000Z","size":1507,"stargazers_count":15,"open_issues_count":2,"forks_count":23,"subscribers_count":94,"default_branch":"main","last_synced_at":"2025-03-29T13:06:20.236Z","etag":null,"topics":["module","unsupported"],"latest_commit_sha":null,"homepage":"https://forge.puppet.com/puppetlabs/cisco_ios","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/puppetlabs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null}},"created_at":"2018-01-03T11:04:30.000Z","updated_at":"2025-02-27T15:24:03.000Z","dependencies_parsed_at":"2022-08-30T06:01:16.839Z","dependency_job_id":null,"html_url":"https://github.com/puppetlabs/cisco_ios","commit_stats":null,"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs%2Fcisco_ios","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs%2Fcisco_ios/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs%2Fcisco_ios/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs%2Fcisco_ios/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/puppetlabs","download_url":"https://codeload.github.com/puppetlabs/cisco_ios/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247345850,"owners_count":20924102,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["module","unsupported"],"created_at":"2024-09-24T19:58:14.541Z","updated_at":"2025-04-05T14:05:07.206Z","avatar_url":"https://github.com/puppetlabs.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n# cisco_ios\n\n#### Table of Contents\n\n1. [Module Description - What the module does and why it is useful](#module-description)\n2. [Support](#support)\n3. [Setup - The basics of getting started with cisco_ios](#setup)\n    * [What cisco_ios affects](#what-cisco_ios-affects)\n    * [Setup requirements](#setup-requirements)\n    * [Beginning with cisco_ios with bolt](#beginning-with-cisco_ios-with-bolt)\n    * [Beginning with cisco_ios with Puppet](#beginning-with-cisco_ios-with-puppet)\n4. [Support](#Support)\n5. [Usage - Configuration options and additional functionality](#usage)\n6. [Reference - An under-the-hood peek at what the module is doing and how](#reference)\n7. [Limitations - OS compatibility, etc.](#limitations)\n8. [Development - Guide for contributing to the module](#development)\n\n\n## Module Description\n\nThe Cisco IOS module allows for the configuration of Cisco Catalyst devices running IOS and IOS-XE.\n\nAny 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`.\n\n## Support\n\nThis module is not supported or maintained by Puppet and does not qualify for Puppet Support plans.\nIt's provided without guarantee or warranty and you can use it at your own risk.\nAll bugfixes, updates, and new feature development will come from community contributions.\n[tier:community]\n\n## Setup\n\n### What cisco_ios affects\n\nThis module installs the Net::SSH::Telnet gem; and Puppet Resource API gem, if necessary. To activate the Puppet Resource API gem, a reload of the puppetserver service is necessary. In most cases, this should happen automatically and cause little to no interruption to service.\n\n### Setup Requirements\n\n#### Device access\n\nThis module requires a user that can access the device via SSH and that has the `enable mode` privilege.\n\n#### Proxy Puppet agent\n\nSince a Puppet agent is not available for the Catalysts (and, seriously, who would want to run an agent on them?) we need a proxy Puppet agent (either a compiler, or another agent) to run Puppet on behalf of the device.\n\n#### Install dependencies\n\nTo install dependencies of the Cisco IOS module:\n\n1. Classify or apply the `cisco_ios` class on each server (server of servers, and if present, compilers and replica servers) that serves catalogs for this module.\n1. Classify or apply the `cisco_ios` class on each proxy Puppet agent that proxies for Cisco IOS devices.\n\nRun puppet agent -t on the server(s) before using the module on the agent(s).\n\n### Beginning with cisco_ios with Bolt\n\nCheck out the [Hands-on Lab](https://github.com/puppetlabs/cisco_ios/tree/main/docs/README.md) for getting started with bolt.\n\n### Beginning with cisco_ios with Puppet\n\nTo get started, create or edit `/etc/puppetlabs/puppet/device.conf` on the proxy Puppet agent, 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.\n\nFor example:\n\n```INI\n[cisco.example.com]\ntype cisco_ios\nurl file:////etc/puppetlabs/puppet/devices/cisco.example.com.conf`\n```\n\nThe credentials file must contain a hash in [HOCON format](https://github.com/lightbend/config/blob/main/HOCON.md) that matches the schema defined in [lib/puppet/transport/schema/cisco_ios.rb](lib/puppet/transport/schema/cisco_ios.rb) for example:\n\n```\nhost:            \"10.0.0.246\"\nport:            22\nuser:            admin\npassword:        password\nenable_password: password\n```\n\nTo automate the creation of these files, use the [device_manager](https://forge.puppet.com/puppetlabs/device_manager) module, the `credentials` section should follow the schema as described above:\n\n```puppet\ndevice_manager { 'cisco.example.com':\n  type        =\u003e 'cisco_ios',\n  credentials =\u003e {\n    host            =\u003e '10.0.0.246',\n    port            =\u003e 22,\n    user            =\u003e 'admin',\n    password        =\u003e 'password',\n    enable_password =\u003e 'password',\n  },\n}\n```\n\n(Using the `device_manager` module will also automatically classify the proxy Puppet agent with the `cisco_ios` class.)\n\n#### Test your setup\n\nRun `puppet device` on the proxy Puppet agent. For example:\n\n`puppet device --verbose --target cisco.example.com`\n\n#### Signing certificates\n\nThe first run of `puppet device` for a device will generate a certificate request:\n\n```bash\nInfo: Creating a new SSL key for cisco.example.com\nInfo: Caching certificate for ca\nInfo: csr_attributes file loading from /opt/puppetlabs/puppet/cache/devices/cisco.example.com/csr_attributes.yaml\nInfo: Creating a new SSL certificate request for cisco.example.com\nInfo: Certificate Request fingerprint (SHA256): ...\nInfo: Caching certificate for ca\n```\n\nUnless [autosign](https://puppet.com/docs/puppet/latest/ssl_autosign.html) is enabled, the following (depending upon `waitforcert`) will be output:\n\n```bash\nNotice: Did not receive certificate\nNotice: Did not receive certificate\nNotice: Did not receive certificate\n...\n```\n\nOr:\n\n```bash\nExiting; no certificate found and waitforcert is disabled\n```\n\nOn the server, execute the following to sign the certificate for the device:\n\n* Puppet 6 or later\n\n```bash\npuppetserver ca sign --certname cisco.example.com\n```\n\nThis will output that the certificate for the device has been signed:\n\n```bash\nSuccessfully signed certificate request for cisco.example.com\n```\n\n* Earlier versions of Puppet\n\n```bash\npuppet cert sign cisco.example.com\n```\n\nThis will output that the certificate for the device has been signed:\n\n```bash\nSigning Certificate Request for:\n  \"cisco.example.com\" (SHA256) ...\nNotice: Signed certificate request for cisco.example.com\nNotice: Removing file Puppet::SSL::CertificateRequest cisco.example.com at '/etc/puppetlabs/puppet/ssl/ca/requests/cisco.example.com.pem'\n```\n\n**Note (Security Warning)** The SSH server key, and hence its identity, will not be verified during the first connection attempt. Please follow up by verifying the SSH key for the device is correct. The fingerprint will be added to the known hosts file. By default this is the device cache directory eg. `/opt/puppetlabs/puppet/cache/devices/cisco.example.com/ssl/known_hosts`.\nThis can be changed by setting the `known_hosts_file` value in the [credentials](#credentials) file.\n\n## Usage\n\nCreate a manifest with the changes you want to apply. For example:\n\n```puppet\n    ntp_server { '1.2.3.4':\n      ensure =\u003e 'present',\n      key =\u003e 94,\n      prefer =\u003e true,\n      minpoll =\u003e 4,\n      maxpoll =\u003e 14,\n      source_interface =\u003e 'Vlan 42',\n    }\n```\n\n\u003e Note: The `--apply` and `--resource` options are only available with Puppet agent 5.5.0 and higher.\n\nRun `puppet device --apply` on the proxy Puppet agent to apply the changes:\n\n`puppet device  --target cisco.example.com --apply manifest.pp `\n\nRun `puppet device --resource` on the proxy Puppet agent to obtain the current values:\n\n`puppet device --target cisco.example.com --resource ntp_server`\n\n### Tasks\n\nTo save the running config, it is possible to use the `cisco_ios::config_save` task. Before running this task, install the module on your machine, along with [Puppet Bolt](https://puppet.com/docs/bolt/latest/bolt_installing.html). When complete, execute the following command:\n\n```\nbolt task run cisco_ios::config_save --nodes ios --modulepath \u003cmodule_installation_dir\u003e --inventoryfile \u003cinventory_yaml_path\u003e\n```\n\nThe following [inventory file](https://puppet.com/docs/bolt/latest/inventory_file.html) can be used to connect to your switch.\n\n```yaml\n# inventory.yaml\nnodes:\n  - name: cisco.example.com\n    alias: ios\n    config:\n      transport: remote\n      remote:\n        remote-transport: cisco_ios\n        user: admin\n        password: password\n        enable_password: password\n```\n\nThe `--modulepath` param can be retrieved by typing `puppet config print modulepath`.\n\n\u003e NOTE: If you have only bolt installed, `puppet config print` does not exist. See [https://puppet.com/docs/bolt/latest/installing_tasks_from_the_forge.html#task-8928](https://puppet.com/docs/bolt/latest/installing_tasks_from_the_forge.html#task-8928) on how bolt can be used to install modules into your boltdir.\n\n### Type\n\nAdd new types to the type directory.\nUse the bundled ios_config example for guidance. Here is a simple example:\n\n```Ruby\n  require 'puppet/resource_api'\n\n  Puppet::ResourceApi.register_type(\n    name: 'new_thing',\n    docs: 'Configure the new thing of the device',\n    features: ['remote_resource'],\n    attributes: {\n      ensure:       {\n        type:       'Enum[present, absent]',\n        desc:       'Whether the new thing should be present or absent on the target system.',\n        default:    'present',\n      },\n      name:         {\n        type:      'String',\n        desc:      'The name of the new thing',\n        behaviour: :namevar,\n      },\n      # Other fields in resource API format\n    },\n  )\n\n```\n\n### Provider\n\nAdd 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`.\n\n### Modes\n\nIf the new provider requires accessing a CLI \"mode\", for example, Interface `(config-if)`, add this as a new mode state to [`Puppet::Transport::CiscoIos`](lib/puppet/transport/cisco_ios.rb) and an associated prompt to [`command.yaml`](lib/puppet/transport/command.yaml).\n\n### Testing\n\nThere are 2 levels of testing found under `spec`.\n\n#### Unit Testing\n\nUnit 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`.\n\nExecute with `bundle exec rake spec`.\n\n#### Acceptance Testing\n\nAcceptance tests are executed on actual devices.\n\nUse test values and make sure that these are non-destructive.\n\nTypically, the following flow is used:\n\n- Remove any existing entry\n- Add test\n- Edit test — with as many values as possible\n- Remove test\n\nAny other logic or values that can be tested should be added, as appropriate.\n\n##### Executing\n\nEnsure that the IP address/hostname, username, password and enable password are specified as environment variables from your execution environment, for example:\n\n```\nexport DEVICE_IP=10.0.10.20\nexport DEVICE_USER=admin\nexport DEVICE_PASSWORD=\"devicePa$$w0rd\"\nexport DEVICE_ENABLE_PASSWORD=\"enablePa$$w0rd\"\n```\n\nExecute the acceptance test suite with the following command:\n\n```\nbundle exec rspec spec/acceptance/\n```\n\n### References\n\nGenerated documentation is available in [REFERENCE.md](REFERENCE.md). If you need to generate this again for any reason, run the following command:\n\n```\nbundle exec puppet strings generate --format markdown --out REFERENCE.md\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpuppetlabs%2Fcisco_ios","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpuppetlabs%2Fcisco_ios","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpuppetlabs%2Fcisco_ios/lists"}