PK X’'BGøÒò ò trigger-1.2.2/genindex.html
|
|
|
|
|
The Trigger developement team is currently a one-man operation led by Jathan McCollum, aka jathanism.
There are several ways to get involved with Trigger:
All contributors will receive proper attribution for their work. We want to give credit where it is due!
If an issue ticket exists for a given issue, please keep all communication in that ticket’s comments. Otherwise, please use whatever avenue of communication works best for you!
Trigger tries very diligently to honor PEP-8, especially (but not limited to!) the following:
While Trigger’s development methodology isn’t set in stone yet, the following items detail how we currently organize the Git repository and expect to perform merges and so forth. This will be chiefly of interest to those who wish to follow a specific Git branch instead of released versions, or to any contributors.
We use semantic versioning. Version numbers should follow this format:
{Major version}.{Minor version}.{Revision number}.{Build number (optional)}
Major releases update the first number, e.g. going from 0.9 to 1.0, and indicate that the software has reached some very large milestone.
For example, the 1.0 release signified a commitment to a medium to long term API and some significant backwards incompatible (compared to the 0.9 series) features. Version 2.0 might indicate a rewrite using a new underlying network technology or an overhaul to be more object-oriented.
Major releases will often be backwards-incompatible with the previous line of development, though this is not a requirement, just a usual happenstance. Users should expect to have to make at least some changes to their settings.py when switching between major versions.
Minor releases, such as moving from 1.0 to 1.1, typically mean that one or more new, large features has been added. They are also sometimes used to mark off the fact that a lot of bug fixes or small feature modifications have occurred since the previous minor release. (And, naturally, some of them will involve both at the same time.)
These releases are guaranteed to be backwards-compatible with all other releases containing the same major version number, so a settings.py that works with 1.0 should also work fine with 1.1 or even 1.9.
The third and final part of version numbers, such as the ‘3’ in 1.0.3, generally indicate a release containing one or more bugfixes, although minor feature modifications may (rarely) occur.
This third number is sometimes omitted for the first major or minor release in a series, e.g. 1.2 or 2.0, and in these cases it can be considered an implicit zero (e.g. 2.0.0).
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!!
In order for Trigger’s core functionality to work, you will need the primary pieces of software:
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.
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 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 is a dependency of Twisted Conch which implements Abstract Syntax Notation One (ASN.1) and is used to encode/decode public & private OpenSSH keys.
PyCrypto is a dependency of Twisted Conch which provides the low-level (C-based) encryption algorithms used to run SSH. There are a couple gotchas associated with installing PyCrypto: its compatibility with Python’s package tools, and the fact that it is a C-based extension.
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:
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.
Used by:
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 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 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:
This documentation is incomplete and is being improved.
Know for now that if you want to use the integrated load queue, you must have the Python MySQL bindings.
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!
Using pip:
sudo pip install trigger
From source (which will use easy_install):
sudo python setup.py install
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.
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).
Trigger expects settings.py to be in /etc/trigger:
sudo cp conf/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!
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 conf/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!
Trigger’s netdevices module expects to find the device metadata file in PREFIX. This is used to customize the automatic ACL associations for network devices.
For the purpose of basic config, we’ll just use the sample netdevices.xml file:
sudo cp conf/netdevices.xml /etc/trigger/netdevices.xml
Once the dependencies are installed, try doing stuff.
Try instantiating NetDevices, which holds your device metadata:
>>> from trigger.netdevices import NetDevices
>>> nd = NetDevices()
>>> dev = nd.find('test1-abc.net.aol.com')
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
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 documentation!
Trigger currently (but hopefully not for too much longer) uses MySQL for the automated ACL load queue used by the load_acl and acl utilities. If you want to use these tools, you need to create a MySQL database and make sure you also have the MySQLdb module installed.
Find conf/acl_queue_schema.sql in the source distribution and import the queue and acl_queue tables into a database of your choice. It’s probably best to create a unique database and database user for this purpose, but we’ll leave that up to you.
Example import:
% mysql trigger -u trigger_user -p < ./conf/acl_queue_schema.sql
Trigger was renumbered to version 1.0 when it was publicly released on April 2, 2012. This legacy version history is incompleted, but is kept here for posterity.