trigger.cmds — Command execution library

This module abstracts the asynchronous execution of commands on multiple network devices. It allows for integrated parsing and event-handling of return data for rapid integration to existing or newly-created tools.

The Commando class is designed to be extended but can still be used as-is to execute commands and return the results as-is.

Please see the source code for ShowClock class for a basic example of one might create a subclass. Better documentation is in the works!

class trigger.cmds.Commando(devices=None, commands=None, incremental=None, max_conns=10, verbose=False, timeout=30, production_only=True, allow_fallback=True)

Execute commands asynchronously on multiple network devices.

This class is designed to be extended but can still be used as-is to execute commands and return the results as-is.

At the bare minimum you must specify a list of devices to interact with. You may optionally specify a list of commands to execute on those devices, but doing so will execute the same commands on every device regardless of platform.

If commands are not specified, they will be expected to be emitted by the generate method for a given platform. Otherwise no commands will be executed.

If you wish to customize the commands executed by device, you must define a to_{vendor_name} method containing your custom logic.

If you wish to customize what is done with command results returned from a device, you must define a from_{vendor_name} method containing your custom logic.

Parameters:
  • devices – A list of device hostnames or NetDevice objects
  • commands – (Optional) A list of commands to execute on the devices.
  • incremental – (Optional) A callback that will be called with an empty sequence upon connection and then called every time a result comes back from the device, with the list of all results.
  • max_conns – (Optional) The maximum number of simultaneous connections to keep open.
  • verbose – (Optional) Whether or not to display informational messages to the console.
  • timeout – (Optional) Time in seconds to wait for each command executed to return a result
  • production_only – (Optional) If set, includes all devices instead of excluding any devices where adminStatus is not set to PRODUCTION.
  • allow_fallback – If set (default), allow fallback to base parse/generate methods when they are not customized in a subclass, otherwise an exception is raised when a method is called that has not been explicitly defined.
errback(failure, device)

The default errback. Overload for custom behavior but make sure it always decrements the connections.

Parameters:
  • failure – Usually a Twisted Failure instance.
  • device – A NetDevice object
generate(device, commands=None, extra=None)

Generate commands to be run on a device. If you don’t provide commands to the class constructor, this will return an empty list.

Define a ‘to_{vendor_name}’ method to customize the behavior for each platform.

Parameters:
  • device – A NetDevice object
  • commands – (Optional) A list of commands to execute on the device. If not specified in they will be inherited from commands passed to the class constructor.
  • extra – (Optional) A dictionary of extra data to send to the generate method for the device.
map_results(commands=None, results=None)

Return a dict of {command: result, ...}

parse(results, device)

Parse output from a device.

Define a ‘from_{vendor_name}’ method to customize the behavior for each platform.

Parameters:
  • results – The results of the commands executed on the device
  • device – A NetDevice object
reactor_running

Return whether reactor event loop is running or not

run()

Nothing happens until you execute this to perform the actual work.

select_next_device(jobs=None)

Select another device for the active queue.

Currently only returns the next device in the job queue. This is abstracted out so that this behavior may be customized, such as for future support for incremental callbacks.

Parameters:jobs – (Optional) The jobs queue. If not set, uses self.jobs.
Returns:A NetDevice object
store_error(device, error)

A simple method for storing an error called by all default parse/generate methods.

If you want to customize the default method for storing results, overload this in your subclass.

Parameters:
  • device – A NetDevice object
  • error – The error to store. Anything you want really, but usually a Twisted Failure instance.
store_results(device, results)

A simple method for storing results called by all default parse/generate methods.

If you want to customize the default method for storing results, overload this in your subclass.

Parameters:
  • device – A NetDevice object
  • results – The results to store. Anything you want really.
to_juniper(device, commands=None, extra=None)

This just creates a series of <command>foo</command> elements to pass along to execute_junoscript()

class trigger.cmds.NetACLInfo(**args)

Class to fetch and parse interface information. Exposes a config attribute which is a dictionary of devices passed to the constructor and their interface information.

Each device is a dictionary of interfaces. Each interface field will default to an empty list if not populated after parsing. Below is a skeleton of the basic config, with expected fields:

config {
    'device1': {
        'interface1': {
            'acl_in': [],
            'acl_out': [],
            'addr': [],
            'description': [],
            'subnets': [],
        }
    }
}

Interface field descriptions:

addr:List of IPy.IP objects of interface addresses
acl_in:List of inbound ACL names
acl_out:List of outbound ACL names
description:List of interface description(s)
subnets:List of IPy.IP objects of interface networks/CIDRs

Example:

>>> n = NetACLInfo(devices=['jm10-cc101-lab.lab.aol.net'])
>>> n.run()
Fetching jm10-cc101-lab.lab.aol.net
>>> n.config.keys()
[<NetDevice: jm10-cc101-lab.lab.aol.net>]
>>> dev = n.config.keys()[0]
>>> n.config[dev].keys()
['lo0.0', 'ge-0/0/0.0', 'ge-0/2/0.0', 'ge-0/1/0.0', 'fxp0.0']
>>> n.config[dev]['lo0.0'].keys()
['acl_in', 'subnets', 'addr', 'acl_out', 'description']
>>> lo0 = n.config[dev]['lo0.0']
>>> lo0['acl_in']; lo0['addr']
['abc123']
[IP('66.185.128.160')]
IPsubnet(addr)

Given ‘172.20.1.4/24’, return IP(‘172.20.1.0/24’).

from_arista(data, device)

Parse IOS config based on EBNF grammar

from_brocade(data, device)

Parse IOS config based on EBNF grammar

from_cisco(data, device)

Parse IOS config based on EBNF grammar

from_foundry(data, device)

Parse IOS config based on EBNF grammar

from_juniper(data, device)

Do all the magic to parse Junos interfaces

ipv4_cidr_to_netmask(bits)

Convert CIDR bits to netmask

to_arista(dev, commands=None, extra=None)

Similar to IOS, but:

  • Arista has now “show conf” so we have to do “show run”
  • The regex used in the CLI for Arista is more “precise” so we have to change the pattern a little bit compared to the on in generate_ios_cmd
to_brocade(dev, commands=None, extra=None)

This is the “show me all interface information” command we pass to IOS devices

to_cisco(dev, commands=None, extra=None)

This is the “show me all interface information” command we pass to IOS devices

to_foundry(dev, commands=None, extra=None)

This is the “show me all interface information” command we pass to IOS devices

to_juniper(dev, commands=None, extra=None)

Generates an etree.Element object suitable for use with JunoScript

class trigger.cmds.ShowClock(devices=None, commands=None, incremental=None, max_conns=10, verbose=False, timeout=30, production_only=True, allow_fallback=True)

A simple example that runs show clock and parses it to datetime.datetime object.

from_brocade(results, device)

Parse Brocade time. Brocade switches and routers behave differently...

from_cisco(results, device)

Parse Cisco time

Previous topic

trigger.changemgmt — Change management library

Next topic

trigger.conf — Configuration & Settings module

This Page