1Net::DHCP::Packet(3)  User Contributed Perl Documentation Net::DHCP::Packet(3)
2
3
4

NAME

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

VERSION

9       version 0.7
10

SYNOPSIS

12          use Net::DHCP::Packet;
13
14          my $p = Net::DHCP::Packet->new(
15
16               'Chaddr' => '000BCDEF',
17               'Xid' => 0x9F0FD,
18               'Ciaddr' => '0.0.0.0',
19               'Siaddr' => '0.0.0.0',
20               'Hops' => 0
21
22           );
23

DESCRIPTION

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

CONSTRUCTOR

28       This module only provides basic constructor. For "easy" constructors,
29       you can use the Net::DHCP::Session module.
30
31       new( )
32       new( BUFFER )
33       new( ARG => VALUE, ARG => VALUE... )
34           Creates an "Net::DHCP::Packet" object, which can be used to send or
35           receive DHCP network packets. BOOTP is not supported.
36
37           Without argument, a default empty packet is created.
38
39             $packet = Net::DHCP::Packet();
40
41           A "BUFFER" argument is interpreted as a binary buffer like one
42           provided by the socket recv() function. if the packet is malformed,
43           a fatal error is issued.
44
45              use IO::Socket::INET;
46              use Net::DHCP::Packet;
47
48              $sock = IO::Socket::INET->new(LocalPort => 67, Proto => "udp", Broadcast => 1)
49                      or die "socket: $@";
50
51              while ($sock->recv($newmsg, 1024)) {
52                  $packet = Net::DHCP::Packet->new($newmsg);
53                  print $packet->toString();
54              }
55
56           To create a fresh new packet new() takes arguments as a key-value
57           pairs :
58
59              ARGUMENT   FIELD      OCTETS       DESCRIPTION
60              --------   -----      ------       -----------
61
62              Op         op            1  Message op code / message type.
63                                          1 = BOOTREQUEST, 2 = BOOTREPLY
64              Htype      htype         1  Hardware address type, see ARP section in "Assigned
65                                          Numbers" RFC; e.g., '1' = 10mb ethernet.
66              Hlen       hlen          1  Hardware address length (e.g.  '6' for 10mb
67                                          ethernet).
68              Hops       hops          1  Client sets to zero, optionally used by relay agents
69                                          when booting via a relay agent.
70              Xid        xid           4  Transaction ID, a random number chosen by the
71                                          client, used by the client and server to associate
72                                          messages and responses between a client and a
73                                          server.
74              Secs       secs          2  Filled in by client, seconds elapsed since client
75                                          began address acquisition or renewal process.
76              Flags      flags         2  Flags (see figure 2).
77              Ciaddr     ciaddr        4  Client IP address; only filled in if client is in
78                                          BOUND, RENEW or REBINDING state and can respond
79                                          to ARP requests.
80              Yiaddr     yiaddr        4  'your' (client) IP address.
81              Siaddr     siaddr        4  IP address of next server to use in bootstrap;
82                                          returned in DHCPOFFER, DHCPACK by server.
83              Giaddr     giaddr        4  Relay agent IP address, used in booting via a
84                                          relay agent.
85              Chaddr     chaddr       16  Client hardware address.
86              Sname      sname        64  Optional server host name, null terminated string.
87              File       file        128  Boot file name, null terminated string; "generic"
88                                          name or null in DHCPDISCOVER, fully qualified
89                                          directory-path name in DHCPOFFER.
90              IsDhcp     isDhcp        4  Controls whether the packet is BOOTP or DHCP.
91                                          DHCP conatains the "magic cookie" of 4 bytes.
92                                          0x63 0x82 0x53 0x63.
93              DHO_*code                   Optional parameters field.  See the options
94                                          documents for a list of defined options.
95                                          See Net::DHCP::Constants.
96              Padding    padding       *  Optional padding at the end of the packet
97
98           See below methods for values and syntax description.
99
100           Note: DHCP options are created in the same order as key-value
101           pairs.
102

METHODS

