Installation

This is a work in progress. Please bear with us as we expand and improve this documentation. If you have any feedback, please don’t hesitate to contact us!!

Dependencies

In order for Trigger’s core functionality to work, you will need the primary pieces of software:

  • the Python programming language (version 2.6 or higher);
  • the setuptools packaging/installation library;
  • the Redis key-value server (and companion Python interface);
  • the IPy IP address parsing library;
  • the PyASN1 library;
  • the Python cryptography library;
  • and the Twisted event-driven networking engine.

Trigger has a tricky set of dependencies. If you want to take full advantage of all of Trigger’s functionality, you’ll need them all. If you only want to use certain parts, you might not need them all. Each dependency will list the components that utilize it to help you make an informed decision.

Please read on for important details on each dependency – there are a few gotchas.

Python

Obviously Trigger requires Python. Only version 2.6 is supported, but Python 2.7 should be just fine. There is currently no official support for Python 3.x. We cannot yet say with confidence that we have worked out all of the legacy kinks from when Trigger was first developed against Python 2.3.

setuptools

Setuptools comes with some Python installations by default; if yours doesn’t, you’ll need to grab it. In such situations it’s typically packaged as python-setuptools, py26-setuptools or similar. Trigger will likely drop its setuptools dependency in the future, or include alternative support for the Distribute project, but for now setuptools is required for installation.

PyASN1

PyASN1 is a dependency of Twisted Conch which implements Abstract Syntax Notation One (ASN.1) and is used to encode/decode public & private OpenSSH keys.

cryptography

cryptography provides the low-level (C-based) encryption primitives.

Twisted

Twisted is huge and has a few dependencies of its. We told you this was tricky! To make things easier, please make sure you install the full-blown Twisted source tarball. You especially need Twisted Conch, which is used to run SSH.

Used by:

Redis

Trigger uses Redis as a datastore for ACL information including device associations and the integrated change queue. Please follow the instructions on the Redis site to get Redis running.

If you’re using Ubuntu, it’s as simple as:

sudo apt-get install redis-server

The Python redis client is required to interact with Redis.

Trigger currently assumes that you’re running Redis on localhost and on the default port (6379). If you would like to change this, update REDIS_HOST in settings.py to reflect the IP address or hostname of your Redis instance.

Note

You may globally disable the use of Redis for loading ACL associations by setting WITH_ACLS to False. Several libraries that interact with devices also have a with_acls argument to toggle this at runtime.

Used by:

IPy

IPy is a class and tools for handling of IPv4 and IPv6 addresses and networks. It is used by Trigger for parsing and handling IP addresses.

Used by:

pytz

pytz is an immensely powerful time zone library for Python that allows accurate and cross platform timezone calculations. It is used by Trigger’s change management interface to allow for strict adherance to scheduled maintenance events.

Used by:

SimpleParse

SimpleParse is an extremely fast parser generator for Python that converts EBNF grammars into parsers. It is used by Trigger’s ACL parser to allow us to translate ACLs from flat files into vendor-agnostic objects.

Used by:

Package tools

We strongly recommend using pip to install Trigger as it is newer and generally better than easy_install. In either case, these tools will automatically install of the dependencies for you quickly and easily.

Other Dependencies

Know for now that if you want to use the integrated load queue, you may potentially require an additional database library.

See Database Drivers below for more information.

Installing Trigger

The following steps will get you the very basic functionality and will be improved over time. As mentioned at the top of this document, if you have any feedback or questions, please get get in touch!

Install Trigger package

Using pip:

sudo pip install trigger

From source (which will use easy_install):

sudo python setup.py install

Create configuration directory

Trigger expects to find its configuration files to be in /etc/trigger. This can be customized using the PREFIX configuration variable within settings.py:

sudo mkdir /etc/trigger

That’s it! Now you’re ready to configure Trigger.

Basic Configuration

Warning

For these steps you’ll need to download the Trigger tarball, expand it, and then navigate to the root directory (the same directory in which you’ll find setup.py).

Copy settings.py

Trigger expects settings.py to be in /etc/trigger:

sudo cp configs/trigger_settings.py /etc/trigger/settings.py

If you really don’t like this, you may override the default location by setting the environment variable TRIGGER_SETTINGS to the desired location. If you go this route, you must make sure all Trigger-based tools have this set prior to any imports!

Copy metadata file

Trigger’s netdevices module expects to find the device metadata file in PREFIX. This file provides Trigger with information about your devices and is at the core of Trigger’s device interaction. Anything that communicates with devices relies on the metadata stored within this file.

For the purpose of basic config, we’ll just use the sample netdevices.json file:

sudo cp configs/netdevices.json /etc/trigger/netdevices.json

For more information on how Trigger uses the netdevices file please see Working with NetDevices.

Copy shared secret file

