rancid.conf(5)                File Formats Manual               rancid.conf(5)




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: /usr/local/var

       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", "YES"  or  "ALL".
              YES  is  less aggressive than ALL.  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.

       LC_COLLATE
              See locale(1).

       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  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 from
              configs.  Otherwise, they will be retained  and  may  appear  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    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 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/local/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), 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

       /usr/local/etc/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.



                                 24 March 2020                  rancid.conf(5)

Man(1) output converted with man2html