1Net::DHCP::Packet(3) User Contributed Perl Documentation Net::DHCP::Packet(3)
2
6 Net::DHCP::Packet - Object methods to create a DHCP packet.
7
9 version 0.696
10
12 use Net::DHCP::Packet;
13 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
22 Represents a DHCP packet as specified in RFC 1533, RFC 2132.
23
25 This module only provides basic constructor. For "easy" constructors,
26 you can use the Net::DHCP::Session module.
27 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 Without argument, a default empty packet is created.
35 $packet = Net::DHCP::Packet();
37 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 use IO::Socket::INET;
43 use Net::DHCP::Packet;
44 $sock = IO::Socket::INET->new(LocalPort => 67, Proto => "udp", Broadcast => 1)
46 or die "socket: $@";
47 while ($sock->recv($newmsg, 1024)) {
49 $packet = Net::DHCP::Packet->new($newmsg);
50 print $packet->toString();
51 }
52 To create a fresh new packet "new()" takes arguments as a key-value
54 pairs :
55 ARGUMENT FIELD OCTETS DESCRIPTION
57 -------- ----- ------ -----------
58 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 See below methods for values and syntax description.
96 Note: DHCP options are created in the same order as key-value
98 pairs.
99
101 ATTRIBUTE METHODS
102 comment( [STRING] )
103 Sets or gets the comment attribute (object meta-data only)
104 op( [BYTE] )
106 Sets/gets the BOOTP opcode.
107 Normal values are:
109 BOOTREQUEST()
111 BOOTREPLY()
112 htype( [BYTE] )
114 Sets/gets the hardware address type.
115 Common value is: "HTYPE_ETHER()" (1) = ethernet
117 hlen ( [BYTE] )
119 Sets/gets the hardware address length. Value must be between 0 and
120 16.
121 For most NIC's, the MAC address has 6 bytes.
123 hops ( [BYTE] )
125 Sets/gets the number of hops.
126 This field is incremented by each encountered DHCP relay agent.
128 xid ( [INTEGER] )
130 Sets/gets the 32 bits transaction id.
131 This field should be a random value set by the DHCP client.
133 secs ( [SHORT] )
135 Sets/gets the 16 bits elapsed boot time in seconds.
136 flags ( [SHORT] )
138 Sets/gets the 16 bits flags.
139 0x8000 = Broadcast reply requested.
141 ciaddr ( [STRING] )
143 Sets/gets the client IP address.
144 IP address is only accepted as a string like '10.24.50.3'.
146 Note: IP address is internally stored as a 4 bytes binary string.
148 See "Special methods" below.
149 yiaddr ( [STRING] )
151 Sets/gets the your IP address.
152 IP address is only accepted as a string like '10.24.50.3'.
154 Note: IP address is internally stored as a 4 bytes binary string.
156 See "Special methods" below.
157 siaddr ( [STRING] )
159 Sets/gets the next server IP address.
160 IP address is only accepted as a string like '10.24.50.3'.
162 Note: IP address is internally stored as a 4 bytes binary string.
164 See "Special methods" below.
165 giaddr ( [STRING] )
167 Sets/gets the relay agent IP address.
168 IP address is only accepted as a string like '10.24.50.3'.
170 Note: IP address is internally stored as a 4 bytes binary string.
172 See "Special methods" below.
173 chaddr ( [STRING] )
175 Sets/gets the client hardware address. Its length is given by the
176 "hlen" attribute.
177 Value is formatted as an Hexadecimal string representation.
179 Example: "0010A706DFFF" for 6 bytes mac address.
181 Note : internal format is packed bytes string. See "Special
183 methods" below.
184 sname ( [STRING] )
186 Sets/gets the "server host name". Maximum size is 63 bytes. If
187 greater a warning is issued.
188 file ( [STRING] )
190 Sets/gets the "boot file name". Maximum size is 127 bytes. If
191 greater a warning is issued.
192 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 Default value is 1, valid DHCP cookie.
198 padding ( [BYTES] )
200 Sets/gets the optional padding at the end of the DHCP packet, i.e.
201 after DHCP options.
202 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 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 Raw binary functions are provided for pure performance optimization,
213 and for unsupported types manipulation.
214 addOptionValue ( CODE, VALUE )
216 Adds a DHCP option field. Common code values are listed in
217 "Net::DHCP::Constants" "DHO_"*.
218 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 If you need access to the raw binary values, please use
224 "addOptionRaw()".
225 $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 addSubOptionValue ( CODE, SUBCODE, VALUE )
231 Adds a DHCP sub-option field. Common code values are listed in
232 "Net::DHCP::Constants" "SUBOPTION_"*.
233 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 If you need access to the raw binary values, please use
239 "addSubOptionRaw()".
240 $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 getOptionValue ( CODE )
247 Returns the value of a DHCP option.
248 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 If you need access to the raw binary values, please use
254 "getOptionRaw()".
255 Return value is either a string or an array, depending on the
257 context.
258 $ip = $pac->getOptionValue(DHO_SUBNET_MASK());
260 $ips = $pac->getOptionValue(DHO_NAME_SERVERS());
261 addOptionRaw ( CODE, VALUE )
263 Adds a DHCP OPTION provided in packed binary format. Please see
264 corresponding RFC for manual type conversion.
265 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 getOptionRaw ( CODE )
271 Gets a DHCP OPTION provided in packed binary format. Please see
272 corresponding RFC for manual type conversion.
273 getSubOptionRaw ( CODE, SUBCODE )
275 Gets a DHCP SUB-OPTION provided in packed binary format. Please
276 see corresponding RFC for manual type conversion.
277 getSubOptionValue ()
279 This is an empty stub for now
280 removeSubOption ()
282 This is an empty stub for now
283 removeOption ( CODE )
285 Remove option from option list.
286 encodeRelayAgent ()
288 These are half baked, but will encode the relay agent options in
289 the future
290 decodeRelayAgent ()
292 These are half baked, but will decode the relay agent options in
293 the future
294 unpackRelayAgent ( HASH )
296 returns a human readable 'relay agent options', not to be confused
297 with "decodeRelayAgent"
298 I packcsr( ARRAYREF )
300 returns the packed Classless Static Route option built from a list
301 of CIDR style address/mask combos
302 unpackcsr
304 Not implemented, currently croaks.
305 addOption ( CODE, VALUE )
307 Removed as of version 0.60. Please use "addOptionRaw()" instead.
308 getOption ( CODE )
310 Removed as of version 0.60. Please use "getOptionRaw()" instead.
311 DHCP OPTIONS TYPES
313 This section describes supported option types (cf. RFC 2132).
314 For unsupported data types, please use "getOptionRaw()" and
316 "addOptionRaw" to manipulate binary format directly.
317 dhcp message type
319 Only supported for DHO_DHCP_MESSAGE_TYPE (053) option. Converts a
320 integer to a single byte.
321 Option code for 'dhcp message' format:
323 (053) DHO_DHCP_MESSAGE_TYPE
325 Example:
327 $pac->addOptionValue(DHO_DHCP_MESSAGE_TYPE(), DHCPINFORM());
329 string
331 Pure string attribute, no type conversion.
332 Option codes for 'string' format:
334 (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 Example:
352 $pac->addOptionValue(DHO_TFTP_SERVER(), "foobar");
354 single ip address
356 Exactly one IP address, in dotted numerical format '192.168.1.1'.
357 Option codes for 'single ip address' format:
359 (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 Example:
369 $pac->addOptionValue(DHO_SUBNET_MASK(), "255.255.255.0");
371 multiple ip addresses
373 Any number of IP address, in dotted numerical format '192.168.1.1'.
374 Empty value allowed.
375 Option codes for 'multiple ip addresses' format:
377 (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 Example:
405 $pac->addOptionValue(DHO_NAME_SERVERS(), "10.0.0.11 192.168.1.10");
407 pairs of ip addresses
409 Even number of IP address, in dotted numerical format
410 '192.168.1.1'. Empty value allowed.
411 Option codes for 'pairs of ip address' format:
413 (021) DHO_POLICY_FILTER
415 (033) DHO_STATIC_ROUTES
416 Example:
418 $pac->addOptionValue(DHO_STATIC_ROUTES(), "10.0.0.1 192.168.1.254");
420 byte, short and integer
422 Numerical value in byte (8 bits), short (16 bits) or integer (32
423 bits) format.
424 Option codes for 'byte (8)' format:
426 (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 Option codes for 'short (16)' format:
443 (013) DHO_BOOT_SIZE
445 (022) DHO_MAX_DGRAM_REASSEMBLY
446 (026) DHO_INTERFACE_MTU
447 (057) DHO_DHCP_MAX_MESSAGE_SIZE
448 Option codes for 'integer (32)' format:
450 (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 Examples:
460 $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 multiple bytes, shorts
466 A list a bytes or shorts.
467 Option codes for 'multiple bytes (8)' format:
469 (055) DHO_DHCP_PARAMETER_REQUEST_LIST
471 Option codes for 'multiple shorts (16)' format:
473 (025) DHO_PATH_MTU_PLATEAU_TABLE
475 (117) DHO_NAME_SERVICE_SEARCH
476 Examples:
478 $pac->addOptionValue(DHO_DHCP_PARAMETER_REQUEST_LIST(), "1 3 6 12 15 28 42 72");
480 SERIALIZATION METHODS
482 serialize ()
483 Converts a Net::DHCP::Packet to a string, ready to put on the
484 network.
485 marshall ( BYTES )
487 The inverse of serialize. Converts a string, presumably a received
488 UDP packet, into a Net::DHCP::Packet.
489 If the packet is malformed, a fatal error is produced.
491 HELPER METHODS
493 toString ()
494 Returns a textual representation of the packet, for debugging.
495 packinet ( STRING )
497 Transforms a IP address "xx.xx.xx.xx" into a packed 4 bytes string.
498 These are simple never failing versions of inet_ntoa and inet_aton.
500 packinets ( STRING )
502 Transforms a list of space delimited IP addresses into a packed
503 bytes string.
504 packinets_array( LIST )
506 Transforms an array (list) of IP addresses into a packed bytes
507 string.
508 unpackinet ( STRING )
510 Transforms a packed bytes IP address into a "xx.xx.xx.xx" string.
511 unpackinets ( STRING )
513 Transforms a packed bytes list of IP addresses into a list of
514 "xx.xx.xx.xx" space delimited string.
515 unpackinets_array ( STRING )
517 Transforms a packed bytes list of IP addresses into a array of
518 "xx.xx.xx.xx" strings.
519 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 ciaddrRaw ( [STRING])
526 Sets/gets the client IP address in packed 4 characters binary
527 strings.
528 yiaddrRaw ( [STRING] )
530 Sets/gets the your IP address in packed 4 characters binary
531 strings.
532 siaddrRaw ( [STRING] )
534 Sets/gets the next server IP address in packed 4 characters binary
535 strings.
536 giaddrRaw ( [STRING] )
538 Sets/gets the relay agent IP address in packed 4 characters binary
539 strings.
540 chaddrRaw ( [STRING] )
542 Sets/gets the client hardware address in packed binary string. Its
543 length is given by the "hlen" attribute.
544
546 Sending a simple DHCP packet:
547 #!/usr/bin/perl
549 # Simple DHCP client - sending a broadcasted DHCP Discover request
550 use IO::Socket::INET;
552 use Net::DHCP::Packet;
553 use Net::DHCP::Constants;
554 # 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 # 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 Sniffing DHCP packets.
573 #!/usr/bin/perl
575 # Simple DHCP server - listen to DHCP packets and print them
576 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 Sending a LEASEQUERY (provided by John A. Murphy).
587 #!/usr/bin/perl
589 # Simple DHCP client - send a LeaseQuery (by IP) and receive the response
590 use IO::Socket::INET;
592 use Net::DHCP::Packet;
593 use Net::DHCP::Constants;
594 $usage = "usage: $0 DHCP_SERVER_IP DHCP_CLIENT_IP\n"; $ARGV[1] || die $usage;
596 # 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 # 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 # send request
617 $handle->send($inform->serialize()) or die "Error sending LeaseQuery: $!\n";
618 #receive response
620 $handle->recv($newmsg, 1024) or die;
621 $packet = Net::DHCP::Packet->new($newmsg);
622 print $packet->toString();
623 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
629 Dean Hamstead <djzort@cpan.org> Previously Stephan Hadinger
630 <shadinger@cpan.org>. Original version by F. van Dun.
631
633 See <https://rt.cpan.org/Dist/Display.html?Queue=Net-DHCP>
634
636 Many young people like to use Github, so by all means send me pull
637 requests at
638 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
646 Net::DHCP::Options, Net::DHCP::Constants.
647perl v5.30.0 2019-07-26 Net::DHCP::Packet(3)