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.7
10
12 use Net::DHCP::Packet;
13 my $p = Net::DHCP::Packet->new(
15 'Chaddr' => '000BCDEF',
17 'Xid' => 0x9F0FD,
18 'Ciaddr' => '0.0.0.0',
19 'Siaddr' => '0.0.0.0',
20 'Hops' => 0
21 );
23
25 Represents a DHCP packet as specified in RFC 1533, RFC 2132.
26
28 This module only provides basic constructor. For "easy" constructors,
29 you can use the Net::DHCP::Session module.
30 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 Without argument, a default empty packet is created.
38 $packet = Net::DHCP::Packet();
40 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 use IO::Socket::INET;
46 use Net::DHCP::Packet;
47 $sock = IO::Socket::INET->new(LocalPort => 67, Proto => "udp", Broadcast => 1)
49 or die "socket: $@";
50 while ($sock->recv($newmsg, 1024)) {
52 $packet = Net::DHCP::Packet->new($newmsg);
53 print $packet->toString();
54 }
55 To create a fresh new packet new() takes arguments as a key-value
57 pairs :
58 ARGUMENT FIELD OCTETS DESCRIPTION
60 -------- ----- ------ -----------
61 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 See below methods for values and syntax description.
99 Note: DHCP options are created in the same order as key-value
101 pairs.
102
104 ATTRIBUTE METHODS
105 See Net::DHCP::Packet::Attributes
106 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 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 Raw binary functions are provided for pure performance optimization,
117 and for unsupported types manipulation.
118 addOptionValue ( CODE, VALUE )
120 Adds a DHCP option field. Common code values are listed in
121 "Net::DHCP::Constants" "DHO_"*.
122 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 If you need access to the raw binary values, please use
128 addOptionRaw().
129 $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 addSubOptionValue ( CODE, SUBCODE, VALUE )
135 Adds a DHCP sub-option field. Common code values are listed in
136 "Net::DHCP::Constants" "SUBOPTION_"*.
137 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 If you need access to the raw binary values, please use
143 addSubOptionRaw().
144 $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 getOptionValue ( CODE )
151 Returns the value of a DHCP option.
152 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 If you need access to the raw binary values, please use
158 getOptionRaw().
159 Return value is either a string or an array, depending on the
161 context.
162 $ip = $pac->getOptionValue(DHO_SUBNET_MASK());
164 $ips = $pac->getOptionValue(DHO_NAME_SERVERS());
165 addOptionRaw ( CODE, VALUE, BOOLEAN )
167 Adds a DHCP OPTION provided in packed binary format. Please see
168 corresponding RFC for manual type conversion.
169 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 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 getOptionRaw ( CODE )
179 Gets a DHCP OPTION provided in packed binary format. Please see
180 corresponding RFC for manual type conversion.
181 getSubOptionRaw ( CODE, SUBCODE )
183 Gets a DHCP SUB-OPTION provided in packed binary format. Please
184 see corresponding RFC for manual type conversion.
185 getSubOptionValue ()
187 This is an empty stub for now
188 removeSubOption ()
190 This is an empty stub for now
191 removeOption ( CODE )
193 Remove option from option list.
194 packclientid( VALUE )
196 returns the packed Client-identifier (pass-through currently)
197 See <https://tools.ietf.org/html/rfc2132#section-9.14> See also
199 <https://tools.ietf.org/html/rfc4361>
200 unpackclientid
202 returns the unpacked clientid.
203 Decodes:
205 type 0 as a string
206 type 1 as a mac address (hex string)
207 everything is passed through
208 See <https://tools.ietf.org/html/rfc2132#section-9.14> See also
210 <https://tools.ietf.org/html/rfc4361>
211 packsipserv( VALUE )
213 returns the packed sip server field (pass-through currently)
214 unpacksipserv
216 returns the unpacked sip server.
217 Decodes:
219 type 1 as an ipv4 address
220 everything is passed through
221 packcsr( ARRAYREF )
223 returns the packed Classless Static Route option built from a list
224 of CIDR style address/mask combos
225 unpackcsr
227 Not implemented, currently croaks.
228 addOption ( CODE, VALUE )
230 Removed as of version 0.60. Please use addOptionRaw() instead.
231 getOption ( CODE )
233 Removed as of version 0.60. Please use getOptionRaw() instead.
234 DHCP OPTIONS TYPES
236 This section describes supported option types (cf. RFC 2132).
237 For unsupported data types, please use getOptionRaw() and
239 "addOptionRaw" to manipulate binary format directly.
240 dhcp message type
242 Only supported for DHO_DHCP_MESSAGE_TYPE (053) option. Converts a
243 integer to a single byte.
244 Option code for 'dhcp message' format:
246 (053) DHO_DHCP_MESSAGE_TYPE
248 Example:
250 $pac->addOptionValue(DHO_DHCP_MESSAGE_TYPE(), DHCPINFORM());
252 string
254 Pure string attribute, no type conversion.
255 Option codes for 'string' format:
257 (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 Example:
275 $pac->addOptionValue(DHO_TFTP_SERVER(), "foobar");
277 single ip address
279 Exactly one IP address, in dotted numerical format '192.168.1.1'.
280 Option codes for 'single ip address' format:
282 (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 Example:
292 $pac->addOptionValue(DHO_SUBNET_MASK(), "255.255.255.0");
294 multiple ip addresses
296 Any number of IP address, in dotted numerical format '192.168.1.1'.
297 Empty value allowed.
298 Option codes for 'multiple ip addresses' format:
300 (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 Example:
328 $pac->addOptionValue(DHO_NAME_SERVERS(), "10.0.0.11 192.168.1.10");
330 pairs of ip addresses
332 Even number of IP address, in dotted numerical format
333 '192.168.1.1'. Empty value allowed.
334 Option codes for 'pairs of ip address' format:
336 (021) DHO_POLICY_FILTER
338 (033) DHO_STATIC_ROUTES
339 Example:
341 $pac->addOptionValue(DHO_STATIC_ROUTES(), "10.0.0.1 192.168.1.254");
343 byte, short and integer
345 Numerical value in byte (8 bits), short (16 bits) or integer (32
346 bits) format.
347 Option codes for 'byte (8)' format:
349 (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 Option codes for 'short (16)' format:
366 (013) DHO_BOOT_SIZE
368 (022) DHO_MAX_DGRAM_REASSEMBLY
369 (026) DHO_INTERFACE_MTU
370 (057) DHO_DHCP_MAX_MESSAGE_SIZE
371 Option codes for 'integer (32)' format:
373 (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 Examples:
383 $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 multiple bytes, shorts
389 A list a bytes or shorts.
390 Option codes for 'multiple bytes (8)' format:
392 (055) DHO_DHCP_PARAMETER_REQUEST_LIST
394 Option codes for 'multiple shorts (16)' format:
396 (025) DHO_PATH_MTU_PLATEAU_TABLE
398 (117) DHO_NAME_SERVICE_SEARCH
399 Examples:
401 $pac->addOptionValue(DHO_DHCP_PARAMETER_REQUEST_LIST(), "1 3 6 12 15 28 42 72");
403 SERIALIZATION METHODS
405 serialize ()
406 Converts a Net::DHCP::Packet to a string, ready to put on the
407 network.
408 marshall ( BYTES )
410 The inverse of serialize. Converts a string, presumably a received
411 UDP packet, into a Net::DHCP::Packet.
412 If the packet is malformed, a fatal error is produced.
414 HELPER METHODS
416 toString ()
417 Returns a textual representation of the packet, for debugging.
418 packsuboptions ( LIST )
420 Transforms an list of lists into packed option. For option 43
421 (vendor specific), 82 (relay agent) etc.
422 unpacksuboptions ( STRING )
424 Unpacks sub-options to a list of lists
425 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 If the level is set to 1, even the absolute minimum just warns.
433 Setting the level to 2 means the packet length checks are skipped
435 altogether.
436 Without a parameter, the method returns the current level.
438 See also Net::DHCP::Packet::IPv4Utils
440
442 Sending a simple DHCP packet:
443 #!/usr/bin/perl
445 # Simple DHCP client - sending a broadcasted DHCP Discover request
446 use IO::Socket::INET;
448 use Net::DHCP::Packet;
449 use Net::DHCP::Constants;
450 # 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 # 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 Sniffing DHCP packets.
469 #!/usr/bin/perl
471 # Simple DHCP server - listen to DHCP packets and print them
472 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 Sending a LEASEQUERY (provided by John A. Murphy).
483 #!/usr/bin/perl
485 # Simple DHCP client - send a LeaseQuery (by IP) and receive the response
486 use IO::Socket::INET;
488 use Net::DHCP::Packet;
489 use Net::DHCP::Constants;
490 $usage = "usage: $0 DHCP_SERVER_IP DHCP_CLIENT_IP\n"; $ARGV[1] || die $usage;
492 # 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 # 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 # send request
513 $handle->send($inform->serialize()) or die "Error sending LeaseQuery: $!\n";
514 #receive response
516 $handle->recv($newmsg, 1024) or die;
517 $packet = Net::DHCP::Packet->new($newmsg);
518 print $packet->toString();
519 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
525 Net::DHCP::Options, Net::DHCP::Constants, Net::DHCP::IPv4Utils,
526 Net::DHCP::Attributes, Net::DHCP::OrderOptions.
527
529 Dean Hamstead <dean@fragfest.com.au>
530
532 This software is Copyright (c) 2022 by Dean Hamstead.
533 This is free software, licensed under:
535 The MIT (X11) License
537perl v5.36.0 2023-01-20 Net::DHCP::Packet(3)