Convene is a utility that leverages Git to help manage backing up remote or local text, usually in the form of configuration files. A task is used to customize what is being archived. When a task is not specified, SNMP is used to attempt to choose which task is loaded based off the sysDescr.
Hosts can be added via a variety of methods such as CSV files, TXT files, zone transfers via DNS, or individually specified on the command-line.
To ease locating files in the repository and to dictate the file structure of the repository, Regular Expressions can be used.
-
Host list support via DNS, CSV, TXT, or command line
-
Repository file structure determined by Regex
-
Device detection (Cisco, etc) via SNMP or by direct specification
-
Customizable with tasks
The following gems are required to use Convene:
-
dnsruby
-
git
-
net-scp
-
net-ssh >= 2.0.23
-
rake
-
saikuro_treemap (for ccn metrics)
-
snmp
Note: The OpenSSL library for Ruby (libopenssl-ruby via apt for Ubuntu) must be installed in order for net-ssh to function properly.
RubyGems is the preferred install method for Convene. It is intended to be installed via the RubyGems system. To get the latest version, simply enter the following int your command prompt:
$ sudo gem install convene-<version>.gem
Prior to using Convene, please make sure ‘git’ is available in your path and you have installed the required lib OpenSSL package (if required, see above).
If you are developing for Convene and would like to run from the source tree, run executables with:
$ ruby -rubygems -I lib bin/convene
Run against a single host:
convene -r /path/to/repository -n host.domain.tld -u username -p password
Run against multiple hosts with the same credentials:
convene -r /path/to/repository -n host.domain.tld -n host.domain.tld -u username -p password
Run against domains with different credentials:
convene -r /path/to/repository -d user1:pass1@domain1.tld -d user2:pass2@domain2.tld
Run against a txt file of host strings containing hosts:
convene -r /path/to/repository -N hostfile.txt -u user -p pass
Run against a CSV file of host strings containing domains:
convene -r /path/to/repository -D domainfile.csv -u user -p pass
Usernames and passwords can also be specified as part of the host string within either file type allowing for greater flexiblility in environments with varying credentials.
<host string>,<snmp community>,<snmp version>,<snmp port>,<snmp timeout>,<snmp retries>
Supports URIs beginning with convene:// or left omitted.
convene://user:pass@device.domain.tld?task=cisco
<username>:<password>@<hostname or domain> Username and password are optional. Omit ‘@’ when listing only host or domain:
user:password@host.domain.tld or host.domain.tld
Specify a task in query notation and skip SNMP finger printing in any host string:
host.domain.tld?task=Cisco
Task examples are available for a small variety of networking devices such as Cisco and Foundry.
The preference in which tasks are loaded is:
* Direct filename specifed in the URI. * User's '.convene/tasks/(filename).rb' in home directory * Tasks included with Convene
Regular experessions can be specified on the command-line with the -x <regex> flag. The overall match of the expression determines whether the host will be added whereas sub-matches determine the file structure of the repository.
-x /.*\.somedomain.tld/
This would add all hosts that match *.somedomain.tld and store the contents of the files under the root repository directory in directories named after the hostname of the device.
-x /.*\.(somedomain.tld)/
Will add all hosts in the example above, however the contents would be stored in the root repository directory in a directory named “somedomain.tld” then in a directory named after the hostname of the device.
Copyright 2010 Andrew R. Greenwood and Jonathan P. Voss