.\" $Id: rrdisk.man,v 2.12 2012/02/29 18:45:36 ksb Exp $
.\" by Kevin Braunsdorf
.\" $Compile: Display%h
.\" $Display: ${groff-groff} -Tascii -tbl -man %f | ${PAGER:-less}
.\" $Install: %b -mDeinstall %o %f && cp %f $DESTDIR/usr/local/man/man8/rrdisk.8
.\" $Deinstall: ${rm-rm} -f $DESTDIR/usr/local/man/[cm]a[nt]8/rrdisk.8*
.TH RRDISK 8 LOCAL
.SH NAME
rrdisk - update remote RRD from local disk input/output statistics
.SH SYNOPSIS
.ds PN "rrdisk
\fI\*(PN\fP [\fB\-A\fP\fBU\fP\fBn\fP\fBp\fP\fBs\fP\fBv\fP] [\-\fIseconds\fP] [\fB\-g\fP\~\fIdiskgroup\fP] [[\fB\-m\fP\~\fImetamap\fP] [\fB\-N\fP\~\fIhostname\fP] [\fB\-t\fP\~\fItarget\fP] [\fB\-u\fP\~\fIpath\fP] [\fIdevices\fP]
.br
\fI\*(PN\fP \fB\-h\fP
.br
\fI\*(PN\fP \fB\-V\fP

.SH DESCRIPTION
Used to feed RRD data about our local disks or NFS mount points.

.PP
\fIRrdisk\fP's
standard input is replaced by a copy of either \fBiostat\fP or
\fBvxstat\fP.  This input is filtered and processed to produce
input for \fBrrdup\fP to monitor disks in near-real time.

.PP
The \fIdevices\fP parameters may be either an old-school device
(as under SunOS 4) or a new-school device name as reported
by \fBiostat\fP \fB\-xn\fP.  They each may be prefixed by a
virtual name to change the name \fBrrdup\fP will see in the
update path, as "\fIvirtual\fP=\fIdevice\fP".

.SH OPTIONS
If the program is called as \fI\*(PN\fP then no options are forced.
.TP
\fB\-\fIseconds\fP
Number of seconds between polls.  This parameter is passed directly to
\fBiostat\fP  or \fBvxstat\fP.  The two sample rates I use are
110 and 179; 110 is good for 5 minute slots, the 179 for 8 minute
slots in an RRD file.  \fIRrdisk\fP defaults to 179, which I think
might be a bug: do not depend on that.
.\" do you want 288 slots or 180 in the RRD file
.TP
\fB\-A\fP
Include all disks, even if an explict list is provided on the command line.
This allows some disks to be remapped, while others are passed "as is".
This used to be the default.
.TP
\fB\-U\fP
\fIRrdisk\fP trys to use \fBiostat\fP's \fB\-l\fP option to reduce
useless data sent from \fBiostat\fP; in some cases this tricks
\fBiostat\fP into sending the wrong drive's data (Solaris with
disk groups under DiskSuite, for example).  The result is that
you get the right number of disks, with some wrong names.
.TP
\fB\-g\fP \fIdiskgroup\fP
Use vxstat for Veritas io stats, for this group.  When you have more than
one disk group on the host you must run more than one copy of \fBrrdisk\fP.
.TP
\fB\-m\fP \fImetamap\fP
For Solaris DiskSuite'd devices in a \fIdisk group\fP the \fBiostat\fP
command expects the names of the disk to be prefixed with the name
of the disk group, but outputs the names with a small integer index
into the meta data.  \fIRrdisk\fP attepmts to  map these automatically,
but when that fails you can provie this options with a parameter
like \fInumber\fP=\fIname\fP.
.TP
\fB\-N\fP \fIhostname\fP
Use the given \fIhostname\fP for rrd updates,
rather than the one returned from
\fBgethostname\fP(2) and processed by whittle.
.TP
\fB\-h\fP
Print a help message.
.TP
\fB\-n\fP
Do not execute commands, trace only.  This removes the diversion of
standard out to a \fBrrdup\fP command.
.TP
\fB\-p\fP | \fB\-s\fP
Allow per-partition disk statistics (a.k.a. \-s under vxstat).
Normally \fBrrdisk\fP expects only the major device to be monitored.
Under AIX this actually does the opposite, is include the controllers
as "disk devices" that represent the sum of all the disks on the adapter
(see \fBiostat\fP \fB\-a\fP).
.TP
\fB\-P\fP
Under AIX include the whole host's as a "virtual adapter"
(see \fBiostat \-p\fP), on SunOS this passes an option to iostat you don't
want (most of the time).
.TP
\fB\-t\fP \fItarget\fP
RRD host to update, passed to \fBrrdup\fP.
By default "peg.sac.fedex.com:31415", provide the empty string ('') to
force the updates to \fIstdout\fP for diagnostics.
.TP
\fB\-u\fP \fIpath\fP
An update path, if the default is not what you want.  This \fIpath\fP
is passed to \fBprintf\fP to form the first parameter to
the \fIupdate\fP line given to \fBrrdup\fP.
.sp
The default template is either \*(lqhost/%s/d-%s.rrd\*(rq, or
\*(lqhost/%s/vx-%s.rrd\*(rq by default.  The frist \fB%s\fP is
filled in from the part of out hostname (\fB\-N\fP above), the second is the
name (or virtual name) of the disk (or slice) being reported.
.TP
\fB\-v\fP
Be verbose.
.TP
\fB\-V\fP
Show version information, including disk maps.  Prefix this with
the \fB\-g\fP option to see \fBvxstat\fP output, and \fB\-p\fP
for partition details.
.SH EXAMPLES
.TP
\fI\*(PN\fP
Send statistics about all our local devices to the RRD database.
This usually results in a lot of wasted (dropped) updates, and
doesn't report per partition information.
.TP
\fI\*(PN\fP \-p \-60
This sends even more verbose output every 1 minute.  Useful to
debug system hangs sometimes.
.TP
\fI\*(PN\fP \-p swap=c0t1d0s1 var=c0t0d0s6
Send information for our swap disk as a virtual disk "swap", and
the local \fB/var\fP filesystem as a virtual "var" partition.
.TP
\fI\*(PN\fP \-g ivdbdg \-s \-V
Display the available slices under the \fBVX\fP group "ivdbdg".
.TP
\fI\*(PN\fP \-m 1=sulaco \-s \-V | grep sulaco
Display the available slices under the disk group "sulaco".
.TP
\fI\*(PN\fP \-t '' \-p \-10
Display updates at 10 second intervals for all disks on this host.

.SH BUGS
The \fBvxstat\fP program buffers output for a \fIlong\fP time,
so updates to \fBVX\fP disks lag quite a bit.  Contacts are Veritas
claim this is fixed in the present (2004) VxVm patch.
.P
More seriously if you want to monitor an NFS mount point you
are going to have issues.  The "name" for an NFS device in the
kernel changes if one umounts it and re-mounts it.  So \fBrrdisk\fP's
mapping table (which it only builds once) will not contain the
new NFS name after a remount.  The automounter, of course, pretty much
precludes any usful NFS samples.
.P
In later versions of this program a summary of many devices might
be allowed for a virtual device (viz. swap=c0t0d0s1+c8t0d0s1).  So
do not use a literal plus (+) in a device name.

.SH AUTHOR
Kevin Braunsdorf
.br
rrdisk @ ksb.npcguild.org.nospam

.SH "SEE ALSO"
sh(1), vxstat(1), iostat(1), rrdup(1l), rrdtool(1l), rrdd(8l), rrufwd(8l)