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 packet object class
7

SYNOPSIS

9       "use Net::DNS::Packet;"
10

DESCRIPTION

12       A "Net::DNS::Packet" object represents a DNS packet.
13

METHODS

15   new
16           $packet = Net::DNS::Packet->new("example.com");
17           $packet = Net::DNS::Packet->new("example.com", "MX", "IN");
18
19           $packet = Net::DNS::Packet->new(\$data);
20           $packet = Net::DNS::Packet->new(\$data, 1);  # set debugging
21
22           ($packet, $err) = Net::DNS::Packet->new(\$data);
23
24           $packet = Net::DNS::Packet->new();
25
26       If passed a domain, type, and class, "new" creates a packet object
27       appropriate for making a DNS query for the requested information.  The
28       type and class can be omitted; they default to A and IN.
29
30       If passed a reference to a scalar containing DNS packet data, "new"
31       creates a packet object from that data.  A second argument can be
32       passed to turn on debugging output for packet parsing.
33
34       If called in array context, returns a packet object and an error
35       string.  The error string will only be defined if the packet object is
36       undefined (i.e., couldn't be created).
37
38       Returns undef if unable to create a packet object (e.g., if the packet
39       data is truncated).
40
41       If called with an empty argument list, "new" creates an empty packet.
42
43   data
44           $data = $packet->data;
45
46       Returns the packet data in binary format, suitable for sending to a
47       nameserver.
48
49   header
50           $header = $packet->header;
51
52       Returns a "Net::DNS::Header" object representing the header section of
53       the packet.
54
55   question, zone
56           @question = $packet->question;
57
58       Returns a list of "Net::DNS::Question" objects representing the
59       question section of the packet.
60
61       In dynamic update packets, this section is known as "zone" and
62       specifies the zone to be updated.
63
64   answer, pre, prerequisite
65           @answer = $packet->answer;
66
67       Returns a list of "Net::DNS::RR" objects representing the answer
68       section of the packet.
69
70       In dynamic update packets, this section is known as "pre" or
71       "prerequisite" and specifies the RRs or RRsets which must or must not
72       preexist.
73
74   authority, update
75           @authority = $packet->authority;
76
77       Returns a list of "Net::DNS::RR" objects representing the authority
78       section of the packet.
79
80       In dynamic update packets, this section is known as "update" and
81       specifies the RRs or RRsets to be added or deleted.
82
83   additional
84           @additional = $packet->additional;
85
86       Returns a list of "Net::DNS::RR" objects representing the additional
87       section of the packet.
88
89   print
90           $packet->print;
91
92       Prints the packet data on the standard output in an ASCII format
93       similar to that used in DNS zone files.
94
95   string
96           print $packet->string;
97
98       Returns a string representation of the packet.
99
100   answerfrom
101           print "packet received from ", $packet->answerfrom, "\n";
102
103       Returns the IP address from which we received this packet.  User-
104       created packets will return undef for this method.
105
106   answersize
107           print "packet size: ", $packet->answersize, " bytes\n";
108
109       Returns the size of the packet in bytes as it was received from a
110       nameserver.  User-created packets will return undef for this method
111       (use "length $packet->data" instead).
112
113   push
114           $ancount = $packet->push(pre        => $rr);
115           $nscount = $packet->push(update     => $rr);
116           $arcount = $packet->push(additional => $rr);
117
118           $nscount = $packet->push(update => $rr1, $rr2, $rr3);
119           $nscount = $packet->push(update => @rr);
120
121       Adds RRs to the specified section of the packet.
122
123       Returns the number of resource records in the specified section.
124
125   unique_push
126           $ancount = $packet->unique_push(pre        => $rr);
127           $nscount = $packet->unique_push(update     => $rr);
128           $arcount = $packet->unique_push(additional => $rr);
129
130           $nscount = $packet->unique_push(update => $rr1, $rr2, $rr3);
131           $nscount = $packet->unique_push(update => @rr);
132
133       Adds RRs to the specified section of the packet provided that the RRs
134       do not already exist in the packet.
135
136       Returns the number of resource records in the specified section.
137
138   safe_push
139       A deprecated name for "unique_push()".
140
141   pop
142           my $rr = $packet->pop("pre");
143           my $rr = $packet->pop("update");
144           my $rr = $packet->pop("additional");
145           my $rr = $packet->pop("question");
146
147       Removes RRs from the specified section of the packet.
148
149   dn_comp
150           $compname = $packet->dn_comp("foo.example.com", $offset);
151
152       Returns a domain name compressed for a particular packet object, to be
153       stored beginning at the given offset within the packet data.  The name
154       will be added to a running list of compressed domain names for future
155       use.
156
157   dn_expand
158           use Net::DNS::Packet qw(dn_expand);
159           ($name, $nextoffset) = dn_expand(\$data, $offset);
160
161           ($name, $nextoffset) = Net::DNS::Packet::dn_expand(\$data, $offset);
162
163       Expands the domain name stored at a particular location in a DNS
164       packet.  The first argument is a reference to a scalar containing the
165       packet data.  The second argument is the offset within the packet where
166       the (possibly compressed) domain name is stored.
167
168       Returns the domain name and the offset of the next location in the
169       packet.
170
171       Returns (undef) if the domain name couldn't be expanded.
172
173   sign_tsig
174           $key_name = "tsig-key";
175           $key      = "awwLOtRfpGE+rRKF2+DEiw==";
176
177           $update = Net::DNS::Update->new("example.com");
178           $update->push("update", rr_add("foo.example.com A 10.1.2.3"));
179
180           $update->sign_tsig($key_name, $key);
181
182           $response = $res->send($update);
183
184       Signs a packet with a TSIG resource record (see RFC 2845).  Uses the
185       following defaults:
186
187           algorithm   = HMAC-MD5.SIG-ALG.REG.INT
188           time_signed = current time
189           fudge       = 300 seconds
190
191       If you wish to customize the TSIG record, you'll have to create it
192       yourself and call the appropriate Net::DNS::RR::TSIG methods.  The
193       following example creates a TSIG record and sets the fudge to 60
194       seconds:
195
196           $key_name = "tsig-key";
197           $key      = "awwLOtRfpGE+rRKF2+DEiw==";
198
199           $tsig = Net::DNS::RR->new("$key_name TSIG $key");
200           $tsig->fudge(60);
201
202           $query = Net::DNS::Packet->new("www.example.com");
203           $query->sign_tsig($tsig);
204
205           $response = $res->send($query);
206
207       You shouldn't modify a packet after signing it; otherwise
208       authentication will probably fail.
209
210   sign_sig0
211       SIG0 support is provided through the Net::DNS::RR::SIG class. This
212       class is not part of the default Net::DNS distribution but resides in
213       the Net::DNS::SEC distribution.
214
215           $update = Net::DNS::Update->new("example.com");
216           $update->push("update", rr_add("foo.example.com A 10.1.2.3"));
217           $update->sign_sig0("Kexample.com+003+25317.private");
218
219       SIG0 support is experimental see Net::DNS::RR::SIG for details.
220
221       The method will call "Carp::croak()" if Net::DNS::RR::SIG cannot be
222       found.
223

COPYRIGHT

225       Copyright (c) 1997-2002 Michael Fuhr.
226
227       Portions Copyright (c) 2002-2004 Chris Reinhardt.
228
229       Portions Copyright (c) 2002-2005 Olaf Kolkman
230
231       Portions Copyright (c) 2007-2008 Dick Franks
232
233       All rights reserved.  This program is free software; you may
234       redistribute it and/or modify it under the same terms as Perl itself.
235

NAME

SYNOPSIS

DESCRIPTION

METHODS

COPYRIGHT

SEE ALSO