Scroll to navigation

DHCP_PROBE(8) System Manager's Manual DHCP_PROBE(8)

NAME

dhcp_probe - locate DCHP and BootP servers on a directly-attached network

SYNOPSIS

dhcp_probe[-cconfig_file][-ddebuglevel][-f][-h][-llog_file][-ocapture_file][-ppid_file][-Qvlan_id][-scapture_bufsize][-T][-v][-wcwd]interface_name

DESCRIPTION

dhcp_probeattempts to discover DHCP and BootP servers on a directly-attached Ethernet network.A network administrator can use this tool to locate unauthorized DHCP and BootP servers.

The program must be run with root privilege.

The program periodically broadcasts a number of DHCP and BootP request packets out a singlephysical interface.Several different kinds of request packets are sent, as a DHCP or BootPserver may only respond to certain requests, depending on the server'sconfiguration.Essentially,dhcp_probemimics a BootP or DHCP client in a variety ofpossible states, attempting to provoke responses from servers.

After sending each request packet,dhcp_probelistens for responses.After filtering out responses that do not appear to be in response to the probe,and responses from known DHCP and BootP servers (identified by their IP source addressesand optionally by their Ethernet source addresses),it logs any responses from unknown servers.

Optionally, responses from unknown servers may also be written toa packet capture file.

Optionally, an external program may be called each time a responsefrom an unknown server is received.

dhcp_probemay not be able tolocate all DHCP and BootP servers; seeLIMITATIONS below.

As DHCP broadcasts do not ordinarily cross IP routers,dhcp_probewill locate only servers that are attached to the samephysical network as the interface specified on the command line.Although BootP Relay Agents running on this network may helpthe broadcasts cross IP routers, these agents typically are configured toconvert the broadcasts to unicasts directed to only the well-knownDHCP or BootP servers located on other physical networks.As a result, BootP Relay Agents will allow your the servers toreceive the requests issued bydhcp_probe,but will not causeremote unknown servers to hear these requests.Therefore, if you have multiple physical networks, you may wishto rundhcp_probeon each of these networks to discoverunknown DHCP and BootP servers on each of them.

dhcp_probefunctions on a single Ethernet interface specified on thecommand line; it does not listen on multiple interfaces.However, if the host has multiple physical interfaces, you may run aninstance ofdhcp_probeon each interface.If your physical interface supports 802.1Q, you can use that tocreate a logical interface on each VLAN, then run an instanceof dhcp_probe on each logical interface.

dhcp_probe is intended for use by a network administrator.Before running dhcp_probe on any network other than one for which you are responsible,contact that network's administrator to learn if it is acceptable for youto run this software on that network.Running this software may violateon a network where you don't have permission to do so may violate thatnetwork's acceptable use policy.

AVAILABILITY

dhcp_probeis a product of the Network Systems Group atPrinceton University's Office ofInformation Technology,and is available fromhttp://www.net.princeton.edu/software/dhcp_probe/

Presently the product builds and runs on Solaris 9 on SPARC with gcc.The program relies on thepcap(3)andlibnet(3)libraries.

OPTIONS

