.\" $Id: pollcsm.man,v 2.4 2012/02/03 19:49:59 ksb Exp $
.\" by Kevin Braunsdorf
.\" $Compile: Display%h
.\" $Display: ${nroff-groff} -Tascii -man %f | ${PAGER:-less}
.\" $Install: %b -mDeinstall %o %f && cp %f $DESTDIR/usr/local/man/man8/pollcsm.8
.\" $Deinstall: ${rm-rm} -f $DESTDIR/usr/local/man/[cm]a[nt]8/pollcsm.8*
.TH POLLCSM 8L LOCAL
.SH NAME
pollcsm \- walk a Cisco CSM MIB to update PEG VIP and real statistics
.SH SYNOPSIS
.ds PN "pollcsm
\fI\*(PN\fP [\fB\-Dnx\fP] [\fB\-c\fP\~\fIread\fP] [\fB\-H\fP\~\fIsample\fP] [\fB\-p\fP\~\fIdelay\fP] \fIcsmA\fP [\fIcsmB\fP]
.br
\fI\*(PN\fP \fB\-h\fP
.br
\fI\*(PN\fP \fB\-V\fP

.SH DESCRIPTION
The performance and engineering site accepts 3 scaler statistics for
each real host behind a CSM vip under the \fBreal.cvu\fP RRD type.
This program sends those data source to PEG
by walking the SNMP MIB for a pair of CSM blades.
This should run on a (at least one) host that is directly connected
to the CSM at level-2 to avoid a lot ofg SNMP traffic in/out of the
blades.
.P
The VIP and real information is reverse mapped from the IP addresses
of the target reals and the VIP.  If you can't map them in DNS you
are just plain out of luck here.  The IP's don't make a useful
PEG interface.
.P
The VIP should reverse to a FQDN of the form
.RS
\fIclass\fP-\fBvip\fP\fIN\fP.\fIlocal\fP.\fIdomain\fP
.RE
Each real host's IP should reverse map the the FQDN of the host:
.RS
\fIshort\fP.\fIdomain\fP
.RE
.P
With that information \fB\*(PN\fP makes pretty nifty names for the
real on each host:
.RS
\fBhost/\fIshort\fP/app-real\fIport\fP.rrd
.RE
and for the VIP
.RS
\fBcluster/\fIclass\fP/app-vip\fIN\fP.\fIlocal\fP_\fIport\fP.rrd
.RE
.P
The \fIport\fP comes from the SNMP MIB, the rest from DNS reverse lookups
of the IP addresses from that MIB.

.SH OPTIONS
Since most of the configuration is in DNS there are not as many
options as you'd think.  There should be more (see BUGS).
.TP
\fB\-D\fP
Display RRD path of each network port we may sample, then exit.
This is used to tell the PEG guys what RRD files to build (once) when
we setup a new switch.
.TP
\fB\-c\fP \fIread\fP
Specify a snmp read-community to access the switch.
.TP
\fB\-H\fP \fIsample\fP[:\fIport\fP]
Specify the sample collection host, running \fBrrdd\fP(8l).
Optionally specify the rrdd(8l) update \fIport\fP (otherwise 31415).
.TP
\fB\-h\fP
Print a brief help message.
.TP
\fB\-N\fP \fInode\fP
Use this node name, rather than the \fIswitch\fP name.
In same cases the switch might not be in DNS, so we may use the
management IP address (from RFC 1918 space), but give it a
sane name on PEG.
.TP
\fB\-n\fP
Don't send any updates to PEG, but show what would be send.
.TP
\fB\-p\fP \fIdelay\fP
Update persistantly, about every \fIdelay\fP seconds.
.TP
\fB\-V\fP
Output only the standard version information.
.TP
\fB\-x\fP
Trace updates on \fIstderr\fP.

.SH EXAMPLES
This  program is usually driven from \fBcron\fP(8), or started for
a single local switch at system boot.
.TP
/usr/local/libexec/pollcsm \-D \-c public MEMI2Crzmd01.dark MEMI2Crzmd02.dark
Output the list of VIP and reals that the CSM fail-over pair
in the dark domain know about.  These depend on reverse DNS a lot.
.TP
/usr/local/libexec/pollcsm \-p 75 \-c public MEMI2Crzmd01.dark MEMI2Crzmd02.dark
Poll the local darm CSMs for status and send it to PEG every 75 seconds.

.SH BUGS
One needs to know an SNMP read-only community string to sample each
CSM, local policy must allow that access.  The code assumes a lot
about reverse DNS mapping IP's back to hostnames.  You'll have to read it
to figure it all out, I bet.
.P
You should be able to specify \fIdomain\fP for each vip, at least.

.SH AUTHORS
Kevin Braunsdorf, NPC Guild with help from other NPCs
.br
peg within-no-spamming_hat ksb.npcguild.org

.SH "SEE ALSO"
sh(1), rrdup(1l), pollcisco(8l), pollcsm(8l)