GSP
Quick Navigator
Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages
Net::DHCP::Packet(3) User Contributed Perl Documentation Net::DHCP::Packet(3)

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

version 0.7

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

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

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

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 description.

Note: DHCP options are created in the same order as key-value pairs.

See Net::DHCP::Packet::Attributes

This section describes how to read or set DHCP options. Methods are given in two flavours : (i) text format with automatic type conversion, (ii) raw binary format.

Standard way of accessing options is through automatic type conversion, described in the "DHCP OPTION TYPES" section. Only a subset of types is supported, mainly those defined in rfc 2132.

Raw binary functions are provided for pure performance optimization, and for unsupported types manipulation.

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

Values are automatically converted according to their data types, depending on their format as defined by RFC 2132. Please see "DHCP OPTION TYPES" for supported options and corresponding formats.

If you need access to the raw binary values, please use addOptionRaw().

   $pac = Net::DHCP::Packet->new();
   $pac->addOption(DHO_DHCP_MESSAGE_TYPE(), DHCPINFORM());
   $pac->addOption(DHO_NAME_SERVERS(), "10.0.0.1", "10.0.0.2"));
Adds a DHCP sub-option field. Common code values are listed in "Net::DHCP::Constants" "SUBOPTION_"*.

Values are automatically converted according to their data types, depending on their format as defined by RFC 2132. Please see "DHCP OPTION TYPES" for supported options and corresponding formats.

If you need access to the raw binary values, please use addSubOptionRaw().

   $pac = Net::DHCP::Packet->new();
   # FIXME update examples
   $pac->addSubOption(DHO_DHCP_MESSAGE_TYPE(), DHCPINFORM());
   $pac->addSubOption(DHO_NAME_SERVERS(), "10.0.0.1", "10.0.0.2"));
Returns the value of a DHCP option.

Automatic type conversion is done according to their data types, as defined in RFC 2132. Please see "DHCP OPTION TYPES" for supported options and corresponding formats.

If you need access to the raw binary values, please use getOptionRaw().

Return value is either a string or an array, depending on the context.

  $ip  = $pac->getOptionValue(DHO_SUBNET_MASK());
  $ips = $pac->getOptionValue(DHO_NAME_SERVERS());
Adds a DHCP OPTION provided in packed binary format. Please see corresponding RFC for manual type conversion.

BOOLEAN indicates if options should be inserted in the order provided. Default is to sort options to work around known quirky clients. See "QUIRK WORK-AROUNDS"

Adds a DHCP SUB-OPTION provided in packed binary format. Please see corresponding RFC for manual type conversion.
Gets a DHCP OPTION provided in packed binary format. Please see corresponding RFC for manual type conversion.
Gets a DHCP SUB-OPTION provided in packed binary format. Please see corresponding RFC for manual type conversion.
This is an empty stub for now
This is an empty stub for now
Remove option from option list.
returns the packed Client-identifier (pass-through currently)

See <https://tools.ietf.org/html/rfc2132#section-9.14> See also <https://tools.ietf.org/html/rfc4361>

returns the unpacked clientid.

Decodes:
type 0 as a string
type 1 as a mac address (hex string)
everything is passed through

See <https://tools.ietf.org/html/rfc2132#section-9.14> See also <https://tools.ietf.org/html/rfc4361>

returns the packed sip server field (pass-through currently)
returns the unpacked sip server.

Decodes:
type 1 as an ipv4 address
everything is passed through

returns the packed Classless Static Route option built from a list of CIDR style address/mask combos
Not implemented, currently croaks.
Removed as of version 0.60. Please use addOptionRaw() instead.
Removed as of version 0.60. Please use getOptionRaw() instead.

This section describes supported option types (cf. RFC 2132).

For unsupported data types, please use getOptionRaw() and "addOptionRaw" to manipulate binary format directly.

Only supported for DHO_DHCP_MESSAGE_TYPE (053) option. Converts a integer to a single byte.

Option code for 'dhcp message' format:

  (053) DHO_DHCP_MESSAGE_TYPE

Example:

  $pac->addOptionValue(DHO_DHCP_MESSAGE_TYPE(), DHCPINFORM());
Pure string attribute, no type conversion.

