1============== 2ciscoconfparse 3============== 4 5.. image:: https://travis-ci.org/mpenning/ciscoconfparse.png?branch=master 6 :target: https://travis-ci.org/mpenning/ciscoconfparse 7 :alt: Travis CI Status 8 9.. image:: https://img.shields.io/pypi/v/ciscoconfparse.svg 10 :target: https://pypi.python.org/pypi/ciscoconfparse/ 11 :alt: Version 12 13.. image:: https://pepy.tech/badge/ciscoconfparse 14 :target: https://pepy.tech/project/ciscoconfparse 15 :alt: Downloads 16 17.. image:: http://img.shields.io/badge/license-GPLv3-blue.svg 18 :target: https://www.gnu.org/copyleft/gpl.html 19 :alt: License 20 21.. contents:: 22 23.. _introduction: 24 25Introduction: What is ciscoconfparse? 26===================================== 27 28Short answer: ciscoconfparse is a Python_ library that helps you quickly answer questions like these about your configurations: 29 30- What interfaces are shutdown? 31- Which interfaces are in trunk mode? 32- What address and subnet mask is assigned to each interface? 33- Which interfaces are missing a critical command? 34- Is this configuration missing a standard config line? 35 36It can help you: 37 38- Audit existing router / switch / firewall / wlc configurations 39- Modify existing configurations 40- Build new configurations 41 42Speaking generally, the library examines an IOS-style config and breaks it 43into a set of linked parent / child relationships. You can perform complex 44queries about these relationships. 45 46.. image:: https://raw.githubusercontent.com/mpenning/ciscoconfparse/master/sphinx-doc/_static/ciscoconfparse_overview_75pct.png 47 :target: https://raw.githubusercontent.com/mpenning/ciscoconfparse/master/sphinx-doc/_static/ciscoconfparse_overview_75pct.png 48 :alt: CiscoConfParse Parent / Child relationships 49 50Usage 51===== 52 53The following code will parse a configuration stored in 'exampleswitch.conf' 54and select interfaces that are shutdown. 55 56.. code:: python 57 58 from ciscoconfparse import CiscoConfParse 59 60 parse = CiscoConfParse('exampleswitch.conf', syntax='ios') 61 62 for intf_obj in parse.find_objects_w_child('^interface', '^\s+shutdown'): 63 print("Shutdown: " + intf_obj.text) 64 65 66The next example will find the IP address assigned to interfaces. 67 68.. code:: python 69 70 from ciscoconfparse import CiscoConfParse 71 72 parse = CiscoConfParse('exampleswitch.conf', syntax='ios') 73 74 for intf_obj in parse.find_objects('^interface'): 75 76 intf_name = intf_obj.re_match_typed('^interface\s+(\S.+?)$') 77 78 # Search children of all interfaces for a regex match and return 79 # the value matched in regex match group 1. If there is no match, 80 # return a default value: '' 81 intf_ip_addr = intf_obj.re_match_iter_typed( 82 r'ip\saddress\s(\d+\.\d+\.\d+\.\d+)\s', result_type=str, 83 group=1, default='') 84 print("{0}: {1}".format(intf_name, intf_ip_addr)) 85 86What if we don't use Cisco? 87=========================== 88 89Don't let that stop you. 90 91As of CiscoConfParse 1.2.4, you can parse `brace-delimited configurations`_ 92into a Cisco IOS style (see `Github Issue #17`_), which means that 93CiscoConfParse can parse these configurations: 94 95- Juniper Networks Junos 96- Palo Alto Networks Firewall configurations 97- F5 Networks configurations 98 99CiscoConfParse also handles anything that has a Cisco IOS style of configuration, which includes: 100 101- Cisco IOS, Cisco Nexus, Cisco IOS-XR, Cisco IOS-XE, Aironet OS, Cisco ASA, Cisco CatOS 102- Arista EOS 103- Brocade 104- HP Switches 105- Force 10 Switches 106- Dell PowerConnect Switches 107- Extreme Networks 108- Enterasys 109- Screenos 110 111Docs 112==== 113 114- The latest copy of the docs are `archived on the web <http://www.pennington.net/py/ciscoconfparse/>`_ 115- There is also a `CiscoConfParse Tutorial <http://pennington.net/tutorial/ciscoconfparse/ccp_tutorial.html>`_ 116 117Building the Package 118==================== 119 120- ``cd`` into the root ciscoconfparse directory 121- Edit the version number in `ciscoconfparse/metadata.json` (as required) 122- ``git commit`` all pending changes 123- ``make test`` 124- ``make repo-push`` 125- ``make pypi`` 126 127.. _Pre-Requisites: 128 129Pre-requisites 130============== 131 132ciscoconfparse_ requires Python versions 3.5+ (note: version 3.7.0 has 133a bug - ref Github issue #117, but version 3.7.1 works); the OS should not 134matter. 135 136.. _Installation: 137 138Installation and Downloads 139========================== 140 141You can install into Python2.x with pip_: 142 143:: 144 145 pip install --upgrade ciscoconfparse 146 147Use ``pip3`` for Python3.x... 148 149:: 150 151 pip3 install --upgrade ciscoconfparse 152 153If you don't want to use pip_, you can install with `easy_install`: 154 155:: 156 157 easy_install -U ciscoconfparse 158 159 160Otherwise `download it from PyPi <https://pypi.python.org/pypi/ciscoconfparse>`_, extract it and run the ``setup.py`` script: 161 162:: 163 164 python setup.py install 165 166If you're interested in the source, you can always pull from the `github repo`_ 167or `bitbucket repo`_: 168 169 170- From github_: 171 :: 172 173 git clone git://github.com/mpenning/ciscoconfparse 174 cd ciscoconfparse/ 175 pip install . 176 177 178.. _`Other-Resources`: 179 180Other Resources 181=============== 182 183- `Dive into Python3`_ is a good way to learn Python 184- `Team CYMRU`_ has a `Secure IOS Template`_, which is especially useful for external-facing routers / switches 185- `Cisco's Guide to hardening IOS devices`_ 186- `Center for Internet Security Benchmarks`_ (An email address, cookies, and javascript are required) 187 188.. _`Bug-Tracker-and-Support`: 189 190Bug Tracker and Support 191======================= 192 193- Please report any suggestions, bug reports, or annoyances with ciscoconfparse_ through the `github bug tracker`_. 194- If you're having problems with general python issues, consider searching for a solution on `Stack Overflow`_. If you can't find a solution for your problem or need more help, you can `ask a question`_. 195- If you're having problems with your Cisco devices, you can open a case with `Cisco TAC`_; if you prefer crowd-sourcing, you can ask on the Stack Exchange `Network Engineering`_ site. 196 197.. _Unit-Tests: 198 199Unit-Tests 200========== 201 202`Travis CI project <https://travis-ci.org>`_ tests ciscoconfparse on Python versions 3.5 and higher, as well as a `pypy JIT`_ executable. 203 204Click the image below for details; the current build status is: 205 206.. image:: https://travis-ci.org/mpenning/ciscoconfparse.png?branch=master 207 :align: center 208 :target: https://travis-ci.org/mpenning/ciscoconfparse 209 :alt: Travis CI Status 210 211.. _`License and Copyright`: 212 213License and Copyright 214===================== 215 216ciscoconfparse_ is licensed GPLv3_ 217 218- Copyright (C) 2020-2021 David Michael Pennington at Cisco Systems 219- Copyright (C) 2019 David Michael Pennington at ThousandEyes 220- Copyright (C) 2012-2019 David Michael Pennington at Samsung Data Services 221- Copyright (C) 2011-2012 David Michael Pennington at Dell Computer Corp 222- Copyright (C) 2007-2011 David Michael Pennington 223 224The word "Cisco" is a registered trademark of Cisco Systems 225 226.. _Author: 227 228Author and Thanks 229================= 230 231ciscoconfparse_ was written by David Michael Pennington (mike [~at~] 232pennington [/dot\] net). 233 234Special thanks: 235 236- Thanks to David Muir Sharnoff for his suggestion about making a special case for IOS banners. 237- Thanks to Alan Cownie for his API suggestions. 238- Thanks to CrackerJackMack_ for reporting `Github Issue #13`_ 239- Soli Deo Gloria 240 241 242.. _ciscoconfparse: https://pypi.python.org/pypi/ciscoconfparse 243 244.. _Python: http://python.org/ 245 246.. _`pypy JIT`: http://pypy.org/ 247 248.. _`Github Issue #13`: https://github.com/mpenning/ciscoconfparse/issues/13 249 250.. _`Github Issue #14`: https://github.com/mpenning/ciscoconfparse/issues/14 251 252.. _`Github Issue #17`: https://github.com/mpenning/ciscoconfparse/issues/17 253 254.. _`brace-delimited configurations`: https://github.com/mpenning/ciscoconfparse/blob/master/configs/sample_01.junos 255 256.. _CrackerJackMack: https://github.com/CrackerJackMack 257 258.. _`David Michael Pennington`: http://pennington.net/ 259 260.. _setuptools: https://pypi.python.org/pypi/setuptools 261 262.. _pip: https://pypi.python.org/pypi/pip 263 264.. _virtualenv: https://pypi.python.org/pypi/virtualenv 265 266.. _`github repo`: https://github.com/mpenning/ciscoconfparse 267 268.. _`bitbucket repo`: https://bitbucket.org/mpenning/ciscoconfparse 269 270.. _bitbucket: https://bitbucket.org/mpenning/ciscoconfparse 271 272.. _github: https://github.com/mpenning/ciscoconfparse 273 274.. _mercurial: http://mercurial.selenic.com/ 275 276.. _`github bug tracker`: https://github.com/mpenning/ciscoconfparse/issues 277 278.. _`hg-git`: http://hg-git.github.io/ 279 280.. _`regular expressions`: http://docs.python.org/2/howto/regex.html 281 282.. _`docs`: http://www.pennington.net/py/ciscoconfparse/ 283 284.. _`ipaddr`: https://code.google.com/p/ipaddr-py/ 285 286.. _`GPLv3`: http://www.gnu.org/licenses/gpl-3.0.html 287 288.. _`ASF License 2.0`: http://www.apache.org/licenses/LICENSE-2.0 289 290.. _`Dive into Python3`: http://www.diveintopython3.net/ 291 292.. _`Network Engineering`: http://networkengineering.stackexchange.com/ 293 294.. _`Stack Overflow`: http://stackoverflow.com/ 295 296.. _`ask a question`: http://stackoverflow.com/questions/ask 297 298.. _`ciscoconfparse NetworkToCode slack channel`: https://app.slack.com/client/T09LQ7E9E/C015B4U8MMF/ 299 300.. _`Secure IOS Template`: https://www.cymru.com/Documents/secure-ios-template.html 301 302.. _`Center for Internet Security Benchmarks`: https://learn.cisecurity.org/benchmarks 303 304.. _`Team CYMRU`: http://www.team-cymru.org/ 305 306.. _`Cisco TAC`: http://cisco.com/go/support 307 308.. _`Juniper networks`: http://www.juniper.net/ 309 310.. _`Cisco's Guide to hardening IOS devices`: http://www.cisco.com/c/en/us/support/docs/ip/access-lists/13608-21.html 311 312