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.696
10

SYNOPSIS

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

DESCRIPTION

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

CONSTRUCTOR

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

METHODS

101   ATTRIBUTE METHODS
102       comment( [STRING] )
103           Sets or gets the comment attribute (object meta-data only)
104
105       op( [BYTE] )
106           Sets/gets the BOOTP opcode.
107
108           Normal values are:
109
110             BOOTREQUEST()
111             BOOTREPLY()
112
113       htype( [BYTE] )
114           Sets/gets the hardware address type.
115
116           Common value is: "HTYPE_ETHER()" (1) = ethernet
117
118       hlen ( [BYTE] )
119           Sets/gets the hardware address length. Value must be between 0 and
120           16.
121
122           For most NIC's, the MAC address has 6 bytes.
123
124       hops ( [BYTE] )
125           Sets/gets the number of hops.
126
127           This field is incremented by each encountered DHCP relay agent.
128
129       xid ( [INTEGER] )
130           Sets/gets the 32 bits transaction id.
131
132           This field should be a random value set by the DHCP client.
133
134       secs ( [SHORT] )
135           Sets/gets the 16 bits elapsed boot time in seconds.
136
137       flags ( [SHORT] )
138           Sets/gets the 16 bits flags.
139
140             0x8000 = Broadcast reply requested.
141
142       ciaddr ( [STRING] )
143           Sets/gets the client IP address.
144
145           IP address is only accepted as a string like '10.24.50.3'.
146
147           Note: IP address is internally stored as a 4 bytes binary string.
148           See "Special methods" below.
149
150       yiaddr ( [STRING] )
151           Sets/gets the your IP address.
152
153           IP address is only accepted as a string like '10.24.50.3'.
154
155           Note: IP address is internally stored as a 4 bytes binary string.
156           See "Special methods" below.
157
158       siaddr ( [STRING] )
159           Sets/gets the next server IP address.
160
161           IP address is only accepted as a string like '10.24.50.3'.
162
163           Note: IP address is internally stored as a 4 bytes binary string.
164           See "Special methods" below.
165
166       giaddr ( [STRING] )
167           Sets/gets the relay agent IP address.
168
169           IP address is only accepted as a string like '10.24.50.3'.
170
171           Note: IP address is internally stored as a 4 bytes binary string.
172           See "Special methods" below.
173
174       chaddr ( [STRING] )
175           Sets/gets the client hardware address. Its length is given by the
176           "hlen" attribute.
177
178           Value is formatted as an Hexadecimal string representation.
179
180             Example: "0010A706DFFF" for 6 bytes mac address.
181
182           Note : internal format is packed bytes string.  See "Special
183           methods" below.
184
185       sname ( [STRING] )
186           Sets/gets the "server host name". Maximum size is 63 bytes. If
187           greater a warning is issued.
188
189       file ( [STRING] )
190           Sets/gets the "boot file name". Maximum size is 127 bytes. If
191           greater a warning is issued.
192
193       isDhcp ( [BOOLEAN] )
194           Sets/gets the DHCP cookie. Returns whether the cookie is valid or
195           not, hence whether the packet is DHCP or BOOTP.
196
197           Default value is 1, valid DHCP cookie.
198
199       padding ( [BYTES] )
200           Sets/gets the optional padding at the end of the DHCP packet, i.e.
201           after DHCP options.
202
203   DHCP OPTIONS METHODS
204       This section describes how to read or set DHCP options. Methods are
205       given in two flavours : (i) text format with automatic type conversion,
206       (ii) raw binary format.
207
208       Standard way of accessing options is through automatic type conversion,
209       described in the "DHCP OPTION TYPES" section. Only a subset of types is
210       supported, mainly those defined in rfc 2132.
211
212       Raw binary functions are provided for pure performance optimization,
213       and for unsupported types manipulation.
214
215       addOptionValue ( CODE, VALUE )
216           Adds a DHCP option field. Common code values are listed in
217           "Net::DHCP::Constants" "DHO_"*.
218
219           Values are automatically converted according to their data types,
220           depending on their format as defined by RFC 2132.  Please see "DHCP
221           OPTION TYPES" for supported options and corresponding formats.
222
223           If you need access to the raw binary values, please use
224           "addOptionRaw()".
225
226              $pac = Net::DHCP::Packet->new();
227              $pac->addOption(DHO_DHCP_MESSAGE_TYPE(), DHCPINFORM());
228              $pac->addOption(DHO_NAME_SERVERS(), "10.0.0.1", "10.0.0.2"));
229
230       addSubOptionValue ( CODE, SUBCODE, VALUE )
231           Adds a DHCP sub-option field. Common code values are listed in
232           "Net::DHCP::Constants" "SUBOPTION_"*.
233
234           Values are automatically converted according to their data types,
235           depending on their format as defined by RFC 2132.  Please see "DHCP
236           OPTION TYPES" for supported options and corresponding formats.
237
238           If you need access to the raw binary values, please use
239           "addSubOptionRaw()".
240
241              $pac = Net::DHCP::Packet->new();
242              # FIXME update exampls
243              $pac->addSubOption(DHO_DHCP_MESSAGE_TYPE(), DHCPINFORM());
244              $pac->addSubOption(DHO_NAME_SERVERS(), "10.0.0.1", "10.0.0.2"));
245
246       getOptionValue ( CODE )
247           Returns the value of a DHCP option.
248
249           Automatic type conversion is done according to their data types, as
250           defined in RFC 2132.  Please see "DHCP OPTION TYPES" for supported
251           options and corresponding formats.
252
253           If you need access to the raw binary values, please use
254           "getOptionRaw()".
255
256           Return value is either a string or an array, depending on the
257           context.
258
259             $ip  = $pac->getOptionValue(DHO_SUBNET_MASK());
260             $ips = $pac->getOptionValue(DHO_NAME_SERVERS());
261
262       addOptionRaw ( CODE, VALUE )
263           Adds a DHCP OPTION provided in packed binary format.  Please see
264           corresponding RFC for manual type conversion.
265
266       addSubOptionRaw ( CODE, SUBCODE, VALUE )
267           Adds a DHCP SUB-OPTION provided in packed binary format.  Please
268           see corresponding RFC for manual type conversion.
269
270       getOptionRaw ( CODE )
271           Gets a DHCP OPTION provided in packed binary format.  Please see
272           corresponding RFC for manual type conversion.
273
274       getSubOptionRaw ( CODE, SUBCODE )
275           Gets a DHCP SUB-OPTION provided in packed binary format.  Please
276           see corresponding RFC for manual type conversion.
277
278       getSubOptionValue ()
279           This is an empty stub for now
280
281       removeSubOption ()
282           This is an empty stub for now
283
284       removeOption ( CODE )
285           Remove option from option list.
286
287       encodeRelayAgent ()
288           These are half baked, but will encode the relay agent options in
289           the future
290
291       decodeRelayAgent ()
292           These are half baked, but will decode the relay agent options in
293           the future
294
295       unpackRelayAgent ( HASH )
296           returns a human readable 'relay agent options', not to be confused
297           with "decodeRelayAgent"
298
299       I packcsr( ARRAYREF )
300           returns the packed Classless Static Route option built from a list
301           of CIDR style address/mask combos
302
303       unpackcsr
304           Not implemented, currently croaks.
305
306       addOption ( CODE, VALUE )
307           Removed as of version 0.60. Please use "addOptionRaw()" instead.
308
309       getOption ( CODE )
310           Removed as of version 0.60. Please use "getOptionRaw()" instead.
311
312   DHCP OPTIONS TYPES
313       This section describes supported option types (cf. RFC 2132).
314
315       For unsupported data types, please use "getOptionRaw()" and
316       "addOptionRaw" to manipulate binary format directly.
317
318       dhcp message type
319           Only supported for DHO_DHCP_MESSAGE_TYPE (053) option.  Converts a
320           integer to a single byte.
321
322           Option code for 'dhcp message' format:
323
324             (053) DHO_DHCP_MESSAGE_TYPE
325
326           Example:
327
328             $pac->addOptionValue(DHO_DHCP_MESSAGE_TYPE(), DHCPINFORM());
329
330       string
331           Pure string attribute, no type conversion.
332
333           Option codes for 'string' format:
334
335             (012) DHO_HOST_NAME
336             (014) DHO_MERIT_DUMP
337             (015) DHO_DOMAIN_NAME
338             (017) DHO_ROOT_PATH
339             (018) DHO_EXTENSIONS_PATH
340             (047) DHO_NETBIOS_SCOPE
341             (056) DHO_DHCP_MESSAGE
342             (060) DHO_VENDOR_CLASS_IDENTIFIER
343             (062) DHO_NWIP_DOMAIN_NAME
344             (064) DHO_NIS_DOMAIN
345             (065) DHO_NIS_SERVER
346             (066) DHO_TFTP_SERVER
347             (067) DHO_BOOTFILE
348             (086) DHO_NDS_TREE_NAME
349             (098) DHO_USER_AUTHENTICATION_PROTOCOL
350
351           Example:
352
353             $pac->addOptionValue(DHO_TFTP_SERVER(), "foobar");
354
355       single ip address
356           Exactly one IP address, in dotted numerical format '192.168.1.1'.
357
358           Option codes for 'single ip address' format:
359
360             (001) DHO_SUBNET_MASK
361             (016) DHO_SWAP_SERVER
362             (028) DHO_BROADCAST_ADDRESS
363             (032) DHO_ROUTER_SOLICITATION_ADDRESS
364             (050) DHO_DHCP_REQUESTED_ADDRESS
365             (054) DHO_DHCP_SERVER_IDENTIFIER
366             (118) DHO_SUBNET_SELECTION
367
368           Example:
369
370             $pac->addOptionValue(DHO_SUBNET_MASK(), "255.255.255.0");
371
372       multiple ip addresses
373           Any number of IP address, in dotted numerical format '192.168.1.1'.
374           Empty value allowed.
375
376           Option codes for 'multiple ip addresses' format:
377
378             (003) DHO_ROUTERS
379             (004) DHO_TIME_SERVERS
380             (005) DHO_NAME_SERVERS
381             (006) DHO_DOMAIN_NAME_SERVERS
382             (007) DHO_LOG_SERVERS
383             (008) DHO_COOKIE_SERVERS
384             (009) DHO_LPR_SERVERS
385             (010) DHO_IMPRESS_SERVERS
386             (011) DHO_RESOURCE_LOCATION_SERVERS
387             (041) DHO_NIS_SERVERS
388             (042) DHO_NTP_SERVERS
389             (044) DHO_NETBIOS_NAME_SERVERS
390             (045) DHO_NETBIOS_DD_SERVER
391             (048) DHO_FONT_SERVERS
392             (049) DHO_X_DISPLAY_MANAGER
393             (068) DHO_MOBILE_IP_HOME_AGENT
394             (069) DHO_SMTP_SERVER
395             (070) DHO_POP3_SERVER
396             (071) DHO_NNTP_SERVER
397             (072) DHO_WWW_SERVER
398             (073) DHO_FINGER_SERVER
399             (074) DHO_IRC_SERVER
400             (075) DHO_STREETTALK_SERVER
401             (076) DHO_STDA_SERVER
402             (085) DHO_NDS_SERVERS
403
404           Example:
405
406             $pac->addOptionValue(DHO_NAME_SERVERS(), "10.0.0.11 192.168.1.10");
407
408       pairs of ip addresses
409           Even number of IP address, in dotted numerical format
410           '192.168.1.1'.  Empty value allowed.
411
412           Option codes for 'pairs of ip address' format:
413
414             (021) DHO_POLICY_FILTER
415             (033) DHO_STATIC_ROUTES
416
417           Example:
418
419             $pac->addOptionValue(DHO_STATIC_ROUTES(), "10.0.0.1 192.168.1.254");
420
421       byte, short and integer
422           Numerical value in byte (8 bits), short (16 bits) or integer (32
423           bits) format.
424
425           Option codes for 'byte (8)' format:
426
427             (019) DHO_IP_FORWARDING
428             (020) DHO_NON_LOCAL_SOURCE_ROUTING
429             (023) DHO_DEFAULT_IP_TTL
430             (027) DHO_ALL_SUBNETS_LOCAL
431             (029) DHO_PERFORM_MASK_DISCOVERY
432             (030) DHO_MASK_SUPPLIER
433             (031) DHO_ROUTER_DISCOVERY
434             (034) DHO_TRAILER_ENCAPSULATION
435             (036) DHO_IEEE802_3_ENCAPSULATION
436             (037) DHO_DEFAULT_TCP_TTL
437             (039) DHO_TCP_KEEPALIVE_GARBAGE
438             (046) DHO_NETBIOS_NODE_TYPE
439             (052) DHO_DHCP_OPTION_OVERLOAD
440             (116) DHO_AUTO_CONFIGURE
441
442           Option codes for 'short (16)' format:
443
444             (013) DHO_BOOT_SIZE
445             (022) DHO_MAX_DGRAM_REASSEMBLY
446             (026) DHO_INTERFACE_MTU
447             (057) DHO_DHCP_MAX_MESSAGE_SIZE
448
449           Option codes for 'integer (32)' format:
450
451             (002) DHO_TIME_OFFSET
452             (024) DHO_PATH_MTU_AGING_TIMEOUT
453             (035) DHO_ARP_CACHE_TIMEOUT
454             (038) DHO_TCP_KEEPALIVE_INTERVAL
455             (051) DHO_DHCP_LEASE_TIME
456             (058) DHO_DHCP_RENEWAL_TIME
457             (059) DHO_DHCP_REBINDING_TIME
458
459           Examples:
460
461             $pac->addOptionValue(DHO_DHCP_OPTION_OVERLOAD(), 3);
462             $pac->addOptionValue(DHO_INTERFACE_MTU(), 1500);
463             $pac->addOptionValue(DHO_DHCP_RENEWAL_TIME(), 24*60*60);
464
465       multiple bytes, shorts
466           A list a bytes or shorts.
467
468           Option codes for 'multiple bytes (8)' format:
469
470             (055) DHO_DHCP_PARAMETER_REQUEST_LIST
471
472           Option codes for 'multiple shorts (16)' format:
473
474             (025) DHO_PATH_MTU_PLATEAU_TABLE
475             (117) DHO_NAME_SERVICE_SEARCH
476
477           Examples:
478
479             $pac->addOptionValue(DHO_DHCP_PARAMETER_REQUEST_LIST(),  "1 3 6 12 15 28 42 72");
480
481   SERIALIZATION METHODS
482       serialize ()
483           Converts a Net::DHCP::Packet to a string, ready to put on the
484           network.
485
486       marshall ( BYTES )
487           The inverse of serialize. Converts a string, presumably a received
488           UDP packet, into a Net::DHCP::Packet.
489
490           If the packet is malformed, a fatal error is produced.
491
492   HELPER METHODS
493       toString ()
494           Returns a textual representation of the packet, for debugging.
495
496       packinet ( STRING )
497           Transforms a IP address "xx.xx.xx.xx" into a packed 4 bytes string.
498
499           These are simple never failing versions of inet_ntoa and inet_aton.
500
501       packinets ( STRING )
502           Transforms a list of space delimited IP addresses into a packed
503           bytes string.
504
505       packinets_array( LIST )
506           Transforms an array (list) of IP addresses into a packed bytes
507           string.
508
509       unpackinet ( STRING )
510           Transforms a packed bytes IP address into a "xx.xx.xx.xx" string.
511
512       unpackinets ( STRING )
513           Transforms a packed bytes list of IP addresses into a list of
514           "xx.xx.xx.xx" space delimited string.
515
516       unpackinets_array ( STRING )
517           Transforms a packed bytes list of IP addresses into a array of
518           "xx.xx.xx.xx" strings.
519
520   SPECIAL METHODS
521       These methods are provided for performance tuning only. They give
522       access to internal data representation , thus avoiding unnecessary type
523       conversion.
524
525       ciaddrRaw ( [STRING])
526           Sets/gets the client IP address in packed 4 characters binary
527           strings.
528
529       yiaddrRaw ( [STRING] )
530           Sets/gets the your IP address in packed 4 characters binary
531           strings.
532
533       siaddrRaw ( [STRING] )
534           Sets/gets the next server IP address in packed 4 characters binary
535           strings.
536
537       giaddrRaw ( [STRING] )
538           Sets/gets the relay agent IP address in packed 4 characters binary
539           strings.
540
541       chaddrRaw ( [STRING] )
542           Sets/gets the client hardware address in packed binary string.  Its
543           length is given by the "hlen" attribute.
544

