/ 
Net-DHCP-0.52
River stage one • 1 direct dependent • 2 total dependents
/ Net::DHCP::Packet

NAME

Net::DHCP::Packet - Object methods to create a DHCP packet.

SYNOPSIS

use Net::DHCP::Packet;

my $p = new Net::DHCP::Packet->new(
     'Chaddr' => '000BCDEF', 
     'Xid' => 0x9F0FD,
     'Ciaddr' => '0.0.0.0',
     'Siaddr' => '0.0.0.0', 'Hops' => 0);

DESCRIPTION

Represents a DHCP packet as specified in RFC 1533, RFC 2132.

CONSTRUCTOR

This module only provides basic constructor. For "easy" constructors, you can use the Net::DHCP::Session module.

new ( BUFFER )
new ( [%ARGS] )

Creates an Net::DHCP::Packet object, which can be used to send or receive DHCP network packets. BOOTP is not supported.

Without argument, a default empty packet is created.

$packet = Net::DHCP::Packet();

A BUFFER argument is interpreted as a binary buffer like one provided by the socket recv() function. if the packet is malformed, a fatal error is issued.

use IO::Socket::INET;
use Net::DHCP::Packet;

$sock = IO::Socket::INET->new(LocalPort => 67, Proto => "udp", Broadcast => 1)
        or die "socket: $@";
        
while ($sock->recv($newmsg, 1024)) {
    $packet = Net::DHCP::Packet->new($newmsg);
    print $packet->toString();
}

To create a fresh new packet new takes arguments as a key-value pairs :

ARGUMENT   FIELD      OCTETS       DESCRIPTION
--------   -----      ------       -----------

Op         op            1  Message op code / message type.
                            1 = BOOTREQUEST, 2 = BOOTREPLY
Htype      htype         1  Hardware address type, see ARP section in "Assigned
                            Numbers" RFC; e.g., '1' = 10mb ethernet.
Hlen       hlen          1  Hardware address length (e.g.  '6' for 10mb
                            ethernet).
Hops       hops          1  Client sets to zero, optionally used by relay agents
                            when booting via a relay agent.
Xid        xid           4  Transaction ID, a random number chosen by the
                            client, used by the client and server to associate
                            messages and responses between a client and a
                            server.
Secs       secs          2  Filled in by client, seconds elapsed since client
                            began address acquisition or renewal process.
Flags      flags         2  Flags (see figure 2).
Ciaddr     ciaddr        4  Client IP address; only filled in if client is in
                            BOUND, RENEW or REBINDING state and can respond
                            to ARP requests.
Yiaddr     yiaddr        4  'your' (client) IP address.
Siaddr     siaddr        4  IP address of next server to use in bootstrap;
                            returned in DHCPOFFER, DHCPACK by server.
Giaddr     giaddr        4  Relay agent IP address, used in booting via a
                            relay agent.
Chaddr     chaddr       16  Client hardware address.
Sname      sname        64  Optional server host name, null terminated string.
File       file        128  Boot file name, null terminated string; "generic"
                            name or null in DHCPDISCOVER, fully qualified
                            directory-path name in DHCPOFFER.
IsDhcp     isDhcp        4  Controls whether the packet is BOOTP or DHCP.
                            DHCP conatains the "magic cookie" of 4 bytes.
                            0x63 0x82 0x53 0x63.
DHO_* code                  Optional parameters field.  See the options
                            documents for a list of defined options.
                            See Net::DHCP::Constants.
Padding    padding       *  Optional padding at the end of the packet

See below methods for values and syntax descrption.

METHODS

ATTRIBUTE METHODS

op ( [BYTE] )

Sets/gets the BOOTP opcode.

Normal values are: BOOTREQUEST() BOOTREPLY()

htype ( [BYTE] )

Sets/gets the hardware address type.

Common value is: HTYPE_ETHER() (1) = ethernet

hlen ( [BYTE] )

Sets/gets the hardware address length. Value must be between 0 and 16.

For most NIC's, the MAC address has 6 bytes.

hops ( [BYTE] )

Sets/gets the number of hops.

This field is incremented by each encountered DHCP relay agent.

xid ( [INTEGER] )

Sets/gets the 32 bits transaction id.

secs ( [SHORT] )

Sets/gets the 16 bits elapsed boot time in seconds.

flags ( [SHORT] )

Sets/gets the 16 bits flags.

0x8000 = Broadcast reply requested.
ciaddr ( [STRING])

Sets/gets the client IP address.

IP address is only accepted as a string like '10.24.50.3'.

yiaddr ( [STRING] )

