Net::DNS::Packet(3pm)

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

NAME

6       Net::DNS::Packet - DNS protocol packet
7

SYNOPSIS

9           use Net::DNS::Packet;
10
11           $query = new Net::DNS::Packet('example.com', 'MX', 'IN');
12
13           $reply = $resolver->send($query);
14

DESCRIPTION

16       A "Net::DNS::Packet" object represents a DNS protocol packet.
17

METHODS

19   new
20           $packet = new Net::DNS::Packet('example.com');
21           $packet = new Net::DNS::Packet('example.com', 'MX', 'IN');
22
23           $packet = new Net::DNS::Packet();
24
25       If passed a domain, type, and class, "new" creates a packet object
26       appropriate for making a DNS query for the requested information.  The
27       type and class can be omitted; they default to A and IN.
28
29       If called with an empty argument list, "new" creates an empty packet.
30
31           $packet = new Net::DNS::Packet(\$data);
32           $packet = new Net::DNS::Packet(\$data, 1);          # set debugging
33
34       If passed a reference to a scalar containing DNS packet data, a new
35       packet object is created by decoding the data.  The optional second
36       boolean argument is used to enable debugging output.
37
38       Returns undef if unable to create a packet object.
39
40       Decoding errors, including data corruption and truncation, are
41       collected in the $@ ($EVAL_ERROR) variable.
42
43           ($packet, $length) = new Net::DNS::Packet(\$data);
44
45       If called in array context, returns a packet object and the number of
46       octets successfully decoded.
47
48       Note that the number of RRs in each section of the packet may differ
49       from the corresponding header value if the data has been truncated or
50       corrupted.
51
52   data
53           $data = $packet->data;
54           $data = $packet->data($limit);
55
56       Returns the packet data in binary format, suitable for sending to a
57       nameserver.
58
59   header
60           $header = $packet->header;
61
62       Constructor method which returns a reference to the unique
63       "Net::DNS::Header" object which represents the header section of the
64       packet.
65
66   EDNS extended header
67           $edns    = $packet->edns;
68           $version = $edns->version;
69           $size    = $edns->size;
70
71       Auxilliary function edns() provides access to EDNS extensions.
72
73   reply
74           $reply = $query->reply( $UDPmax );
75
76       Constructor method which returns a new reply packet.
77
78       The optional UDPsize argument is the maximum UDP packet size which can
79       be reassembled by the local network stack, and is advertised in
80       response to an EDNS query.
81
82   question, zone
83           @question = $packet->question;
84
85       Returns a list of "Net::DNS::Question" objects representing the
86       question section of the packet.
87
88       In dynamic update packets, this section is known as "zone" and
89       specifies the zone to be updated.
90
91   answer, pre, prerequisite
92           @answer = $packet->answer;
93
94       Returns a list of "Net::DNS::RR" objects representing the answer
95       section of the packet.
96
97       In dynamic update packets, this section is known as "pre" or
98       "prerequisite" and specifies the RRs or RRsets which must or must not
99       preexist.
100
101   authority, update
102           @authority = $packet->authority;
103
104       Returns a list of "Net::DNS::RR" objects representing the authority
105       section of the packet.
106
107       In dynamic update packets, this section is known as "update" and
108       specifies the RRs or RRsets to be added or deleted.
109
110   additional
111           @additional = $packet->additional;
112
113       Returns a list of "Net::DNS::RR" objects representing the additional
114       section of the packet.
115
116   print
117           $packet->print;
118
119       Prints the packet data on the standard output in an ASCII format
120       similar to that used in DNS zone files.
121
122   string
123           print $packet->string;
124
125       Returns a string representation of the packet.
126
127   answerfrom
128           print "packet received from ", $packet->answerfrom, "\n";
129
130       Returns the IP address from which we received this packet.  User-
131       created packets will return undef for this method.
132
133   answersize
134           print "packet size: ", $packet->answersize, " bytes\n";
135
136       Returns the size of the packet in bytes as it was received from a
137       nameserver.  User-created packets will return undef for this method
138       (use "length $packet->data" instead).
139
140   push
141           $ancount = $packet->push(prereq => $rr);
142           $nscount = $packet->push(update => $rr);
143           $arcount = $packet->push(additional => $rr);
144
145           $nscount = $packet->push(update => $rr1, $rr2, $rr3);
146           $nscount = $packet->push(update => @rr);
147
148       Adds RRs to the specified section of the packet.
149
150       Returns the number of resource records in the specified section.
151
152   unique_push
153           $ancount = $packet->unique_push(prereq => $rr);
154           $nscount = $packet->unique_push(update => $rr);
155           $arcount = $packet->unique_push(additional => $rr);
156
157           $nscount = $packet->unique_push(update => $rr1, $rr2, $rr3);
158           $nscount = $packet->unique_push(update => @rr);
159
160       Adds RRs to the specified section of the packet provided that the RRs
161       do not already exist in the packet.
162
163       Returns the number of resource records in the specified section.
164
165   pop
166           my $rr = $packet->pop("pre");
167           my $rr = $packet->pop("update");
168           my $rr = $packet->pop("additional");
169           my $rr = $packet->pop("question");
170
171       Removes RRs from the specified section of the packet.
172
173   dn_comp
174           $compname = $packet->dn_comp("foo.example.com", $offset);
175
176       Returns a domain name compressed for a particular packet object, to be
177       stored beginning at the given offset within the packet data.  The name
178       will be added to a running list of compressed domain names for future
179       use.
180
181   dn_expand
182           use Net::DNS::Packet qw(dn_expand);
183           ($name, $nextoffset) = dn_expand(\$data, $offset);
184
185           ($name, $nextoffset) = Net::DNS::Packet::dn_expand(\$data, $offset);
186
187       Expands the domain name stored at a particular location in a DNS
188       packet.  The first argument is a reference to a scalar containing the
189       packet data.  The second argument is the offset within the packet where
190       the (possibly compressed) domain name is stored.
191
192       Returns the domain name and the offset of the next location in the
193       packet.
194
195       Returns undef if the domain name could not be expanded.
196
197   sign_tsig
198           $key_name = "tsig-key";
199           $key      = "awwLOtRfpGE+rRKF2+DEiw==";
200
201           $update = Net::DNS::Update->new("example.com");
202           $update->push("update", rr_add("foo.example.com A 10.1.2.3"));
203
204           $update->sign_tsig($key_name, $key);
205
206           $response = $res->send($update);
207
208       Attaches a TSIG resource record object containing a key, which will be
209       used to sign a packet with a TSIG resource record (see RFC 2845).  Uses
210       the following defaults:
211
212           algorithm   = HMAC-MD5.SIG-ALG.REG.INT
213           time_signed = current time
214           fudge       = 300 seconds
215
216       If you wish to customize the TSIG record, you'll have to create it
217       yourself and call the appropriate Net::DNS::RR::TSIG methods.  The
218       following example creates a TSIG record and sets the fudge to 60
219       seconds:
220
221           $key_name = "tsig-key";
222           $key      = "awwLOtRfpGE+rRKF2+DEiw==";
223
224           $tsig = Net::DNS::RR->new("$key_name TSIG $key");
225           $tsig->fudge(60);
226
227           $query = Net::DNS::Packet->new("www.example.com");
228           $query->sign_tsig($tsig);
229
230           $response = $res->send($query);
231
232   sign_sig0
233       SIG0 support is provided through the Net::DNS::RR::SIG class. This
234       class is not part of the default Net::DNS distribution but resides in
235       the Net::DNS::SEC distribution.
236
237           $update = Net::DNS::Update->new("example.com");
238           $update->push("update", rr_add("foo.example.com A 10.1.2.3"));
239           $update->sign_sig0("Kexample.com+003+25317.private");
240
241       SIG0 support is experimental see Net::DNS::RR::SIG for details.
242
243       The method will call "Carp::croak()" if Net::DNS::RR::SIG cannot be
244       found.
245
246   truncate
247       The truncate method takes a maximum length as argument and then tries
248       to truncate the packet an set the TC bit according to the rules of
249       RFC2181 Section 9.
250
251       The minimum maximum length that is honored is 512 octets.
252

COPYRIGHT

254       Copyright (c)1997-2002 Michael Fuhr.
255
256       Portions Copyright (c)2002-2004 Chris Reinhardt.
257
258       Portions Copyright (c)2002-2009 Olaf Kolkman
259
260       Portions Copyright (c)2007-2008 Dick Franks
261
262       All rights reserved.
263
264       This program is free software; you may redistribute it and/or modify it
265       under the same terms as Perl itself.
266

NAME

SYNOPSIS

DESCRIPTION

METHODS

COPYRIGHT

SEE ALSO