Configuration and defaults

This document describes the configuration options available.

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 /tmp/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 encryptoin 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_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.

Default:

'/etc/trigger/.tackf'

DEFAULT_REALM

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

Default:

'aol'

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")]

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:

[]

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

SSH_TYPES

A list of manufacturers that support SSH logins. Only add one if ALL devices of that manufacturer have SSH logins enabled. (Don’t forget the trailing comma when you add a new entry.)

Default:

['ARISTA NETWORKS', 'CITRIX', 'JUNIPER', 'NETSCREEN TECHNOLOGIES']

VALID_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:

('ARISTA NETWORKS', 'CISCO SYSTEMS', 'DELL', 'JUNIPER', 'FOUNDRY', 'CITRIX', 'BROCADE')

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:

('ARISTA NETWORKS', 'BROCADE' 'CISCO SYSTEMS', 'DELL', 'FOUNDRY')

NetDevices settings

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_FORMAT

One of xml, json, sqlite. This MUST match the actual format of NETDEVICES_FILE or it won’t work for obvious reasons.

You may override this location by setting the NETDEVICES_FORMAT environment variable to the format of the file.

Default:

'xml'

NETDEVICES_FILE

Path to netdevices device metadata source file, which is used to populate NetDevices. This may be JSON, XML, or a SQLite3 database. You must set NETDEVICES_FORMAT to match the type of data.

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

Default:

'/etc/trigger/netdevices.xml'

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:

()

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 Redis or another task queue solution (such as Celery). For now, you’ll need to populate this with information for your MySQL database.

These are all self-explanatory, I hope.

DATABASE_NAME

The name of the database.

Default:

''

DATABASE_USER

The username to use to connect to the database.

Default:

''

DATABASE_PASSWORD

The password for the user account used to connect to the database.

Default:

''

DATABASE_HOST

The host on which your MySQL databse resides.

Default:

'127.0.0.1'

DATABASE_PORT

The destination port used by MySQL.

Default:

3306

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.

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

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

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