104   ATTRIBUTE METHODS
105       See Net::DHCP::Packet::Attributes
106
107   DHCP OPTIONS METHODS
108       This section describes how to read or set DHCP options. Methods are
109       given in two flavours : (i) text format with automatic type conversion,
110       (ii) raw binary format.
111
112       Standard way of accessing options is through automatic type conversion,
113       described in the "DHCP OPTION TYPES" section. Only a subset of types is
114       supported, mainly those defined in rfc 2132.
115
116       Raw binary functions are provided for pure performance optimization,
117       and for unsupported types manipulation.
118
119       addOptionValue ( CODE, VALUE )
120           Adds a DHCP option field. Common code values are listed in
121           "Net::DHCP::Constants" "DHO_"*.
122
123           Values are automatically converted according to their data types,
124           depending on their format as defined by RFC 2132.  Please see "DHCP
125           OPTION TYPES" for supported options and corresponding formats.
126
127           If you need access to the raw binary values, please use
128           addOptionRaw().
129
130              $pac = Net::DHCP::Packet->new();
131              $pac->addOption(DHO_DHCP_MESSAGE_TYPE(), DHCPINFORM());
132              $pac->addOption(DHO_NAME_SERVERS(), "10.0.0.1", "10.0.0.2"));
133
134       addSubOptionValue ( CODE, SUBCODE, VALUE )
135           Adds a DHCP sub-option field. Common code values are listed in
136           "Net::DHCP::Constants" "SUBOPTION_"*.
137
138           Values are automatically converted according to their data types,
139           depending on their format as defined by RFC 2132.  Please see "DHCP
140           OPTION TYPES" for supported options and corresponding formats.
141
142           If you need access to the raw binary values, please use
143           addSubOptionRaw().
144
145              $pac = Net::DHCP::Packet->new();
146              # FIXME update examples
147              $pac->addSubOption(DHO_DHCP_MESSAGE_TYPE(), DHCPINFORM());
148              $pac->addSubOption(DHO_NAME_SERVERS(), "10.0.0.1", "10.0.0.2"));
149
150       getOptionValue ( CODE )
151           Returns the value of a DHCP option.
152
153           Automatic type conversion is done according to their data types, as
154           defined in RFC 2132.  Please see "DHCP OPTION TYPES" for supported
155           options and corresponding formats.
156
157           If you need access to the raw binary values, please use
158           getOptionRaw().
159
160           Return value is either a string or an array, depending on the
161           context.
162
163             $ip  = $pac->getOptionValue(DHO_SUBNET_MASK());
164             $ips = $pac->getOptionValue(DHO_NAME_SERVERS());
165
166       addOptionRaw ( CODE, VALUE, BOOLEAN )
167           Adds a DHCP OPTION provided in packed binary format.  Please see
168           corresponding RFC for manual type conversion.
169
170           BOOLEAN indicates if options should be inserted in the order
171           provided.  Default is to sort options to work around known quirky
172           clients.  See "QUIRK WORK-AROUNDS"
173
174       addSubOptionRaw ( CODE, SUBCODE, VALUE )
175           Adds a DHCP SUB-OPTION provided in packed binary format.  Please
176           see corresponding RFC for manual type conversion.
177
178       getOptionRaw ( CODE )
179           Gets a DHCP OPTION provided in packed binary format.  Please see
180           corresponding RFC for manual type conversion.
181
182       getSubOptionRaw ( CODE, SUBCODE )
183           Gets a DHCP SUB-OPTION provided in packed binary format.  Please
184           see corresponding RFC for manual type conversion.
185
186       getSubOptionValue ()
187           This is an empty stub for now
188
189       removeSubOption ()
190           This is an empty stub for now
191
192       removeOption ( CODE )
193           Remove option from option list.
194
195       packclientid( VALUE )
196           returns the packed Client-identifier (pass-through currently)
197
198           See <https://tools.ietf.org/html/rfc2132#section-9.14> See also
199           <https://tools.ietf.org/html/rfc4361>
200
201       unpackclientid
202           returns the unpacked clientid.
203
204           Decodes:
205            type 0 as a string
206            type 1 as a mac address (hex string)
207            everything is passed through
208
209           See <https://tools.ietf.org/html/rfc2132#section-9.14> See also
210           <https://tools.ietf.org/html/rfc4361>
211
212       packsipserv( VALUE )
213           returns the packed sip server field (pass-through currently)
214
215       unpacksipserv
216           returns the unpacked sip server.
217
218           Decodes:
219            type 1 as an ipv4 address
220            everything is passed through
221
222       packcsr( ARRAYREF )
223           returns the packed Classless Static Route option built from a list
224           of CIDR style address/mask combos
225
226       unpackcsr
227           Not implemented, currently croaks.
228
229       addOption ( CODE, VALUE )
230           Removed as of version 0.60. Please use addOptionRaw() instead.
231
232       getOption ( CODE )
233           Removed as of version 0.60. Please use getOptionRaw() instead.
234
235   DHCP OPTIONS TYPES
236       This section describes supported option types (cf. RFC 2132).
237
238       For unsupported data types, please use getOptionRaw() and
239       "addOptionRaw" to manipulate binary format directly.
240
241       dhcp message type
242           Only supported for DHO_DHCP_MESSAGE_TYPE (053) option.  Converts a
243           integer to a single byte.
244
245           Option code for 'dhcp message' format:
246
247             (053) DHO_DHCP_MESSAGE_TYPE
248
249           Example:
250
251             $pac->addOptionValue(DHO_DHCP_MESSAGE_TYPE(), DHCPINFORM());
252
253       string
254           Pure string attribute, no type conversion.
255
256           Option codes for 'string' format:
257
258             (012) DHO_HOST_NAME
259             (014) DHO_MERIT_DUMP
260             (015) DHO_DOMAIN_NAME
261             (017) DHO_ROOT_PATH
262             (018) DHO_EXTENSIONS_PATH
263             (047) DHO_NETBIOS_SCOPE
264             (056) DHO_DHCP_MESSAGE
265             (060) DHO_VENDOR_CLASS_IDENTIFIER
266             (062) DHO_NWIP_DOMAIN_NAME
267             (064) DHO_NIS_DOMAIN
268             (065) DHO_NIS_SERVER
269             (066) DHO_TFTP_SERVER
270             (067) DHO_BOOTFILE
271             (086) DHO_NDS_TREE_NAME
272             (098) DHO_USER_AUTHENTICATION_PROTOCOL
273
274           Example:
275
276             $pac->addOptionValue(DHO_TFTP_SERVER(), "foobar");
277
278       single ip address
279           Exactly one IP address, in dotted numerical format '192.168.1.1'.
280
281           Option codes for 'single ip address' format:
282
283             (001) DHO_SUBNET_MASK
284             (016) DHO_SWAP_SERVER
285             (028) DHO_BROADCAST_ADDRESS
286             (032) DHO_ROUTER_SOLICITATION_ADDRESS
287             (050) DHO_DHCP_REQUESTED_ADDRESS
288             (054) DHO_DHCP_SERVER_IDENTIFIER
289             (118) DHO_SUBNET_SELECTION
290
291           Example:
292
293             $pac->addOptionValue(DHO_SUBNET_MASK(), "255.255.255.0");
294
295       multiple ip addresses
296           Any number of IP address, in dotted numerical format '192.168.1.1'.
297           Empty value allowed.
298
299           Option codes for 'multiple ip addresses' format:
300
301             (003) DHO_ROUTERS
302             (004) DHO_TIME_SERVERS
303             (005) DHO_NAME_SERVERS
304             (006) DHO_DOMAIN_NAME_SERVERS
305             (007) DHO_LOG_SERVERS
306             (008) DHO_COOKIE_SERVERS
307             (009) DHO_LPR_SERVERS
308             (010) DHO_IMPRESS_SERVERS
309             (011) DHO_RESOURCE_LOCATION_SERVERS
310             (041) DHO_NIS_SERVERS
311             (042) DHO_NTP_SERVERS
312             (044) DHO_NETBIOS_NAME_SERVERS
313             (045) DHO_NETBIOS_DD_SERVER
314             (048) DHO_FONT_SERVERS
315             (049) DHO_X_DISPLAY_MANAGER
316             (068) DHO_MOBILE_IP_HOME_AGENT
317             (069) DHO_SMTP_SERVER
318             (070) DHO_POP3_SERVER
319             (071) DHO_NNTP_SERVER
320             (072) DHO_WWW_SERVER
321             (073) DHO_FINGER_SERVER
322             (074) DHO_IRC_SERVER
323             (075) DHO_STREETTALK_SERVER
324             (076) DHO_STDA_SERVER
325             (085) DHO_NDS_SERVERS
326
327           Example:
328
329             $pac->addOptionValue(DHO_NAME_SERVERS(), "10.0.0.11 192.168.1.10");
330
331       pairs of ip addresses
332           Even number of IP address, in dotted numerical format
333           '192.168.1.1'.  Empty value allowed.
334
335           Option codes for 'pairs of ip address' format:
336
337             (021) DHO_POLICY_FILTER
338             (033) DHO_STATIC_ROUTES
339
340           Example:
341
342             $pac->addOptionValue(DHO_STATIC_ROUTES(), "10.0.0.1 192.168.1.254");
343
344       byte, short and integer
345           Numerical value in byte (8 bits), short (16 bits) or integer (32
346           bits) format.
347
348           Option codes for 'byte (8)' format:
349
350             (019) DHO_IP_FORWARDING
351             (020) DHO_NON_LOCAL_SOURCE_ROUTING
352             (023) DHO_DEFAULT_IP_TTL
353             (027) DHO_ALL_SUBNETS_LOCAL
354             (029) DHO_PERFORM_MASK_DISCOVERY
355             (030) DHO_MASK_SUPPLIER
356             (031) DHO_ROUTER_DISCOVERY
357             (034) DHO_TRAILER_ENCAPSULATION
358             (036) DHO_IEEE802_3_ENCAPSULATION
359             (037) DHO_DEFAULT_TCP_TTL
360             (039) DHO_TCP_KEEPALIVE_GARBAGE
361             (046) DHO_NETBIOS_NODE_TYPE
362             (052) DHO_DHCP_OPTION_OVERLOAD
363             (116) DHO_AUTO_CONFIGURE
364
365           Option codes for 'short (16)' format:
366
367             (013) DHO_BOOT_SIZE
368             (022) DHO_MAX_DGRAM_REASSEMBLY
369             (026) DHO_INTERFACE_MTU
370             (057) DHO_DHCP_MAX_MESSAGE_SIZE
371
372           Option codes for 'integer (32)' format:
373
374             (002) DHO_TIME_OFFSET
375             (024) DHO_PATH_MTU_AGING_TIMEOUT
376             (035) DHO_ARP_CACHE_TIMEOUT
377             (038) DHO_TCP_KEEPALIVE_INTERVAL
378             (051) DHO_DHCP_LEASE_TIME
379             (058) DHO_DHCP_RENEWAL_TIME
380             (059) DHO_DHCP_REBINDING_TIME
381
382           Examples:
383
384             $pac->addOptionValue(DHO_DHCP_OPTION_OVERLOAD(), 3);
385             $pac->addOptionValue(DHO_INTERFACE_MTU(), 1500);
386             $pac->addOptionValue(DHO_DHCP_RENEWAL_TIME(), 24*60*60);
387
388       multiple bytes, shorts
389           A list a bytes or shorts.
390
391           Option codes for 'multiple bytes (8)' format:
392
393             (055) DHO_DHCP_PARAMETER_REQUEST_LIST
394
395           Option codes for 'multiple shorts (16)' format:
396
397             (025) DHO_PATH_MTU_PLATEAU_TABLE
398             (117) DHO_NAME_SERVICE_SEARCH
399
400           Examples:
401
402             $pac->addOptionValue(DHO_DHCP_PARAMETER_REQUEST_LIST(),  "1 3 6 12 15 28 42 72");
403
404   SERIALIZATION METHODS
405       serialize ()
406           Converts a Net::DHCP::Packet to a string, ready to put on the
407           network.
408
409       marshall ( BYTES )
410           The inverse of serialize. Converts a string, presumably a received
411           UDP packet, into a Net::DHCP::Packet.
412
413           If the packet is malformed, a fatal error is produced.
414
415   HELPER METHODS
416       toString ()
417           Returns a textual representation of the packet, for debugging.
418
419       packsuboptions ( LIST )
420           Transforms an list of lists into packed option.  For option 43
421           (vendor specific), 82 (relay agent) etc.
422
423       unpacksuboptions ( STRING )
424           Unpacks sub-options to a list of lists
425
426       min_len_handling ( LEVEL )
427           By default, the level is set to 0. If the packet is shorter than
428           the minimum "BOOTP_MIN_LEN", a warning is issued; if it is shorter
429           than the absolute minimum "BOOTP_ABSOLUTE_MIN_LEN", an exception is
430           thrown.
431
432           If the level is set to 1, even the absolute minimum just warns.
433
434           Setting the level to 2 means the packet length checks are skipped
435           altogether.
436
437           Without a parameter, the method returns the current level.
438
439       See also Net::DHCP::Packet::IPv4Utils
440

