============= Introduction ============= Overview --------- ciscoconfparse_ is similar to an advanced grep and diff API for python_; it should be used with text network configuration files (such as those from Cisco, Juniper, Palo Alto, etc). It is the first generation of ciscoconfparse_, which was the primary development vehicle from 2007 until 2023. As of 2023, ciscoconfparse2_ is released and you should use that unless you have a good reason to stick with the original ciscoconfparse_. ciscoconfparse_ can: - Audit existing router / switch / firewall / wlc configurations against a text configuration template - Retrieve portions of the configuration - Modify existing configurations - Build new configurations The library examines an IOS-style config and breaks it into a set of linked parent / child relationships; each configuration line is stored in a different :class:`~models_cisco.IOSCfgLine` object. .. figure:: _static/ciscoconfparse_overview.png :width: 600px :alt: ciscoconfparse overview :align: left Figure 1, An Example of Parent-line / Child-line relationships Then you issue queries against these relationships using a familiar family syntax model. Queries can either be in the form of a simple string, or you can use `regular expressions`_. The API provides powerful query tools, including the ability to find all parents that have or do not have children matching a certain template. The package also provides a set of methods to query and manipulate the :class:`~models_cisco.IOSCfgLine` objects themselves. This gives you a flexible mechanism to build your own custom queries, because the :class:`~models_cisco.IOSCfgLine` objects store all the parent / child hierarchy in them. |br| |br| |br| |br| |br| |br| |br| |br| What is ciscoconfparse good for? ---------------------------------- After several network evolutions, you may have a tangled mess of conflicting or misconfigured network devices. Misconfigurations of proxy-arp, static routes, FHRP timers, routing protocols, duplicated subnets, cdp, console passwords, or aaa schemes have a measurable affect on up time and beg for a tool to audit them. However, manually scrubbing configurations is a long and error-prone process. Audits aren't the only use for ciscoconfparse. Let's suppose you are working on a design and need a list of dot1q trunks on a switch with more than 400 interfaces. You can't grep for them because you need the interface names of layer2 trunks; the interface name is stored on one line, and the trunk configuration is stored somewhere below the interface name. With ciscoconfparse, it's really this easy... .. sourcecode:: python >>> from ciscoconfparse import CiscoConfParse >>> parse = CiscoConfParse('/tftpboot/largeConfig.conf', syntax='ios', factory=False) >>> >>> # Find parent interfaces that are configured with 'switchport trunk' >>> dot1q_trunks = parse.find_parent_objects("^interface", "switchport trunk") >>> for intf in dot1q_trunks: ... print(intf) ... >>> This example: - Imports `CiscoConfParse`_ - Searches a Cisco IOS configuration file stored in ``/tftpboot/largeConfig.conf`` - Use the default 'ios' syntax for the configuration file - Use the default 'factory' setting, which is disabled - Search for configuration lines which have: - The parent beginning with ``interface`` (and anything else on the config line); ``^`` is a special character that requests to anchor the string at the beginning of the config line. - A child of that parent configured with ``switchport trunk`` (and anything else on the config line) The search found two configuration lines. We don't have Ciscos -------------------- Don't let that stop you. CiscoConfParse parses anything that has a Cisco IOS style of configuration, which includes: - Cisco IOS, Cisco Nexus, Cisco IOS-XR, Cisco IOS-XE, Aironet OS, Cisco ASA, Cisco CatOS - Arista EOS - Brocade - HP Switches - Force 10 Switches - Dell PowerConnect Switches - Extreme Networks - Enterasys As of CiscoConfParse 1.2.4, you can parse `brace-delimited configurations`_ into a Cisco IOS style (see `Github Issue #17`_), which means that CiscoConfParse understands these configurations too: - Juniper Networks Junos, and Screenos - Palo Alto Networks Firewall configurations - F5 Networks configurations Quotes ------ These are a few selected public mentions about CiscoConfParse; I usually try not to share private emails without asking, thus the quotes aren't long at this time. |br| |br| .. raw:: html CiscoConfParse Github issue #13 |br| |br| .. raw:: html Reddit comment - 20150328 |br| |br| .. raw:: html Have to audit 100 catalyst sw configs for misconfiguration/non-standard configs. Perfect job for CiscoConfParse; Jochen - l0b0 (@verbosemode) June 23, 2010 |br| |br| .. raw:: html |br| |br| What's new in version 1.0.0 --------------------------- I wrote :mod:`ciscoconfparse` in 2007 as literally my first Python project; through the years, my understanding of Python improved, and I also found many missing features along the way. Some of these features, like changing a configuration after it was parsed, required non-trivial changes to the whole project. Starting in version 0.9, I initiated a major rewrite; several important changes were made: - Python3.x compatibility; Python2.4 deprecation - Major improvement in config parsing speed - Much better unit-test coverage - Too many bug fixes to count - New feature - :mod:`ciscoconfparse` inserts, deletes and appends config lines - Rearchitected the library, with an eye towards more future improvements - Revisions in scripting flow. All users are encouraged to use :class:`~models_cisco.IOSCfgLine()` objects whenever possible. Typically, you'll start by matching them with :func:`~ciscoconfparse.CiscoConfParse.find_objects()`. Working directly with :class:`~models_cisco.IOSCfgLine()` objects makes your scripts less complicated and it also makes them faster than using legacy :mod:`ciscoconfparse` syntax. .. _`brace-delimited configurations`: https://github.com/mpenning/ciscoconfparse/blob/81cb4bee7c5ad95301b9e8b3562d70f11fa32505/configs/sample_01.junos .. _`Github Issue #17`: https://github.com/mpenning/ciscoconfparse/issues/17 .. _`This project [ciscoconfparse] has really been a lifesaver`: https://github.com/mpenning/ciscoconfparse/issues/13#issuecomment-71340177 .. _`Dive into Python3`: https://diveintopython3.problemsolving.io/ .. _`regular expressions`: https://docs.python.org/3/howto/regex.html .. _Python: http://python.org/ .. _ciscoconfparse: https://github.com/mpenning/ciscoconfparse .. _ciscoconfparse2: https://github.com/mpenning/ciscoconfparse2 .. _CiscoConfParse: https://github.com/mpenning/ciscoconfparse .. |br| raw:: html