rancid-run(1) General Commands Manual rancid-run(1)NAME
rancid-run - run rancid for each of the groups
SYNOPSIS
rancid-run [-V] [-f rancid.conf] [-f rancid.conf] [-m mail_rcpt] [-r device_name] [group [group ...]]
DESCRIPTION
rancid-run is a sh(1) script to run rancid(1) for a set of rancid group(s).
rancid-run reads rancid.conf(5) to configure itself, then uses control_rancid(1) to run rancid(1) for each rancid group. The set of rancid
groups can either be provided as command-line arguments or via the LIST_OF_GROUPS variable in rancid.conf(5), if the group argument is
omitted.
A lock file is maintained per-group to prevent simultaneous runs for a given group by rancid-run(1). The lock file will be named
.<group>.run.lock and will be located in /var/lib/rancid.
A log file is produced under $LOGDIR/logs for each rancid group processed. The file name will be <group>.YYYYMMDD.HHMMSS (year month day .
hour minute second).
rancid-run is normally used to run rancid from cron(8). For example:
0 * * * * /usr/local/rancid/bin/rancid-run
The command-line options are as follows:
-V Prints package name and version strings.
-f rancid.conf
Specify an alternate configuration file.
-m mail_rcpt
Specify the recipient of diff mail, which is normally rancid-<group>. The argument may be a single address, multiple comma
separated addresses, or -m may be specified multiple times.
-r device_name
Run rancid for a single device, device_name. device_name should be name, as it appears in a group's router.db. The device must be
marked "up". If a group is not specified on the command-line, rancid will be run against any group in which the device_name
appears.
The -r option alters the subject line of the diff mail. It will begin with <group name>/<device name> rather than just the group
name alone.
ENVIRONMENT
rancid-run utilizes the following environment variables from rancid.conf(5).
BASEDIR
Location of group directories, etc. This is set to the "localstatedir" by the configure script at installation time.
LIST_OF_GROUPS
List of rancid groups to collect.
PATH Search path for utilities.
TMPDIR Directory to hold temporary files.
ERRORS
If rancid fails to run or collect a device's configuration, the particular group's log file (mentioned above) should be consulted. Any
errors produced by the revision control system (CVS or Subversion) or any of the rancid scripts should be included there, whether they be a
botched cvs tree, login authentication failure, rancid configuration error, etc. If the log file produces no clues, the next debugging
step should be run the commands manually. For example, can the user who runs rancid login to the device with 'clogin hostname', and so on.
FILES
$BASEDIR/etc/rancid.conf
rancid-run configuration file.
SEE ALSO control_rancid(1), rancid.conf(5), router.db(5)
5 October 2006 rancid-run(1)
Check Out this Related Man Page
rancid.conf(5) File Formats Manual rancid.conf(5)NAME
rancid.conf - rancid environment configuration file
DESCRIPTION
rancid.conf contains environment configuration information for rancid-run(1) and rancid-cvs(1), including shell PATH, list of rancid
groups, etc. It is read by several scripts at run-time and others inherit the configration from a parent process which has read it.
The syntax of rancid.conf is that of sh(1). rancid.conf is used to set environment variables used by other rancid scripts to effect their
run-time behavior or to enable them to find their resources.
VARIABLES
The following variables are used (listed alphabetically):
ACLSORT
Permits disabling of access-list sorting, which could alter statement order that had been cleverly crafted by the administrator for
optimal performance, thus making recovery and comparsion more difficult.
Default: YES
BASEDIR
BASEDIR is the directory where rancid-run's log directory, the revision control system's repository, and rancid group directories
will be placed.
Its value is configure's localstatedir and should be modified if rancid is moved to a new location in the file system without re-
installing from the distribution.
Default: /var/lib/rancid
CVSROOT
cvs(1) and rancid-cvs(1) use this environment variable to locate the CVS repository. In some cases, and for Subversion, it is used
as an argument to commands. It should not be necessary to alter it.
Default: $BASEDIR/CVS
FILTER_PWDS
Determines which passwords will be filtered from configs. The value may be "NO", "YES", or "ALL" to filter none of the passwords,
only those which are reversable or plain-text, or all (plus ssh keys, etc), respectively.
Default: YES
Note: a value of "NO" could be a security issue since diffs are sent via e-mail. A value of "ALL" is encouraged.
Note: FILTER_PWDS does not affect the handling of SNMP community strings. see NOCOMMSTR below.
Note: passwords whose value cycles and would produce erroneous diffs are always filtered (e.g.: Alteon passwords).
LIST_OF_GROUPS
Defines a list of group names of routers separated by white-space. These names become the directory names in $BASEDIR which contain
the data for that set of devices. rancid-run(1) also uses this variable to determine which device groups it should collect. Choose
these names to be descriptive of the set of devices and do not use spaces, unprintable characters, etc.
Example: LIST_OF_GROUPS="UofO USFS"
Two groups are defined; UofO (University of Oregon) and USFS (US Forest Service). Each will have a directory created (see rancid-
cvs(1)) $BASEDIR/UofO and $BASEDIR/USFS respectively, which will contain their data.
Each group must also have aliases for the administrative and diff recipients set-up in /etc/aliases. For example:
rancid-uofo: frank
rancid-admin-uofo: joe,bob
rancid-usfs: frank
rancid-admin-usfs: joe,bob
LOCKTIME
Defines the number of hours a group's lock file may age before rancid starts to complain about a hung collection. The default is 4
hours.
LOGDIR Directory where rancid-run places log files.
Default: $BASEDIR/logs
MAILDOMAIN
Define the domain part of addresses for administrative and diff e-mail. The value of this variable is simply appended to the normal
mail addresses. For example rancid-usfs@example.com, if MAILDOMAIN had been set to "@example.com".
MAILHEADERS
Define additional mail headers to be added to rancid mail, such as Precedence or X- style headers. Individual headers must be
separated by a
(new line).
Default: Precedence: bulk
Example: Precedence: bulk
X-clamation: beef cake
MAX_ROUNDS
Defines how many times rancid should retry collection of devices that fail. The minimum is 1.
Default: 4.
NOCOMMSTR
If set, rancid(1) will filter SNMP community strings from configs. Otherwise, they will be retained and may appear in clear-text in
e-mail diffs. By default, this is not set.
NOPIPE If set, rancid(1) will use temporary files to save the output from the router and then read these to build the file which will be
saved in CVS (or Subversion). Otherwise, an IPC pipe will be used. We have found that the buffering mechanisms used in perl and
expect are heinous. Using temporary files may result in a noticeable improvement in speed. By default, this is not set.
OLDTIME
Specified as a number of hours, OLDTIME defines how many hours should pass since a successful collection of a device's configuration
and when control_rancid(1) should start complaining about failures. The value should be greater than the number of hours between
rancid-run cron runs.
Default: 24
PAR_COUNT
Defines the number of rancid processes that rancid_par(1) will start simultaneously as control_rancid(1) attempts to perform
collections. Raising this value will decrease the amount of time necessary for a complete collection of a (or all) rancid groups at
the expense of system load. The default is relatively cautious. If collections are not completing quickly enough for users, use
trial and error of speed versus system load to find a suitable value.
Default: 5
PATH Is a colon separate list of directory pathnames in the the file system where rancid's sh(1) and perl(1) scripts should look for the
programs that it needs, such as telnet(1). Its value is set by configure. Should it be necessary to modify PATH, note that it must
include /usr/lib/rancid/bin.
RCSSYS Sets which revision control system is in use. Valid values are cvs for CVS or svn for Subversion.
Default: cvs
TERM Some Unix utilities require TERM, the terminal type, to be set to a sane value. Some clients, such as telnet(1) and ssh(1),
communicate this to the server (i.e.: the remote device), thus this can affect the behavior of login sessions on a device. The
default should suffice.
Default: network
TMPDIR Some Unix utilities recognize TMPDIR as a directory where temporary files can be stored. In some cases, rancid utilizes this
directory for lock files and other temporary files.
Default: /tmp
Each of these are simply environment variables. In order for them to be present in the environment of child processes, each must be
exported. See sh(1) for more information on the built-in command export.
ERRORS
rancid.conf is interpreted directly by sh(1), so its syntax follows that of the bourne shell. Errors may produce quite unexpected results.
FILES
/etc/rancid/rancid.conf
Configuration file described here.
SEE ALSO control_rancid(1), rancid(1), rancid-cvs(1), rancid-run(1)HISTORY
In RANCID releases prior to 2.3, rancid.conf was named env and located in the bin directory. This was changed to be more consistent with
common file location practices.
18 December 2007 rancid.conf(5)