root/docs/config/modules/dns.xml

Revision 2511639a540520051242159e76ed25a0351911fd, 8.0 kB (checked in by Theo Schlossnagle <jesus@omniti.com>, 2 years ago)

Updated DNS docs

  • Property mode set to 100644
Line 
1 <?xml version="1.0"?>
2 <section>
3   <title>dns</title>
4   <para>The dns module leverages libudns to allow highly concurrent DNS lookups of a variety of DNS RR types.  In the event that you name a dns check <parameter>in-addr.arpa</parameter> with an rtype of <parameter>PTR</parameter>, the result of the query may be used throughout reconnoiter as the identifying hostname of that target.</para>
5   <para>This module provides the <function>inaddrarpa</function> interpolation method which will reverse a dot-delimited IP address.  This is particularly useful for constructing in-addr.arpa queries, but also used for checking blacklists, whitelists and other IP-based DNS databases.</para>
6   <variablelist>
7     <varlistentry>
8       <term>loader</term>
9       <listitem>
10         <para>C</para>
11       </listitem>
12     </varlistentry>
13     <varlistentry>
14       <term>image</term>
15       <listitem>
16         <para>dns.so</para>
17       </listitem>
18     </varlistentry>
19   </variablelist>
20   <section>
21     <title>Module Configuration</title>
22   </section>
23   <section>
24     <title>Check Configuration</title>
25     <variablelist>
26       <varlistentry>
27         <term>nameserver</term>
28         <listitem>
29           <variablelist>
30             <varlistentry>
31               <term>required</term>
32               <listitem>
33                 <para>optional</para>
34               </listitem>
35             </varlistentry>
36             <varlistentry>
37               <term>default</term>
38               <listitem>
39                 <para>%[target_ip] or determined from underlying system</para>
40               </listitem>
41             </varlistentry>
42             <varlistentry>
43               <term>allowed</term>
44               <listitem>
45                 <para>.+</para>
46               </listitem>
47             </varlistentry>
48           </variablelist>
49           <para>The domain name server to query. If the name of the check is in-addr.arpa, the system default nameserver is used.  Otherwise, the nameserver is the %[target_ip] of the the check.  If set to the string "default" the underlying system default nameserver is used.</para>
50         </listitem>
51       </varlistentry>
52     </variablelist>
53     <variablelist>
54       <varlistentry>
55         <term>port</term>
56         <listitem>
57           <variablelist>
58             <varlistentry>
59               <term>required</term>
60               <listitem>
61                 <para>optional</para>
62               </listitem>
63             </varlistentry>
64             <varlistentry>
65               <term>default</term>
66               <listitem>
67                 <para>53</para>
68               </listitem>
69             </varlistentry>
70             <varlistentry>
71               <term>allowed</term>
72               <listitem>
73                 <para>\d+</para>
74               </listitem>
75             </varlistentry>
76           </variablelist>
77           <para>The port on which the remote server's DNS service is running.</para>
78         </listitem>
79       </varlistentry>
80     </variablelist>
81     <variablelist>
82       <varlistentry>
83         <term>ctype</term>
84         <listitem>
85           <variablelist>
86             <varlistentry>
87               <term>required</term>
88               <listitem>
89                 <para>optional</para>
90               </listitem>
91             </varlistentry>
92             <varlistentry>
93               <term>default</term>
94               <listitem>
95                 <para>IN</para>
96               </listitem>
97             </varlistentry>
98             <varlistentry>
99               <term>allowed</term>
100               <listitem>
101                 <para>(IN|CH|HS)</para>
102               </listitem>
103             </varlistentry>
104           </variablelist>
105           <para>The DNS class of the query. IN: Internet, CH: Chaos, HS: Hesoid.</para>
106         </listitem>
107       </varlistentry>
108     </variablelist>
109     <variablelist>
110       <varlistentry>
111         <term>rtype</term>
112         <listitem>
113           <variablelist>
114             <varlistentry>
115               <term>required</term>
116               <listitem>
117                 <para>optional</para>
118               </listitem>
119             </varlistentry>
120             <varlistentry>
121               <term>default</term>
122               <listitem>
123                 <para>A|PTR</para>
124               </listitem>
125             </varlistentry>
126             <varlistentry>
127               <term>allowed</term>
128               <listitem>
129                 <para>(A|AAAA|TXT|MX|SOA|CNAME|PTR|NS|MB|MD|MF|MG|MR)</para>
130               </listitem>
131             </varlistentry>
132           </variablelist>
133           <para>The DNS resource record type of the query.  If the name of the check is in-addr.arpa, the default is PTR, otherwise it is A.</para>
134         </listitem>
135       </varlistentry>
136     </variablelist>
137     <variablelist>
138       <varlistentry>
139         <term>query</term>
140         <listitem>
141           <variablelist>
142             <varlistentry>
143               <term>required</term>
144               <listitem>
145                 <para>required</para>
146               </listitem>
147             </varlistentry>
148             <varlistentry>
149               <term>default</term>
150               <listitem>
151                 <para>%[name]|%[:inaddrarpa:target_ip]</para>
152               </listitem>
153             </varlistentry>
154             <varlistentry>
155               <term>allowed</term>
156               <listitem>
157                 <para>.+</para>
158               </listitem>
159             </varlistentry>
160           </variablelist>
161           <para>The query to send.  If the name of the check is in-addr.arpa, the reverse IP octet notation of in-addr.arpa syntax is synthesized by default.  Otherwise the default query is the name of the check itself.</para>
162         </listitem>
163       </varlistentry>
164     </variablelist>
165     <variablelist>
166       <varlistentry>
167         <term>want_sort</term>
168         <listitem>
169           <variablelist>
170             <varlistentry>
171               <term>required</term>
172               <listitem>
173                 <para>optional</para>
174               </listitem>
175             </varlistentry>
176             <varlistentry>
177               <term>default</term>
178               <listitem>
179                 <para>true</para>
180               </listitem>
181             </varlistentry>
182             <varlistentry>
183               <term>allowed</term>
184               <listitem>
185                 <para>(true|false|on|off)</para>
186               </listitem>
187             </varlistentry>
188           </variablelist>
189           <para>Sorts (strcmp) the answers if multiple RRs are returned in the result set.</para>
190         </listitem>
191       </varlistentry>
192     </variablelist>
193   </section>
194   <example>
195     <title>Establishing PTR records for hosts.</title>
196     <para>The following established names for targets 10.1.2.{3,4,5,6} using the local nameserver (10.1.2.2) that provides service for that network.</para>
197     <programlisting>
198       &lt;noit&gt;
199         &lt;modules&gt;
200           &lt;module image="dns" name="dns"/&gt;
201         &lt;/modules&gt;
202         &lt;checks&gt;
203           &lt;config&gt;
204             &lt;nameserver&gt;10.1.2.2&lt;/nameserver&gt;
205           &lt;/config&gt;
206           &lt;ptr module="dns" name="in-addr.arpa"&gt;
207             &lt;check uuid="2cddb2a8-76ff-11dd-83c8-f75cb8b93bd9" target="10.1.2.3"/&gt;
208             &lt;check uuid="2dd79110-76ff-11dd-9b54-739adc274a93" target="10.1.2.4"/&gt;
209             &lt;check uuid="5627560a-76ff-11dd-941f-4b75679cb908" target="10.1.2.5"/&gt;
210             &lt;check uuid="5fdcb8de-76ff-11dd-ae16-2740afc178ae" target="10.1.2.6"/&gt;
211           &lt;/ptr&gt;
212         &lt;/checks&gt;
213       &lt;/noit&gt;
214     </programlisting>
215   </example>
216   <example>
217     <title>Checking labs.omniti.com.</title>
218     <para>The following checks the DNS server residing at 66.225.209.4 for the A record of labs.omniti.com.</para>
219     <programlisting>
220       &lt;noit&gt;
221         &lt;modules&gt;
222           &lt;module image="dns" name="dns"/&gt;
223         &lt;/modules&gt;
224         &lt;checks&gt;
225           &lt;ns1 module="dns" target="66.225.209.4"&gt;
226             &lt;check uuid="3cddb2a8-76ff-11dd-83c8-f75cb8b93bd9" name="labs.omniti.com"/&gt;
227           &lt;/ns1&gt;
228         &lt;/checks&gt;
229       &lt;/noit&gt;
230     </programlisting>
231   </example>
232 </section>
Note: See TracBrowser for help on using the browser.