Annotation of embedaddon/dhcping/dhcping.pod, revision 1.1
1.1 ! misho 1: #
! 2: # $Id: dhcping.pod,v 1.1 2002/01/27 01:57:15 mavetju Exp $
! 3: #
! 4:
! 5: =head1 NAME
! 6:
! 7: B<dhcping> - send a DHCP request to DHCP server to see if it's up and running
! 8:
! 9: =head1 SYNOPSIS
! 10:
! 11: B<dhcping>
! 12: [B<-v>] [B<-q>] [B<-i>] [B<-r>]
! 13: B<-t> I<maxwait>
! 14: B<-c> I<client-IP-address>
! 15: B<-s> I<server-IP-address>
! 16: B<-h> I<client-hardware-address>
! 17: [B<-g> I<gateway-IP-address>]
! 18:
! 19: =head1 DESCRIPTION
! 20:
! 21: This command allows the system administrator to check if a remote
! 22: DHCP server is still functioning.
! 23:
! 24: Options are:
! 25:
! 26: =over
! 27:
! 28: =item B<-v>
! 29:
! 30: Verbose, print some information.
! 31:
! 32: =item B<-i>
! 33:
! 34: Use DHCPINFORM packets.
! 35:
! 36: =item B<-r>
! 37:
! 38: Use DHCPREQUEST packets (default behaviour).
! 39:
! 40: =item B<-q>
! 41:
! 42: Quiet, print nothing on the screen.
! 43:
! 44: =item B<-t> I<maxwait>
! 45:
! 46: Maximum time to wait for an answer from the server in seconds.
! 47: Default is 3 seconds.
! 48:
! 49: =item B<-c> I<client-IP-address>
! 50:
! 51: Request this IP address. Note that this is also the IP address the
! 52: answer will be sent to.
! 53:
! 54: =item B<-s> I<server-IP-address>
! 55:
! 56: Send the DHCP packet to this IP address.
! 57:
! 58: =item B<-h> I<client-hardware-address>
! 59:
! 60: Use this hardware-address in the DHCP request. It can be up to
! 61: sixteen octets seperated by colons (i.e. 01:02:03:04)
! 62:
! 63: =item B<-g> I<gateway-IP-address>
! 64:
! 65: Use this IP address for the gateway IP address in the DHCP packet.
! 66: This option is currently broken.
! 67:
! 68: =back
! 69:
! 70: =head1 RETURN VALUES
! 71:
! 72: If everything goes okay, it returns 0. If there went something
! 73: wrong, it returns 1.
! 74:
! 75: =head1 SETUP
! 76:
! 77: This program should be installed setuid root or ran by root only.
! 78: See SECURITY for more information.
! 79:
! 80: On your DHCP server, add these lines to the dhcpd.conf:
! 81:
! 82: host <your monitoring host FQDN> {
! 83: hardware ethernet <your monitor host mac address>;
! 84: fixed-address <your monitoring host IP address>;
! 85: }
! 86:
! 87: Then try it:
! 88:
! 89: $ dhcping -c I<your monitoring host IP address> \
! 90: -s I<your DHCP server IP address> \
! 91: -h I<your monitor host mac address>
! 92:
! 93: It will either respond with "no answer" or "Got answer from: I<your
! 94: DHCP server IP address>"
! 95:
! 96: The DHCP server logfile will give:
! 97: S<DHCPREQUEST for 192.168.1.1 from 00:20:18:56:29:8f via ed0>
! 98: S<DHCPACK on 192.168.1.1 to 00:20:18:56:29:8f via ed0>
! 99: S<DHCPRELEASE of 192.168.1.1 from 00:20:18:56:29:8f via ed0 (found)>
! 100:
! 101: Running in DHCPINFORM mode with B<-i>:
! 102:
! 103: If you see "DHCPINFORM from 192.168.1.1 via xl0: not authoritative
! 104: for subnet 192.168.1.0", you should add the authoritative statement
! 105: to the subnet, See dhcpd.conf(5) for details.
! 106:
! 107: When running in very verbose mode, B<dhcping> tries to dump all
! 108: data of the send and received DHCP packets. It will first dump the
! 109: packet in hex-format, then decodes the header and finally the
! 110: options.
! 111:
! 112: =head1 HOW IT WORKS
! 113:
! 114: The client either sends a DHCPREQUEST or DHCPINFORM packet to the
! 115: server and waits for an answer. Then, if a DHCPREQUEST was send,
! 116: it will send a DHCPRELEASE back to the server.
! 117:
! 118: =head1 SECURITY
! 119:
! 120: This program is installed setuid root as it requires the privileges
! 121: to bind itself to port 68 (bootpc). Root privileges are dropped as
! 122: soon as the program has bound itself to that port.
! 123:
! 124: =head1 BUGS
! 125:
! 126: Currently (this may, or may not, change in the future) the ISC DHCP
! 127: daemon does not write leases with a fixed IP address in the
! 128: dhcpd.leases file.
! 129:
! 130: DHCPINFORM packets can only be used on subnets the server is authori-
! 131: tative for. If the monitoring script runs on a subnet the server
! 132: isn't authoritative for, it should use the DHCPREQUEST packets. I
! 133: also experienced some problems with ISC DHCPD v2 servers, but that
! 134: is also in the README of it.
! 135:
! 136: The B<-V> option is still working, but shouldn't be used for
! 137: debugging of the packets. Better use dhcpdump(8) for that, which
! 138: is available on my website. I wanted to remove it, but decided only
! 139: to do it from the documentation, not from the code. Maybe I'll need
! 140: it one day for debugging.
! 141:
! 142: =head1 AUTHOR
! 143:
! 144: Edwin Groothuis, edwin@mavetju.org (http://www.mavetju.org)
! 145:
! 146: =head1 SEE ALSO
! 147:
! 148: dhcpd(8), dhclient(8), dhcpd.conf(5), dhcpdump(8)
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>