1rancid.conf(5)                File Formats Manual               rancid.conf(5)
2
3
4

NAME

6       rancid.conf - rancid environment configuration file
7

DESCRIPTION

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
14       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

VARIABLES

19       The following variables are used (listed alphabetically):
20
21       ACLFILTERSEQ
22              Disables filtering of prefix-list/access-list sequence  numbers.
23              This option implies ACLSORT=NO for lists with sequence numbers.
24
25              Default: YES
26
27       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
33              Default: YES
34
35       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
40              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
44              Default: /var
45
46       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
56              Default: $BASEDIR/CVS
57
58       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
63              Example: DIFFSCRIPT="sed -e '/^=/d' | expand"; export DIFFSCRIPT
64
65       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
71              Default: YES
72
73              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
77              Note: FILTER_OSC does not currently affect the handling of  SNMP
78              community strings.  see NOCOMMSTR below.
79
80       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
86              Default: YES
87
88              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
91              Note: FILTER_PWDS does not affect the handling of SNMP community
92              strings.  see NOCOMMSTR below.
93
94              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
98       LC_COLLATE
99              See locale(1).
100
101       LIST_OF_GROUPS
102              Defines a list of group names of  routers  separated  by  white-
103              space.  These names become the directory names in $BASEDIR which
104              contain the data for that set of  devices.   rancid-run(1)  also
105              uses  this  variable  to determine which device groups it should
106              collect.  Choose these names to be descriptive  of  the  set  of
107              devices and do not use spaces, unprintable characters, etc.
108
109              Example: LIST_OF_GROUPS="UofO USFS"
110
111              Two groups are defined; UofO (University of Oregon) and USFS (US
112              Forest Service).   Each  will  have  a  directory  created  (see
113              rancid-cvs(1))  $BASEDIR/UofO  and  $BASEDIR/USFS  respectively,
114              which will contain their data.
115
116              Each group must also have aliases  for  the  administrative  and
117              diff recipients set-up in /etc/aliases.  For example:
118
119                        rancid-uofo:            frank
120                        rancid-admin-uofo:      joe,bob
121                        rancid-usfs:            frank
122                        rancid-admin-usfs:      joe,bob
123
124
125       LOCKTIME
126              Defines  the  number of hours a group's lock file may age before
127              rancid starts to complain about a hung collection.  The  default
128              is 4 hours.
129
130       LOGDIR Directory  where  rancid-run  places log files.  This can not be
131              set or altered effectively in a group-specific rancid.conf.
132
133              Default: $BASEDIR/logs
134
135       MAILDOMAIN
136              Define the domain part of addresses for administrative and  diff
137              e-mail.   The  value  of this variable is simply appended to the
138              normal mail addresses.  For example rancid-usfs@example.com,  if
139              MAILDOMAIN had been set to "@example.com".
140
141       MAILHEADERS
142              Define  additional mail headers to be added to rancid mail, such
143              as Precedence or X- style headers.  Individual headers  must  be
144              separated by a \n (new line).
145
146              Default: Precedence: bulk
147
148              Example: Precedence: bulk\nX-clamation: beef cake
149
150       MAILOPTS
151              Define  additional  options  used  to  invoke  sendmail(8).   By
152              default, this is not set.
153
154              Example: MAILOPTS="-f bounces.go.here@example.com"
155
156       MAILSPLIT
157              Defines the maximum BODY size of diffs in kilobytes,  such  that
158              diffs  are  split  into  clunks  no  larger  than N kbytes.  The
159              minimum is 0, which disables splitting.
160
161              Default: 0.
162
163       MAX_ROUNDS
164              Defines how many times rancid should retry collection of devices
165              that fail.  The minimum is 0.
166
167              Default: 4.
168
169       NOCOMMSTR
170              If  set,  rancid(1)  will  filter  SNMP  community  strings from
171              configs.  Otherwise, they will be retained  and  may  appear  in
172              clear-text in e-mail diffs.  By default, this is not set.
173
174       OLDTIME
175              Specified  as  a number of hours, OLDTIME defines how many hours
176              should  pass  since  a  successful  collection  of  a   device's
177              configuration    and   when   control_rancid(1)   should   start
178              complaining about failures.  The value should  be  greater  than
179              the number of hours between rancid-run cron runs.
180
181              Default: 24
182
183       PAR_COUNT
184              Defines  the  number  of rancid processes that par(1) will start
185              simultaneously  as   control_rancid(1)   attempts   to   perform
186              collections.   Raising  this  value  will decrease the amount of
187              time necessary for a complete collection of a  (or  all)  rancid
188              groups at the expense of system load.  The default is relatively
189              cautious.  If collections are not completing quickly enough  for
190              users, use trial and error of speed versus system load to find a
191              suitable value.
192
193              Default: 5
194
195       PATH   Is a colon separate list of directory pathnames in the the  file
196              system  where rancid's sh(1) and perl(1) scripts should look for
197              the programs that it needs, such as telnet(1).  Its value is set
198              by  configure.  Should it be necessary to modify PATH, note that
199              it must include /usr/libexec/rancid.
200
201       RCSSYS Sets which revision control system is in use.  Valid values  are
202              cvs for CVS, git for Git or svn for Subversion.
203
204              Default: cvs
205
206       SENDMAIL
207              The filename or FQPN of the sendmail executable (or script) that
208              will accept the -t option, such that it will read recipients and
209              other headers from stdin.
210
211       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
217              Default: network
218
219       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
223              Default: /tmp
224
225       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

ERRORS

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

FILES

235       /etc/rancid/rancid.conf
236              Configuration file described here.
237
238       <group>/rancid.conf
239              Group-specific configuration file described here.
240

SEE ALSO

242       control_rancid(1), rancid(1), rancid-cvs(1), rancid-run(1)
243

HISTORY

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
249
250
251                                 15 April 2019                  rancid.conf(5)
Impressum