trigger.twister — Asynchronous device interaction library

Login and basic command-line interaction support using the Twisted asynchronous I/O framework. The Trigger Twister is just like the Mersenne Twister, except not at all.

class trigger.twister.IncrementalXMLTreeBuilder(callback, *args, **kwargs)

Version of XMLTreeBuilder that runs a callback on each tag.

We need this because JunoScript treats the entire session as one XML document. IETF NETCONF fixes that.

class trigger.twister.Interactor

Creates an interactive shell. Intended for use as an action with pty_connect(). See gong for an example.

connectionMade()

Fire up stdin/stdout once we connect.

dataReceived(data)

And write data to the terminal.

class trigger.twister.IoslikeSendExpect(dev, commands, incremental=None, with_errors=False, timeout=None, command_interval=0)

Action for use with TriggerTelnet. Take a list of commands, and send them to the device until we run out or one errors. Wait for a prompt after each.

connectionMade()

Do this when we connect.

dataReceived(bytes)

Do this when we get data.

timeoutConnection()

Do this when we timeout.

class trigger.twister.TriggerClientFactory(deferred, creds=None, init_commands=None)

Factory for all clients. Subclass me.

clientConnectionFailed(connector, reason)

Do this when the connection fails.

clientConnectionLost(connector, reason)

Do this when the connection is lost.

class trigger.twister.TriggerSSHChannelBase(localWindow=0, localMaxPacket=0, remoteWindow=0, remoteMaxPacket=0, conn=None, data=None, avatar=None)

Base class for SSH Channels. setup_channelOpen() should be called by channelOpen() in the child class.

loseConnection()

Terminate the connection. Link this to the transport method of the same name.

setup_channelOpen(data)

Call me in your subclass in self.channelOpen():

def channelOpen(self, data):
self.setup_channelOpen(data) self.conn.sendRequest(self, ‘shell’, ‘’) # etc.
timeoutConnection()

Do this when the connection times out.

class trigger.twister.TriggerSSHChannelFactory(deferred, commands, creds=None, incremental=None, with_errors=False, timeout=None, channel=None, command_interval=0)

Intended to be used as a parent of automated SSH channels (e.g. Junoscript, NetScreen, NetScaler) to eliminate boiler plate in those subclasses.

class trigger.twister.TriggerSSHConnection

Used to manage, you know, an SSH connection.

channelClosed(channel)

Close the channel when we’re done.

serviceStarted()

Open the channel once we start.

class trigger.twister.TriggerSSHJunoscriptChannel(localWindow=0, localMaxPacket=0, remoteWindow=0, remoteMaxPacket=0, conn=None, data=None, avatar=None)

Run Junoscript commands on a Juniper router. This completely assumes that we are the only channel in the factory (a TriggerJunoscriptFactory) and walks all the way back up to the factory for its arguments.

channelOpen(data)

Do this when channel opens.

dataReceived(data)

Do this when we receive data.

class trigger.twister.TriggerSSHNetscalerChannel(localWindow=0, localMaxPacket=0, remoteWindow=0, remoteMaxPacket=0, conn=None, data=None, avatar=None)

Same as TriggerSSHJunoscriptChannel but for NetScreen. Mostly copy-pasted, and probably needs refactoring but it works.

channelOpen(data)

Do this when channel opens.

dataReceived(bytes)

Do this when we receive data.

class trigger.twister.TriggerSSHNetscreenChannel(localWindow=0, localMaxPacket=0, remoteWindow=0, remoteMaxPacket=0, conn=None, data=None, avatar=None)

An SSH Channel to interact with NetScreens (running ScreenOS).

channelOpen(data)

Do this when the channel opens.

dataReceived(bytes)

Do this when we receive data.

class trigger.twister.TriggerSSHPtyChannel(localWindow=0, localMaxPacket=0, remoteWindow=0, remoteMaxPacket=0, conn=None, data=None, avatar=None)

Used by pty_connect() to turn up an SSH pty channel.

channelOpen(data)

Setup the terminal when the channel opens.

class trigger.twister.TriggerSSHPtyClientFactory(deferred, action, creds=None, display_banner=None, init_commands=None)

Factory for an interactive SSH connection. ‘action’ is a Protocol that will be connected to the session after login. Use it to interact with the user and pass along commands.

class trigger.twister.TriggerSSHTransport

Call with magic factory attributes ‘creds’, a tuple of login credentials, and ‘channel’, the class of channel to open.

connectionSecure()

Once we’re secure, authenticate.

receiveError(reason, desc)

Do this when we receive an error.

sendDisconnect(reason, desc)

Trigger disconnect of the transport.

verifyHostKey(pubKey, fingerprint)

Verify host key, but don’t actually verify. Awesome.

class trigger.twister.TriggerSSHUserAuth(user, instance)

Perform user authentication over SSH.

getGenericAnswers(name, information, prompts)

Send along the password when authentication mechanism is not ‘password’. This is most commonly the case with ‘keyboard-interactive’, which even when configured within self.preferredOrder, does not work using default getPassword() method.

