rancid.conf(5)

📦
version 3.14 · 7 versions
, in debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking

🎀 NAME 🎀

okay bestie, gather round — this is rancid.conf(5), straight out of the File Formats Manual, and it's literally the rancid environment configuration file. yes, the whole thing. we're doing this. 💖

✨ DESCRIPTION ✨

So rancid.conf holds all the environment configuration info for rancid-run(1) and rancid-cvs(1) — we're talking the shell PATH, the list of rancid groups, all of it. Several scripts read this file at run-time, and the others just inherit the config from a parent process that already read it. iconic behavior honestly.

The syntax of rancid.conf is the syntax of sh(1). That's it. That's the vibe. You use it to set environment variables that the other rancid scripts read to change how they behave at run-time, or to help them find their resources. 🦋

💅 VARIABLES 💅

Here's every single one, listed alphabetically (we love an organized queen):

  • ACLFILTERREGEX — If it's non-empty, this is a semi-colon-separated (';') list of regexes. The contents of ACLs whose name matches a regex in this list get filtered. Why do we care? Because the whole point is filtering out auto-generated lists, which reduces the churn inside rancid. Setting this implies ACLFILTERSEQ=YES. Heads up though: not all device types and not all ACL types are supported by this feature. Default: undefined.
  • ACLFILTERSEQ — Disables filtering of prefix-list/access-list sequence numbers. This option implies ACLSORT=NO for lists with sequence numbers. Default: YES.
  • ACLSORT — Lets you disable access-list sorting. Lowkey important, because sorting could alter statement order that an administrator had cleverly crafted for optimal performance — which makes recovery and comparison more difficult. Default: YES.
  • BASEDIR — This is the directory where rancid-run's log directory, the revision control system's repository, and the rancid group directories all get placed. Its value is configure's localstatedir, and you should change it if rancid gets moved to a new location in the file system without a re-install 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 — especially for Subversion and git — it's used as an argument to commands. Generally you shouldn't need to touch it, but it can be set to a remote location if the RCS system supports that. If it is remote, any necessary authentication has to be handled separately from RANCID, because RANCID 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 — Decides whether oscillating data like keys, passwords, etc. get filtered out of configs. The value can be "NO", "YES" or "ALL". YES is less aggressive than ALL. And psst — FILTER_PWDS 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 get filtered from configs. The value may be "NO", "YES", or "ALL" — meaning filter none of the passwords, only those which are reversable or plain-text, or all of them (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.
  • LC_COLLATE — See locale(1).
  • LIST_OF_GROUPS — Defines a list of group names of routers, separated by whitespace. These names become the directory names in $BASEDIR which hold the data for that set of devices. rancid-run(1) also uses this variable to figure out which device groups it should collect. Pick names that are descriptive of the set of devices, and do not use spaces, unprintable characters, etc.

Example:

LIST_OF_GROUPS="UofO USFS"

Two groups are defined here: UofO (University of Oregon) and USFS (US Forest Service). Each will get 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 how many 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 — Defines 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 — Defines additional mail headers to add to rancid mail, like 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 — Defines 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, so that diffs get split into 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 out of configs. Otherwise they're retained and may show up in clear-text in e-mail diffs. 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 before control_rancid(1) starts 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 while control_rancid(1) is attempting to perform collections. Raising this value decreases the time needed for a complete collection of a (or all) rancid group(s), at the expense of system load. The default is relatively cautious. If collections aren't finishing quickly enough for your users, do some trial and error — speed versus system load — to find a suitable value. Default: 5.
  • PATH — A colon-separated list of directory pathnames in the file system where rancid's sh(1) and perl(1) scripts should look for the programs they need, such as telnet(1). Its value is set by configure. If you do need 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.
  • SENDMAIL — The filename or FQPN of the sendmail executable (or script) that will accept the -t option, such that it will read recipients and other headers from stdin.
  • 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), so 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 uses this directory for lock files and other temporary files. Default: /tmp.

Each of these are simply environment variables. And for them to actually be present in the environment of child processes, each one must be exported. See sh(1) for more info on the built-in command export. 🫶

😭 ERRORS 😭

rancid.conf is interpreted directly by sh(1), so its syntax follows that of the bourne shell. Which means errors may produce quite unexpected results. no cap, be careful out there.

📁 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. It got changed to be more consistent with common file location practices. a glow-up, honestly. 💅

and that's the whole page, bestie 🦋 this one's dated 20 July 2021 and it lives in section 5 as rancid.conf(5) — go forth and configure responsibly 💖✨

📦 where this page comes from