Option codes for 'string' format:

  (012) DHO_HOST_NAME
  (014) DHO_MERIT_DUMP
  (015) DHO_DOMAIN_NAME
  (017) DHO_ROOT_PATH
  (018) DHO_EXTENSIONS_PATH
  (047) DHO_NETBIOS_SCOPE
  (056) DHO_DHCP_MESSAGE
  (060) DHO_VENDOR_CLASS_IDENTIFIER
  (062) DHO_NWIP_DOMAIN_NAME
  (064) DHO_NIS_DOMAIN
  (065) DHO_NIS_SERVER
  (066) DHO_TFTP_SERVER
  (067) DHO_BOOTFILE
  (086) DHO_NDS_TREE_NAME
  (098) DHO_USER_AUTHENTICATION_PROTOCOL

Example:

  $pac->addOptionValue(DHO_TFTP_SERVER(), "foobar");
Exactly one IP address, in dotted numerical format '192.168.1.1'.

Option codes for 'single ip address' format:

  (001) DHO_SUBNET_MASK
  (016) DHO_SWAP_SERVER
  (028) DHO_BROADCAST_ADDRESS
  (032) DHO_ROUTER_SOLICITATION_ADDRESS
  (050) DHO_DHCP_REQUESTED_ADDRESS
  (054) DHO_DHCP_SERVER_IDENTIFIER
  (118) DHO_SUBNET_SELECTION

Example:

  $pac->addOptionValue(DHO_SUBNET_MASK(), "255.255.255.0");
Any number of IP address, in dotted numerical format '192.168.1.1'. Empty value allowed.

Option codes for 'multiple ip addresses' format:

  (003) DHO_ROUTERS
  (004) DHO_TIME_SERVERS
  (005) DHO_NAME_SERVERS
  (006) DHO_DOMAIN_NAME_SERVERS
  (007) DHO_LOG_SERVERS
  (008) DHO_COOKIE_SERVERS
  (009) DHO_LPR_SERVERS
  (010) DHO_IMPRESS_SERVERS
  (011) DHO_RESOURCE_LOCATION_SERVERS
  (041) DHO_NIS_SERVERS
  (042) DHO_NTP_SERVERS
  (044) DHO_NETBIOS_NAME_SERVERS
  (045) DHO_NETBIOS_DD_SERVER
  (048) DHO_FONT_SERVERS
  (049) DHO_X_DISPLAY_MANAGER
  (068) DHO_MOBILE_IP_HOME_AGENT
  (069) DHO_SMTP_SERVER
  (070) DHO_POP3_SERVER
  (071) DHO_NNTP_SERVER
  (072) DHO_WWW_SERVER
  (073) DHO_FINGER_SERVER
  (074) DHO_IRC_SERVER
  (075) DHO_STREETTALK_SERVER
  (076) DHO_STDA_SERVER
  (085) DHO_NDS_SERVERS

Example:

  $pac->addOptionValue(DHO_NAME_SERVERS(), "10.0.0.11 192.168.1.10");
Even number of IP address, in dotted numerical format '192.168.1.1'. Empty value allowed.

Option codes for 'pairs of ip address' format:

  (021) DHO_POLICY_FILTER
  (033) DHO_STATIC_ROUTES

Example:

  $pac->addOptionValue(DHO_STATIC_ROUTES(), "10.0.0.1 192.168.1.254");
Numerical value in byte (8 bits), short (16 bits) or integer (32 bits) format.

Option codes for 'byte (8)' format:

  (019) DHO_IP_FORWARDING
  (020) DHO_NON_LOCAL_SOURCE_ROUTING
  (023) DHO_DEFAULT_IP_TTL
  (027) DHO_ALL_SUBNETS_LOCAL
  (029) DHO_PERFORM_MASK_DISCOVERY
  (030) DHO_MASK_SUPPLIER
  (031) DHO_ROUTER_DISCOVERY
  (034) DHO_TRAILER_ENCAPSULATION
  (036) DHO_IEEE802_3_ENCAPSULATION
  (037) DHO_DEFAULT_TCP_TTL
  (039) DHO_TCP_KEEPALIVE_GARBAGE
  (046) DHO_NETBIOS_NODE_TYPE
  (052) DHO_DHCP_OPTION_OVERLOAD
  (116) DHO_AUTO_CONFIGURE

