The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
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.