By default, Trigger’s tacacsrc module expects to find .tackf in the PREFIX. This is the location of the file that contains the passphrase used for the symettric encryption of user credentials within the .tacacsrc file. For starters, just use the sample file provided in the Trigger distribution:

sudo cp tests/data/tackf /etc/trigger/.tackf

If you’re using a non-standard location, be sure to update the TACACSRC_KEYFILE configuration variable within settings.py with the location of .tackf!

For more information on how Trigger uses encryption to protect credentials please see Managing Credentials with .tacacsrc.

Copy autoacl.py

Trigger’s autoacl module expects to find autoacl.py in the PREFIX. This is used to customize the automatic ACL associations for network devices.

sudo cp configs/autoacl.py /etc/trigger/autoacl.py

If you’re using a non-standard location, be sure to update the AUTOACL_FILE configuration variable within settings.py with the location of autoacl.py!

Copy bounce.py

Trigger’s bounce module expects to find bounce.py in the PREFIX. This module controls how change management (aka maintenance or “bounce”) windows get auto-applied to network devices.

sudo cp configs/bounce.py /etc/trigger/bounce.py

If you’re using a non-standard location, be sure to update the BOUNCE_FILE configuration variable within settings.py with the location of bounce.py!

Verifying Functionality

Warning

For these steps you’ll still need to be at the root directory of the Trigger tarball. If you haven’t already, download it, expand it, and then navigate to the root directory (the same directory in which you’ll find setup.py).

Once the dependencies are installed, fire up your trusty Python interpreter in interactive mode and try doing stuff.

Important

Throughout this documentation you will see commands or code preceded by a triple greater-than prompt (>>>). This indicates that they are being entered into a Python interpreter in interactive mode.

To start Python in interactive mode, it’s as simple as executing python from a command prompt:

% python
Python 2.7.2 (default, Jun 20 2012, 16:23:33)
Type "help", "copyright", "credits" or "license" for more information.
>>>

For more information, please see the official Python documentation on interactive mode.

NetDevices

Try instantiating NetDevices, which holds your device metadata:

>>> from trigger.netdevices import NetDevices
>>> nd = NetDevices()
>>> dev = nd.find('test1-abc.net.aol.com')

ACL Parser

Try parsing an ACL using the ACL parser (the tests directory can be found within the Trigger distribution):

>>> from trigger.acl import parse
>>> acl = parse(open("tests/data/acl.test"))
>>> len(acl.terms)
103

ACL Database

Warning

This WILL NOT work without Redis installed and WITH_ACLS set to True. If you have ACL support disabled, just skip this section.

Try loading the AclsDB to inspect automatic associations. First directly from autoacl:

>>> from trigger.acl.autoacl import autoacl
>>> autoacl(dev)
set(['juniper-router.policer', 'juniper-router-protect'])

And then inherited from autoacl by AclsDB:

>>> from trigger.acl.db import AclsDB
>>> a = AclsDB()
>>> a.get_acl_set(dev)
>>> dev.implicit_acls
set(['juniper-router.policer', 'juniper-router-protect'])

Now that you’ve properly installed Trigger, you might want to know how to use it. Please have a look at the Usage Guide.

Integrated Load Queue

Trigger currently uses a database for the automated ACL load queue used by the load_acl and acl utilities.

The supported databases are MySQL, PostgreSQL, and SQLite.

SQLite is the easiest to get running because generally this module is part of the Python standard library, and the database can be a simple file on your system.

It’s probably best to create a unique database and database user for this purpose, but we’ll leave that up to you.

If you want to use this functionality, you will need to do the following:

  • Choose your database solution
  • Create a database on it to be used by the load queue
  • If you’re not using SQLite, ensure you have the database driver installed
  • Specify your database settings in settings.py
  • Run the init_task_db tool
  • Profit!

Database Drivers

Note

If you are using sqlite3 you may ignore this section as the driver is included in the Python standard library.

Some of the database libraries are Python C extensions and so will expect gcc and a number of development libraries to be available on your system.

Generally you will need the development headers for Python and OpenSSL as well as the development libraries for the database you’re using.

PostgreSQL

Your only choice is psycopg2. This is a Python C extension which requires compilation.

Here are some tips to install the library dependencies:

Ubuntu
sudo apt-get install libpq-dev libssl-dev python-dev
CentOS/RedHat
sudo yum install postgresql-devel openssl-devel python-devel

MySQL

For MySQL you have two choices:

  1. PyMySQL, a pure Python MySQL driver.
  2. MySQL-python. This is a Python C extension which requires compilation.

If you’re using MySQL-python, here are some tips to install the library dependencies:

Ubuntu
sudo apt-get install libmysqlclient-dev libssl-dev python-dev
CentOS/RedHat
sudo yum install mysql-devel openssl-devel python-devel