EXAMPLES

546       Sending a simple DHCP packet:
547
548         #!/usr/bin/perl
549         # Simple DHCP client - sending a broadcasted DHCP Discover request
550
551         use IO::Socket::INET;
552         use Net::DHCP::Packet;
553         use Net::DHCP::Constants;
554
555         # creat DHCP Packet
556         $discover = Net::DHCP::Packet->new(
557                               xid => int(rand(0xFFFFFFFF)), # random xid
558                               Flags => 0x8000,              # ask for broadcast answer
559                               DHO_DHCP_MESSAGE_TYPE() => DHCPDISCOVER()
560                               );
561
562         # send packet
563         $handle = IO::Socket::INET->new(Proto => 'udp',
564                                         Broadcast => 1,
565                                         PeerPort => '67',
566                                         LocalPort => '68',
567                                         PeerAddr => '255.255.255.255')
568                       or die "socket: $@";     # yes, it uses $@ here
569         $handle->send($discover->serialize())
570                       or die "Error sending broadcast inform:$!\n";
571
572       Sniffing DHCP packets.
573
574         #!/usr/bin/perl
575         # Simple DHCP server - listen to DHCP packets and print them
576
577         use IO::Socket::INET;
578         use Net::DHCP::Packet;
579         $sock = IO::Socket::INET->new(LocalPort => 67, Proto => "udp", Broadcast => 1)
580                 or die "socket: $@";
581         while ($sock->recv($newmsg, 1024)) {
582                 $packet = Net::DHCP::Packet->new($newmsg);
583                 print STDERR $packet->toString();
584         }
585
586       Sending a LEASEQUERY (provided by John A. Murphy).
587
588         #!/usr/bin/perl
589         # Simple DHCP client - send a LeaseQuery (by IP) and receive the response
590
591         use IO::Socket::INET;
592         use Net::DHCP::Packet;
593         use Net::DHCP::Constants;
594
595         $usage = "usage: $0 DHCP_SERVER_IP DHCP_CLIENT_IP\n"; $ARGV[1] || die $usage;
596
597         # create a socket
598         $handle = IO::Socket::INET->new(Proto => 'udp',
599                                         Broadcast => 1,
600                                         PeerPort => '67',
601                                         LocalPort => '67',
602                                         PeerAddr => $ARGV[0])
603                       or die "socket: $@";     # yes, it uses $@ here
604
605         # create DHCP Packet
606         $inform = Net::DHCP::Packet->new(
607                             op => BOOTREQUEST(),
608                             Htype  => '0',
609                             Hlen   => '0',
610                             Ciaddr => $ARGV[1],
611                             Giaddr => $handle->sockhost(),
612                             Xid => int(rand(0xFFFFFFFF)),     # random xid
613                             DHO_DHCP_MESSAGE_TYPE() => DHCPLEASEQUERY
614                             );
615
616         # send request
617         $handle->send($inform->serialize()) or die "Error sending LeaseQuery: $!\n";
618
619         #receive response
620         $handle->recv($newmsg, 1024) or die;
621         $packet = Net::DHCP::Packet->new($newmsg);
622         print $packet->toString();
623
624       A simple DHCP Server is provided in the "examples" directory. It is
625       composed of "dhcpd.pl" a *very* simple server example, and
626       "dhcpd_test.pl" a simple tester for this server.
627

AUTHOR

629       Dean Hamstead <djzort@cpan.org> Previously Stephan Hadinger
630       <shadinger@cpan.org>.  Original version by F. van Dun.
631

BUGS

633       See <https://rt.cpan.org/Dist/Display.html?Queue=Net-DHCP>
634

GOT PATCHES?

636       Many young people like to use Github, so by all means send me pull
637       requests at
638
639       https://github.com/djzort/Net-DHCP
640
642       This is free software. It can be distributed and/or modified under the
643       same terms as Perl itself.
644

SEE ALSO

646       Net::DHCP::Options, Net::DHCP::Constants.
647
648
649
650perl v5.32.1                      2021-01-27              Net::DHCP::Packet(3)
Impressum