Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Net::DHCP::Packet(3)  User Contributed Perl Documentation Net::DHCP::Packet(3)

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

VERSION
       version 0.696

SYNOPSIS
	  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);

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

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

       new( )
       new( BUFFER )
       new( ARG	=> VALUE, ARG => VALUE... )
	   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.

METHODS
   ATTRIBUTE METHODS
       comment(	[STRING] )
	   Sets	or gets	the comment attribute (object meta-data	only)

       op( [BYTE] )
	   Sets/gets the BOOTP opcode.

	   Normal values are:

	     BOOTREQUEST()
	     BOOTREPLY()

       htype( [BYTE] )
	   Sets/gets the hardware address type.

	   Common value	is: "HTYPE_ETHER()" (1)	= ethernet

       hlen ( [BYTE] )
	   Sets/gets the hardware address length. Value	must be	between	0 and
	   16.

	   For most NIC's, the MAC address has 6 bytes.

       hops ( [BYTE] )
	   Sets/gets the number	of hops.

	   This	field is incremented by	each encountered DHCP relay agent.

       xid ( [INTEGER] )
	   Sets/gets the 32 bits transaction id.

	   This	field should be	a random value set by the DHCP client.

       secs ( [SHORT] )
	   Sets/gets the 16 bits elapsed boot time in seconds.

       flags ( [SHORT] )
	   Sets/gets the 16 bits flags.

	     0x8000 = Broadcast	reply requested.

       ciaddr (	[STRING] )
	   Sets/gets the client	IP address.

	   IP address is only accepted as a string like	'10.24.50.3'.

	   Note: IP address is internally stored as a 4	bytes binary string.
	   See "Special	methods" below.

       yiaddr (	[STRING] )
	   Sets/gets the your IP address.

	   IP address is only accepted as a string like	'10.24.50.3'.

	   Note: IP address is internally stored as a 4	bytes binary string.
	   See "Special	methods" below.

       siaddr (	[STRING] )
	   Sets/gets the next server IP	address.

	   IP address is only accepted as a string like	'10.24.50.3'.

	   Note: IP address is internally stored as a 4	bytes binary string.
	   See "Special	methods" below.

       giaddr (	[STRING] )
	   Sets/gets the relay agent IP	address.

	   IP address is only accepted as a string like	'10.24.50.3'.

	   Note: IP address is internally stored as a 4	bytes binary string.
	   See "Special	methods" below.

       chaddr (	[STRING] )
	   Sets/gets the client	hardware address. Its length is	given by the
	   "hlen" attribute.

	   Value is formatted as an Hexadecimal	string representation.

	     Example: "0010A706DFFF" for 6 bytes mac address.

	   Note	: internal format is packed bytes string.  See "Special
	   methods" below.

       sname ( [STRING]	)
	   Sets/gets the "server host name". Maximum size is 63	bytes. If
	   greater a warning is	issued.

       file ( [STRING] )
	   Sets/gets the "boot file name". Maximum size	is 127 bytes. If
	   greater a warning is	issued.

       isDhcp (	[BOOLEAN] )
	   Sets/gets the DHCP cookie. Returns whether the cookie is valid or
	   not,	hence whether the packet is DHCP or BOOTP.

	   Default value is 1, valid DHCP cookie.

       padding ( [BYTES] )
	   Sets/gets the optional padding at the end of	the DHCP packet, i.e.
	   after DHCP options.

   DHCP	OPTIONS	METHODS
       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.

       addOptionValue (	CODE, VALUE )
	   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"));

       addSubOptionValue ( CODE, SUBCODE, VALUE	)
	   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 exampls
	      $pac->addSubOption(DHO_DHCP_MESSAGE_TYPE(), DHCPINFORM());
	      $pac->addSubOption(DHO_NAME_SERVERS(), "10.0.0.1", "10.0.0.2"));

       getOptionValue (	CODE )
	   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());

       addOptionRaw ( CODE, VALUE )
	   Adds	a DHCP OPTION provided in packed binary	format.	 Please	see
	   corresponding RFC for manual	type conversion.

       addSubOptionRaw ( CODE, SUBCODE,	VALUE )
	   Adds	a DHCP SUB-OPTION provided in packed binary format.  Please
	   see corresponding RFC for manual type conversion.

       getOptionRaw ( CODE )
	   Gets	a DHCP OPTION provided in packed binary	format.	 Please	see
	   corresponding RFC for manual	type conversion.

       getSubOptionRaw ( CODE, SUBCODE )
	   Gets	a DHCP SUB-OPTION provided in packed binary format.  Please
	   see corresponding RFC for manual type conversion.

       getSubOptionValue ()
	   This	is an empty stub for now

       removeSubOption ()
	   This	is an empty stub for now

       removeOption ( CODE )
	   Remove option from option list.

       encodeRelayAgent	()
	   These are half baked, but will encode the relay agent options in
	   the future

       decodeRelayAgent	()
	   These are half baked, but will decode the relay agent options in
	   the future

       unpackRelayAgent	( HASH )
	   returns a human readable 'relay agent options', not to be confused
	   with	"decodeRelayAgent"

       I packcsr( ARRAYREF )
	   returns the packed Classless	Static Route option built from a list
	   of CIDR style address/mask combos

       unpackcsr
	   Not implemented, currently croaks.

       addOption ( CODE, VALUE )
	   Removed as of version 0.60. Please use "addOptionRaw()" instead.

       getOption ( CODE	)
	   Removed as of version 0.60. Please use "getOptionRaw()" instead.

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

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

       dhcp message type
	   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());

       string
	   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");

       single ip address
	   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");

       multiple	ip addresses
	   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");

       pairs of	ip addresses
	   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");

       byte, short and integer
	   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);

       multiple	bytes, shorts
	   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");

   SERIALIZATION METHODS
       serialize ()
	   Converts a Net::DHCP::Packet	to a string, ready to put on the
	   network.

       marshall	( BYTES	)
	   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.

   HELPER METHODS
       toString	()
	   Returns a textual representation of the packet, for debugging.

       packinet	( STRING )
	   Transforms a	IP address "xx.xx.xx.xx" into a	packed 4 bytes string.

	   These are simple never failing versions of inet_ntoa	and inet_aton.

       packinets ( STRING )
	   Transforms a	list of	space delimited	IP addresses into a packed
	   bytes string.

       packinets_array(	LIST )
	   Transforms an array (list) of IP addresses into a packed bytes
	   string.

       unpackinet ( STRING )
	   Transforms a	packed bytes IP	address	into a "xx.xx.xx.xx" string.

       unpackinets ( STRING )
	   Transforms a	packed bytes list of IP	addresses into a list of
	   "xx.xx.xx.xx" space delimited string.

       unpackinets_array ( STRING )
	   Transforms a	packed bytes list of IP	addresses into a array of
	   "xx.xx.xx.xx" strings.

   SPECIAL METHODS
       These methods are provided for performance tuning only. They give
       access to internal data representation ,	thus avoiding unnecessary type
       conversion.

       ciaddrRaw ( [STRING])
	   Sets/gets the client	IP address in packed 4 characters binary
	   strings.

       yiaddrRaw ( [STRING] )
	   Sets/gets the your IP address in packed 4 characters	binary
	   strings.

       siaddrRaw ( [STRING] )
	   Sets/gets the next server IP	address	in packed 4 characters binary
	   strings.

       giaddrRaw ( [STRING] )
	   Sets/gets the relay agent IP	address	in packed 4 characters binary
	   strings.

       chaddrRaw ( [STRING] )
	   Sets/gets the client	hardware address in packed binary string.  Its
	   length is given by the "hlen" attribute.

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

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

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

GOT PATCHES?
       Many young people like to use Github, so	by all means send me pull
       requests	at

       https://github.com/djzort/Net-DHCP

COPYRIGHT
       This is free software. It can be	distributed and/or modified under the
       same terms as Perl itself.

SEE ALSO
       Net::DHCP::Options, Net::DHCP::Constants.

perl v5.24.1			  2017-07-03		  Net::DHCP::Packet(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | CONSTRUCTOR | METHODS | EXAMPLES | AUTHOR | BUGS | GOT PATCHES? | COPYRIGHT | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Net::DHCP::Packet&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help