Configuration

This document describes the configuration options available for Trigger.

If you’re using the default loader, you must create or copy the provided trigger_settings.py module and make sure it is in /etc/trigger/settings.py on the local system.

A Word about Defaults

There are two Trigger components that rely on Python modules to be provided on disk in /etc/trigger and these are:

If your custom configuration either cannot be found or fails to import, Trigger will fallback to the defaults.

settings.py

Using a custom settings.py

You may override the default location using the TRIGGER_SETTINGS environment variable.

For example, set this variable and fire up the Python interpreter:

% export TRIGGER_SETTINGS=/home/jathan/sandbox/trigger/conf/trigger_settings.py
% python
Type "help", "copyright", "credits" or "license" for more information.
>>> import os
>>> os.environ.get('TRIGGER_SETTINGS')
'/home/j/jathan/sandbox/netops/trigger/conf/trigger_settings.py'
>>> from trigger.conf import settings

Observe that it doesn’t complain. You have loaded settings.py from a custom location!

Using global defaults

If you don’t want to specify your own settings.py, it will warn you and fallback to the defaults:

>>> from trigger.conf import settings
trigger/conf/__init__.py:114: RuntimeWarning: Module could not be imported from /etc/trigger/settings.py. Using default global settings.
  warnings.warn(str(err) + ' Using default global settings.', RuntimeWarning)

autoacl()

The trigger.netdevices and trigger.acl modules require autoacl().

Trigger wants to import the autoacl() function from either a module you specify or, failing that, the default location.

Using a custom autoacl()

You may override the default location of the module containing the autoacl() function using the AUTOACL_FILE environment variable just like how you specified a custom location for settings.py.

Using default autoacl()

Just as with settings.py, the same goes for autoacl():

>>> from trigger.acl.autoacl import autoacl
trigger/acl/autoacl.py:44: RuntimeWarning: Function autoacl() could not be found in /etc/trigger/autoacl.py, using default!
  warnings.warn(msg, RuntimeWarning)

Keep in mind this autoacl() has the expected signature but does nothing with the arguments and only returns an empty set:

>>> autoacl('foo')
set([])

Configuration Directives

Global settings

PREFIX

This is where Trigger should look for its essential files including autoacl.py and netdevices.xml.

Default:

'/etc/trigger'

USE_GPG_AUTH

Toggles whether or not we should use GPG authentication for storing TACACS credentials in the user’s .tacacsrc file. Set to False to use the old .tackf encryption method, which sucks but requires almost no overhead. Should be False unless instructions/integration is ready for GPG. At this time the documentation for the GPG support is incomplete.

Default:

False

TACACSRC

Sets the location of the .tacacsrc file.

You may override this by setting the TACACSRC environment variable to the path of the file.

Default:

'$HOME/.tacacsrc'

TACACSRC_KEYFILE

Only used if GPG auth is disabled. This is the location of the file that contains the passphrase used for the two-way hashing of the user credentials within the .tacacsrc file.

You may override this by setting the TACACSRC_KEYFILE environment variable to path of the file.

Default:

'/etc/trigger/.tackf'

DEFAULT_REALM

Default login realm to store user credentials (username, password) for general use within the .tacacsrc file.

Default:

'aol'

TEXTFSM_TEMPLATE_DIR

Default path to TextFSM template directory. It is recommended to pull the Network to Code templates from here Network to Code templates and place them inside the vendor directory inside the trigger root.

Default:

'/etc/trigger/vendor/ntc_templates'

FIREWALL_DIR

Location of firewall policy files.

Default:

'/data/firewalls'

TFTPROOT_DIR

Location of the tftproot directory.

Default:

'/data/tftproot'

INTERNAL_NETWORKS

A list of IPy.IP objects describing your internally owned networks. All network blocsk owned/operated and considered a part of your network should be included. The defaults are private IPv4 networks defined by RFC 1918.

Default:

