doc/names/howto/names.html

   1 <?xml version="1.0" encoding="utf-8"?><!DOCTYPE html  PUBLIC '-//W3C//DTD XHTML 1.0 Transitional//EN'  'http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd'><html lang="en" xmlns="http://www.w3.org/1999/xhtml">
   2   <head>
   3 <title>Twisted Documentation: Creating and working with a names (DNS) server</title>
   4 <link href="stylesheet.css" rel="stylesheet" type="text/css"/>
   5   </head>
   6
   7   <body bgcolor="white">
   8     <h1 class="title">Creating and working with a names (DNS) server</h1>
   9     <div class="toc"><ol><li><a href="#auto0">Creating a non-authoritative server</a></li><li><a href="#auto1">Creating an authoritative server</a></li></ol></div>
  10     <div class="content">
  11 <span/>
  12
  13 <p>A Names server can be perform three basic operations:</p>
  14
  15 <ul>
  16 <li>act as a recursive server, forwarding queries to other servers</li>
  17 <li>perform local caching of recursively discovered records</li>
  18 <li>act as the authoritative server for a domain</li>
  19 </ul>
  20
  21 <h2>Creating a non-authoritative server<a name="auto0"/></h2>
  22
  23 <p>
  24 The first two of these are easy, and you can create a server that performs them
  25 with the command <code class="shell">twistd -n dns --recursive --cache</code>.
  26 You may wish to run this as root since it will try to bind to UDP port 53.  Try
  27 performing a lookup with it, <code class="shell">dig twistedmatrix.com
  28 @127.0.0.1</code>.
  29 </p>
  30
  31 <h2>Creating an authoritative server<a name="auto1"/></h2>
  32
  33 <p>To act as the authority for a domain, two things are necessary: the address
  34 of the machine on which the domain name server will run must be registered
  35 as a nameserver for the domain; and the domain name server must be
  36 configured to act as the authority.  The first requirement is beyond the
  37 scope of this howto and will not be covered.
  38 </p>
  39
  40 <p>To configure Names to act as the authority
  41 for <code>example-domain.com</code>, we first create a zone file for
  42 this domain.</p>
  43
  44 <div class="py-listing"><pre><p class="py-linenumber"> 1
  45  2
  46  3
  47  4
  48  5
  49  6
  50  7
  51  8
  52  9
  53 10
  54 11
  55 12
  56 13
  57 14
  58 15
  59 16
  60 17
  61 18
  62 19
  63 20
  64 21
  65 22
  66 23
  67 24
  68 25
  69 26
  70 27
  71 28
  72 29
  73 30
  74 31
  75 32
  76 33
  77 34
  78 35
  79 36
  80 37
  81 </p><span class="py-src-variable">zone</span> = [
  82     <span class="py-src-variable">SOA</span>(
  83         <span class="py-src-comment"># For whom we are the authority</span>
  84         <span class="py-src-string">'example-domain.com'</span>,
  85
  86         <span class="py-src-comment"># This nameserver's name</span>
  87         <span class="py-src-variable">mname</span> = <span class="py-src-string">&quot;ns1.example-domain.com&quot;</span>,
  88
  89         <span class="py-src-comment"># Mailbox of individual who handles this</span>
  90         <span class="py-src-variable">rname</span> = <span class="py-src-string">&quot;root.example-domain.com&quot;</span>,
  91
  92         <span class="py-src-comment"># Unique serial identifying this SOA data</span>
  93         <span class="py-src-variable">serial</span> = <span class="py-src-number">2003010601</span>,
  94
  95         <span class="py-src-comment"># Time interval before zone should be refreshed</span>
  96         <span class="py-src-variable">refresh</span> = <span class="py-src-string">&quot;1H&quot;</span>,
  97
  98         <span class="py-src-comment"># Interval before failed refresh should be retried</span>
  99         <span class="py-src-variable">retry</span> = <span class="py-src-string">&quot;1H&quot;</span>,
 100
 101         <span class="py-src-comment"># Upper limit on time interval before expiry</span>
 102         <span class="py-src-variable">expire</span> = <span class="py-src-string">&quot;1H&quot;</span>,
 103
 104         <span class="py-src-comment"># Minimum TTL</span>
 105         <span class="py-src-variable">minimum</span> = <span class="py-src-string">&quot;1H&quot;</span>
 106     ),
 107
 108     <span class="py-src-variable">A</span>(<span class="py-src-string">'example-domain.com'</span>, <span class="py-src-string">'127.0.0.1'</span>),
 109     <span class="py-src-variable">NS</span>(<span class="py-src-string">'example-domain.com'</span>, <span class="py-src-string">'ns1.example-domain.com'</span>),
 110
 111     <span class="py-src-variable">CNAME</span>(<span class="py-src-string">'www.example-domain.com'</span>, <span class="py-src-string">'example-domain.com'</span>),
 112     <span class="py-src-variable">CNAME</span>(<span class="py-src-string">'ftp.example-domain.com'</span>, <span class="py-src-string">'example-domain.com'</span>),
 113
 114     <span class="py-src-variable">MX</span>(<span class="py-src-string">'example-domain.com'</span>, <span class="py-src-number">0</span>, <span class="py-src-string">'mail.example-domain.com'</span>),
 115     <span class="py-src-variable">A</span>(<span class="py-src-string">'mail.example-domain.com'</span>, <span class="py-src-string">'123.0.16.43'</span>)
 116 ]
 117 </pre><div class="caption">Zone file - <a href="listings/names/example-domain.com"><span class="filename">listings/names/example-domain.com</span></a></div></div>
 118
 119 <p>Next, run the command <code class="shell">twistd -n dns --pyzone
 120 example-domain.com</code>.  Now try querying the domain locally (again, with
 121 dig): <code class="shell">dig -t any example-domain.com @127.0.0.1</code>.
 122 </p>
 123
 124 <p>Names can also read a traditional, BIND-syntax zone file.  Specify these
 125 with the <code>--bindzone</code> parameter.  The $GENERATE and $INCLUDE
 126 directives are not yet supported.
 127 </p>
 128
 129 </div>
 130
 131     <p><a href="index.html">Index</a></p>
 132     <span class="version">Version: 12.1.0</span>
 133   </body>
 134 </html>