Specifies the configuration file.If not specified, this defaults to/etc/dhcp_probe.cf.The configuration file is read at startup, and is re-readwhenever a SIGHUP is received.Seedhcp_probe.cf(5).
Sets thedebuglevelvariable that controls the amount of debugging messages generated.If not specified, this defaults to 0 (no debugging).For a summary of the types of messages produced at eachdebug level, see DEBUG LEVELS below.
Specifies that the program should not fork, but insteadremain in the foreground.Only use this when you are starting the program manually fortesting purposes.When in the foreground, any messages produced by the programare written tostderrinstead of tosyslog(3)or anylog_fileyou might specify with the-loption.
Display a brief usage summary, then exit.
Log messages to the specified file instead of tosyslog(3).(This option is ignored if you also specify the-foption, as that directs messages tostderr.)The log file is opened shortly after the program starts.It is closed and re-opened when the program receivesa SIGUSR1 signal.
When a response packet is received from an unexpected server,write the packet to the specified file.The file is opened and truncated shortly after the program starts.It is closed and re-opened (and truncated) when the programreceives a SIGUSR2 signal.The file is apcap(3)savefile, and may be read with any programthat understands the pcap savefile format; e.g.tcpdump(1).
Specifies the file that will contain the program's processid.If not specified, this defaults to/var/run/dhcp_probe.pid.Thepid_fileis written shortly after the program starts, and is removedwhen the program exits under its own control.
Specifies that the packets we send should be tagged withan 802.1Q VLAN ID vlan_id.Valid values range from 0 to 4095.If not specified, the packets we send do not containan 802.1Q header.
Specifies the size of the buffer that will be used tocapture all the responses (Ethernet frames) to a single request packet;responses which do not fit are silently dropped.The value is specified in bytes, and must fit into your host'srange for anint;values outside that range may result in unpredictable results.If not specified, this defaults to 30280, which is enoughfor twenty maximum-size Ethernet frames (1514*20).Typical responses are Ethernet frames ranging from 342-590 bytes, so thedefault capture buffer size should hold over 50 of them.
Enables the 'socket receive timeout' feature.On some platforms, dhcp_probe may ignore theresponse_wait_time(described indhcp_probe.cf(5)),instead waiting forever for a responseafter it sends a probe packet.As perpcap(3),this is because the read timeout we pass to pcap_open_live()is not supported on all platforms.If you encounter this issue, try enabling our 'socket receive timeout' feature;it might help.Enabling this feature causes the program to also set a socket receivetimeout on the socket underlying the pcap capture; we set this timeout to theresponse_wait_time.On some platforms, the program's socket receive timeout feature does not work;instead the program will report that it cannot set the receive timeout,and will exit.
Display the program's version number, then exit.
Specifies the working directory; shortly after starting theprogram changes its current working directory to this.If not specified, this defaults to/.
Specifies the name of the interface the program should use;this argument is required.This must be an Ethernet interface which is up and has been assignedan IP address.

OPERATION

After initialization, the program enters its main event loop,in which it remains until you signal the program to exitwith a SIGINT, SIGTERM, or SIGQUIT.

The main event loop (a.k.a. the "probe cycle")consists of the following actions, repeated untilthe program receives a request to quit:

1.
Handle any signals that have been received.
2.
Install apcap(3)filter to listen for UDP packets destined to the BootP client port(UDP port 68).
3.
Broadcast a DHCP or BootP request packet out the specified interface.
4.
Listen forresponse_wait_timemilliseconds for any responses received by thepcap(3)filter.(Theresponse_wait_timedefaults to 5000 milliseconds (5 seconds), and may be changed in thedhcp_probe.cf(5)file.)

Any responses that contains a bootp_chaddr field not equal to thechaddr used in the probe is ignored, as are any that haveincorrect bootp_htype or bootp_hlen fields.These are not responses to our probe.

Any responses from known DHCP and BootP servers are ignored.The IP source address for responses from each known server is declared using alegal_serverstatement in thedhcp_probe.cf(5)file.Any response with an IP source address that does not appear in alegal_serverstatement is treated as an unknown server.

The Ethernet source address for responses from each known server is alsooptionaly declared using alegal_server_ethersrcstatement in thedhcp_probe.cf(5)file.If at least onelegal_server_ethersrcis specified, then any response with an Ethernet source addressthat does not appear in alegal_server_ethersrcstatement is treated as an unknown server.If nolegal_server_ethersrcstatements appear, then the response's Ethernet source address is not checked.(Thelegal_server_ethersrcstatement is considered experimental in version 1.3.0,as it has received only limited testing.)

For each response from an unknown server:

