Return to dhcping.pod CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / dhcping

Annotation of embedaddon/dhcping/dhcping.pod, revision 1.1.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)