[IPy.IP("10.0.0.0/8"), IPy.IP("172.16.0.0/12"), IPy.IP("192.168.0.0/16")]

VENDOR_MAP

New in version 1.2.

A mapping of manufacturer attribute values to canonical vendor name used by Trigger. These single-word, lowercased canonical names are used throughout Trigger.

If your internal definition differs from the UPPERCASED ones specified below (which they probably do, customize them here.

Default:

{
    'A10 NETWORKS': 'a10',
    'ARISTA NETWORKS': 'arista',
    'BROCADE': 'brocade',
    'CISCO SYSTEMS': 'cisco',
    'CITRIX': 'citrix',
    'DELL': 'dell',
    'FOUNDRY': 'foundry',
    'JUNIPER': 'juniper',
    'NETSCREEN TECHNOLOGIES': 'netscreen',
}

SUPPORTED_PLATFORMS

New in version 1.2.

A dictionary keyed by manufacturer name containing a list of the device types for each that is officially supported by Trigger. Do not modify this unless you know what you’re doing!

Default:

{
    'a10': ['SWITCH'],
    'arista': ['SWITCH'],
    'brocade': ['ROUTER', 'SWITCH'],
    'cisco': ['ROUTER', 'SWITCH', 'FIREWALL'],
    'citrix': ['SWITCH'],
    'dell': ['SWITCH'],
    'foundry': ['ROUTER', 'SWITCH'],
    'juniper': ['FIREWALL', 'ROUTER', 'SWITCH'],
    'netscreen': ['FIREWALL']
}

SUPPORTED_VENDORS

A tuple of strings containing the names of valid manufacturer names. These are currently defaulted to what Trigger supports internally. Do not modify this unless you know what you’re doing!

Default:

(
    'a10',
    'arista',
    'aruba',
    'avocent',
    'brocade',
    'cisco',
    'citrix',
    'dell',
    'f5',
    'force10',
    'foundry',
    'juniper',
    'mrv',
    'netscreen',
    'paloalto',
    'pica8',
)

SUPPORTED_TYPES

A tuple of device types officially supported by Trigger. Do not modify this unless you know what you’re doing!

Default:

('CONSOLE', 'DWDM', 'FIREWALL', 'LOAD_BALANCER', 'ROUTER', 'SWITCH')

DEFAULT_TYPES

New in version 1.2.

A mapping of of vendor names to the default device type for each in the event that a device object is created and the deviceType attribute isn’t set for some reason.

Default:

{
    'a10': 'SWITCH',
    'arista': 'SWITCH',
    'brocade': 'SWITCH',
    'citrix': 'SWITCH',
    'cisco': 'ROUTER',
    'dell': 'SWITCH',
    'foundry': 'SWITCH',
    'juniper': 'ROUTER',
    'netscreen': 'FIREWALL',
}

FALLBACK_TYPE

New in version 1.2.

When a vendor is not explicitly defined within DEFAULT_TYPES, fallback to this type.

Default:

'ROUTER'

FALLBACK_MANUFACTURER

New in version 1.5.3.

When a manufacturer/vendor is not explicitly defined for a NetDevice object, fallback to to this value.

Default:

'UNKNOWN'

Twister settings

These settings are used to customize the timeouts and methods used by Trigger to connect to network devices.

DEFAULT_TIMEOUT

Default timeout in seconds for commands executed during a session. If a response is not received within this window, the connection is terminated.

Default:

300

TELNET_TIMEOUT

Default timeout in seconds for initial telnet connections.

Default:

60

TELNET_ENABLED

New in version 1.2.

Whether or not to allow telnet fallback. Set to False to disable support for telnet.

Default:

True

SSH_PORT

New in version 1.4.4.

Destination TCP port to use for SSH client connections.

Default:

22

SSH_AUTHENTICATION_ORDER

New in version 1.5.1.

The preferred order in which SSH authentication methods are tried. Customize this if you wish to change the order of, or modify the supported methods.

Default:

['password', 'keyboard-interactive', 'publickey']

TELNET_PORT

New in version 1.4.4.

Destination TCP port to use for Telnet client connections.

Default:

23

TRIGGER_ENABLEPW

New in version 1.4.3.

When connecting to devices that require the entry of an enable password (such as when a “>” prompt is detected), Trigger may automatically execute the “enable” command and pass the enable password along for you.

You may provide the enable password by setting the TRIGGER_ENABLEPW environment variable.

Default:

None

SSH_PTY_DISABLED

New in version 1.2.

A mapping of vendors to the types of devices for that vendor for which you would like to disable interactive (pty) SSH sessions, such as when using bin/gong.

Default:

{
    'dell': ['SWITCH'],
}

SSH_ASYNC_DISABLED

New in version 1.2.

A mapping of vendors to the types of devices for that vendor for which you would like to disable asynchronous (NON-interactive) SSH sessions, such as when using execute or Commando to remotely control a device.

Default:

{
    'arista': ['SWITCH'],
    'brocade': ['SWITCH'],
    'dell': ['SWITCH'],
}

IOSLIKE_VENDORS

A tuple of strings containing the names of vendors that basically just emulate Cisco’s IOS and can be treated accordingly for the sake of interaction.

Default:

('a10', 'arista', 'brocade', 'cisco', 'dell', 'foundry')

CONTINUE_PROMPTS

A list of strings representing continue prompts sent by devices that indicate the device is awaiting user confirmation when interacting with the device. If a continue prompt is detected, Trigger will temporarily set this value to the prompt and send along the next command (for example if you’re expecting such a prompt and you want to send along “yes”).

When checking these prompts, the incoming output data from the device will be tested whether it ends with one of these prompts. These should be as specific as possible, including trailing spaces.

The default values are common continue prompts encountered throughout the lifetime of the Trigger project’s development, and is by no means comprehensive. If you need to customize these prompts for your environment, utilize this setting.

Default:

[
    'continue?',
    'proceed?',
    '(y/n):',
    '[y/n]:',
    '[confirm]',
    '[yes/no]: ',
    'overwrite file [startup-config] ?[yes/press any key for no]....'
]

GORC_FILE

The file path where a user’s .gorc is expected to be found.

Default:

'~/.gorc'

GORC_ALLOWED_COMMANDS

The only root commands that are allowed to be executed when defined within a users’s ~/.gorc file. Any root commands not specified here will be filtered out by filter_commands().

Default:

'~/.gorc'

NetDevices settings

WITH_ACLS

Globally toggle whether to load ACL associations from the Redis database. If you don’t have Redis or aren’t using Trigger to manage ACLs set this to False.

Note

If you are doing work that does not require ACL information setting this to False can speed things up. Several libraries that interact with devices also have a with_acls argument to toggle this at runtime.

Default:

False

DEFAULT_ADMIN_STATUS

New in version 1.6.

When the administrative status is not defined using the adminStatus field on a NetDevice object, the default administrative status will be used.

By default Trigger only operates on devices set to PRODUCTION. This is covered in more detail under Instantiating NetDevices.

Default:

'PRODUCTION'

AUTOACL_FILE

Path to the explicit module file for autoacl.py so that we can still perform from trigger.acl.autoacl import autoacl without modifying sys.path.

Default:

'/etc/trigger/autoacl.py'

NETDEVICES_LOADERS

New in version 1.3.

A tuple of data loader classes, specified as strings. Optionally, a tuple can be used instead of a string. The first item in the tuple should be the Loader’s module, subsequent items are passed to the Loader during initialization.

Loaders should inherit from BaseLoader. For now, please see the source code for the pre-defined loader objects at trigger/netdevices/loaders/filesystem.py for examples.

Default:

(
    'trigger.netdevices.loaders.filesystem.XMLLoader',
    'trigger.netdevices.loaders.filesystem.JSONLoader',
    'trigger.netdevices.loaders.filesystem.SQLiteLoader',
    'trigger.netdevices.loaders.filesystem.CSVLoader',
    'trigger.netdevices.loaders.filesystem.RancidLoader',
)

NETDEVICES_SOURCE

New in version 1.3.

A path or URL to netdevices device metadata source data, which is used to populate NetDevices with NetDevice objects. For more information on this, see NETDEVICES_LOADERS.

This value may be as simple as an absolute path to a file on your local system, or it may be a fully-fledge URL such as http://user:pass@myhost.com:8080/stuff?foo=bar#fragment-data. This URL data is parsed and passed onto a BaseLoader subclass for retrieving device metadata.

You may override this location by setting the NETDEVICES_SOURCE environment variable to the path of the file.

Default:

'/etc/trigger/netdevices.xml'

RANCID_RECURSE_SUBDIRS

New in version 1.2.

When using RANCID as a data source, toggle whether to treat the RANCID root as a normal instance, or as the root to multiple instances.

You may override this location by setting the RANCID_RECURSE_SUBDIRS environment variable to any True value.

Default:

False

VALID_OWNERS

A tuple of strings containing the names of valid owning teams for NetDevice objects. This is intended to be a master list of the valid owners to have a central configuration entry to easily reference. Please see the sample settings file for an example to use in your environment.

Default:

()

JUNIPER_FULL_COMMIT_FIELDS

Fields and values defined here will dictate which Juniper devices receive a commit-configuration full when populating commit_commands. The fields and values must match the objects exactly or it will fallback to commit-configuration.

Example:

# Perform "commit full" on all Juniper EX4200 switches.
JUNIPER_FULL_COMMIT_FIELDS = {
    'deviceType': 'SWITCH',
    'make': 'EX4200',
}

Default

{}

Bounce Window settings

BOUNCE_FILE

New in version 1.3.

The path of the explicit module file containing custom bounce window mappings. This file is expected to define a bounce() function that takes a NetDevice object as an argument and returns a BounceWindow object.

You may override the default location of the module containing the bounce() function by setting the BOUNCE_FILE environment variable to the path of the file.

Default:

'/etc/trigger/bounce.py'

BOUNCE_DEFAULT_TZ

New in version 1.3.

The name of the default timezone for bounce windows. Olson zoneinfo names are used for this in the format of Area/Location. All BounceWindow objects are configured using “US/Eastern”.

Default:

'US/Eastern'

BOUNCE_DEFAULT_COLOR

New in version 1.3.

The default fallback window color for bounce windows. Must be one of ‘green’, ‘yellow’, or ‘red’.

green:Low Risk. Minor impact on user or customer environments. Backing-out the change, if required, is easily accomplished. User notification is often unnecessary.
yellow:Medium Risk. Potential exists for substantially impacting user or customer environments. Backing-out the change, if required, can be accomplished in a reasonable timeframe.
red:High Risk. The highest potential impact on users or cutomers. Any non-standard add, move or change falls into this category. Backing-out of a high-risk change may be time-consuming or difficult.

Default:

'red'

Redis settings

REDIS_HOST

Redis master server. This will be used unless it is unreachable.

Default:

'127.0.0.1'

REDIS_PORT

The Redis port.

Default:

6379

REDIS_DB

The Redis DB to use.

Default:

0

Database settings

These will eventually be replaced with another task queue solution (such as Celery). For now, you’ll need to populate this with information for your database.

These are all self-explanatory, I hope. For more information on database drivers that you may need, please see Database Drivers.

DATABASE_ENGINE

The database driver you intend to use for the task queue. This can be one of postgresql, mysql, sqlite3. For the purpose of backwards compatibility this defaults to mysql.

Default:

'mysql'

DATABASE_NAME

The name of the database. If using sqlite3, this is the path to the database file.

Default:

''

DATABASE_USER

The username to use to connect to the database. (Not used with sqlite3)

Default:

''

DATABASE_PASSWORD

The password for the user account used to connect to the database. (Not used with sqlite)

Default:

''

DATABASE_HOST

The host on which your database resides. Set to empty string for localhost. (Not used with sqlite3)

Default:

''

DATABASE_PORT

The destination port used by the task queue. Set to empty string for default. (Not used with sqlite3)

Default:

''

Access-list Management settings

These are various settings that control what files may be modified, by various tools and libraries within the Trigger suite. These settings are specific to the functionality found within the trigger.acl module.

IGNORED_ACLS

This is a list of FILTER names of ACLs that should be skipped or ignored by tools. These should be the names of the filters as they appear on devices. We want this to be mutable so it can be modified at runtime.

Default:

[]

NONMOD_ACLS

This is a list of FILE names of ACLs that shall not be modified by tools. These should be the names of the files as they exist in FIREWALL_DIR. Trigger expects ACLs to be prefixed with 'acl.'.

Default:

[]

VIPS

This is a dictionary mapping of real IP to external NAT IP address for used by your connecting host(s) (aka jump host). This is used primarily by load_acl in the event that a connection from a real IP fails (such as via tftp) or when explicitly passing the --no-vip flag.

Format: {local_ip: external_ip}

Default:

{}

Access-list loading & rate-limiting settings

All of the following esttings are currently only used by load_acl. If and when the load_acl functionality gets moved into the library API, this may change.

ALLOW_JUNIPER_MULTILINE_COMMENTS

Whether to allow multi-line comments to be used in Juniper firewall filters. The default behavior is to result in a syntax error when a multi-line comment is detected when parsing a firewall filter using the acl library.

Default:

False

AUTOLOAD_FILTER

A list of FILTER names (not filenames) that will be skipped during automated loads (load_acl --auto). This setting was renamed from AUTOLOAD_BLACKLIST; usage of that name is being phased out.

Default:

[]

AUTOLOAD_FILTER_THRESH

A dictionary mapping for FILTER names (not filenames) and a numeric threshold. Modify this if you want to create a list that if over the specified number of devices will be treated as bulk loads.

For now, we provided examples so that this has more context/meaning. The current implementation is kind of broken and doesn’t scale for data centers with a large of number of devices.

Default:

{}

AUTOLOAD_BULK_THRESH

Any ACL applied on a number of devices >= this number will be treated as bulk loads. For example, if this is set to 5, any ACL applied to 5 or more devices will be considered a bulk ACL load.

Default:

10

BULK_MAX_HITS

This is a dictionary mapping of filter names to the number of bulk hits. Use this to override BULK_MAX_HITS_DEFAULT. Please note that this number is used PER EXECUTION of load_acl --auto. For example if you ran it once per hour, and your bounce window were 3 hours, this number should be the total number of expected devices per ACL within that allotted bounce window. Yes this is confusing and needs to be redesigned.)

