bjmllr / ios_parser

parser for network router configuration files

ios_parser

convert switch and router config files to structured data

Basic Parsing

require 'ios_parser'
text = my_method_to_get_a_raw_config
config = IOSParser.parse(text)

JSON Serialization and Deserialization

my_http_client.put_json(config.to_json)
config = IOSParser.from_json(my_http_client.get_json)

Query for a single element (the first to match)

config.find('hostname').to_hash
# => { :args => ["hostname", "myswitch"], :commands => [] }

case-style Queries

config.find_all(starts_with: ['interface', /Gigabit/])
# => [{:args=>["interface", "GigabitEthernet0/1"],
#      :commands=>[{:args=>["switchport", "mode", "trunk"], :commands=>[]},
#                  {:args=>["logging", "event", "trunk-status"], :commands=>[]},
#                  {:args=>["speed", 1000], :commands=>[]}]},
#     {:args=>["interface", "GigabitEthernet0/2"],
#      :commands=>[{:args=>["switchport", "mode", "trunk"], :commands=>[]},
#                  {:args=>["logging", "event", "trunk-status"], :commands=>[]},
#                  {:args=>["speed", 1000], :commands=>[]}]}]

Chained Queries

config.find(starts_with: ['interface', 'GigabitEthernet0/1']).find('speed').args[1]
# => 1000

Nesting Queries

#find_all returns an Array, so you can't chain IOSParser queries after it. Instead, you can use nested queries with Ruby's Array and Enumerable APIs. This is useful to transform and clean data.

config.find_all("interface").flat_map do |i|
  s = i.find("speed")
  s ? [{  interface: i.args.last,  speed: s.args.last  }] : []
end
# => [{:interface=>"GigabitEthernet0/1", :speed=>1000},
#     {:interface=>"GigabitEthernet0/2", :speed=>1000}]

Compound Query Matchers

Compound matchers combine or modify the meaning of other matchers. Their argument can be a single hash if all of the affected matchers have different names, and an array of hashes if it is necessary to use the same matcher name with multiple arguments.

Available Compound Query Matchers

• parent - matches commands by their parents (e.g., parent: { starts_with: 'interface' } will match the first level of subcommands of any interface section)
• any_child - matches commands that match at least one child command (e.g., any_child: { name: 'speed' } will match any command that has a child command starting with speed)
• no_child - matches commands that do not match any child command (e.g., no_child: { name: 'speed' } will match commands that do not have a child command starting with speed)
• any - matches commands that match any of an array of queries (e.g., any: [{ starts_with: 'interface' }, { starts_with: 'ip route' }] will match all interfaces and all IOS-style static routes)
• all - matches commands that match all of an array of queries (e.g., all: { starts_with: 'interface', line: /FastEthernet/ } will match all FastEthernet interfaces)
• none - negation of any
• not_all / not - negation of all

Available Base Query Matchers

• name - matches the first argument of a command (e.g., name: ip will match ip route or ip http server)
• starts_with - matches the leading arguments of a command
• contains - matches any sequence of arguments of a command
• ends_with - matches the trailling arguments of a command
• line - matches the string form of a command (all the arguments separated by single spaces)
• depth - matches based on how many command sections contain the command (e.g., depth: 0 will only match top-level commands), accepts integers and integer ranges

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/bjmllr/ios_parser. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

Copyright and License

Copyright (C) 2016 Ben Miller

The gem is available as free software under the terms of the GNU General Public License, Version 3.