1rancid.conf(5) File Formats Manual rancid.conf(5)
2
6 rancid.conf - rancid environment configuration file
7
9 rancid.conf contains environment configuration information for rancid-
10 run(1) and rancid-cvs(1), including shell PATH, list of rancid groups,
11 etc. It is read by several scripts at run-time and others inherit the
12 configration from a parent process which has read it.
13 The syntax of rancid.conf is that of sh(1). rancid.conf is used to set
15 environment variables used by other rancid scripts to effect their run-
16 time behavior or to enable them to find their resources.
17
19 The following variables are used (listed alphabetically):
20 ACLFILTERSEQ
22 Disables filtering of prefix-list/access-list sequence numbers.
23 This option implies ACLSORT=NO for lists with sequence numbers.
24 Default: YES
26 ACLSORT
28 Permits disabling of access-list sorting, which could alter
29 statement order that had been cleverly crafted by the
30 administrator for optimal performance, thus making recovery and
31 comparsion more difficult.
32 Default: YES
34 BASEDIR
36 BASEDIR is the directory where rancid-run's log directory, the
37 revision control system's repository, and rancid group
38 directories will be placed.
39 Its value is configure's localstatedir and should be modified if
41 rancid is moved to a new location in the file system without re-
42 installing from the distribution.
43 Default: /var
45 CVSROOT
47 cvs(1) and rancid-cvs(1) use this environment variable to locate
48 the CVS repository. In some cases, particularly for Subversion
49 and git, it is used as an argument to commands. In general, it
50 should not be necessary to alter it, but it could be set to a
51 remote location if the the RCS system supports it. If it is a
52 remote location, any necessary authentication must be handled
53 separately from RANCiD, which provides no means of interacting
54 with the remote.
55 Default: $BASEDIR/CVS
57 DIFFSCRIPT
59 Defines an alternate filter for the output of the RCS diff. The
60 filter should read from stdin and write to stdout. The default
61 is defined in control_rancid and only improves readability.
62 Example: DIFFSCRIPT="sed -e '/^=/d' | expand"; export DIFFSCRIPT
64 FILTER_OSC
66 Determines if oscillating data such as keys, passwords, etc are
67 filtered from configs. The value may be "NO", "YES" or "ALL".
68 YES is less aggressive than ALL. The FILTER_PWDS variable may
69 override this.
70 Default: YES
72 Note: a value of "NO" will most likely produce large
74 repositories and frequent diff e-mail. A value of "YES" is
75 encouraged.
76 Note: FILTER_OSC does not currently affect the handling of SNMP
78 community strings. see NOCOMMSTR below.
79 FILTER_PWDS
81 Determines which passwords will be filtered from configs. The
82 value may be "NO", "YES", or "ALL" to filter none of the
83 passwords, only those which are reversable or plain-text, or all
84 (plus ssh keys, etc), respectively.
85 Default: YES
87 Note: a value of "NO" could be a security issue since diffs are
89 sent via e-mail. A value of "ALL" is encouraged.
90 Note: FILTER_PWDS does not affect the handling of SNMP community
92 strings. see NOCOMMSTR below.
93 Note: passwords whose value cycles (oscillates) and would
95 produce erroneous diffs may be filtered (e.g.: Alteon
96 passwords). See the FILTER_OSC variable.
97 LIST_OF_GROUPS
99 Defines a list of group names of routers separated by white-
100 space. These names become the directory names in $BASEDIR which
101 contain the data for that set of devices. rancid-run(1) also
102 uses this variable to determine which device groups it should
103 collect. Choose these names to be descriptive of the set of
104 devices and do not use spaces, unprintable characters, etc.
105 Example: LIST_OF_GROUPS="UofO USFS"
107 Two groups are defined; UofO (University of Oregon) and USFS (US
109 Forest Service). Each will have a directory created (see
110 rancid-cvs(1)) $BASEDIR/UofO and $BASEDIR/USFS respectively,
111 which will contain their data.
112 Each group must also have aliases for the administrative and
114 diff recipients set-up in /etc/aliases. For example:
115 rancid-uofo: frank
117 rancid-admin-uofo: joe,bob
118 rancid-usfs: frank
119 rancid-admin-usfs: joe,bob
120 LOCKTIME
123 Defines the number of hours a group's lock file may age before
124 rancid starts to complain about a hung collection. The default
125 is 4 hours.
126 LOGDIR Directory where rancid-run places log files. This can not be
128 set or altered effectively in a group-specific rancid.conf.
129 Default: $BASEDIR/logs
131 MAILDOMAIN
133 Define the domain part of addresses for administrative and diff
134 e-mail. The value of this variable is simply appended to the
135 normal mail addresses. For example rancid-usfs@example.com, if
136 MAILDOMAIN had been set to "@example.com".
137 MAILHEADERS
139 Define additional mail headers to be added to rancid mail, such
140 as Precedence or X- style headers. Individual headers must be
141 separated by a \n (new line).
142 Default: Precedence: bulk
144 Example: Precedence: bulk\nX-clamation: beef cake
146 MAILOPTS
148 Define additional options used to invoke sendmail(8). By
149 default, this is not set.
150 Example: MAILOPTS="-f bounces.go.here@example.com"
152 MAILSPLIT
154 Defines the maximum BODY size of diffs in kilobytes, such that
155 diffs are split into clunks no larger than N kbytes. The
156 minimum is 0, which disables splitting.
157 Default: 0.
159 MAX_ROUNDS
161 Defines how many times rancid should retry collection of devices
162 that fail. The minimum is 0.
163 Default: 4.
165 NOCOMMSTR
167 If set, rancid(1) will filter SNMP community strings from
168 configs. Otherwise, they will be retained and may appear in
169 clear-text in e-mail diffs. By default, this is not set.
170 NOPIPE If set, rancid(1) will use temporary files to save the output
172 from the router and then read these to build the file which will
173 be saved in CVS (or Subversion or git). Otherwise, an IPC pipe
174 will be used. We have found that the buffering mechanisms used
175 in perl and expect are heinous. Using temporary files may
176 result in a noticeable improvement in speed. By default, this
177 is not set.
178 OLDTIME
180 Specified as a number of hours, OLDTIME defines how many hours
181 should pass since a successful collection of a device's
182 configuration and when control_rancid(1) should start
183 complaining about failures. The value should be greater than
184 the number of hours between rancid-run cron runs.
185 Default: 24
187 PAR_COUNT
189 Defines the number of rancid processes that par(1) will start
190 simultaneously as control_rancid(1) attempts to perform
191 collections. Raising this value will decrease the amount of
192 time necessary for a complete collection of a (or all) rancid
193 groups at the expense of system load. The default is relatively
194 cautious. If collections are not completing quickly enough for
195 users, use trial and error of speed versus system load to find a
196 suitable value.
197 Default: 5
199 PATH Is a colon separate list of directory pathnames in the the file
201 system where rancid's sh(1) and perl(1) scripts should look for
202 the programs that it needs, such as telnet(1). Its value is set
203 by configure. Should it be necessary to modify PATH, note that
204 it must include /usr/libexec/rancid.
205 RCSSYS Sets which revision control system is in use. Valid values are
207 cvs for CVS, git for Git or svn for Subversion.
208 Default: cvs
210 TERM Some Unix utilities require TERM, the terminal type, to be set
212 to a sane value. Some clients, such as telnet(1) and ssh(1),
213 communicate this to the server (i.e.: the remote device), thus
214 this can affect the behavior of login sessions on a device. The
215 default should suffice.
216 Default: network
218 TMPDIR Some Unix utilities recognize TMPDIR as a directory where
220 temporary files can be stored. In some cases, rancid utilizes
221 this directory for lock files and other temporary files.
222 Default: /tmp
224 Each of these are simply environment variables. In order for them to
226 be present in the environment of child processes, each must be
227 exported. See sh(1) for more information on the built-in command
228 export.
229
231 rancid.conf is interpreted directly by sh(1), so its syntax follows
232 that of the bourne shell. Errors may produce quite unexpected results.
233
235 /etc/rancid/rancid.conf
236 Configuration file described here.
237 <group>/rancid.conf
239 Group-specific configuration file described here.
240
242 control_rancid(1), rancid(1), rancid-cvs(1), rancid-run(1)
243
245 In RANCID releases prior to 2.3, rancid.conf was named env and located
246 in the bin directory. This was changed to be more consistent with
247 common file location practices.
248 19 December 2016 rancid.conf(5)