Examples:

  • 1 per load_acl execution; ~3 per day, per 3-hour bounce window
  • 2 per load_acl execution; ~6 per day, per 3-hour bounce window

Format: {'filter_name': max_hits}

Default:

{}

BULK_MAX_HITS_DEFAULT

If an ACL is bulk but not defined in BULK_MAX_HITS, use this number as max_hits. For example using the default value of 1, that means load on one device per ACL, per data center or site location, per load_acl --auto execution.

Default:

1

GET_TFTP_SOURCE

A callable that you may define within settings.py, that given a NetDevice object as an argument, will determine the right TFTP source-address to utilize.

This is specifically used within the bin/load_acl tool when connecting to IOS-like (Cisco clone) devices to push ACL changes by telling the device from where to pull the change over TFTP.

The callable you define must take 2 arguments: dev (a NetDevice object), and no_vip (a Boolean), and must return a hostname or IP address that for example:

def _my_tftp_getter(dev=None, no_vip=True):
    return '1.2.3.4'

Note

For the default implementation, please see the source code in global_settings. This version’s behavior is modified by VIPS to help decied whether to utilize a public or private IP, and return that address.

Default:

trigger.conf.global_settings._get_tftp_source()

STAGE_ACLS

A callable that you may define within settings.py that given a list of ACL filenames will stage the files in the appropriate location for them to be retrieved, for example, via TFTP from a remote device. This could do anything you require as a staging step prior to executing ACL changes such as uploading files to another system.

