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 configuration 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):
- ACLFILTERSEQ
- Disables filtering of prefix-list/access-list sequence numbers. This
option implies ACLSORT=NO for lists with sequence numbers.
Default: YES
- 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 comparison 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, 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.
Default: $BASEDIR/CVS
- DIFFSCRIPT
- 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
DIFFSCRIPT
- FILTER_OSC
- Determines if oscillating data such as keys, passwords, etc are filtered
from configs. The value may be "NO" or "YES". The
FILTER_PWDS variable may override this.
Default: YES
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.
- 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 (oscillates) and would produce erroneous
diffs may be filtered (e.g.: Alteon passwords). See the FILTER_OSC
variable.
- 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. This can not be set or
altered effectively in a group-specific rancid.conf.
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
\n (new line).
Default: Precedence: bulk
Example: Precedence: bulk\nX-clamation: beef cake
- MAILOPTS
- Define additional options used to invoke sendmail(8). By default,
this is not set.
Example: MAILOPTS="-f bounces.go.here@example.com"
- MAILSPLIT
- Defines the maximum BODY size of diffs in kilobytes, such that diffs are
split clunks no larger than N kbytes. The minimum is 0, which disables
splitting.
Default: 0.
- MAX_ROUNDS
- Defines how many times rancid should retry collection of devices that
fail. The minimum is 0.
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 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.
- 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, git for Git 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.
- <group>/rancid.conf
- Group-specific 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.