If the reponse packet contains a non-zeroyiaddrfield, and one or morelease_network_of_concernstatements were specified,determine if theyiaddrvalue falls within any of the "Lease Networks of Concern".
Log a message showing the response packet's source IP and Ethernet addresses.If the response packet's yiaddr is non-zero and falls within a "Lease Networks of Concern",the log message also reports that.
If the-ooption was specified, the packet is also written to a packet capture file.
If analert_program_namewas specified in thedhcp_probe.cf(5)file,that program is executed, with the following arguments in order:the name of the calling program (e.g.dhcp_probe),the name of the interface on which the unexpected response packet was received,the IP source address of the packet,and the Ethernet source address of the packet.(We do not wait for thealert_program_nameto complete; it runs in a child process.)
If analert_program_name2was specified in thedhcp_probe.cf(5)file,that program is executed, with the following required options: 


   -p the name of the calling program (e.g. dhcp_probe)


   -I the name of the interface on which the unexpected response packet was received


   -i the IP source address of the packet


   -m and the Ethernet source address of the packet
If the response packet's yiaddr is non-zero and falls within a "Lease Networks of Concern",the following optional options are also passed: 


   -y the non-zero yiaddr value
(We do not wait for thealert_program_name2to complete; it runs in a child process.)
5.
Remove thepcap(3)filter installed earlier.
6.
If any signals have arrived requesting that we quit, exit gracefully.
7.
Repeat steps 2-6 for each flavor of DHCP and BootP request packet theprogram supports (see PACKET FLAVORS below).
8.
Handle any signals that have been received.
9.
Sleep forcycle_timeseconds.(Thecycle_timedefaults to 300 seconds, andand may be changed in thedhcp_probe.cf(5)file.)

Thepcap(3)filter the program installs normally does not specify that the interface should beplaced into promiscuous mode (although it is possible the interface is already in promiscuousmode for some other reason).However, if in thedhcp_probe.cf(5)file you specify achaddrorether_srcvalue other than the interface's actual hardware address,then the pcap filterwillspecify that the interface should be placed into promiscuous mode.

Although the filter used withpcap(3)specifies only UDP packets destined to portbootpcshould be collected,on systems wherebpfisn't part of the kernel,pcap(3)must implementbpfas part of the application.This can increase the number of packets that must be passed fromthe kernel to user space to be filtered.The program attempts to minimize the side-effects of this byremoving thepcap(3)filter when it isn't actually listening for responses.In particular, the filter is not installed during the time theprogram sleeps between each probe cycle(thecycle_time).

If you do specify analert_program_name,take care that the program you specify is safe for a privilegeduser to run; it is executed with the same (i.e. root) privileges asthe calling program.

PACKET FLAVORS

No single request packet is likely to provoke a responsefrom every possible BootP and DHCP server.Some servers may only response to either BootP, or DHCP, butnot both.Some servers may be configured to only respond to a smallset of known clients.Some DHCP servers will only provide leases to a smallset of known clients, but may be willing to respond(negatively) to unknown clients thatrequest a lease renewal on an inappropriate IP address.Therefore,dhcp_probeactually sends not one, but five differentflavor request packets, in the hopes of provoking responsesfrom a wider variety of unknown servers.

The packet flavors are:

This packet is typical of a BootP client requesting an IP address.

It will typically provoke a BOOTPREPLY from a BootP server willing torespond to any BootP client.(BootP servers configured to only respond to a set of known clientsmay not respond.)

This packet is typical of a DHCP client in the INIT state.

The options field contains a DHCP Message Type specifying DHCPDISCOVER.

