.\" $Id: haveip.man,v 1.17 2012/10/31 15:33:44 ksb Exp $
.\" by KS Braunsdorf
.\" $Compile: Display%h
.\" $Display: ${groff:-groff} -Tascii -man %f | ${PAGER:-less}
.\" $Display(*): ${groff:-groff} -T%s -man %f
.\" $Install: %b -mDeinstall %o %f && cp %f $DESTDIR/usr/local/man/man1/haveip.1
.\" $Deinstall: ${rm-rm} -f $DESTDIR/usr/local/man/[cm]a[nt]1/haveip.1*
.TH HAVEIP 1 LOCAL
.SH NAME
haveip - boolean operations on our local IP configuration
.SH SYNOPSIS
.ds PN "haveip
\fI\*(PN\fP \fIround-robins\fP
.br
\fI\*(PN\fP \fB\-h\fP
.br
\fI\*(PN\fP \fB\-V\fP

.SH DESCRIPTION
When a shell program needs to check for a host's membership in a
DNS record it should check the exit code from \fI\*(PN\fP.
This utility is specifically designed to allow a task scheduled
on many hosts to only take action on those listed (in DNS) as
\*(lqin service\*(rq.

.P
To meet \fI\*(PN\fP's criteria a host must present at least one IP address
from each \fIround-robin\fP presented on the command line.
That is to say some network interface on the host must offer at
least one IP from each record (that is respond to IP traffic, no port
access is checked).

.P
One of the intended uses of \fI\*(PN\fP is to facilitate distributed job
scheduling.  There are cases when an application runs across many hosts,
and a particular \fBcron\fP task must run on each of those host (on all
hosts where the application is currently active).
So the \fBcron\fP table entry conditionally runs the job when
\fI\*(PN\fP approves the DNS round-robin.
The script may also check for a running listener with \fBpgrep\fP(1) and
\fBlsof\fP(1), as a safety feature.

.SH OPTIONS
.TP
\fB\-h\fP
Print a brief help message.
.TP
\fB\-V\fP
Show only the program's version information.

.SH EXAMPLES
.TP
.nf
\fI\*(PN\fP \fB\-h\fP
.fi
The standard help output is the only output.
.TP
.nf
\fI\*(PN\fP 127.0.0.1 && echo OK
.fi
Assuming that the IPv4 \fIlocalhost\fP loop-back address is
configured on \fIlo0\fP, this should \fBecho\fP(1) \*(lqOK\*(rq.
.TP
.nf
\fI\*(PN\fP 255.255.255.255 && echo impossible
.fi
Assuming the rules for a broadcast address are the way I
learned them this should never output \*(lqimpossible\*(rq.
.TP
.nf
\fI\*(PN\fP www.example.com backup.example.com && \fIgoFor...\fP
.fi
Runs the \fIgoFor...\fP command only when we are included
in \fBboth\fP \*(lqwww.example.com\*(rq and \*(lqbackup.example.com\*(rq.
.TP
.nf
\fI\*(PN\fP master.example.com || \fBrsync\fP \-arSH master.example.com::\fI...\fP
.fi
Runs an \fBrsync\fP(1) command to copy data from the \*(lqmaster\*(rq service
if we are \fBnot\fP the provider of that service.  There could be many
mirrors that are not the master.
.TP
.nf
1 5 * * * /usr/local/bin/haveip appcron.example.com && /opt/app/scripts/run-cron\fI
.fi
Example of a \fBcron\fP table entry that runs at 1 minute past 5 AM every day
and runs the /opt/app/scripts/run-cron command only on a host where \fI\*(PN\fP
returns success.
.TP
.nf
1 5 * * * /usr/local/bin/haveip appcron.example.com && mk \-smRun \-d5AM /opt/app/lib/cron.mk\fI
.fi
Same as the above, but factor the actual command to run out into a marked
file, as used by \fBmk\fP.  The means we don't have to update the
\fIcrontab\fP when the script to run changes parameters or location
(as long as the rules file's location doesn't change).
.TP
The marked file might contain something like:
.nf
$Run(*): /opt/app/scripts/run-cron \-C purge.cf \-B %d \fI...\fP
$Run: /opt/app/scripts/run-cron \-C purge.cf
.fi

.SH BUGS
We do not check for the multicast range, or
process CIDR notation on the command line.
.P
It is not really possible to check for another host directly, as we cannot
see their network interfaces.
.P
Doesn't know about SRV records.  That's another program to write.

.SH AUTHOR
.nf
Alex Docauer \- alex dot docauer at gmail.com.spam.not
KS Braunsdorf \- haveip at ksb.npcguild.org.nospan
.fi

.SH "SEE ALSO"
.hlm 0
sh(1), host(1), ifconfig(8), cron(8), crontab(1), rsync(1), pgrep(1),
mk(1l)