Return to dhcping.pod CVS log

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

dhcping

    1: #
    2: # $Id: dhcping.pod,v 1.1.1.1 2012/02/21 22:27:53 misho 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)