Sets/gets the your IP address.

IP address is only accepted as a string like '10.24.50.3'.

siaddr ( [STRING] )

Sets/gets the next server IP address.

IP address is only accepted as a string like '10.24.50.3'.

giaddr ( [STRING] )

Sets/gets the relay agent IP address.

IP address is only accepted as a string like '10.24.50.3'.

chaddr ( [STRING] )

Sets/gets the client hardware address. Its length is given by the hlen attribute.

Valude is formatted as an Hexadecimal string representation.

Example: "0010A706DFFF" for 6 bytes mac address.

Note : internal format is packed bytes string.

sname ( [STRING] )

Sets/gets the "server host name". Maximum size is 63 bytes. If greater a warning is issued.

Note : internal format is null terminated string.

file ( [STRING] )

Sets/gets the "boot file name". Maximum size is 127 bytes. If greater a warning is issued.

Note : internal format is null terminated string.

isDhcp ( [BOOLEAN] )

Sets/gets the DHCP cookie. Returns whether the cookie is valid or not, hence whether the packet is DHCP or BOOTP.

Default value is 1, valid DHCP cookie.

padding ( [BYTES] )

Sets/gets the optional padding at the end of the DHCP packet, i.e. after DHCP options.

addOption ( CODE, VALUE )

Adds a DHCP option field. Common code values are listed in Net::DHCP::Constants DHO_*.

Warning: values must be in packed binary format, depending on the code value, as described in RFC 2132. No control is done.

$packet = new Net::DHCP::Packet->new();
$packet->addOption(DHO_DHCP_MESSAGE_TYPE(), DHCPINFORM());
$packet->addOption(DHO_NAME_SERVERS(), packinets("10.0.0.1 10.0.0.2"));
getOption ($type)

Returns the value of a DHCP option.

Warning: values are returned as packed binary strings, as described if RFC 2132.

SERIALIZATION METHODS

serialize ()

Converts a Net::DHCP::Packet to a string, ready to put on the network.

marshall ( BYTES )

The inverse of serialize. Converts a string, presumably a received UDP packet, into a Net::DHCP::Packet.

If the packet is malformed, a fatal error is produced.

HELPER METHODS

toString ()

Returns a textual representation of the packet, for debugging.

packinet ( STRING )

Transforms a IP address "xx.xx.xx.xx" into a packed 4 bytes string.

These are simple never failing versions of inet_ntoa and inet_aton.

packinets ( STRING )

Transforms a list of space delimited IP addresses into a packed bytes string.

unpackinet ( STRING )

Transforms a packed bytes IP address into a "xx.xx.xx.xx" string.

unpackinets ( STRING )

Transforms a packed bytes liste of IP addresses into a list of "xx.xx.xx.xx" space delimited string.

EXAMPLES

Sending a simple DHCP packet:

#!/usr/bin/perl
# Simple DHCP client - sending a broadcasted DHCP Discover request

use IO::Socket::INET;
use Net::DHCP::Packet;
use Net::DHCP::Constants;

# creat DHCP Packet
$discover = Net::DHCP::Packet->new(
                      op => BOOTREQUEST(),
                      xid => int(rand(0xFFFFFFFF)), # random xid
                      Flags => 0x8000,              # ask for broadcast answer
                      DHO_DHCP_MESSAGE_TYPE() => DHCPDISCOVER()
                      );

# send packet
$handle = IO::Socket::INET->new(Proto => 'udp',
                                Broadcast => 1,
                                PeerPort => '67',
                                LocalPort => '68',
                                PeerAddr => '255.255.255.255')
              or die "socket: $@";     # yes, it uses $@ here
$handle->send($discover->serialize())
              or die "Error sending broadcast inform:$!\n";

Sniffing DHCP packets.

#!/usr/bin/perl
# Simple DHCP server - listen to DHCP packets and print them

use IO::Socket::INET;
use Net::DHCP::Packet;
$sock = IO::Socket::INET->new(LocalPort => 67, Proto => "udp", Broadcast => 1)
        or die "socket: $@";
while ($sock->recv($newmsg, 1024)) {
        $packet = Net::DHCP::Packet->new($newmsg);
        print $packet->toString();
}

AUTHOR

Stephan Hadinger <shadinger@cpan.org>. Original version by F. van Dun.

BUGS

I only ran some simple tests on Windows 2000 with a W2K DHCP server and a USR DHCP server. Not yet tested on Unix platform.

COPYRIGHT

This is free software. It can be distributed and/or modified under the same terms as Perl itself.

SEE ALSO

Net::DHCP::Options, Net::DHCP::Constants.