rancid.conf - rancid environment configuration file
contains environment configuration information for
(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 configuration from a parent process which has read it.
The syntax of rancid.conf
is that of sh
used to set environment variables used by other rancid scripts to effect their
run-time behavior or to enable them to find their resources.
The following variables are used (listed alphabetically):
- Disables filtering of prefix-list/access-list sequence
numbers. This option implies ACLSORT=NO for lists with sequence numbers.
- 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 comparison more difficult.
- 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
- cvs(1) and rancid-cvs(1) use this environment
variable to locate the CVS repository. In some cases, particularly for
Subversion and git, it is used as an argument to commands. In general, it
should not be necessary to alter it, but it could be set to a remote
location if the the RCS system supports it. If it is a remote location,
any necessary authentication must be handled separately from RANCiD, which
provides no means of interacting with the remote.
- Defines an alternate filter for the output of the RCS diff.
The filter should read from stdin and write to stdout. The default is
defined in control_rancid and only improves readability.
Example: DIFFSCRIPT="sed -e '/^=/d' | expand"; export
- Determines if oscillating data such as keys, passwords, etc
are filtered from configs. The value may be "NO",
"YES" or "ALL". YES is less aggressive than ALL. The
FILTER_PWDS variable may override this.
Note: a value of "NO" will most likely produce large repositories
and frequent diff e-mail. A value of "YES" is encouraged.
Note: FILTER_OSC does not currently affect the handling of SNMP
community strings. see NOCOMMSTR below.
- 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.
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 (oscillates) and would produce erroneous
diffs may be filtered (e.g.: Alteon passwords). See the FILTER_OSC
- 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
Each group must also have aliases for the administrative and diff recipients
set-up in /etc/aliases. For example:
- 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
- Directory where rancid-run places log files. This
can not be set or altered effectively in a group-specific
- 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 email@example.com, if MAILDOMAIN
had been set to "@example.com".
- Define additional mail headers to be added to rancid mail,
such as Precedence or X- style headers. Individual headers must be
separated by a \n (new line).
Default: Precedence: bulk
Example: Precedence: bulk\nX-clamation: beef cake
- Define additional options used to invoke
sendmail(8). By default, this is not set.
Example: MAILOPTS="-f firstname.lastname@example.org"
- Defines the maximum BODY size of diffs in kilobytes, such
that diffs are split into clunks no larger than N kbytes. The minimum is
0, which disables splitting.
- Defines how many times rancid should retry collection of
devices that fail. The minimum is 0.
- 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.
- 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 or git). 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.
- 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.
- 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.
- 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.
- Sets which revision control system is in use. Valid values
are cvs for CVS, git for Git or svn for Subversion.
- 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.
- 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.
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
for more information on the built-in command export.
is interpreted directly by sh
(1), so its syntax
follows that of the bourne shell. Errors may produce quite unexpected results.
- Configuration file described here.
- Group-specific configuration file described here.
In RANCID releases prior to 2.3, rancid.conf
was named env
located in the bin directory. This was changed to be more consistent with
common file location practices.