cisco-documentation

Documentation Method for Cisco Devices using excel.

Requirements

• python3 (3.9)
• pip
• cisco-documentation

Installation

python3.9 -m pip install cisco-documentation

Updating

pip install --upgrade --upgrade-strategy eager cisco-documentation

Usage

For CiscoDocumentation

• Update switch-list.txt with a complete list of switches.
  • Device types supported include cisco_ios (ssh), cisco_ios_telnet (telnet)
  • Cisco s300 will need additional changes before it will work.
• Optional: Create load-credentials.txt to load the keychain with credentials for all switches. cisco-documentation --load-creds /dir/to/creds.txt
• Run cisco-documentation.

usage: cisco-documentation [-h] [--excel-template] [--switch-list SWITCH_LIST] [--load-creds LOAD_CREDS] [--output-dir OUTPUT_DIR] [--fetch-info] [--parse-info] [--update-wireshark-oui]
                           [--update-excel UPDATE_EXCEL]

optional arguments:
  -h, --help            show this help message and exit
  --excel-template      Create the excel documentation template in the cwd.
  --switch-list SWITCH_LIST
                        Specify the switch list to use to collect documentation.
  --load-creds LOAD_CREDS
                        Load credentials into the keystore from this text document. (switch-ip,username,password)
  --output-dir OUTPUT_DIR
                        Set the output directory for switch configs, arp table output, etc.
  --fetch-info          Fetch information from the switches (outputs to OUTPUT_DIR/output.json)
  --parse-info          Parses stored info from OUTPUT_DIR/output.json and outputs OUTPUT_DIR/output.csv
  --update-wireshark-oui
                        This updates the wireshark oui list to identify vendors based on the device mac address.
  --update-excel UPDATE_EXCEL
                        This is the filename to update the 'SWITCHES' and 'ARP' sheets of the specified workbook automatically. This perminently erases the current 'SWITCHES' worksheet. This
                        only appends values to the 'ARP' sheet.

For RunCommands

• This is a simple script to run multiple commands on the switches in switch_list.txt
  • Note: RunCommands.py does not use multiprocessing, and RunCommands2.py has not been maintained, but should still be operational.
• Run python3.9 ./RunCommands.py
• Enter commands separated by ~.
  • For example, to configure spanning-tree mode on all switches in switch_list.txt you could run conf t~spanning-tree mode mst~end~wr

Updating the Excel Spreadsheet

• Update the ARP sheet with the output from arp_output.txt. Also add the output from arp-scan if there are devices missing (if a device isn't communicating over the l3 switch, or there is no l3 switch in the network, these devices will not exist in the arp table.)
  • If devices don't communicate over the gateway, their arp entries will not exist on the l3 switch. Using nmap beforehand from a separate subnet will populate the arp table on this switch - assuming devices are properly programed with a default gateway.
• Copy the output from output.txt into the SWITCHES sheet. This will update formulas used to the right of the output to look up device information from each sheet.
• Device information should be contained in a sheet named after each l2 network.
• L2 networks should be named, vlans/ranges assigned on the OVERVIEW sheet.

Building and installing from source

python3.9 -m pip uninstall cisco-documentation -y
rm dist/cisco_documentation-*-py2.py3-none-any.whl
python3.9 setup.py bdist_wheel --universal
python3.9 -m pip install dist/cisco_documentation-*-py2.py3-none-any.whl
# To upload to pypi
twine upload dist/*

Using an ssh jumphost

To use a jumphost you need to be able to authenticate to the jumphost using an ssh key.

Setting up key authentication to a jumphost.

Generate your local key.

ssh-keygen -t rsa

Copy the key to the remote server.

ssh-copy-id user@ip.or.dns

Setup the ssh_config file.

cat ~/.ssh/yourJumpHostConfigFileName
host jumphost
  IdentitiesOnly yes
  IdentityFile ~/.ssh/id_rsa
  User user
  HostName ip.or.dns

host * !jumphost
  User admin
  # Force usage of this SSH config file
  ProxyCommand ssh -F ~/.ssh/yourJumpHostConfigFileName -W %h:%p jumphost
  # Alternate solution using netcat
  #ProxyCommand ssh -F ./ssh_config jumphost nc %h %p

Running the command specifying the ssh-config file.

cisco-documentation <your other options here> --ssh-config ~/.ssh/yourJumpHostConfigFileName
run-commands <your other options here> --ssh-config ~/.ssh/yourJumpHostConfigFileName

Changelog

0.0.11

• Added processing of cdp for cases where lldp does not show the neighbor.

0.0.10

• Added an option for a local keyring to default to /keyring.json if there are no valid backends. (i.e. ubuntu server default install)
• Updated formatting to black.
• Added generic error handling when collecting information sequentially. Failed collection will skip the device in the results.
• Added option to collect information from a single device. (--switch)
• Fixed run-commands by adding the default-creds options.

0.0.9

• Added rich to the requirements.
• Added option to run sequentially instead of in parallel. (--parallel flag)
• Added function and cli app to help test and save credentials.

0.0.8

• Fixed an over-indentation of the arp table generation causing large files.
• Changed the arp_output.csv to be tab-delimited for easier copy/paste to excel.

0.0.7

• Added better error handling - still writes to output.json if a single connection fails.
• Changed section to support fetching cisco specific information via telnet.

0.0.6

• Added config-merge command.
• Added port-descriptions command.
• Made additional functions to re-use more code.
• Added jinja-merge command for templating switch configurations.

0.0.5

• Updated readme to fix some outdated information.
• Updated the --help to add some context.
• Updated the wireshark_oui.txt file.
• Added an option to update the wireshark_oui.txt file.
• Fixed the get_oui_dict function to return the generated oui_dict.
• Added a step for creation of arp_output.csv output with the arp information.
• Removed aiomultiprocess from requirements.
• Added option to update an excel file directly.