CiscoConfParse Object

class ciscoconfparse.CiscoConfParse(config='', comment='!', debug=False, factory=False, linesplit_rgx='\r*\n+', ignore_blank_lines=True, syntax='ios')

Parses Cisco IOS configurations and answers queries about the configs

Initialize CiscoConfParse.

Kwargs:
  • config (list or str): A list of configuration statements, or a configuration file path to be parsed
  • comment (str): A comment delimiter. This should only be changed when parsing non-Cisco IOS configurations, which do not use a ! as the comment delimiter. comment defaults to ‘!’. This value can hold multiple characters in case the config uses multiple characters for comment delimiters; however, the comment delimiters are always assumed to be one character wide
  • debug (bool): debug defaults to False, and should be kept that way unless you’re working on a very tricky config parsing problem. Debug output is not particularly friendly
  • factory (bool): factory defaults to False; if set True, it enables a beta-quality configuration line classifier.
  • linesplit_rgx (str): linesplit_rgx is used when parsing configuration files to find where new configuration lines are. It is best to leave this as the default, unless you’re working on a system that uses unusual line terminations (for instance something besides Unix, OSX, or Windows)
  • ignore_blank_lines (bool): ignore_blank_lines defaults to True; when this is set True, ciscoconfparse ignores blank configuration lines. You might want to set ignore_blank_lines to False if you intentionally use blank lines in your configuration (ref: Github Issue #2), or you are parsing configurations which naturally have blank lines (such as Cisco Nexus configurations).
  • syntax (str): syntax defaults to ‘ios’; You can choose from the following values: ios, asa
Attributes:
  • comment_delimiter (str): A string containing the comment-delimiter
  • ConfigObjs (IOSConfigList) : A custom list, which contains all parsed IOSCfgLine instances.
  • all_parents (list) : A list of all parent IOSCfgLine instances.
  • last_index (int) : An integer with the last index in ConfigObjs
Returns:

This example illustrates how to parse a simple Cisco IOS configuration with CiscoConfParse into a variable called parse. This example also illustrates what the ConfigObjs and ioscfg attributes contain.

>>> config = [
...     'logging trap debugging',
...     'logging 172.28.26.15',
...     ] 
>>> parse = CiscoConfParse(config)
>>> parse
<CiscoConfParse: 2 lines / syntax: ios / comment delimiter: '!' / factory: False>
>>> parse.ConfigObjs
<IOSConfigList, comment='!', conf=[<IOSCfgLine # 0 'logging trap debugging'>, <IOSCfgLine # 1 'logging 172.28.26.15'>]>
>>> parse.ioscfg
['logging trap debugging', 'logging 172.28.26.15']
>>>
append_line(linespec)

Unconditionally insert linespec (a text line) at the end of the configuration

Args:
  • linespec (str): Text IOS configuration line
Returns:
atomic()

Call atomic() to manually fix up ConfigObjs relationships after modifying a parsed configuration. This method is slow; try to batch calls to atomic() if possible.

Warning

If you modify a configuration after parsing it with CiscoConfParse, you must call commit() or atomic() before searching the configuration again with methods such as find_objects() or find_lines(). Failure to call commit() or atomic() on config modifications could lead to unexpected search results.

commit()

Alias for calling the atomic() method. This method is slow; try to batch calls to commit() if possible.

Warning

If you modify a configuration after parsing it with CiscoConfParse, you must call commit() or atomic() before searching the configuration again with methods such as find_objects() or find_lines(). Failure to call commit() or atomic() on config modifications could lead to unexpected search results.

convert_braces_to_ios(input_list, stop_width=4)
delete_lines(linespec, exactmatch=False, ignore_ws=False)

Find all IOSCfgLine objects whose text matches linespec, and delete the object

find_all_children(linespec, exactmatch=False, ignore_ws=False)

Returns the parents matching the linespec, and all their children. This method is different than find_children(), because find_all_children() finds children of children. find_children() only finds immediate children.

Args:
  • linespec (str): Text regular expression for the line to be matched
Kwargs:
  • exactmatch (bool): boolean that controls whether partial matches are valid
  • ignore_ws (bool): boolean that controls whether whitespace is ignored
Returns:
  • list. A list of matching configuration lines

Suppose you are interested in finding all archive statements in the following configuration...

username ddclient password 7 107D3D232342041E3A
archive
 log config
  logging enable
  hidekeys
 path ftp://ns.foo.com//tftpboot/Foo-archive
!

Using the config above, we expect to find the following config lines...

archive
 log config
  logging enable
  hidekeys
 path ftp://ns.foo.com//tftpboot/Foo-archive

We would accomplish this by querying find_all_children(‘^archive’)...

>>> from ciscoconfparse import CiscoConfParse
>>> config = ['username ddclient password 7 107D3D232342041E3A',
...           'archive',
...           ' log config',
...           '  logging enable',
...           '  hidekeys',
...           ' path ftp://ns.foo.com//tftpboot/Foo-archive',
...           '!',
...     ]
>>> p = CiscoConfParse(config)
>>> p.find_all_children('^archive')
['archive', ' log config', '  logging enable', '  hidekeys', ' path ftp://ns.foo.com//tftpboot/Foo-archive']
>>>
find_blocks(linespec, exactmatch=False, ignore_ws=False)

Find all siblings matching the linespec, then find all parents of those siblings. Return a list of config lines sorted by line number, lowest first. Note: any children of the siblings should NOT be returned.

Args:
  • linespec (str): Text regular expression for the line to be matched
Kwargs:
  • exactmatch (bool): boolean that controls whether partial matches are valid
  • ignore_ws (bool): boolean that controls whether whitespace is ignored
Returns:
  • list. A list of matching configuration lines

This example finds bandwidth percent statements in following config, the siblings of those bandwidth percent statements, as well as the parent configuration statements required to access them.

!
policy-map EXTERNAL_CBWFQ
 class IP_PREC_HIGH
  priority percent 10
  police cir percent 10
    conform-action transmit
    exceed-action drop
 class IP_PREC_MEDIUM
  bandwidth percent 50
  queue-limit 100
 class class-default
  bandwidth percent 40
  queue-limit 100
policy-map SHAPE_HEIR
 class ALL
  shape average 630000
  service-policy EXTERNAL_CBWFQ
!

The following config lines should be returned:

policy-map EXTERNAL_CBWFQ
 class IP_PREC_MEDIUM
  bandwidth percent 50
  queue-limit 100
 class class-default
  bandwidth percent 40
  queue-limit 100

We do this by quering find_blocks(‘bandwidth percent’)...

>>> from ciscoconfparse import CiscoConfParse
>>> config = ['!', 
...           'policy-map EXTERNAL_CBWFQ', 
...           ' class IP_PREC_HIGH', 
...           '  priority percent 10', 
...           '  police cir percent 10', 
...           '    conform-action transmit', 
...           '    exceed-action drop', 
...           ' class IP_PREC_MEDIUM', 
...           '  bandwidth percent 50', 
...           '  queue-limit 100', 
...           ' class class-default', 
...           '  bandwidth percent 40', 
...           '  queue-limit 100', 
...           'policy-map SHAPE_HEIR', 
...           ' class ALL', 
...           '  shape average 630000', 
...           '  service-policy EXTERNAL_CBWFQ', 
...           '!',
...     ]
>>> p = CiscoConfParse(config)
>>> p.find_blocks('bandwidth percent')
['policy-map EXTERNAL_CBWFQ', ' class IP_PREC_MEDIUM', '  bandwidth percent 50', '  queue-limit 100', ' class class-default', '  bandwidth percent 40', '  queue-limit 100']
>>>
>>> p.find_blocks(' class class-default')
['policy-map EXTERNAL_CBWFQ', ' class IP_PREC_HIGH', ' class IP_PREC_MEDIUM', ' class class-default']
>>>
find_children(linespec, exactmatch=False, ignore_ws=False)

Returns the parents matching the linespec, and their immediate children. This method is different than find_all_children(), because find_all_children() finds children of children. find_children() only finds immediate children.

Args:
  • linespec (str): Text regular expression for the line to be matched
Kwargs:
  • exactmatch (bool): boolean that controls whether partial matches are valid
  • ignore_ws (bool): boolean that controls whether whitespace is ignored
Returns:
  • list. A list of matching configuration lines

Suppose you are interested in finding all immediate children of the archive statements in the following configuration...

username ddclient password 7 107D3D232342041E3A
archive
 log config
  logging enable
  hidekeys
 path ftp://ns.foo.com//tftpboot/Foo-archive
!

Using the config above, we expect to find the following config lines...

archive
 log config
 path ftp://ns.foo.com//tftpboot/Foo-archive

We would accomplish this by querying find_children(‘^archive’)...

>>> from ciscoconfparse import CiscoConfParse
>>> config = ['username ddclient password 7 107D3D232342041E3A',
...           'archive',
...           ' log config',
...           '  logging enable',
...           '  hidekeys',
...           ' path ftp://ns.foo.com//tftpboot/Foo-archive',
...           '!',
...     ]
>>> p = CiscoConfParse(config)
>>> p.find_children('^archive')
['archive', ' log config', ' path ftp://ns.foo.com//tftpboot/Foo-archive']
>>>
find_children_w_parents(parentspec, childspec, ignore_ws=False)

Parse through the children of all parents matching parentspec, and return a list of children that matched the childspec.

Args:
  • parentspec (str): Text regular expression for the line to be matched; this must match the parent’s line
  • childspec (str): Text regular expression for the line to be matched; this must match the child’s line
Kwargs:
  • ignore_ws (bool): boolean that controls whether whitespace is ignored
Returns:
  • list. A list of matching child configuration lines

This example finds the port-security lines on FastEthernet0/1 in following config...

!
interface FastEthernet0/1
 switchport access vlan 532
 switchport port-security
 switchport port-security violation protect
 switchport port-security aging time 5
 switchport port-security aging type inactivity
 spanning-tree portfast
 spanning-tree bpduguard enable
!
interface FastEthernet0/2
 switchport access vlan 300
 spanning-tree portfast
 spanning-tree bpduguard enable
!
interface FastEthernet0/2
 duplex full
 speed 100
 switchport access vlan 300
 spanning-tree portfast
 spanning-tree bpduguard enable
!

The following lines should be returned:

switchport port-security
switchport port-security violation protect
switchport port-security aging time 5
switchport port-security aging type inactivity

We do this by quering find_children_w_parents(); we set our parent as ^interface and set the child as switchport port-security.

>>> config = ['!', 
...           'interface FastEthernet0/1', 
...           ' switchport access vlan 532', 
...           ' switchport port-security', 
...           ' switchport port-security violation protect', 
...           ' switchport port-security aging time 5', 
...           ' switchport port-security aging type inactivity', 
...           ' spanning-tree portfast', 
...           ' spanning-tree bpduguard enable', 
...           '!', 
...           'interface FastEthernet0/2', 
...           ' switchport access vlan 300', 
...           ' spanning-tree portfast', 
...           ' spanning-tree bpduguard enable', 
...           '!', 
...           'interface FastEthernet0/3', 
...           ' duplex full', 
...           ' speed 100', 
...           ' switchport access vlan 300', 
...           ' spanning-tree portfast', 
...           ' spanning-tree bpduguard enable', 
...           '!',
...     ]
>>> p = CiscoConfParse(config)
>>> p.find_children_w_parents('^interface\sFastEthernet0/1',            'port-security')
[' switchport port-security', ' switchport port-security violation protect', ' switchport port-security aging time 5', ' switchport port-security aging type inactivity']
>>>
find_interface_objects(intfspec, exactmatch=True)

Find all IOSCfgLine objects whose text is an abbreviation for intfspec and return the IOSIntfLine objects in a python list.

Note

The configuration must be parsed with factory=True to use this method

Args:
  • intfspec (str): A string which is the abbreviation (or full name) of the interface
Kwargs:
  • exactmatch (bool): Defaults to True; when True, this option requires intfspec match the whole interface name and number.
Returns:
  • list. A list of matching IOSIntfLine objects
>>> config = [
...     '!',
...     'interface Serial1/0',
...     ' ip address 1.1.1.1 255.255.255.252',
...     '!',
...     'interface Serial1/1',
...     ' ip address 1.1.1.5 255.255.255.252',
...     '!',
...     ]
>>> parse = CiscoConfParse(config, factory=True)
>>>
>>> parse.find_interface_objects('Se 1/0')
[<IOSIntfLine # 1 'Serial1/0' info: '1.1.1.1/30'>]
>>>
find_lineage(linespec, exactmatch=False)

Iterate through to the oldest ancestor of this object, and return a list of all ancestors / children in the direct line. Cousins or aunts / uncles are not returned. Note, all children of this object are returned.

find_lines(linespec, exactmatch=False, ignore_ws=False)

This method is the equivalent of a simple configuration grep (Case-sensitive).

Args:
  • linespec (str): Text regular expression for the line to be matched
Kwargs:
  • exactmatch (bool): Defaults to False. When set True, this option requires linespec match the whole configuration line, instead of a portion of the configuration line.
  • ignore_ws (bool): boolean that controls whether whitespace is ignored. Default is False.
Returns:
  • list. A list of matching configuration lines
find_objects(linespec, exactmatch=False, ignore_ws=False)

Find all IOSCfgLine objects whose text matches linespec and return the IOSCfgLine objects in a python list. find_objects() is similar to find_lines(); however, the former returns a list of IOSCfgLine objects, while the latter returns a list of text configuration statements. Going forward, I strongly encourage people to start using find_objects() instead of find_lines().

Args:
  • linespec (str): A string or python regular expression, which should be matched
Kwargs:
  • exactmatch (bool): Defaults to False. When set True, this option requires linespec match the whole configuration line, instead of a portion of the configuration line.
  • ignore_ws (bool): boolean that controls whether whitespace is ignored. Default is False.
Returns:
  • list. A list of matching IOSCfgLine objects

This example illustrates the difference between find_objects() and find_lines().

>>> config = [
...     '!',
...     'interface Serial1/0',
...     ' ip address 1.1.1.1 255.255.255.252',
...     '!',
...     'interface Serial1/1',
...     ' ip address 1.1.1.5 255.255.255.252',
...     '!',
...     ]
>>> parse = CiscoConfParse(config)
>>>
>>> parse.find_objects(r'^interface')
[<IOSCfgLine # 1 'interface Serial1/0'>, <IOSCfgLine # 4 'interface Serial1/1'>]
>>>
>>> parse.find_lines(r'^interface')
['interface Serial1/0', 'interface Serial1/1']
>>>
find_objects_dna(dnaspec, exactmatch=False)

Find all IOSCfgLine objects whose text matches dnaspec and return the IOSCfgLine objects in a python list.

Note

find_objects_dna() requires the configuration to be parsed with factory=True

Args:
  • dnaspec (str): A string or python regular expression, which should be matched. This argument will be used to match dna attribute of the object
Kwargs:
  • exactmatch (bool): Defaults to False. When set True, this option requires dnaspec match the whole configuration line, instead of a portion of the configuration line.
Returns:
  • list. A list of matching IOSCfgLine objects
>>> config = [
...     '!',
...     'hostname MyRouterHostname',
...     '!',
...     ]
>>> parse = CiscoConfParse(config, factory=True, syntax='ios')
>>>
>>> obj_list = parse.find_objects_dna(r'Hostname')
>>> obj_list
[<IOSHostnameLine # 1 'MyRouterHostname'>]
>>>
>>> # The IOSHostnameLine object has a hostname attribute
>>> obj_list[0].hostname
'MyRouterHostname'
>>>
find_objects_w_child(parentspec, childspec, ignore_ws=False)

Return a list of parent IOSCfgLine objects, which matched the parentspec and whose children match childspec. Only the parent IOSCfgLine objects will be returned.

Args:
  • parentspec (str): Text regular expression for the IOSCfgLine object to be matched; this must match the parent’s line
  • childspec (str): Text regular expression for the line to be matched; this must match the child’s line
Kwargs:
  • ignore_ws (bool): boolean that controls whether whitespace is ignored
Returns:
  • list. A list of matching parent IOSCfgLine objects

This example uses find_objects_w_child() to find all ports that are members of access vlan 300 in following config...

!
interface FastEthernet0/1
 switchport access vlan 532
 spanning-tree vlan 532 cost 3
!
interface FastEthernet0/2
 switchport access vlan 300
 spanning-tree portfast
!
interface FastEthernet0/2
 duplex full
 speed 100
 switchport access vlan 300
 spanning-tree portfast
!

The following interfaces should be returned:

interface FastEthernet0/2
interface FastEthernet0/3

We do this by quering find_objects_w_child(); we set our parent as ^interface and set the child as switchport access vlan 300.

>>> config = ['!', 
...           'interface FastEthernet0/1', 
...           ' switchport access vlan 532', 
...           ' spanning-tree vlan 532 cost 3', 
...           '!', 
...           'interface FastEthernet0/2', 
...           ' switchport access vlan 300', 
...           ' spanning-tree portfast', 
...           '!', 
...           'interface FastEthernet0/3', 
...           ' duplex full', 
...           ' speed 100', 
...           ' switchport access vlan 300', 
...           ' spanning-tree portfast', 
...           '!',
...     ]
>>> p = CiscoConfParse(config)
>>> p.find_objects_w_child('^interface', 
...     'switchport access vlan 300')
...
[<IOSCfgLine # 5 'interface FastEthernet0/2'>, <IOSCfgLine # 9 'interface FastEthernet0/3'>]
>>>
find_objects_w_parents(parentspec, childspec, ignore_ws=False)

Parse through the children of all parents matching parentspec, and return a list of child objects, which matched the childspec.

Args:
  • parentspec (str): Text regular expression for the line to be matched; this must match the parent’s line
  • childspec (str): Text regular expression for the line to be matched; this must match the child’s line
Kwargs:
  • ignore_ws (bool): boolean that controls whether whitespace is ignored
Returns:
  • list. A list of matching child objects

This example finds the object for “ge-0/0/0” under “interfaces” in the following config...

interfaces 
    ge-0/0/0 
        unit 0 
            family ethernet-switching 
                port-mode access
                vlan 
                    members VLAN_FOO
    ge-0/0/1 
        unit 0 
            family ethernet-switching 
                port-mode trunk
                vlan 
                    members all
                native-vlan-id 1
    vlan 
        unit 0 
            family inet 
                address 172.16.15.5/22

The following object should be returned:

<IOSCfgLine # 7 '    ge-0/0/1' (parent is # 0)>

We do this by quering find_childobj_w_parents(); we set our parent as ^s*interface and set the child as ^s+ge-0/0/1.

>>> config = ['interfaces',
...           '    ge-0/0/0',
...           '        unit 0',
...           '            family ethernet-switching',
...           '                port-mode access',
...           '                vlan',
...           '                    members VLAN_FOO',
...           '    ge-0/0/1',
...           '        unit 0',
...           '            family ethernet-switching',
...           '                port-mode trunk',
...           '                vlan',
...           '                    members all',
...           '                native-vlan-id 1',
...           '    vlan',
...           '        unit 0',
...           '            family inet',
...           '                address 172.16.15.5/22',
...     ]
>>> p = CiscoConfParse(config)
>>> p.find_objects_w_parents('^\s*interfaces',            r'\s+ge-0/0/1')
[<IOSCfgLine # 7 '    ge-0/0/1' (parent is # 0)>]
>>>
find_objects_wo_child(parentspec, childspec, ignore_ws=False)

Return a list of parent IOSCfgLine objects, which matched the parentspec and whose children did not match childspec. Only the parent IOSCfgLine objects will be returned. For simplicity, this method only finds oldest_ancestors without immediate children that match.

Args:
  • parentspec (str): Text regular expression for the IOSCfgLine object to be matched; this must match the parent’s line
  • childspec (str): Text regular expression for the line to be matched; this must match the child’s line
Kwargs:
  • ignore_ws (bool): boolean that controls whether whitespace is ignored
Returns:
  • list. A list of matching parent configuration lines

This example finds all ports that are autonegotiating in the following config...

!
interface FastEthernet0/1
 switchport access vlan 532
 spanning-tree vlan 532 cost 3
!
interface FastEthernet0/2
 switchport access vlan 300
 spanning-tree portfast
!
interface FastEthernet0/2
 duplex full
 speed 100
 switchport access vlan 300
 spanning-tree portfast
!

The following interfaces should be returned:

interface FastEthernet0/1
interface FastEthernet0/2

We do this by quering find_objects_wo_child(); we set our parent as ^interface and set the child as speedsd+ (a regular-expression which matches the word ‘speed’ followed by an integer).

>>> config = ['!', 
...           'interface FastEthernet0/1', 
...           ' switchport access vlan 532', 
...           ' spanning-tree vlan 532 cost 3', 
...           '!', 
...           'interface FastEthernet0/2', 
...           ' switchport access vlan 300', 
...           ' spanning-tree portfast', 
...           '!', 
...           'interface FastEthernet0/3', 
...           ' duplex full', 
...           ' speed 100', 
...           ' switchport access vlan 300', 
...           ' spanning-tree portfast', 
...           '!',
...     ]
>>> p = CiscoConfParse(config)
>>> p.find_objects_wo_child(r'^interface', r'speed\s\d+')
[<IOSCfgLine # 1 'interface FastEthernet0/1'>, <IOSCfgLine # 5 'interface FastEthernet0/2'>]
>>>
find_parents_w_child(parentspec, childspec, ignore_ws=False)

Parse through all children matching childspec, and return a list of parents that matched the parentspec. Only the parent lines will be returned.

Args:
  • parentspec (str): Text regular expression for the line to be matched; this must match the parent’s line
  • childspec (str): Text regular expression for the line to be matched; this must match the child’s line
Kwargs:
  • ignore_ws (bool): boolean that controls whether whitespace is ignored
Returns:
  • list. A list of matching parent configuration lines

This example finds all ports that are members of access vlan 300 in following config...

!
interface FastEthernet0/1
 switchport access vlan 532
 spanning-tree vlan 532 cost 3
!
interface FastEthernet0/2
 switchport access vlan 300
 spanning-tree portfast
!
interface FastEthernet0/2
 duplex full
 speed 100
 switchport access vlan 300
 spanning-tree portfast
!

The following interfaces should be returned:

interface FastEthernet0/2
interface FastEthernet0/3

We do this by quering find_parents_w_child(); we set our parent as ^interface and set the child as switchport access vlan 300.

>>> config = ['!', 
...           'interface FastEthernet0/1', 
...           ' switchport access vlan 532', 
...           ' spanning-tree vlan 532 cost 3', 
...           '!', 
...           'interface FastEthernet0/2', 
...           ' switchport access vlan 300', 
...           ' spanning-tree portfast', 
...           '!', 
...           'interface FastEthernet0/3', 
...           ' duplex full', 
...           ' speed 100', 
...           ' switchport access vlan 300', 
...           ' spanning-tree portfast', 
...           '!',
...     ]
>>> p = CiscoConfParse(config)
>>> p.find_parents_w_child('^interface', 'switchport access vlan 300')
['interface FastEthernet0/2', 'interface FastEthernet0/3']
>>>
find_parents_wo_child(parentspec, childspec, ignore_ws=False)

Parse through all parents matching parentspec, and return a list of parents that did NOT have children match the childspec. For simplicity, this method only finds oldest_ancestors without immediate children that match.

Args:
  • parentspec (str): Text regular expression for the line to be matched; this must match the parent’s line
  • childspec (str): Text regular expression for the line to be matched; this must match the child’s line
Kwargs:
  • ignore_ws (bool): boolean that controls whether whitespace is ignored
Returns:
  • list. A list of matching parent configuration lines

This example finds all ports that are autonegotiating in the following config...

!
interface FastEthernet0/1
 switchport access vlan 532
 spanning-tree vlan 532 cost 3
!
interface FastEthernet0/2
 switchport access vlan 300
 spanning-tree portfast
!
interface FastEthernet0/2
 duplex full
 speed 100
 switchport access vlan 300
 spanning-tree portfast
!

The following interfaces should be returned:

interface FastEthernet0/1
interface FastEthernet0/2

We do this by quering find_parents_wo_child(); we set our parent as ^interface and set the child as speedsd+ (a regular-expression which matches the word ‘speed’ followed by an integer).

>>> config = ['!', 
...           'interface FastEthernet0/1', 
...           ' switchport access vlan 532', 
...           ' spanning-tree vlan 532 cost 3', 
...           '!', 
...           'interface FastEthernet0/2', 
...           ' switchport access vlan 300', 
...           ' spanning-tree portfast', 
...           '!', 
...           'interface FastEthernet0/3', 
...           ' duplex full', 
...           ' speed 100', 
...           ' switchport access vlan 300', 
...           ' spanning-tree portfast', 
...           '!',
...     ]
>>> p = CiscoConfParse(config)
>>> p.find_parents_wo_child('^interface', 'speed\s\d+')
['interface FastEthernet0/1', 'interface FastEthernet0/2']
>>>
has_line_with(linespec)
insert_after(linespec, insertstr='', exactmatch=False, ignore_ws=False, atomic=False)

Find all IOSCfgLine objects whose text matches linespec, and insert insertstr after those line objects

insert_after_child(parentspec, childspec, insertstr='', exactmatch=False, excludespec=None, ignore_ws=False, atomic=False)

Find all IOSCfgLine objects whose text matches linespec and have a child matching childspec, and insert an IOSCfgLine object for insertstr after those child objects.

insert_before(linespec, insertstr='', exactmatch=False, ignore_ws=False, atomic=False)

Find all objects whose text matches linespec, and insert ‘insertstr’ before those line objects

ioscfg

A list containing all text configuration statements

objs

An alias to the ConfigObjs attribute

prepend_line(linespec)

Unconditionally insert an IOSCfgLine object for linespec (a text line) at the top of the configuration

replace_all_children(parentspec, childspec, replacestr, excludespec=None, exactmatch=False, atomic=False)

Replace lines matching childspec within all children (recursive) of lines whilch match parentspec

replace_children(parentspec, childspec, replacestr, excludespec=None, exactmatch=False, atomic=False)

Replace lines matching childspec within the parentspec‘s immediate children.

Args:
  • parentspec (str): Text IOS configuration line
  • childspec (str): Text IOS configuration line, or regular expression
  • replacestr (str): Text IOS configuration, which should replace text matching childspec.
Kwargs:
  • excludespec (str): A regular expression, which indicates childspec lines which must be skipped. If excludespec is None, no lines will be excluded.
  • exactmatch (bool): Defaults to False. When set True, this option requires linespec match the whole configuration line, instead of a portion of the configuration line.
Returns:

replace_children() just searches through a parent’s child lines and replaces anything matching childspec with replacestr. This method is one of my favorites for quick and dirty standardization efforts if you know the commands are already there (just set inconsistently).

One very common use case is rewriting all vlan access numbers in a configuration. The following example sets storm-control broadcast level 0.5 on all GigabitEthernet ports.

>>> from ciscoconfparse import CiscoConfParse
>>> config = ['!', 
...           'interface GigabitEthernet1/1',
...           ' description {I have a broken storm-control config}',
...           ' switchport',
...           ' switchport mode access',
...           ' switchport access vlan 50',
...           ' switchport nonegotiate',
...           ' storm-control broadcast level 0.2',
...           '!'
...     ]
>>> p = CiscoConfParse(config)
>>> p.replace_children(r'^interface\sGigabit', r'broadcast\slevel\s\S+', 'broadcast level 0.5')
[' storm-control broadcast level 0.5']
>>>

One thing to remember about the last example, you cannot use a regular expression in replacestr; just use a normal python string.

replace_lines(linespec, replacestr, excludespec=None, exactmatch=False, atomic=False)

This method is a text search and replace (Case-sensitive). You can optionally exclude lines from replacement by including a string (or compiled regular expression) in excludespec.

Args:
  • linespec (str): Text regular expression for the line to be matched
  • replacestr (str): Text used to replace strings matching linespec
Kwargs:
  • excludespec (str): Text regular expression used to reject lines, which would otherwise be replaced. Default value of excludespec is None, which means nothing is excluded
  • exactmatch (bool): boolean that controls whether partial matches are valid
  • atomic (bool): boolean that controls whether the config is reparsed after replacement (default True)
Returns:
  • list. A list of changed configuration lines

This example finds statements with EXTERNAL_CBWFQ in following config, and replaces all matching lines (in-place) with EXTERNAL_QOS. For the purposes of this example, let’s assume that we do not want to make changes to any descriptions on the policy.

!
policy-map EXTERNAL_CBWFQ
 description implement an EXTERNAL_CBWFQ policy
 class IP_PREC_HIGH
  priority percent 10
  police cir percent 10
    conform-action transmit
    exceed-action drop
 class IP_PREC_MEDIUM
  bandwidth percent 50
  queue-limit 100
 class class-default
  bandwidth percent 40
  queue-limit 100
policy-map SHAPE_HEIR
 class ALL
  shape average 630000
  service-policy EXTERNAL_CBWFQ
!

We do this by calling replace_lines(linespec=’EXTERNAL_CBWFQ’, replacestr=’EXTERNAL_QOS’, excludespec=’description’)...

>>> from ciscoconfparse import CiscoConfParse
>>> config = ['!', 
...           'policy-map EXTERNAL_CBWFQ', 
...           ' description implement an EXTERNAL_CBWFQ policy',
...           ' class IP_PREC_HIGH', 
...           '  priority percent 10', 
...           '  police cir percent 10', 
...           '    conform-action transmit', 
...           '    exceed-action drop', 
...           ' class IP_PREC_MEDIUM', 
...           '  bandwidth percent 50', 
...           '  queue-limit 100', 
...           ' class class-default', 
...           '  bandwidth percent 40', 
...           '  queue-limit 100', 
...           'policy-map SHAPE_HEIR', 
...           ' class ALL', 
...           '  shape average 630000', 
...           '  service-policy EXTERNAL_CBWFQ', 
...           '!',
...     ]
>>> p = CiscoConfParse(config)
>>> p.replace_lines('EXTERNAL_CBWFQ', 'EXTERNAL_QOS', 'description')
['policy-map EXTERNAL_QOS', '  service-policy EXTERNAL_QOS']
>>>

Now when we call p.find_blocks(‘policy-map EXTERNAL_QOS’), we get the changed configuration, which has the replacements except on the policy-map’s description.

>>> p.find_blocks('EXTERNAL_QOS')
['policy-map EXTERNAL_QOS', ' description implement an EXTERNAL_CBWFQ policy', ' class IP_PREC_HIGH', ' class IP_PREC_MEDIUM', ' class class-default', 'policy-map SHAPE_HEIR', ' class ALL', '  shape average 630000', '  service-policy EXTERNAL_QOS']
>>>
req_cfgspec_all_diff(cfgspec, ignore_ws=False)

req_cfgspec_all_diff takes a list of required configuration lines, parses through the configuration, and ensures that none of cfgspec’s lines are missing from the configuration. req_cfgspec_all_diff returns a list of missing lines from the config.

One example use of this method is when you need to enforce routing protocol standards, or standards against interface configurations.

Example

>>> config = [
...     'logging trap debugging',
...     'logging 172.28.26.15',
...     ] 
>>> p = CiscoConfParse(config)
>>> required_lines = [
...     "logging 172.28.26.15",
...     "logging 172.16.1.5",
...     ]
>>> diffs = p.req_cfgspec_all_diff(required_lines)
>>> diffs
['logging 172.16.1.5']
>>>
req_cfgspec_excl_diff(linespec, uncfgspec, cfgspec)

req_cfgspec_excl_diff accepts a linespec, an unconfig spec, and a list of required configuration elements. Return a list of configuration diffs to make the configuration comply. All other config lines matching the linespec that are not listed in the cfgspec will be removed with the uncfgspec regex.

Uses for this method include the need to enforce syslog, acl, or aaa standards.

Example

>>> config = [
...     'logging trap debugging',
...     'logging 172.28.26.15',
...     ] 
>>> p = CiscoConfParse(config)
>>> required_lines = [
...     "logging 172.16.1.5",
...     "logging 1.10.20.30",
...     "logging 192.168.1.1",
...     ]
>>> linespec = "logging\s+\d+\.\d+\.\d+\.\d+"
>>> unconfspec = linespec
>>> diffs = p.req_cfgspec_excl_diff(linespec, unconfspec, 
...     required_lines)
>>> diffs
['no logging 172.28.26.15', 'logging 172.16.1.5', 'logging 1.10.20.30', 'logging 192.168.1.1']
>>>
save_as(filepath)

Save a text copy of the configuration at filepath; this method uses the OperatingSystem’s native line separators (such as \r\n in Windows).

sync_diff(cfgspec, linespec, uncfgspec=None, ignore_order=True, remove_lines=True, debug=False)

sync_diff() accepts a list of required configuration elements, a linespec, and an unconfig spec. This method return a list of configuration diffs to make the configuration comply with cfgspec.

Args:
  • cfgspec (list): A list of required configuration lines
  • linespec (str): A regular expression, which filters lines to be diff’d
Kwargs:
  • uncfgspec (str): A regular expression, which is used to unconfigure lines. When ciscoconfparse removes a line, it takes the entire portion of the line that matches uncfgspec, and prepends “no” to it.
  • ignore_order (bool): Indicates whether the configuration should be reordered to minimize the number of diffs. Default: True (usually it’s a good idea to leave ignore_order True, except for ACL comparisions)
  • remove_lines (bool): Indicates whether the lines which are not in cfgspec should be removed. Default: True. When remove_lines is True, all other config lines matching the linespec that are not listed in the cfgspec will be removed with the uncfgspec regex.
  • debug (bool): Miscellaneous debugging; Default: False
Returns:
  • list. A list of string configuration diffs

Uses for this method include the need to enforce syslog, acl, or aaa standards.

Example

>>> config = [
...     'logging trap debugging',
...     'logging 172.28.26.15',
...     ] 
>>> p = CiscoConfParse(config)
>>> required_lines = [
...     "logging 172.16.1.5",
...     "logging 1.10.20.30",
...     "logging 192.168.1.1",
...     ]
>>> linespec = "logging\s+\d+\.\d+\.\d+\.\d+"
>>> unconfspec = linespec
>>> diffs = p.sync_diff(required_lines, linespec, unconfspec)
>>> diffs
['no logging 172.28.26.15', 'logging 172.16.1.5', 'logging 1.10.20.30', 'logging 192.168.1.1']
>>>