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