Option codes for 'short (16)' format:

  (013) DHO_BOOT_SIZE
  (022) DHO_MAX_DGRAM_REASSEMBLY
  (026) DHO_INTERFACE_MTU
  (057) DHO_DHCP_MAX_MESSAGE_SIZE

Option codes for 'integer (32)' format:

  (002) DHO_TIME_OFFSET
  (024) DHO_PATH_MTU_AGING_TIMEOUT
  (035) DHO_ARP_CACHE_TIMEOUT
  (038) DHO_TCP_KEEPALIVE_INTERVAL
  (051) DHO_DHCP_LEASE_TIME
  (058) DHO_DHCP_RENEWAL_TIME
  (059) DHO_DHCP_REBINDING_TIME

Examples:

  $pac->addOptionValue(DHO_DHCP_OPTION_OVERLOAD(), 3);
  $pac->addOptionValue(DHO_INTERFACE_MTU(), 1500);
  $pac->addOptionValue(DHO_DHCP_RENEWAL_TIME(), 24*60*60);
A list a bytes or shorts.

Option codes for 'multiple bytes (8)' format:

  (055) DHO_DHCP_PARAMETER_REQUEST_LIST

Option codes for 'multiple shorts (16)' format:

  (025) DHO_PATH_MTU_PLATEAU_TABLE
  (117) DHO_NAME_SERVICE_SEARCH

Examples:

  $pac->addOptionValue(DHO_DHCP_PARAMETER_REQUEST_LIST(),  "1 3 6 12 15 28 42 72");

Converts a Net::DHCP::Packet to a string, ready to put on the network.
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.

Returns a textual representation of the packet, for debugging.
Transforms an list of lists into packed option. For option 43 (vendor specific), 82 (relay agent) etc.
Unpacks sub-options to a list of lists
By default, the level is set to 0. If the packet is shorter than the minimum "BOOTP_MIN_LEN", a warning is issued; if it is shorter than the absolute minimum "BOOTP_ABSOLUTE_MIN_LEN", an exception is thrown.

If the level is set to 1, even the absolute minimum just warns.

Setting the level to 2 means the packet length checks are skipped altogether.

Without a parameter, the method returns the current level.

See also Net::DHCP::Packet::IPv4Utils

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(
                        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 STDERR $packet->toString();
  }

Sending a LEASEQUERY (provided by John A. Murphy).

  #!/usr/bin/perl
  # Simple DHCP client - send a LeaseQuery (by IP) and receive the response
  use IO::Socket::INET;
  use Net::DHCP::Packet;
  use Net::DHCP::Constants;
  $usage = "usage: $0 DHCP_SERVER_IP DHCP_CLIENT_IP\n"; $ARGV[1] || die $usage;
  # create a socket
  $handle = IO::Socket::INET->new(Proto     => 'udp',
                                  Broadcast => 1,
                                  PeerPort  => '67',
                                  LocalPort => '67',
                                  PeerAddr  => $ARGV[0])
                or die "socket: $@";     # yes, it uses $@ here
  # create DHCP Packet
  $inform = Net::DHCP::Packet->new(
                      op     => BOOTREQUEST(),
                      Htype  => '0',
                      Hlen   => '0',
                      Ciaddr => $ARGV[1],
                      Giaddr => $handle->sockhost(),
                      Xid    => int(rand(0xFFFFFFFF)), # random xid
                      DHO_DHCP_MESSAGE_TYPE() => DHCPLEASEQUERY
                      );
  # send request
  $handle->send($inform->serialize()) or die "Error sending LeaseQuery: $!\n";
  #receive response
  $handle->recv($newmsg, 1024) or die;
  $packet = Net::DHCP::Packet->new($newmsg);
  print $packet->toString();

A simple DHCP Server is provided in the "examples" directory. It is composed of "dhcpd.pl" a *very* simple server example, and "dhcpd_test.pl" a simple tester for this server.

Net::DHCP::Options, Net::DHCP::Constants, Net::DHCP::IPv4Utils, Net::DHCP::Attributes, Net::DHCP::OrderOptions.

Dean Hamstead <dean@fragfest.com.au>

This software is Copyright (c) 2022 by Dean Hamstead.

This is free software, licensed under:

  The MIT (X11) License
2025-07-04 perl v5.40.2
Search for    or go to Top of page |  Section 3 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.