EXAMPLES

442       Sending a simple DHCP packet:
443
444         #!/usr/bin/perl
445         # Simple DHCP client - sending a broadcasted DHCP Discover request
446
447         use IO::Socket::INET;
448         use Net::DHCP::Packet;
449         use Net::DHCP::Constants;
450
451         # creat DHCP Packet
452         $discover = Net::DHCP::Packet->new(
453                               xid => int(rand(0xFFFFFFFF)), # random xid
454                               Flags => 0x8000,              # ask for broadcast answer
455                               DHO_DHCP_MESSAGE_TYPE() => DHCPDISCOVER()
456                               );
457
458         # send packet
459         $handle = IO::Socket::INET->new(Proto => 'udp',
460                                         Broadcast => 1,
461                                         PeerPort => '67',
462                                         LocalPort => '68',
463                                         PeerAddr => '255.255.255.255')
464                       or die "socket: $@";     # yes, it uses $@ here
465         $handle->send($discover->serialize())
466                       or die "Error sending broadcast inform:$!\n";
467
468       Sniffing DHCP packets.
469
470         #!/usr/bin/perl
471         # Simple DHCP server - listen to DHCP packets and print them
472
473         use IO::Socket::INET;
474         use Net::DHCP::Packet;
475         $sock = IO::Socket::INET->new(LocalPort => 67, Proto => "udp", Broadcast => 1)
476                 or die "socket: $@";
477         while ($sock->recv($newmsg, 1024)) {
478                 $packet = Net::DHCP::Packet->new($newmsg);
479                 print STDERR $packet->toString();
480         }
481
482       Sending a LEASEQUERY (provided by John A. Murphy).
483
484         #!/usr/bin/perl
485         # Simple DHCP client - send a LeaseQuery (by IP) and receive the response
486
487         use IO::Socket::INET;
488         use Net::DHCP::Packet;
489         use Net::DHCP::Constants;
490
491         $usage = "usage: $0 DHCP_SERVER_IP DHCP_CLIENT_IP\n"; $ARGV[1] || die $usage;
492
493         # create a socket
494         $handle = IO::Socket::INET->new(Proto     => 'udp',
495                                         Broadcast => 1,
496                                         PeerPort  => '67',
497                                         LocalPort => '67',
498                                         PeerAddr  => $ARGV[0])
499                       or die "socket: $@";     # yes, it uses $@ here
500
501         # create DHCP Packet
502         $inform = Net::DHCP::Packet->new(
503                             op     => BOOTREQUEST(),
504                             Htype  => '0',
505                             Hlen   => '0',
506                             Ciaddr => $ARGV[1],
507                             Giaddr => $handle->sockhost(),
508                             Xid    => int(rand(0xFFFFFFFF)), # random xid
509                             DHO_DHCP_MESSAGE_TYPE() => DHCPLEASEQUERY
510                             );
511
512         # send request
513         $handle->send($inform->serialize()) or die "Error sending LeaseQuery: $!\n";
514
515         #receive response
516         $handle->recv($newmsg, 1024) or die;
517         $packet = Net::DHCP::Packet->new($newmsg);
518         print $packet->toString();
519
520       A simple DHCP Server is provided in the "examples" directory. It is
521       composed of "dhcpd.pl" a *very* simple server example, and
522       "dhcpd_test.pl" a simple tester for this server.
523

SEE ALSO

525       Net::DHCP::Options, Net::DHCP::Constants, Net::DHCP::IPv4Utils,
526       Net::DHCP::Attributes, Net::DHCP::OrderOptions.
527

AUTHOR

529       Dean Hamstead <dean@fragfest.com.au>
530
532       This software is Copyright (c) 2022 by Dean Hamstead.
533
534       This is free software, licensed under:
535
536         The MIT (X11) License
537
538
539
540perl v5.36.0                      2023-01-20              Net::DHCP::Packet(3)
Impressum