The options field contains a DHCP Client Identifier, which is computedby prepending 0x'01' to the value ofchaddr.(The valuechaddris specified in thedhcp_probe.cf(5)file, otherwise it defaults to the interface's Ethernet address.)

This packet will typically provoke a DHCPOFFER from a DHCP server willing torespond to any DHCP client.(DHCP servers configured to only offer leases to a set of known clientsmay not respond.)

This packet is typical of a DHCP client in the SELECTING state; i.e. a clientwhich has previously issued a DHCPDISCOVER, then received a DHCPOFFER fromsome DHCP server.

The options field contains a DHCP Message Type specifying DHCPREQUEST.

The options field contains a DHCP Client Identifier,which is computedby prepending 0x'01' to the value ofchaddr.(The valuechaddris specified in thedhcp_probe.cf(5)file, otherwise it defaults to the interface's Ethernet address.)

The options field contains a DHCP Server Identifier specifyingserver_id,which should be an IP address that does not correspond to any valid DHCP Server Identifieron your network.(The valueserver_idis specified in thedhcp_probe.cf(5)file, otherwise it defaults to 10.254.254.254.)

The options field contains a DHCP Requested IP Address specifyingclient_ip_address,which should be an IP address that does not correspond to any valid IP addresson your network.(The valueclient_ip_addressis specified in thedhcp_probe.cf(5)file, otherwise it defaults to 172.31.254.254.)

This packet occassionally provokes a response from a broken DHCP serverthat fails to respect the DHCP Server Identifier option.

This packet is typical of a DHCP client in the INIT-REBOOT state; i.e. a clientwhich has obtained a DHCP lease in the past, is bringing up its IP stack,and hopes to obtain (or extend) a DHCP lease on the same IP address as in the past.

The options field contains a DHCP Message Type specifying DHCPREQUEST.

The options field contains a DHCP Client Identifier,which is computedby prepending 0x'01' to the value ofchaddr.(The valuechaddris specified in thedhcp_probe.cf(5)file, otherwise it defaults to the interface's Ethernet address.)

The options field contains a DHCP Requested IP Address specifyingclient_ip_address,which should be an IP address that does not correspond to any valid IP addresson your network; ideally it should be one that is topologically inappropriatefor your network.(The valueclient_ip_addressis specified in thedhcp_probe.cf(5)file, otherwise it defaults to 172.31.254.254.)

If the Requested IP Address option is topologically inappropriate for your network,this packet may provoke a DHCPNAK from any DHCP server thatbelieves it is authoritative for the network's IP topology.

This packet is typical of a DHCP client in the REBINDING state; i.e. a clientwhich has obtained a DHCP lease which is between its DHCP T2 and expiration time.

The options field contains a DHCP Message Type specifying DHCPREQUEST.

The options field contains a DHCP Client Identifier,which is computedby prepending 0x'01' to the value ofchaddr.(The valuechaddris specified in thedhcp_probe.cf(5)file, otherwise it defaults to the interface's Ethernet address.)

The ciaddr field containsclient_ip_address,which should be an IP address that does not correspond to any valid IP addresson your network; ideally it should be one that is topologically inappropriatefor your network.(The valueclient_ip_addressis specified in thedhcp_probe.cf(5)file, otherwise it defaults to 172.31.254.254.)

If the value of ciaddr is topologically inappropriate for your network,this packet will provoke a DHCPNAK from any DHCP server thatbelieves it is authoritative for the network's IP topology.

All the request packets sent by the programshare the following common characteristics:

Ethernet Header

destination: ff:ff:ff:ff:ff:ff
source:ether_srcfromdhcp_probe.cf(5),else interface hardware address
type: ETHERTYPE_IP (0x0800)

IP Header

version: 4
header length: 5
tos: 0
total length: 328 (20-byte IP header + 8-byte UDP header + 300-byte BootP/DHCP payload)
identifier: 1
flags: 0
fragment offset: 0
ttl: 60
protocol: IPPROTO_UDP (17)
header checksum: (computed)
source address: 0.0.0.0
destination address: 255.255.255.255
options: (none)

UDP Header

source port: PORT_BOOTPC (68)
dest port: PORT_BOOTPS (67)
checksum: (computed)

BootP/DHCP Payload

op: BOOTREQUEST (1)
htype: HTYPE_ETHER (1)
hlen: HLEN_ETHER (6)
hops: 0
xid: 1
secs: 0
flags: 0
ciaddr: 0.0.0.0 (except for DHCPREQUEST (REBINDING) packets it isclient_ip_addressfromdhcp_probe.cf(5),else 172.31.254.254)
siaddr: 0.0.0.0
giaddr: 0.0.0.0
chaddr:chaddrfromdhcp_probe.cf(5),else interface hardware address
sname: (all 0's)
file: (all 0's)
options: RFC1048 cookie (0x63825363),possibly followed by DHCP options,followed by END option (0xFF),followed by PAD options (0x00) to bring the field to 64 bytes

MULTIPLE INTERFACES

Although dhcp_probe only supports monitoring a single physical interface,you may run an instance of the program on each physical interface;each monitors a different physical network.

When running multiple copies of dhcp_probe, be sure to specifya differentpid_filefor each instance.

If you specify alog_fileand/or acapture_file,be sure to specify a different one for each instance.

You may specify a differentconfig_filefor each instance.If you don't need to customize the settings in that file for eachinstance, you may usethe same configuration file for all instances.

If you have multiple logical interfaces on the same physicalinterface, or multiple logical IP networks running on a singlephysical network, there is no need to run multiple instancesof dhcp_probe to monitor each logical interfaces or logical network.A single instance of the program running on a physical interfaceis sufficient to provoke any servers on that physical networkthat might be willing to respond.

If your physical interface supports 802.1Q, you can use a singlephysical interface to monitor multiple VLANs.Use your operating system to create a logical interface on each VLAN,then run an instance of the program on each logical interface.Since the program is responsible for constructing Ethernet frame headers,you will probably need to specify the -Q option to instruct it toadd to outgoing frames an 802.1Q VLAN header with the appropriate VLAN ID.

SIGNALS

The program will respond to a number of signals:

If logging to a file, close and re-open it.If the program is in the middle of a probe cycle, handlingthe signal is deferred until the end of the cycle.(Has no effect if logging tosyslog(3)or if the-foption was specified.)
If capturing to a file, close and re-open it.If the program is in the middle of a probe cycle, handlingthe signal is deferred until the end of the cycle.(Has no effect if the-ooption was not specified.)

Because re-opening the capture file causes thefile to be truncated and a newpcap(3)header to bewritten to it, if you want to save theprior contents of the capture file, move the existingcapture file aside before sending the signal.

Reread the configuration file.If the program is in the middle of a probe cycle, handlingthe signal is deferred until the end of the cycle.
Exit gracefully.If the program is in the middle of a probe cycle, handlingthe signal is deferred until the program finishessending and receiving responses for the current flavorrequest packet.

LEASE NETWORKS OF CONCERN

Most rogue BootP/DHCP servers distribute private IP addresses toclients, or send DHCPNAK messages to legitimate clients.Some even more disruptive rogue BootP/DHCP servers may distribute IP addressesthat fall within your own networks' IP ranges.The "Lease Networks of Concern" feature is intended to help youidentify these particularly disruptive servers.

You may activate the feature by specifying thelease_network_of_concernstatement in your configuration file.Use the statement multiple times to specify all your legitimate network ranges.

When a rogue BootP/DHCP server is detected,if the rogue's response packet contains a non-zeroyiaddrvalue, the value is compared to the "Lease Networks of Concern" you specified.If the value falls within any of those network ranges, the messagelogged bydhcp_probeis extended to make note of this, and to report theyiaddrvalue.Furthermore, if you are using thealert_program_name2feature, the alert program is called with an extra-y yiaddroption so that alert program can take any additional action desired.

DEBUG LEVELS

The program produces increasingly detailed output as thedebuglevelincreases.Under normal circumstances, you can run atdebuglevel0.Here's roughly what messages are added at eachdebuglevel.

0
Display the IP source (and Ethernet source) of each unexpected DHCP or BootP response packet.

Startup and shutdown notice.

Non-fatal errors in the configuration file.

Fatal errors.

1
At startup, show some information about the program's configuration.
2
Show each time we start and finish (re-)reading the configuration file.

Show each time we close and re-open the logfile or capture file.

Report on response packets that could not be parsed (e.g. truncated).

3
Each time we (re-)read the configuration file, echo the information we obtain from it.
7
For each parsable response packet, show the Ethernet source and destination, the IP source and destination,and indicate when the IP source is a legal (known) server.
11
For each probe cycle, show when the cycle begins and ends, when we write a packet, andwhen we begin and end listening for response packets.

AUTHOR

The program was written by Irwin Tillmanof Princeton University's OIT Network Systems Group.It was written to run on Solaris,relying on the generally-availablepcap(3)andlibnet(3)libraries.

FILES

/etc/dhcp_probe.cf
Configuration file read by the program.Seedhcp_probe.cf(5).The name of this file can be overridden by a command-line option.
/etc/dhcp_probe.pid
Contains the program's processid.The name of this file can be overridden by a command-line option.

LIMITATIONS

dhcp_probeis not guaranteed to locate all unknown DHCP and BootPservers attached to a network.If a BootP server is configured so it only responds to certain clients(e.g. those with certain hardware addresses), it will not respondto the BOOTPREQUEST packet we sent.If a DHCP server is configured so it only responds to certain clients(e.g. those with certain hardware addresses or DHCP Client Identifiers),it will not respond to the packets we send that mimic DHCP clientsin the INIT state.If a DHCP server is configured so it does not send DHCPNAK packetsto clients requesting topologically-inappropriate IP addresses,it will not respond the packets we send that mimic DHCP clientsin the INIT-REBOOT and REBINDING states.

The upshot is thatit is possible thatdhcp_probewill be unable toprovoke some BootP and DHCP servers into responding at all.

Flushing out such servers can be extremely difficult.One approach is to capture all UDP/IP packet destined to the BootP clientport which cross your network; since most of these packets are unicast at Layer 2,capturing is only effective ifallsuch packets must pass by yourcapture device's Ethernet interface (e.g. the capture device islocated at a network choke point, or the networkdoes not involve any Layer 2 switching).Another approach is to do UDP port scanning for all deviceslistening on the BootP server port, and assume that thosewhich are listening on that port are running a BootP or DHCP server.

Malicious BootP or DHCP servers that forge the IP source address(and possibly the Ethernet source address) of their responsesto match the values specified bylegal_serverandlegal_server_ethersrcstatementswill not be detected.

BUGS

The packet capture buffer size is limited; if a single request packetprovokes more responses than will fit into the buffer, those that donot fit are silently dropped, without any diagnostic indicatingthat the buffer was too small.You can adjust the size of the packet capture buffer size using the-s capture_bufsizeoption.

We do not support non-Ethernet interfaces.

Because (re-)opening a packet capture file causes the file to be openedfor writing (not appending),the contents of any existing packet capture file of the same name is lost when theprogram starts or receives a SIGUSR2 signal.If the file's previous contents should be preserved, move the oldfile aside before starting the program or sending it a SIGUSR2 signal.(This "feature" exists because opening apcap(3)savefilealways involves writing a pcap header record to the start of the file, sopcap always opens the file using mode "w".)

Becausepcap(3)opens the packet capture file with a simplefopen(3)without checking to see if the file already exists, dhcp_probemay be tricked into overwriting or corrupting an existing file.As dhcp_probe is run with root privileges, this is a serious concern.To avoid this problem, if you use the-ooption, ensure that the directory thatwill contain the capture file is writable only by root.

The packet capture file that is written is unparseable afterthe first packet.E.g. if read withtcpdump(8),it reports:tcpdump: pcap_loop: truncated dump file.

On platforms wherepcap(3)is unable to support thetimeoutargument topcap_open_live,the program may not reliably detect responses from DHCP and BootP servers,or may not function at all.

SEE ALSO

dhcp_probe.cf(5)

pcap(3)
(a.k.a. libpcap, a packet capture library),available fromhttp://www.tcpdump.org.(An older version is available fromftp://ftp.ee.lbl.gov/libpcap.tar.Z.)
(a.k.a libwrite, a packet writing library),available fromhttp://www.packetfactory.net/libnet
Mar 9 2009 Princeton Univ.