summaryrefslogtreecommitdiffstats
path: root/README
blob: c5174a973b3e649553c7b666be949c0ed5567ac7 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
Rancid is a "Really Awesome New Cisco confIg Differ" developed to
maintain CVS controlled copies of router configs.

*** The Following Information is Very Important ****
Rancid 2.3 introduces a new directory layout.  It has been changed to more
closely follow the standard path hierarchy, which is defined by the FHS
standard and autoconf, and/or make these locations more easily configurable
within rancid.

The obvious advantage of this is making rancid more easily packagable; i.e.:
NetBSD pkgsrc, FreeBSD port, Linux RPM, etc.

Please please please please read the UPGRADING file for more information.
**********

The following is the packing list for Rancid.  .in is stripped from
the files below by configure with substitutions completed:

README		This file.
CHANGES		List of changes to Rancid.
Todo		Partial list of what needs to be done.
rancid.conf.in	Environment settings needed.
rancid-run.in	Script designed to be run from cron calling control_rancid.
control_rancid.in
		Builds router list, calls rancid on each router and
		handles cvs routines.
rancid-fe.in	chooses between rancid/[abefhjrx]rancid/cat5rancid.
rancid.in	Runs commands on cisco routers and processes the output.
brancid.in	Runs commands on baynet/nortel routers and processes the output.
erancid.in	Runs commands on ADC EZ-T3 muxes and processes the output.
f10rancid.in	Runs commands on Force10 routers and processes the output.
francid.in	Runs commands on foundry switches and processes the output.
hrancid.in	Runs commands on hp procurve switches and processes the output.
jrancid.in	Runs commands on juniper routers and processes the output.
mrancid.in	Runs commands on MRT daemons and processes the output.
nrancid.in	Runs commands on netscreen routers and processes the output.
rrancid.in	Runs commands on redback routers and processes the output.
xrancid.in	Runs commands on extreme switches and processes the output.
cat5rancid.in	Runs commands on cisco Cat switches and processes the output.
blogin.in	Expect script that logs into baynet/nortel routers either
		interactively, runs a set of commands, or runs another expect
		script.
clogin.in	Expect script that logs into routers either interactively,
		runs a set of commands, or runs another expect script.
elogin.in	Expect script that logs into ADC EZ-T3 muxes either
		interactively, runs a set of commands, or runs another expect
		script.
flogin.in	Expect script that logs into foundry switches.  Once foundry
		cleans up their bloody UI, clogin should do the job.
hlogin.in	Expect script that logs into hp procurve switches either
		interactively, runs a set of commands, or runs another expect
		script.
jlogin.in	Expect script that logs into juniper routers similarly to
		clogin.  It is not terribly robust, but mainly used for it's
		-c and -s options.
.cloginrc	TCL commands to set passwords, usernames etc. used by clogin
		and jlogin.
par.in		Parallel processing of commands - any commands.
rancid-cvs.in	Creates all of the CVS and config directories.
hpuifilter.c	HP procurve login filter - see end of hlogin(1).
etc/		Configuration file samples
etc/lg.conf.sample
etc/rancid.conf.sample
man/		man pages
share/		Readmes, samples, utilities, contribs, etc

The following are included as part of the installation tools:

Makefile.in	processed by configure to produce Makefiles
configure	GNU autoconf script
install-sh	GNU autoconf shell script to simulate BSD style install
mkinstalldirs	GNU autoconf shell script to make installation directories

rancid will also need to have the following packages:
cvs		Code revision system available from prep.ai.mit.edu:/pub/gnu
gnudiff		gnudiff provides the uni-diff (-u) option.  If you do not have
		a diff that supports -u, configure will set-up rancid to use
		'diff -c' or 'diff -C'.
perl5		perl version 5 or greater available from www.cpan.org
expect		http://expect.nist.gov/  We highly suggest that you stick to
		expect 5.24.1 (or so).  This seems to work best.  Note that
		you need to have the accompanying tcl &/ tk.
tcl		Required by expect.

Bill Fenner (now maintained by others) has a cgi script for interacting
with CVS repositories via a web interface.  This provides a great way to
view rancid diffs and full configs, especially for those unfamiliar with
cvs.  The package is not included, but can be found here:

	http://www.freebsd.org/projects/cvsweb.html


Quick Installation Guide (an example):

1) ./configure [--prefix=<basedir>]
   By default, rancid will be installed under /usr/local/rancid (the default
   "prefix").  This can be overridden with the --prefix option.  E.g.:

	./configure --prefix=/home/rancid

   Rancid uses autoconf's "localstatedir" as the location of it's logs,
   CVS respository, and directories where it's groups are placed.  The user
   who will run rancid (from cron, etc) will need write access to these
   directories.  By default, this is <prefix>/var, or /home/rancid/var
   following the example above.

   We realize that this is not optimal, but it follows the standards.  We
   suggest that this be altered to include the package name, like so:

	./configure --prefix=/home/rancid \
			--localstatedir=/home/rancid/var/rancid

   The user who will run rancid must have write permission in "localstatedir".

   See ./configure --help for other configure options.

2) make install

3) Modify <sysconfdir>/rancid.conf (e.g.: <basedir>/etc/rancid.conf).  The
   variable LIST_OF_GROUPS is a space delimited list of router "groups".
   E.g.:
	LIST_OF_GROUPS="backbone aggregation switches"