getPassword(prompt=None)

Send along the password.

ssh_USERAUTH_BANNER(packet)

Display SSH banner.

ssh_USERAUTH_FAILURE(packet)

An almost exact duplicate of SSHUserAuthClient.ssh_USERAUTH_FAILURE modified to forcefully disconnect. If we receive authentication failures, instead of looping until the server boots us and performing a sendDisconnect(), we raise a LoginFailure and call loseConnection().

See the base docstring for the method signature.

class trigger.twister.TriggerTelnet(timeout=60)

Telnet-based session. Primarily used by IOS-like type devices.

enableRemote(option)

Allow telnet clients to enable options if for some reason they aren’t enabled already (e.g. ECHO). (Ref: http://bit.ly/wkFZFg) For some reason Arista Networks hardware is the only vendor that needs this method right now.

login_state_machine(bytes)

Track user login state.

state_enable()

Special Foundry breakage because they don’t do auto-enable from TACACS by default. Use ‘aaa authentication login privilege-mode’. Also, why no space after the Password: prompt here?

state_enable_pw()

Pass the enable password from the factory or NetDevices

state_logged_in()

Once we’re logged in, exit state machine and pass control to the action.

state_login_pw()

Pass the login password from the factory or NetDevices

state_password()

After we got password prompt, check for enabled prompt.

state_percent_error()

Found a % error message. Don’t return immediately because we don’t have the error text yet.

state_raise_error()

Do this when we get a login failure.

state_username()

After we’ve gotten username, check for password prompt.

timeoutConnection()

Do this when we timeout logging in.

class trigger.twister.TriggerTelnetClientFactory(deferred, action, creds=None, loginpw=None, enablepw=None, init_commands=None)

Factory for a telnet connection.

trigger.twister.execute_ioslike(device, commands, creds=None, incremental=None, with_errors=False, timeout=300, loginpw=None, enablepw=None, command_interval=0)

Connect to a Cisco/IOS-like device over telnet. See execute_junoscript().

trigger.twister.execute_junoscript(device, commands, creds=None, incremental=None, with_errors=False, timeout=300)

Connect to a Juniper and enable XML mode. Sequentially execute all the XML commands in the iterable ‘commands’ (ElementTree.Element objects suitable for wrapping in <rpc>). Returns a deferred, whose callback will get a sequence of all the XML results after the connection is finished.

If any command returns xnm:error, the connection is dropped immediately and the errback will fire with the failed command; or, set ‘with_errors’ to get the exception objects in the list instead. Connection failures will still fire the errback.

Any None object in the command sequence will result in a None being placed in the output sequence, with no command issued to the router.

@incremental (optional) will be called with an empty sequence immediately on connecting, and each time a result comes back with the list of all results.

@commands is usually just a list. However, you can have also make it a generator, and have it and @incremental share a closure to some state variables. This allows you to determine what commands to execute dynamically based on the results of previous commands. This implementation is experimental and it might be a better idea to have the ‘incremental’ callback determine what command to execute next; it could then be a method of an object that keeps state.

BEWARE: Your generator cannot block; you must immediately decide what next command to execute, if any.

@timeout is the command timeout in seconds or None to disable. The default is in settings.DEFAULT_TIMEOUT; CommandTimeout errors will result if a command seems to take longer than that to run. LoginTimeout errors are always possible and cannot be disabled.

trigger.twister.execute_netscaler(device, commands, creds=None, incremental=None, with_errors=False, timeout=300, command_interval=0)

Connect to a NetScaler device. See execute_junoscript().

trigger.twister.execute_netscreen(device, commands, creds=None, incremental=None, with_errors=False, timeout=300)

Connect to a NetScreen device. See execute_junoscript().

trigger.twister.has_ioslike_error(s)

Test whether a string seems to contain an IOS-like error.

trigger.twister.has_junoscript_error(tag)

Test whether an Element contains a Junoscript xnm:error.

trigger.twister.has_netscaler_error(s)

Test whether a string seems to contain a NetScaler error.

trigger.twister.is_awaiting_confirmation(prompt)

Checks if a prompt is asking for us for confirmation and returns a Boolean.

Parameters:prompt – The prompt string to check
trigger.twister.pty_connect(device, action, creds=None, display_banner=None, ping_test=False, init_commands=None)

Connect to a device and log in. Use SSHv2 or telnet as appropriate.

Parameters:
  • device – A NetDevice object.
  • action – A Protocol object (not class) that will be activated when

the session is ready.

Parameters:creds – is a 2-tuple (username, password). By default, .tacacsrc AOL

credentials will be used. Override that here.

Parameters:display_banner – Will be called for SSH pre-authentication banners.

It will receive two args, ‘banner’ and ‘language’. By default, nothing will be done with the banner.

Parameters:ping_test – If set, the device is pinged and succeed in order to

proceed.

Parameters:init_commands – A list of commands to execute upon logging into

the device.

Previous topic

trigger.tacacsrc — Network credentials library

Next topic

trigger.utils — CLI tools and utilities library

This Page