This is specifically used within the bin/load_acl tool when preparing ACLs to be loaded onto devices.

The callable you define must take 3 arguments: acls (a list of filenames), log (a Twisted Python logging object), and sanitize_acls (a Boolean). It must return a 3-tuple of (acl_contents, file_paths, failures), where: acl_contents is a list of strings where each string is the entire contents of an ACL file, file_paths is a list of file paths used to locate the files (such as for use with TFTP, and fails an error string indicating an failure or None indicating success. For example:

def _my_stage_acls(acls, log=None, sanitize_acls=False):
    acl_contents = []
    file_paths = []
    fails = None
    for acl in acls:
        if sanitize_acls:
            # Do stuff to the acl
        file_contents = open(acl).read()
        if not file_contents:
            fails = "%s could not be read"
            log.msg(fails)
            return ([], [], fails)
        acl_contents.append(file_contents)

    log.msg('All ACLs ready for staging')
    return (acl_contents, file_paths, fails)

Note

For the default implementation, please see the source code in global_settings. This expects to find ACL files within FIREWALL_DIR and to stage them into TFTPROOT_DIR, which assumes that the TFTP server is running on the local system.

Default:

trigger.conf.global_settings._stage_acls()

On-Call Engineer Display settings

GET_CURRENT_ONCALL

This variable should reference a function that returns data for your on-call engineer, or failing that None. The function should return a dictionary that looks like this:

{
    'username': 'mrengineer',
    'name': 'Joe Engineer',
    'email': 'joe.engineer@example.notreal'
}

Default:

lambda x=None: x

CM Ticket Creation settings

CREATE_CM_TICKET

This variable should reference a function that creates a CM ticket and returns the ticket number, or None. It defaults to _create_cm_ticket_stub, which can be found within the settings.py source code and is a simple function that takes any arguments and returns None.

Default:

_create_cm_ticket_stub

Notification settings

EMAIL_SENDER

New in version 1.2.2.

The default email sender for email notifications. It’s probably a good idea to make this a no-reply address.

Default:

'nobody@not.real'

SUCCESS_EMAILS

A list of email addresses to email when things go well (such as from load_acl --auto).

Default:

[]

FAILURE_EMAILS

A list of email addresses to email when things go not well.

Default:

[]

NOTIFICATION_SENDER

New in version 1.2.2.

The default sender for integrated notifications. This defaults to the fully-qualified domain name (FQDN) for the local host.

Default:

socket.gethostname()

SUCCESS_RECIPIENTS

New in version 1.2.2.

Destinations (hostnames, addresses) to notify when things go well.

Default:

[]

FAILURE_RECIPIENTS

New in version 1.2.2.

Destinations (hostnames, addresses) to notify when things go not well.

Default:

[]

NOTIFICATION_HANDLERS

New in version 1.2.2.

This is a list of fully-qualified import paths for event handler functions. Each path should end with a callable that handles a notification event and returns True in the event of a successful notification, or None.

To activate a handler, add it to this list. Each handler is represented by a string: the full Python path to the handler’s function name.

Handlers are processed in order. Once an event is succesfully handled, all processing stops so that each event is only handled once.

Until this documentation improves, for a good example of how to create a custom handler, review the source code for email_handler().

Default:

[
    'trigger.utils.notifications.handlers.email_handler',
]