4) Put .cloginrc in the home directory of the user who will run rancid.
   .cloginrc must be not be readable/writable/executable by "others",
   i.e.: .cloginrc must be mode 0600 or 0640.

5) Modify .cloginrc.

   Test to make sure that you can log into every router.

   Note: the juniper user you use *must* log into a cli shell (which
   is the default on a juniper).

   See the file cloginrc.sample, located in <datadir> (<basedir>/share/rancid),
   for examples and good starting point.  Also take a look at the cloginrc
   manual page, 'man -M <basedir>/man cloginrc'.

6) Modify /etc/aliases
   Rancid sends the diffs and other administrative emails to rancid-<GROUP>
   and problems to rancid-admin-<GROUP>, where <GROUP> is the "GROUP" of
   routers.  This way you can separate your backbone routers from your
   access routers or separate based upon network etc...  Different router
   uses forced different people being interested in router "groups" -
   thus this setup.  Make sure email to rancid-<GROUP> works.  /etc/aliases
   can be maintainable by Majordomo stuff, but make sure the user that
   runs rancid can post to the list.

   The Precedence header set to bulk or junk *hopefully* avoids replies from
   auto-responders and vacation type mail filters.

   The --enable-mail-plus option to configure will set each of the "rancid-"
   addresses mentioned above to "rancid+".  See sendmail's operation manual
   for more information on handling of '+'.

   The --enable-adminmail-plus configure option will set each of the
   "rancid-admin-" addresses mentioned above to "rancid-admin+".  If this
   option is not used, the value of --enable-mail-plus is assumed.  That is,
   the addresses will be "rancid+", if it is specified.

7) Run rancid-cvs.
   This creates all of the necessary directories and config files for
   each of the groups in LIST_OF_GROUPS and imports them into CVS.  This
   will also be run each time a new group is added.  Do not create the
   directories or CVS repository manually, allow rancid-cvs do it.  Also see
   'man -M <basedir>/man rancid-cvs'.

8) For each "group", modify the router.db file in the group directory.
   The file is of the form "router:mfg:state" where "router" is
   the name (we use FQDN) of the router, mfg is the manufacturer
   from the set of (cat5|cisco|juniper) (see router.db.5 for a complete
   list and description), and "state" is either up or down.  Each router
   listed as "up" will have the configuration grabbed.  Note: manufacturer
   cat5 is intended only for cisco catalyst switches running catalyst (not
   IOS) code.

   e.g.: <localstatedir>/<group>/router.db:
	cisco-router.domain.com:cisco:up
	adc-mux.domain.com:ezt3:up
	foundry-switch-router.domain.com:foundry:up
	juniper-router.domain.com:juniper:up
	redback-dsl-router.domain.com:redback:down
	extreme-switch.domain.com:extreme:down

9) For first-time users or new installations, run bin/rancid-run (with no
   arguments) and check the resulting log file(s) (in logs/*) for errors.
   Repeat until there are no errors.

10) Put rancid-run in cron to be called however often you want it to
   run for each group (rancid-run [<GROUP>]).  If you run it less
   often than once/hour, check the setting of OLDTIME in etc/rancid.conf.
   E.g.:
	# run config differ hourly
	1 * * * * <BASEDIR>/bin/rancid-run
	# clean out config differ logs
	50 23 * * * /usr/bin/find <localstatedir>/logs -type f -mtime +2 -exec rm {} \;

11) Note: If you are using any of these programs (other than
    rancid-run) out of cron, make sure that you set your $PATH
    correctly so that they work.  E.g.: if you are using clogin,
    it can call id, telnet, ssh, and/or rsh.

    configure already makes sure that $PATH is set correctly in
    etc/rancid.conf for rancid-run, so you could use the $PATH from there. e.g.:

	50 23 * * * . <sysconfdir>/rancid.conf; clogin -c 'sh vers' router

12) Send any bugs, suggestions or updates to rancid@shrubbery.net.
    See the web page at http://www.shrubbery.net/rancid.  We have
    created the standard mailing lists for those interested;
    rancid-announce@shrubbery.net and rancid-discuss@shrubbery.net.
    Subscribe by sending an email whose body contains "subscribe
    rancid-<announce or discuss>" to majordomo@shrubbery.net.

    If you are reporting problems, please include the version of rancid,
    expect, and your OS in the email.


Problem with clogin/telnet hanging within rancid or scripts?

If you have experienced rancid (or more precisely, telnet) hanging on a
solaris 2.6 box; check to be sure you have the following two patches
installed (see showrev -p).  There may be more recent versions of these
patches and they are likely included with 2.7 and 2.8: 

Patch-ID# 105529-08
Keywords: security tcp rlogin TCP ACK FIN packet listen
Synopsis: SunOS 5.6: /kernel/drv/tcp patch

Patch-ID# 105786-11
Keywords: security ip tcp_priv_stream routing ip_enable_group_ifs ndd
Synopsis: SunOS 5.6: /kernel/drv/ip patch

Another possibile contributor is expect/tcl.  We've noticed that expect
5.24.1 (possibly 5.28.*) and whatever tcl happens to compile with it, 
seems to not exhibit this problem, while 5.32.* appears to on linux and
solaris but not on netbsd 1.5.

Also, for rancid 2.3 and later, changes were made to the login scripts
which use some more elaborate regexes that have failed with expect versions
prior to 5.40.  While 5.40 works, it still seems to need the patch offered
on the rancid web page.

See www.shrubbery.net/rancid for additional notes on this.

-Hank