Home Explore Help
Sign In
zorun
/
kea
1
0
Fork 0
Files Issues 0 Pull Requests 0 Wiki
Tree: bddce14fdd
Branches Tags
kea
/
doc
/
guide
/
bind10-guide.html

bind10-guide.html 153 KB
History Raw

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091109210931094109510961097109810991100110111021103110411051106110711081109111011111112111311141115111611171118111911201121112211231124112511261127112811291130113111321133113411351136113711381139114011411142114311441145114611471148114911501151115211531154115511561157115811591160116111621163116411651166116711681169117011711172117311741175117611771178117911801181118211831184118511861187118811891190119111921193119411951196119711981199120012011202120312041205120612071208120912101211121212131214121512161217121812191220122112221223122412251226122712281229123012311232123312341235123612371238123912401241124212431244124512461247124812491250125112521253125412551256125712581259126012611262126312641265126612671268126912701271127212731274127512761277127812791280128112821283128412851286128712881289129012911292129312941295129612971298129913001301130213031304130513061307130813091310131113121313131413151316131713181319132013211322132313241325132613271328132913301331133213331334133513361337133813391340134113421343134413451346134713481349135013511352135313541355135613571358135913601361136213631364136513661367136813691370137113721373137413751376137713781379138013811382138313841385138613871388138913901391139213931394139513961397139813991400140114021403140414051406140714081409141014111412141314141415141614171418141914201421142214231424142514261427142814291430143114321433143414351436143714381439144014411442144314441445144614471448144914501451145214531454145514561457145814591460146114621463146414651466146714681469147014711472147314741475147614771478147914801481148214831484148514861487148814891490149114921493149414951496149714981499150015011502150315041505150615071508150915101511151215131514151515161517151815191520152115221523152415251526152715281529153015311532153315341535153615371538153915401541154215431544154515461547154815491550155115521553155415551556155715581559156015611562156315641565156615671568156915701571157215731574157515761577157815791580158115821583158415851586158715881589159015911592159315941595159615971598159916001601160216031604160516061607160816091610161116121613161416151616161716181619162016211622162316241625162616271628162916301631163216331634163516361637163816391640164116421643164416451646164716481649165016511652165316541655165616571658165916601661166216631664166516661667166816691670167116721673167416751676167716781679168016811682168316841685168616871688168916901691169216931694169516961697169816991700170117021703170417051706170717081709171017111712171317141715171617171718171917201721172217231724172517261727172817291730173117321733173417351736173717381739174017411742174317441745174617471748174917501751175217531754175517561757175817591760176117621763176417651766176717681769177017711772177317741775177617771778177917801781178217831784178517861787178817891790179117921793179417951796179717981799180018011802180318041805180618071808180918101811181218131814181518161817181818191820182118221823182418251826182718281829183018311832183318341835183618371838183918401841184218431844184518461847184818491850185118521853185418551856185718581859186018611862186318641865186618671868186918701871187218731874187518761877187818791880188118821883188418851886188718881889189018911892189318941895189618971898189919001901190219031904190519061907190819091910191119121913191419151916191719181919192019211922192319241925192619271928192919301931193219331934193519361937193819391940194119421943194419451946194719481949195019511952195319541955195619571958195919601961196219631964196519661967196819691970197119721973197419751976197719781979198019811982198319841985198619871988198919901991199219931994199519961997199819992000200120022003200420052006200720082009201020112012201320142015201620172018201920202021202220232024202520262027202820292030203120322033203420352036203720382039204020412042 
  1. <html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>BIND 10 Guide</title><link rel="stylesheet" href="./bind10-guide.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><meta name="description" content="BIND 10 is a framework that features Domain Name System (DNS) suite and Dynamic Host Configuration Protocol (DHCP) servers with development managed by Internet Systems Consortium (ISC). It includes DNS libraries, modular components for controlling authoritative and recursive DNS servers, and experimental DHCPv4 and DHCPv6 servers. This is the reference guide for BIND 10 version 20120712. The most up-to-date version of this document (in PDF, HTML, and plain text formats), along with other documents for BIND 10, can be found at ."></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="book" title="BIND 10 Guide"><div class="titlepage"><div><div><h1 class="title"><a name="id1168229451102"></a>BIND 10 Guide</h1></div><div><h2 class="subtitle">Administrator Reference for BIND 10</h2></div><div><p class="releaseinfo">This is the reference guide for BIND 10 version
    2. 

  2.         20120712.</p></div><div><p class="copyright">Copyright © 2010-2012 Internet Systems Consortium, Inc.</p></div><div><div class="abstract" title="Abstract"><p class="title"><b>Abstract</b></p><p>BIND 10 is a framework that features Domain Name System
    3. 

  3.       (DNS) suite and Dynamic Host Configuration Protocol (DHCP)
    4. 

  4.       servers with development managed by Internet Systems Consortium (ISC).
    5. 

  5.       It includes DNS libraries, modular components for controlling
    6. 

  6.       authoritative and recursive DNS servers, and experimental DHCPv4
    7. 

  7.       and DHCPv6 servers.
    8. 

  8.       </p><p>
    9. 

  9.         This is the reference guide for BIND 10 version 20120712.
    10. 

  10.         The most up-to-date version of this document (in PDF, HTML,
    11. 

  11.         and plain text formats), along with other documents for
    12. 

  12.         BIND 10, can be found at <a class="ulink" href="http://bind10.isc.org/docs" target="_top">http://bind10.isc.org/docs</a>.
    13. 

  13.         </p></div></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="preface"><a href="#id1168229451188">Preface</a></span></dt><dd><dl><dt><span class="section"><a href="#acknowledgements">1. Acknowledgements</a></span></dt></dl></dd><dt><span class="chapter"><a href="#intro">1. Introduction</a></span></dt><dd><dl><dt><span class="section"><a href="#id1168229451275">1.1. Supported Platforms</a></span></dt><dt><span class="section"><a href="#required-software">1.2. Required Software at Run-time</a></span></dt><dt><span class="section"><a href="#starting_stopping">1.3. Starting and Stopping the Server</a></span></dt><dt><span class="section"><a href="#managing_once_running">1.4. Managing BIND 10</a></span></dt></dl></dd><dt><span class="chapter"><a href="#installation">2. Installation</a></span></dt><dd><dl><dt><span class="section"><a href="#packages">2.1. Packages</a></span></dt><dt><span class="section"><a href="#install-hierarchy">2.2. Install Hierarchy</a></span></dt><dt><span class="section"><a href="#build-requirements">2.3. Building Requirements</a></span></dt><dt><span class="section"><a href="#quickstart">2.4. Quick start</a></span></dt><dt><span class="section"><a href="#install">2.5. Installation from source</a></span></dt><dd><dl><dt><span class="section"><a href="#id1168229436957">2.5.1. Download Tar File</a></span></dt><dt><span class="section"><a href="#id1168229436977">2.5.2. Retrieve from Git</a></span></dt><dt><span class="section"><a href="#id1168229437037">2.5.3. Configure before the build</a></span></dt><dt><span class="section"><a href="#id1168229437136">2.5.4. Build</a></span></dt><dt><span class="section"><a href="#id1168229437150">2.5.5. Install</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#bind10">3. Starting BIND10 with <span class="command"><strong>bind10</strong></span></a></span></dt><dd><dl><dt><span class="section"><a href="#start">3.1. Starting BIND 10</a></span></dt><dt><span class="section"><a href="#bind10.config">3.2. Configuration to start processes</a></span></dt></dl></dd><dt><span class="chapter"><a href="#msgq">4. Command channel</a></span></dt><dt><span class="chapter"><a href="#cfgmgr">5. Configuration manager</a></span></dt><dt><span class="chapter"><a href="#cmdctl">6. Remote control daemon</a></span></dt><dd><dl><dt><span class="section"><a href="#cmdctl.spec">6.1. Configuration specification for b10-cmdctl</a></span></dt></dl></dd><dt><span class="chapter"><a href="#bindctl">7. Control and configure user interface</a></span></dt><dt><span class="chapter"><a href="#authserver">8. Authoritative Server</a></span></dt><dd><dl><dt><span class="section"><a href="#id1168229438312">8.1. Server Configurations</a></span></dt><dt><span class="section"><a href="#id1168229438638">8.2. Data Source Backends</a></span></dt><dd><dl><dt><span class="section"><a href="#in-memory-datasource">8.2.1. In-memory Data Source</a></span></dt><dt><span class="section"><a href="#in-memory-datasource-with-sqlite3-backend">8.2.2. In-memory Data Source with SQLite3 Backend</a></span></dt><dt><span class="section"><a href="#in-memory-datasource-loading">8.2.3. Reloading an In-memory Data Source</a></span></dt><dt><span class="section"><a href="#in-memory-datasource-disabling">8.2.4. Disabling In-memory Data Sources</a></span></dt></dl></dd><dt><span class="section"><a href="#id1168229438940">8.3. Loading Master Zones Files</a></span></dt></dl></dd><dt><span class="chapter"><a href="#xfrin">9. Incoming Zone Transfers</a></span></dt><dd><dl><dt><span class="section"><a href="#id1168229439105">9.1. Configuration for Incoming Zone Transfers</a></span></dt><dt><span class="section"><a href="#id1168229439142">9.2. Enabling IXFR</a></span></dt><dt><span class="section"><a href="#zonemgr">9.3. Secondary Manager</a></span></dt><dt><span class="section"><a href="#id1168229439316">9.4. Trigger an Incoming Zone Transfer Manually</a></span></dt><dt><span class="section"><a href="#id1168229439342">9.5. Incoming Transfers with In-memory Datasource</a></span></dt></dl></dd><dt><span class="chapter"><a href="#xfrout">10. Outbound Zone Transfers</a></span></dt><dt><span class="chapter"><a href="#ddns">11. Dynamic DNS Update</a></span></dt><dd><dl><dt><span class="section"><a href="#id1168229439633">11.1. Enabling Dynamic Update</a></span></dt><dt><span class="section"><a href="#id1168229439733">11.2. Access Control</a></span></dt><dt><span class="section"><a href="#id1168229439954">11.3. Miscellaneous Operational Issues</a></span></dt></dl></dd><dt><span class="chapter"><a href="#resolverserver">12. Recursive Name Server</a></span></dt><dd><dl><dt><span class="section"><a href="#id1168229440091">12.1. Access Control</a></span></dt><dt><span class="section"><a href="#id1168229440276">12.2. Forwarding</a></span></dt></dl></dd><dt><span class="chapter"><a href="#dhcp4">13. DHCPv4 Server</a></span></dt><dd><dl><dt><span class="section"><a href="#dhcp4-usage">13.1. DHCPv4 Server Usage</a></span></dt><dt><span class="section"><a href="#dhcp4-config">13.2. DHCPv4 Server Configuration</a></span></dt><dt><span class="section"><a href="#dhcp4-std">13.3. Supported standards</a></span></dt><dt><span class="section"><a href="#dhcp4-limit">13.4. DHCPv4 Server Limitations</a></span></dt></dl></dd><dt><span class="chapter"><a href="#dhcp6">14. DHCPv6 Server</a></span></dt><dd><dl><dt><span class="section"><a href="#dhcp6-usage">14.1. DHCPv6 Server Usage</a></span></dt><dt><span class="section"><a href="#dhcp6-config">14.2. DHCPv6 Server Configuration</a></span></dt><dt><span class="section"><a href="#dhcp6-std">14.3. Supported DHCPv6 Standards</a></span></dt><dt><span class="section"><a href="#dhcp6-limit">14.4. DHCPv6 Server Limitations</a></span></dt></dl></dd><dt><span class="chapter"><a href="#libdhcp">15. libdhcp++ library</a></span></dt><dd><dl><dt><span class="section"><a href="#iface-detect">15.1. Interface detection</a></span></dt><dt><span class="section"><a href="#packet-handling">15.2. DHCPv4/DHCPv6 packet handling</a></span></dt></dl></dd><dt><span class="chapter"><a href="#statistics">16. Statistics</a></span></dt><dt><span class="chapter"><a href="#logging">17. Logging</a></span></dt><dd><dl><dt><span class="section"><a href="#id1168229440926">17.1. Logging configuration</a></span></dt><dd><dl><dt><span class="section"><a href="#id1168229440937">17.1.1. Loggers</a></span></dt><dt><span class="section"><a href="#id1168229441248">17.1.2. Output Options</a></span></dt><dt><span class="section"><a href="#id1168229441431">17.1.3. Example session</a></span></dt></dl></dd><dt><span class="section"><a href="#id1168229441640">17.2. Logging Message Format</a></span></dt></dl></dd></dl></div><div class="list-of-tables"><p><b>List of Tables</b></p><dl><dt>3.1. <a href="#id1168229437333">Special startup components</a></dt></dl></div><div class="preface" title="Preface"><div class="titlepage"><div><div><h2 class="title"><a name="id1168229451188"></a>Preface</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#acknowledgements">1. Acknowledgements</a></span></dt></dl></div><div class="section" title="1. Acknowledgements"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="acknowledgements"></a>1. Acknowledgements</h2></div></div></div><p>ISC would like to acknowledge generous support for
    14. 

  14.       BIND 10 development of DHCPv4 and DHCPv6 components provided
    15. 

  15.       by <a class="ulink" href="http://www.comcast.com/" target="_top">Comcast</a>.</p></div></div><div class="chapter" title="Chapter 1. Introduction"><div class="titlepage"><div><div><h2 class="title"><a name="intro"></a>Chapter 1. Introduction</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#id1168229451275">1.1. Supported Platforms</a></span></dt><dt><span class="section"><a href="#required-software">1.2. Required Software at Run-time</a></span></dt><dt><span class="section"><a href="#starting_stopping">1.3. Starting and Stopping the Server</a></span></dt><dt><span class="section"><a href="#managing_once_running">1.4. Managing BIND 10</a></span></dt></dl></div><p>
    16. 

  16.       BIND is the popular implementation of a DNS server, developer
    17. 

  17.       interfaces, and DNS tools.
    18. 

  18.       BIND 10 is a rewrite of BIND 9 and ISC DHCP.
    19. 

  19.       BIND 10 is written in C++ and Python and provides a modular
    20. 

  20.       environment for serving, maintaining, and developing DNS and DHCP.
    21. 

  21.       BIND 10 provides a EDNS0- and DNSSEC-capable authoritative
    22. 

  22.       DNS server and a caching recursive name server which also
    23. 

  23.       provides forwarding.
    24. 

  24.       It also provides experimental DHCPv4 and DHCPv6 servers.
    25. 

  25.     </p><p>
    26. 

  26.       This guide covers the experimental prototype of
    27. 

  27.       BIND 10 version 20120712.
    28. 

  28.     </p><div class="section" title="1.1. Supported Platforms"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id1168229451275"></a>1.1. Supported Platforms</h2></div></div></div><p>
    29. 

  29.   BIND 10 builds have been tested on (in no particular order)
    30. 

  30.   Debian GNU/Linux 6 and unstable, Ubuntu 9.10, NetBSD 5,
    31. 

  31.   Solaris 10 and 11, FreeBSD 7 and 8, CentOS Linux 5.3,
    32. 

  32.   MacOS 10.6 and 10.7, and OpenBSD 5.1.
    33. 

  33. 

  34.   It has been tested on Sparc, i386, and amd64 hardware
    35. 

  35.   platforms.
    36. 

  36. 

  37.         It is planned for BIND 10 to build, install and run on
    38. 

  38.         Windows and standard Unix-type platforms.
    39. 

  39.       </p></div><div class="section" title="1.2. Required Software at Run-time"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="required-software"></a>1.2. Required Software at Run-time</h2></div></div></div><p>
    40. 

  40.         Running BIND 10 uses various extra software which may
    41. 

  41.         not be provided in some operating systems' default
    42. 

  42.         installations nor standard packages collections. You may
    43. 

  43.         need to install this required software separately.
    44. 

  44.         (For the build requirements, also see
    45. 

  45.         <a class="xref" href="#build-requirements" title="2.3. Building Requirements">Section 2.3, &#8220;Building Requirements&#8221;</a>.)
    46. 

  46.       </p><p>
    47. 

  47.         BIND 10 requires at least Python 3.1
    48. 

  48.         (<a class="ulink" href="http://www.python.org/" target="_top">http://www.python.org/</a>).
    49. 

  49.         It also works with Python 3.2.
    50. 

  50.       </p><p>
    51. 

  51.         BIND 10 uses the Botan crypto library for C++
    52. 

  52.         (<a class="ulink" href="http://botan.randombit.net/" target="_top">http://botan.randombit.net/</a>).
    53. 

  53.         It requires at least Botan version 1.8.
    54. 

  54.       </p><p>
    55. 

  55.         BIND 10 uses the log4cplus C++ logging library
    56. 

  56.         (<a class="ulink" href="http://log4cplus.sourceforge.net/" target="_top">http://log4cplus.sourceforge.net/</a>).
    57. 

  57.         It requires at least log4cplus version 1.0.3.
    58. 

  58. 

  59.       </p><p>
    60. 

  60.         The authoritative DNS server uses SQLite3
    61. 

  61.         (<a class="ulink" href="http://www.sqlite.org/" target="_top">http://www.sqlite.org/</a>).
    62. 

  62. 

  63.         It needs at least SQLite version 3.3.9.
    64. 

  64.       </p><p>
    65. 

  65.         The <span class="command"><strong>b10-ddns</strong></span>, <span class="command"><strong>b10-xfrin</strong></span>,
    66. 

  66.         <span class="command"><strong>b10-xfrout</strong></span>, and <span class="command"><strong>b10-zonemgr</strong></span>
    67. 

  67.         components require the libpython3 library and the Python
    68. 

  68.         _sqlite3.so module (which is included with Python).
    69. 

  69.         Python modules need to be built for the corresponding Python 3.
    70. 

  70.       </p></div><div class="section" title="1.3. Starting and Stopping the Server"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="starting_stopping"></a>1.3. Starting and Stopping the Server</h2></div></div></div><p>
    71. 

  71.         BIND 10 is modular.  Part of this modularity is
    72. 

  72.         accomplished using multiple cooperating processes which, together,
    73. 

  73.         provide the server functionality.  This is a change from
    74. 

  74.         the previous generation of BIND software, which used a
    75. 

  75.         single process.
    76. 

  76.       </p><p>
    77. 

  77.         At first, running many different processes may seem confusing.
    78. 

  78.         However, these processes are started, stopped, and maintained
    79. 

  79.         by a single command, <span class="command"><strong>bind10</strong></span>.
    80. 

  80.         This command starts a master process which will start other
    81. 

  81.         processes as needed.
    82. 

  82.         The processes started by the <span class="command"><strong>bind10</strong></span>
    83. 

  83.         command have names starting with "b10-", including:
    84. 

  84.       </p><p>
    85. 

  85. 

  86.         </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
    87. 

  87.               <span class="command"><strong>b10-auth</strong></span> &#8212;
    88. 

  88.               Authoritative DNS server.
    89. 

  89.               This process serves DNS requests.
    90. 

  90.             </li><li class="listitem">
    91. 

  91.               <span class="command"><strong>b10-cfgmgr</strong></span> &#8212;
    92. 

  92.               Configuration manager.
    93. 

  93.               This process maintains all of the configuration for BIND 10.
    94. 

  94.             </li><li class="listitem">
    95. 

  95.               <span class="command"><strong>b10-cmdctl</strong></span> &#8212;
    96. 

  96.               Command and control service.
    97. 

  97.               This process allows external control of the BIND 10 system.
    98. 

  98.             </li><li class="listitem">
    99. 

  99.               <span class="command"><strong>b10-ddns</strong></span> &#8212;
    100. 

  100.               Dynamic DNS update service.
    101. 

  101.               This process is used to handle incoming DNS update
    102. 

  102.               requests to allow granted clients to update zones
    103. 

  103. 	      for which BIND 10 is serving as a primary server.
    104. 

  104.             </li><li class="listitem">
    105. 

  105.               <span class="command"><strong>b10-msgq</strong></span> &#8212;
    106. 

  106.               Message bus daemon.
    107. 

  107.               This process coordinates communication between all of the other
    108. 

  108.               BIND 10 processes.
    109. 

  109.             </li><li class="listitem">
    110. 

  110.               <span class="command"><strong>b10-resolver</strong></span> &#8212;
    111. 

  111.               Recursive name server.
    112. 

  112.               This process handles incoming DNS queries and provides
    113. 

  113.               answers from its cache or by recursively doing remote lookups.
    114. 

  114.             </li><li class="listitem">
    115. 

  115.               <span class="command"><strong>b10-sockcreator</strong></span> &#8212;
    116. 

  116.               Socket creator daemon.
    117. 

  117.               This process creates sockets used by
    118. 

  118.               network-listening BIND 10 processes.
    119. 

  119.             </li><li class="listitem">
    120. 

  120.               <span class="command"><strong>b10-stats</strong></span> &#8212;
    121. 

  121.               Statistics collection daemon.
    122. 

  122.               This process collects and reports statistics data.
    123. 

  123.             </li><li class="listitem">
    124. 

  124.               <span class="command"><strong>b10-stats-httpd</strong></span> &#8212;
    125. 

  125.               HTTP server for statistics reporting.
    126. 

  126.               This process reports statistics data in XML format over HTTP.
    127. 

  127.             </li><li class="listitem">
    128. 

  128.               <span class="command"><strong>b10-xfrin</strong></span> &#8212;
    129. 

  129.               Incoming zone transfer service.
    130. 

  130.               This process is used to transfer a new copy
    131. 

  131.               of a zone into BIND 10, when acting as a secondary server.
    132. 

  132.             </li><li class="listitem">
    133. 

  133.               <span class="command"><strong>b10-xfrout</strong></span> &#8212;
    134. 

  134.               Outgoing zone transfer service.
    135. 

  135.               This process is used to handle transfer requests to
    136. 

  136.               send a local zone to a remote secondary server.
    137. 

  137.             </li><li class="listitem">
    138. 

  138.               <span class="command"><strong>b10-zonemgr</strong></span> &#8212;
    139. 

  139.               Secondary zone manager.
    140. 

  140.               This process keeps track of timers and other
    141. 

  141.               necessary information for BIND 10 to act as a slave server.
    142. 

  142.             </li></ul></div><p>
    143. 

  143.       </p><p>
    144. 

  144.         These are ran by <span class="command"><strong>bind10</strong></span>
    145. 

  145.         and do not need to be manually started independently.
    146. 

  146.       </p></div><div class="section" title="1.4. Managing BIND 10"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="managing_once_running"></a>1.4. Managing BIND 10</h2></div></div></div><p>
    147. 

  147.         Once BIND 10 is running, a few commands are used to interact
    148. 

  148.         directly with the system:
    149. 

  149.         </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
    150. 

  150.               <span class="command"><strong>bindctl</strong></span> &#8212;
    151. 

  151.               Interactive administration interface.
    152. 

  152.               This is a low-level command-line tool which allows
    153. 

  153.               a developer or an experienced administrator to control
    154. 

  154.               BIND 10.
    155. 

  155.             </li><li class="listitem">
    156. 

  156.               <span class="command"><strong>b10-loadzone</strong></span> &#8212;
    157. 

  157.               Zone file loader.
    158. 

  158.               This tool will load standard masterfile-format zone files into
    159. 

  159.               BIND 10.
    160. 

  160.             </li><li class="listitem">
    161. 

  161.               <span class="command"><strong>b10-cmdctl-usermgr</strong></span> &#8212;
    162. 

  162.               User access control.
    163. 

  163.               This tool allows an administrator to authorize additional users
    164. 

  164.               to manage BIND 10.
    165. 

  165.             </li></ul></div><p>
    166. 

  166.       </p></div><p>
    167. 

  167.       The tools and modules are covered in full detail in this guide.
    168. 

  168. 

  169.       In addition, manual pages are also provided in the default installation.
    170. 

  170.     </p><p>
    171. 

  171.       BIND 10 also provides libraries and programmer interfaces
    172. 

  172.       for C++ and Python for the message bus, configuration backend,
    173. 

  173.       and, of course, DNS. These include detailed developer
    174. 

  174.       documentation and code examples.
    175. 

  175. 

  176. 

  177.     </p></div><div class="chapter" title="Chapter 2. Installation"><div class="titlepage"><div><div><h2 class="title"><a name="installation"></a>Chapter 2. Installation</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#packages">2.1. Packages</a></span></dt><dt><span class="section"><a href="#install-hierarchy">2.2. Install Hierarchy</a></span></dt><dt><span class="section"><a href="#build-requirements">2.3. Building Requirements</a></span></dt><dt><span class="section"><a href="#quickstart">2.4. Quick start</a></span></dt><dt><span class="section"><a href="#install">2.5. Installation from source</a></span></dt><dd><dl><dt><span class="section"><a href="#id1168229436957">2.5.1. Download Tar File</a></span></dt><dt><span class="section"><a href="#id1168229436977">2.5.2. Retrieve from Git</a></span></dt><dt><span class="section"><a href="#id1168229437037">2.5.3. Configure before the build</a></span></dt><dt><span class="section"><a href="#id1168229437136">2.5.4. Build</a></span></dt><dt><span class="section"><a href="#id1168229437150">2.5.5. Install</a></span></dt></dl></dd></dl></div><div class="section" title="2.1. Packages"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="packages"></a>2.1. Packages</h2></div></div></div><p>
    178. 

  178.         Some operating systems or softare package vendors may
    179. 

  179.         provide ready-to-use, pre-built software packages for
    180. 

  180.         the BIND 10 suite.
    181. 

  181.         Installing a pre-built package means you do not need to
    182. 

  182.         install build-only prerequisites and do not need to
    183. 

  183.         <span class="emphasis"><em>make</em></span> the software.
    184. 

  184.       </p><p>
    185. 

  185.         FreeBSD ports, NetBSD pkgsrc, and Debian
    186. 

  186.         <span class="emphasis"><em>testing</em></span> package collections provide
    187. 

  187.         all the prerequisite packages.
    188. 

  188.       </p></div><div class="section" title="2.2. Install Hierarchy"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="install-hierarchy"></a>2.2. Install Hierarchy</h2></div></div></div><p>
    189. 

  189.         The following is the standard, common layout of the
    190. 

  190.         complete BIND 10 installation:
    191. 

  191.         </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
    192. 

  192.               <code class="filename">bin/</code> &#8212;
    193. 

  193.               general tools and diagnostic clients.
    194. 

  194.             </li><li class="listitem">
    195. 

  195.             <code class="filename">etc/bind10-devel/</code> &#8212;
    196. 

  196.             configuration files.
    197. 

  197.           </li><li class="listitem">
    198. 

  198.               <code class="filename">lib/</code> &#8212;
    199. 

  199.               libraries and python modules.
    200. 

  200.             </li><li class="listitem">
    201. 

  201.               <code class="filename">libexec/bind10-devel/</code> &#8212;
    202. 

  202.               executables that a user wouldn't normally run directly and
    203. 

  203.               are not run independently.
    204. 

  204.               These are the BIND 10 modules which are daemons started by
    205. 

  205.               the <span class="command"><strong>bind10</strong></span> tool.
    206. 

  206.             </li><li class="listitem">
    207. 

  207.               <code class="filename">sbin/</code> &#8212;
    208. 

  208.               commands used by the system administrator.
    209. 

  209.             </li><li class="listitem">
    210. 

  210.               <code class="filename">share/bind10-devel/</code> &#8212;
    211. 

  211.               configuration specifications.
    212. 

  212.             </li><li class="listitem">
    213. 

  213.               <code class="filename">share/doc/bind10-devel/</code> &#8212;
    214. 

  214.               this guide and other supplementary documentation.
    215. 

  215.             </li><li class="listitem">
    216. 

  216.               <code class="filename">share/man/</code> &#8212;
    217. 

  217.               manual pages (online documentation).
    218. 

  218.             </li><li class="listitem">
    219. 

  219.               <code class="filename">var/bind10-devel/</code> &#8212;
    220. 

  220.               data source and configuration databases.
    221. 

  221.             </li></ul></div><p>
    222. 

  222.       </p></div><div class="section" title="2.3. Building Requirements"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="build-requirements"></a>2.3. Building Requirements</h2></div></div></div><p>
    223. 

  223.           In addition to the run-time requirements (listed in
    224. 

  224.           <a class="xref" href="#required-software" title="1.2. Required Software at Run-time">Section 1.2, &#8220;Required Software at Run-time&#8221;</a>), building BIND 10
    225. 

  225.           from source code requires various development include headers and
    226. 

  226.           program development tools.
    227. 

  227.         </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
    228. 

  228.             Some operating systems have split their distribution packages into
    229. 

  229.             a run-time and a development package.  You will need to install
    230. 

  230.             the development package versions, which include header files and
    231. 

  231.             libraries, to build BIND 10 from source code.
    232. 

  232.           </p></div><p>
    233. 

  233.           Building from source code requires the Boost
    234. 

  234.           build-time headers
    235. 

  235.           (<a class="ulink" href="http://www.boost.org/" target="_top">http://www.boost.org/</a>).
    236. 

  236.           At least Boost version 1.35 is required.
    237. 

  237.   
    238. 

  238.   
    239. 

  239.         </p><p>
    240. 

  240.           To build BIND 10, also install the Botan (at least version
    241. 

  241.           1.8) and the log4cplus (at least version 1.0.3)
    242. 

  242.           development include headers.
    243. 

  243.         </p><p>
    244. 

  244.           Building BIND 10 also requires a C++ compiler and
    245. 

  245.           standard development headers, make, and pkg-config.
    246. 

  246.           BIND 10 builds have been tested with GCC g++ 3.4.3, 4.1.2,
    247. 

  247.           4.1.3, 4.2.1, 4.3.2, and 4.4.1; Clang++ 2.8; and Sun C++ 5.10.
    248. 

  248.         </p><p>
    249. 

  249.           Visit the user-contributed wiki at <a class="ulink" href="http://bind10.isc.org/wiki/SystemSpecificNotes" target="_top">http://bind10.isc.org/wiki/SystemSpecificNotes</a>
    250. 

  250.           for system-specific installation tips.
    251. 

  251.         </p></div><div class="section" title="2.4. Quick start"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="quickstart"></a>2.4. Quick start</h2></div></div></div><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
    252. 

  252.           This quickly covers the standard steps for installing
    253. 

  253.           and deploying BIND 10 as an authoritative name server using
    254. 

  254.           its defaults. For troubleshooting, full customizations and further
    255. 

  255.           details, see the respective chapters in the BIND 10 guide.
    256. 

  256.         </p></div><p>
    257. 

  257.         To quickly get started with BIND 10, follow these steps.
    258. 

  258.       </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
    259. 

  259.             Install required run-time and build dependencies.
    260. 

  260.           </li><li class="listitem">
    261. 

  261.             Download the BIND 10 source tar file from
    262. 

  262.             <a class="ulink" href="ftp://ftp.isc.org/isc/bind10/" target="_top">ftp://ftp.isc.org/isc/bind10/</a>.
    263. 

  263.           </li><li class="listitem"><p>Extract the tar file:
    264. 

  264.           </p><pre class="screen">$ <strong class="userinput"><code>gzcat bind10-<em class="replaceable"><code>VERSION</code></em>.tar.gz | tar -xvf -</code></strong></pre><p>
    265. 

  265.           </p></li><li class="listitem"><p>Go into the source and run configure:
    266. 

  266.             </p><pre class="screen">$ <strong class="userinput"><code>cd bind10-<em class="replaceable"><code>VERSION</code></em></code></strong>
    267. 

  267.   $ <strong class="userinput"><code>./configure</code></strong></pre><p>
    268. 

  268.           </p></li><li class="listitem"><p>Build it:
    269. 

  269.             </p><pre class="screen">$ <strong class="userinput"><code>make</code></strong></pre><p>
    270. 

  270.           </p></li><li class="listitem"><p>Install it (to default /usr/local):
    271. 

  271.             </p><pre class="screen">$ <strong class="userinput"><code>make install</code></strong></pre><p>
    272. 

  272.           </p></li><li class="listitem"><p>Start the server:
    273. 

  273.             </p><pre class="screen">$ <strong class="userinput"><code>/usr/local/sbin/bind10</code></strong></pre><p>
    274. 

  274.           </p></li><li class="listitem"><p>Test it; for example:
    275. 

  275.             </p><pre class="screen">$ <strong class="userinput"><code>dig @127.0.0.1 -c CH -t TXT authors.bind</code></strong></pre><p>
    276. 

  276.          </p></li><li class="listitem"><p>Load desired zone file(s), for example:
    277. 

  277.             </p><pre class="screen">$ <strong class="userinput"><code>b10-loadzone <em class="replaceable"><code>your.zone.example.org</code></em></code></strong></pre><p>
    278. 

  278.           </p></li><li class="listitem">
    279. 

  279.             Test the new zone.
    280. 

  280.           </li></ol></div></div><div class="section" title="2.5. Installation from source"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="install"></a>2.5. Installation from source</h2></div></div></div><p>
    281. 

  281.         BIND 10 is open source software written in C++ and Python.
    282. 

  282.         It is freely available in source code form from ISC as a
    283. 

  283.         downloadable tar file or via BIND 10's Git code revision control
    284. 

  284.         service. (It may also be available in pre-compiled ready-to-use
    285. 

  285.         packages from operating system vendors.)
    286. 

  286.       </p><div class="section" title="2.5.1. Download Tar File"><div class="titlepage"><div><div><h3 class="title"><a name="id1168229436957"></a>2.5.1. Download Tar File</h3></div></div></div><p>
    287. 

  287.           Downloading a release tar file is the recommended method to
    288. 

  288.           obtain the source code.
    289. 

  289.         </p><p>
    290. 

  290.           The BIND 10 releases are available as tar file downloads from
    291. 

  291.           <a class="ulink" href="ftp://ftp.isc.org/isc/bind10/" target="_top">ftp://ftp.isc.org/isc/bind10/</a>.
    292. 

  292.           Periodic development snapshots may also be available.
    293. 

  293.         </p></div><div class="section" title="2.5.2. Retrieve from Git"><div class="titlepage"><div><div><h3 class="title"><a name="id1168229436977"></a>2.5.2. Retrieve from Git</h3></div></div></div><p>
    294. 

  294.           Downloading this "bleeding edge" code is recommended only for
    295. 

  295.           developers or advanced users.  Using development code in a production
    296. 

  296.           environment is not recommended.
    297. 

  297.         </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
    298. 

  298.             When using source code retrieved via Git, additional
    299. 

  299.             software will be required:  automake (v1.11 or newer),
    300. 

  300.             libtoolize, and autoconf (2.59 or newer).
    301. 

  301.             These may need to be installed.
    302. 

  302.           </p></div><p>
    303. 

  303.           The latest development code (and temporary experiments
    304. 

  304.           and un-reviewed code) is available via the BIND 10 code revision
    305. 

  305.           control system. This is powered by Git and all the BIND 10
    306. 

  306.           development is public.
    307. 

  307.           The leading development is done in the <span class="quote">&#8220;<span class="quote">master</span>&#8221;</span>
    308. 

  308.           branch.
    309. 

  309.         </p><p>
    310. 

  310.           The code can be checked out from
    311. 

  311.           <code class="filename">git://git.bind10.isc.org/bind10</code>;
    312. 

  312.           for example:
    313. 

  313. 

  314.         </p><pre class="screen">$ <strong class="userinput"><code>git clone git://git.bind10.isc.org/bind10</code></strong></pre><p>
    315. 

  315.         </p><p>
    316. 

  316.           When checking out the code from
    317. 

  317.           the code version control system, it doesn't include the
    318. 

  318.           generated configure script, Makefile.in files, nor their
    319. 

  319.           related build files.
    320. 

  320.           They can be created by running <span class="command"><strong>autoreconf</strong></span>
    321. 

  321.           with the <code class="option">--install</code> switch.
    322. 

  322.           This will run <span class="command"><strong>autoconf</strong></span>,
    323. 

  323.           <span class="command"><strong>aclocal</strong></span>,
    324. 

  324.           <span class="command"><strong>libtoolize</strong></span>,
    325. 

  325.           <span class="command"><strong>autoheader</strong></span>,
    326. 

  326.           <span class="command"><strong>automake</strong></span>,
    327. 

  327.           and related commands.
    328. 

  328.         </p></div><div class="section" title="2.5.3. Configure before the build"><div class="titlepage"><div><div><h3 class="title"><a name="id1168229437037"></a>2.5.3. Configure before the build</h3></div></div></div><p>
    329. 

  329.           BIND 10 uses the GNU Build System to discover build environment
    330. 

  330.           details.
    331. 

  331.           To generate the makefiles using the defaults, simply run:
    332. 

  332.           </p><pre class="screen">$ <strong class="userinput"><code>./configure</code></strong></pre><p>
    333. 

  333.         </p><p>
    334. 

  334.           Run <span class="command"><strong>./configure</strong></span> with the <code class="option">--help</code>
    335. 

  335.           switch to view the different options. Some commonly-used options are:
    336. 

  336. 

  337.           </p><div class="variablelist"><dl><dt><span class="term">--prefix</span></dt><dd>Define the installation location (the
    338. 

  338.                 default is <code class="filename">/usr/local/</code>).
    339. 

  339.               </dd><dt><span class="term">--with-boost-include</span></dt><dd>Define the path to find the Boost headers.
    340. 

  340.               </dd><dt><span class="term">--with-pythonpath</span></dt><dd>Define the path to Python 3.1 if it is not in the
    341. 

  341.                 standard execution path.
    342. 

  342.               </dd><dt><span class="term">--with-gtest</span></dt><dd>Enable building the C++ Unit Tests using the
    343. 

  343.                 Google Tests framework. Optionally this can define the
    344. 

  344.                 path to the gtest header files and library.
    345. 

  345.               </dd></dl></div><p>
    346. 

  346. 

  347.         </p><p>
    348. 

  348.           For example, the following configures it to
    349. 

  349.     find the Boost headers, find the
    350. 

  350.     Python interpreter, and sets the installation location:
    351. 

  351. 

  352.           </p><pre class="screen">$ <strong class="userinput"><code>./configure \
    353. 

  353.       --with-boost-include=/usr/pkg/include \
    354. 

  354.       --with-pythonpath=/usr/pkg/bin/python3.1 \
    355. 

  355.       --prefix=/opt/bind10</code></strong></pre><p>
    356. 

  356.         </p><p>
    357. 

  357.           If the configure fails, it may be due to missing or old
    358. 

  358.           dependencies.
    359. 

  359.         </p></div><div class="section" title="2.5.4. Build"><div class="titlepage"><div><div><h3 class="title"><a name="id1168229437136"></a>2.5.4. Build</h3></div></div></div><p>
    360. 

  360.     After the configure step is complete, to build the executables
    361. 

  361.     from the C++ code and prepare the Python scripts, run:
    362. 

  362. 

  363.           </p><pre class="screen">$ <strong class="userinput"><code>make</code></strong></pre><p>
    364. 

  364.         </p></div><div class="section" title="2.5.5. Install"><div class="titlepage"><div><div><h3 class="title"><a name="id1168229437150"></a>2.5.5. Install</h3></div></div></div><p>
    365. 

  365.           To install the BIND 10 executables, support files,
    366. 

  366.           and documentation, run:
    367. 

  367.           </p><pre class="screen">$ <strong class="userinput"><code>make install</code></strong></pre><p>
    368. 

  368.         </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>The install step may require superuser privileges.</p></div></div></div></div><div class="chapter" title="Chapter 3. Starting BIND10 with bind10"><div class="titlepage"><div><div><h2 class="title"><a name="bind10"></a>Chapter 3. Starting BIND10 with <span class="command"><strong>bind10</strong></span></h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#start">3.1. Starting BIND 10</a></span></dt><dt><span class="section"><a href="#bind10.config">3.2. Configuration to start processes</a></span></dt></dl></div><p>
    369. 

  369.       BIND 10 provides the <span class="command"><strong>bind10</strong></span> command which
    370. 

  370.       starts up the required processes.
    371. 

  371.       <span class="command"><strong>bind10</strong></span>
    372. 

  372.       will also restart some processes that exit unexpectedly.
    373. 

  373.       This is the only command needed to start the BIND 10 system.
    374. 

  374.     </p><p>
    375. 

  375.       After starting the <span class="command"><strong>b10-msgq</strong></span> communications channel,
    376. 

  376.       <span class="command"><strong>bind10</strong></span> connects to it,
    377. 

  377.       runs the configuration manager, and reads its own configuration.
    378. 

  378.       Then it starts the other modules.
    379. 

  379.     </p><p>
    380. 

  380.       The <span class="command"><strong>b10-sockcreator</strong></span>, <span class="command"><strong>b10-msgq</strong></span> and
    381. 

  381.       <span class="command"><strong>b10-cfgmgr</strong></span>
    382. 

  382.       services make up the core. The <span class="command"><strong>b10-msgq</strong></span> daemon
    383. 

  383.       provides the communication channel between every part of the system.
    384. 

  384.       The <span class="command"><strong>b10-cfgmgr</strong></span> daemon is always needed by every
    385. 

  385.       module, if only to send information about themselves somewhere,
    386. 

  386.       but more importantly to ask about their own settings, and
    387. 

  387.       about other modules. The <span class="command"><strong>b10-sockcreator</strong></span> daemon
    388. 

  388.       helps allocate Internet addresses and ports as needed for BIND 10
    389. 

  389.       network services.
    390. 

  390.     </p><p>
    391. 

  391.       In its default configuration, the <span class="command"><strong>bind10</strong></span>
    392. 

  392.       master process will also start up
    393. 

  393.       <span class="command"><strong>b10-cmdctl</strong></span> for administration tools to
    394. 

  394.       communicate with the system, and
    395. 

  395.       <span class="command"><strong>b10-stats</strong></span> for statistics collection.
    396. 

  396.     </p><div class="section" title="3.1. Starting BIND 10"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="start"></a>3.1. Starting BIND 10</h2></div></div></div><p>
    397. 

  397.         To start the BIND 10 service, simply run <span class="command"><strong>bind10</strong></span>.
    398. 

  398.         Run it with the <code class="option">--verbose</code> switch to
    399. 

  399.         get additional debugging or diagnostic output.
    400. 

  400.       </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
    401. 

  401.           If the setproctitle Python module is detected at start up,
    402. 

  402.           the process names for the Python-based daemons will be renamed
    403. 

  403.           to better identify them instead of just <span class="quote">&#8220;<span class="quote">python</span>&#8221;</span>.
    404. 

  404.           This is not needed on some operating systems.
    405. 

  405.         </p></div></div><div class="section" title="3.2. Configuration to start processes"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="bind10.config"></a>3.2. Configuration to start processes</h2></div></div></div><p>
    406. 

  406. 	The processes to be used can be configured for
    407. 

  407. 	<span class="command"><strong>bind10</strong></span> to start, with the exception
    408. 

  408. 	of the required <span class="command"><strong>b10-sockcreator</strong></span>,
    409. 

  409. 	<span class="command"><strong>b10-msgq</strong></span> and <span class="command"><strong>b10-cfgmgr</strong></span>
    410. 

  410. 	components.
    411. 

  411. 	The configuration is in the <code class="varname">Boss/components</code>
    412. 

  412. 	section. Each element represents one component, which is
    413. 

  413. 	an abstraction of a process.
    414. 

  414.       </p><p>
    415. 

  415. 	To add a process to the set, let's say the resolver (which
    416. 

  416. 	is not started by default), you would do this:
    417. 

  417.         </p><pre class="screen">&gt; <strong class="userinput"><code>config add Boss/components b10-resolver</code></strong>
    418. 

  418. &gt; <strong class="userinput"><code>config set Boss/components/b10-resolver/special resolver</code></strong>
    419. 

  419. &gt; <strong class="userinput"><code>config set Boss/components/b10-resolver/kind needed</code></strong>
    420. 

  420. &gt; <strong class="userinput"><code>config set Boss/components/b10-resolver/priority 10</code></strong>
    421. 

  421. &gt; <strong class="userinput"><code>config commit</code></strong></pre><p>
    422. 

  422. 	Now, what it means. We add an entry called
    423. 

  423. 	<span class="quote">&#8220;<span class="quote">b10-resolver</span>&#8221;</span>. It is both a name used to
    424. 

  424. 	reference this component in the configuration and the name
    425. 

  425. 	of the process to start. Then we set some parameters on
    426. 

  426. 	how to start it.
    427. 

  427.       </p><p>
    428. 

  428. 	The <code class="varname">special</code> setting is for components
    429. 

  429. 	that need some kind of special care during startup or
    430. 

  430. 	shutdown. Unless specified, the component is started in a
    431. 

  431. 	usual way. This is the list of components that need to be
    432. 

  432. 	started in a special way, with the value of special used
    433. 

  433. 	for them:
    434. 

  434. 

  435.         </p><div class="table"><a name="id1168229437333"></a><p class="title"><b>Table 3.1. Special startup components</b></p><div class="table-contents"><table summary="Special startup components" border="1"><colgroup><col align="left"><col align="left"><col align="left"></colgroup><thead><tr><th align="left">Component</th><th align="left">Special</th><th align="left">Description</th></tr></thead><tbody><tr><td align="left">b10-auth</td><td align="left">auth</td><td align="left">Authoritative DNS server</td></tr><tr><td align="left">b10-resolver</td><td align="left">resolver</td><td align="left">DNS resolver</td></tr><tr><td align="left">b10-cmdctl</td><td align="left">cmdctl</td><td align="left">Command control (remote control interface)</td></tr></tbody></table></div></div><p><br class="table-break">
    436. 

  436.       </p><p>
    437. 

  437. 	The <code class="varname">kind</code> specifies how a failure of the
    438. 

  438. 	component should be handled.  If it is set to
    439. 

  439. 	<span class="quote">&#8220;<span class="quote">dispensable</span>&#8221;</span> (the default unless you set
    440. 

  440. 	something else), it will get started again if it fails. If
    441. 

  441. 	it is set to <span class="quote">&#8220;<span class="quote">needed</span>&#8221;</span> and it fails at startup,
    442. 

  442. 	the whole <span class="command"><strong>bind10</strong></span> shuts down and exits
    443. 

  443. 	with an error exit code. But if it fails some time later, it
    444. 

  444. 	is just started again. If you set it to <span class="quote">&#8220;<span class="quote">core</span>&#8221;</span>,
    445. 

  445. 	you indicate that the system is not usable without the
    446. 

  446. 	component and if such component fails, the system shuts
    447. 

  447. 	down no matter when the failure happened.  This is the
    448. 

  448. 	behaviour of the core components (the ones you can't turn
    449. 

  449. 	off), but you can declare any other components as core as
    450. 

  450. 	well if you wish (but you can turn these off, they just
    451. 

  451. 	can't fail).
    452. 

  452.       </p><p>
    453. 

  453. 	The <code class="varname">priority</code> defines order in which the
    454. 

  454. 	components should start.  The ones with higher numbers are
    455. 

  455. 	started sooner than the ones with lower ones. If you don't
    456. 

  456. 	set it, 0 (zero) is used as the priority.  Usually, leaving
    457. 

  457. 	it at the default is enough.
    458. 

  458.       </p><p>
    459. 

  459.         There are other parameters we didn't use in our example.
    460. 

  460.         One of them is <code class="varname">address</code>. It is the address
    461. 

  461.         used by the component on the <span class="command"><strong>b10-msgq</strong></span>
    462. 

  462.         message bus. The special components already know their
    463. 

  463.         address, but the usual ones don't. The address is by
    464. 

  464.         convention the thing after <span class="emphasis"><em>b10-</em></span>, with
    465. 

  465.         the first letter capitalized (eg. <span class="command"><strong>b10-stats</strong></span>
    466. 

  466.         would have <span class="quote">&#8220;<span class="quote">Stats</span>&#8221;</span> as its address).
    467. 

  467. 

  468.       </p><p>
    469. 

  469. 	The last one is <code class="varname">process</code>. It is the name
    470. 

  470. 	of the process to be started.  It defaults to the name of
    471. 

  471. 	the component if not set, but you can use this to override
    472. 

  472. 	it. (The special components also already know their
    473. 

  473.         executable name.)
    474. 

  474.       </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
    475. 

  475.           The configuration is quite powerful, but that includes
    476. 

  476.           a lot of space for mistakes. You could turn off the
    477. 

  477.           <span class="command"><strong>b10-cmdctl</strong></span>, but then you couldn't
    478. 

  478.           change it back the usual way, as it would require it to
    479. 

  479.           be running (you would have to find and edit the configuration
    480. 

  480.           directly).  Also, some modules might have dependencies:
    481. 

  481.           <span class="command"><strong>b10-stats-httpd</strong></span> needs
    482. 

  482.           <span class="command"><strong>b10-stats</strong></span>, <span class="command"><strong>b10-xfrout</strong></span>
    483. 

  483.           needs <span class="command"><strong>b10-auth</strong></span> to be running, etc.
    484. 

  484. 

  485. 

  486. 

  487.         </p><p>
    488. 

  488.           In short, you should think twice before disabling something here.
    489. 

  489.         </p></div><p>
    490. 

  490.         It is possible to start some components multiple times (currently
    491. 

  491.         <span class="command"><strong>b10-auth</strong></span> and <span class="command"><strong>b10-resolver</strong></span>).
    492. 

  492.         You might want to do that to gain more performance (each one uses only
    493. 

  493.         single core). Just put multiple entries under different names, like
    494. 

  494.         this, with the same config:
    495. 

  495.         </p><pre class="screen">&gt; <strong class="userinput"><code>config add Boss/components b10-resolver-2</code></strong>
    496. 

  496. &gt; <strong class="userinput"><code>config set Boss/components/b10-resolver-2/special resolver</code></strong>
    497. 

  497. &gt; <strong class="userinput"><code>config set Boss/components/b10-resolver-2/kind needed</code></strong>
    498. 

  498. &gt; <strong class="userinput"><code>config commit</code></strong></pre><p>
    499. 

  499.       </p><p>
    500. 

  500.         However, this is work in progress and the support is not yet complete.
    501. 

  501.         For example, each resolver will have its own cache, each authoritative
    502. 

  502.         server will keep its own copy of in-memory data and there could be
    503. 

  503.         problems with locking the sqlite database, if used. The configuration
    504. 

  504.         might be changed to something more convenient in future.
    505. 

  505. 	Other components don't expect such a situation, so it would
    506. 

  506. 	probably not do what you want. Such support is yet to be
    507. 

  507. 	implemented.
    508. 

  508.       </p></div></div><div class="chapter" title="Chapter 4. Command channel"><div class="titlepage"><div><div><h2 class="title"><a name="msgq"></a>Chapter 4. Command channel</h2></div></div></div><p>
    509. 

  509.         The BIND 10 components use the <span class="command"><strong>b10-msgq</strong></span>
    510. 

  510.         message routing daemon to communicate with other BIND 10 components.
    511. 

  511.         The <span class="command"><strong>b10-msgq</strong></span> implements what is called the
    512. 

  512.         <span class="quote">&#8220;<span class="quote">Command Channel</span>&#8221;</span>.
    513. 

  513.         Processes intercommunicate by sending messages on the command
    514. 

  514.         channel.
    515. 

  515.         Example messages include shutdown, get configurations, and set
    516. 

  516.         configurations.
    517. 

  517.         This Command Channel is not used for DNS message passing.
    518. 

  518.         It is used only to control and monitor the BIND 10 system.
    519. 

  519.       </p><p>
    520. 

  520.         Administrators do not communicate directly with the
    521. 

  521.         <span class="command"><strong>b10-msgq</strong></span> daemon.
    522. 

  522.         By default, BIND 10 uses a UNIX domain socket file named
    523. 

  523.         <code class="filename">/usr/local/var/bind10-devel/msg_socket</code>
    524. 

  524.         for this interprocess communication.
    525. 

  525.       </p></div><div class="chapter" title="Chapter 5. Configuration manager"><div class="titlepage"><div><div><h2 class="title"><a name="cfgmgr"></a>Chapter 5. Configuration manager</h2></div></div></div><p>
    526. 

  526.          The configuration manager, <span class="command"><strong>b10-cfgmgr</strong></span>,
    527. 

  527.          handles all BIND 10 system configuration.  It provides
    528. 

  528.          persistent storage for configuration, and notifies running
    529. 

  529.          modules of configuration changes.
    530. 

  530.       </p><p>
    531. 

  531.         The <span class="command"><strong>b10-auth</strong></span> and <span class="command"><strong>b10-xfrin</strong></span>
    532. 

  532.         daemons and other components receive their configurations
    533. 

  533.         from the configuration manager over the <span class="command"><strong>b10-msgq</strong></span>
    534. 

  534.         command channel.
    535. 

  535.       </p><p>The administrator doesn't connect to it directly, but
    536. 

  536.         uses a user interface to communicate with the configuration
    537. 

  537.         manager via <span class="command"><strong>b10-cmdctl</strong></span>'s REST-ful interface.
    538. 

  538.         <span class="command"><strong>b10-cmdctl</strong></span> is covered in <a class="xref" href="#cmdctl" title="Chapter 6. Remote control daemon">Chapter 6, <i>Remote control daemon</i></a>.
    539. 

  539.       </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
    540. 

  540.           The development prototype release only provides
    541. 

  541.           <span class="command"><strong>bindctl</strong></span> as a user interface to
    542. 

  542.           <span class="command"><strong>b10-cmdctl</strong></span>.
    543. 

  543.           Upcoming releases will provide another interactive command-line
    544. 

  544.           interface and a web-based interface.
    545. 

  545.         </p></div><p>
    546. 

  546.         The <span class="command"><strong>b10-cfgmgr</strong></span> daemon can send all
    547. 

  547.         specifications and all current settings to the
    548. 

  548.         <span class="command"><strong>bindctl</strong></span> client (via
    549. 

  549.         <span class="command"><strong>b10-cmdctl</strong></span>).
    550. 

  550.         <span class="command"><strong>b10-cfgmgr</strong></span> relays configurations received
    551. 

  551.         from <span class="command"><strong>b10-cmdctl</strong></span> to the appropriate modules.
    552. 

  552.       </p><p>
    553. 

  553.         The stored configuration file is at
    554. 

  554.         <code class="filename">/usr/local/var/bind10-devel/b10-config.db</code>.
    555. 

  555.         (The directory is what was defined at build configure time for
    556. 

  556.         <code class="option">--localstatedir</code>.
    557. 

  557.         The default is <code class="filename">/usr/local/var/</code>.)
    558. 

  558.         The format is loosely based on JSON and is directly parseable
    559. 

  559.         python, but this may change in a future version.
    560. 

  560.         This configuration data file is not manually edited by the
    561. 

  561.         administrator.
    562. 

  562.       </p><p>
    563. 

  563.       The configuration manager does not have any command line arguments.
    564. 

  564.       Normally it is not started manually, but is automatically
    565. 

  565.       started using the <span class="command"><strong>bind10</strong></span> master process
    566. 

  566.       (as covered in <a class="xref" href="#bind10" title="Chapter 3. Starting BIND10 with bind10">Chapter 3, <i>Starting BIND10 with <span class="command"><strong>bind10</strong></span></i></a>).
    567. 

  567.     </p></div><div class="chapter" title="Chapter 6. Remote control daemon"><div class="titlepage"><div><div><h2 class="title"><a name="cmdctl"></a>Chapter 6. Remote control daemon</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#cmdctl.spec">6.1. Configuration specification for b10-cmdctl</a></span></dt></dl></div><p>
    568. 

  568.       <span class="command"><strong>b10-cmdctl</strong></span> is the gateway between
    569. 

  569.       administrators and the BIND 10 system.
    570. 

  570.       It is a HTTPS server that uses standard HTTP Digest
    571. 

  571.       Authentication for username and password validation.
    572. 

  572.       It provides a REST-ful interface for accessing and controlling
    573. 

  573.       BIND 10.
    574. 

  574.     </p><p>
    575. 

  575.       When <span class="command"><strong>b10-cmdctl</strong></span> starts, it firsts
    576. 

  576.       asks <span class="command"><strong>b10-cfgmgr</strong></span> about what modules are
    577. 

  577.       running and what their configuration is (over the
    578. 

  578.       <span class="command"><strong>b10-msgq</strong></span> channel). Then it will start listening
    579. 

  579.       on HTTPS for clients &#8212; the user interface &#8212; such
    580. 

  580.       as <span class="command"><strong>bindctl</strong></span>.
    581. 

  581.     </p><p>
    582. 

  582.       <span class="command"><strong>b10-cmdctl</strong></span> directly sends commands
    583. 

  583.       (received from the user interface) to the specified component.
    584. 

  584.       Configuration changes are actually commands to
    585. 

  585.       <span class="command"><strong>b10-cfgmgr</strong></span> so are sent there.
    586. 

  586.     </p><p>The HTTPS server requires a private key,
    587. 

  587.       such as a RSA PRIVATE KEY.
    588. 

  588.       The default location is at
    589. 

  589.       <code class="filename">/usr/local/etc/bind10-devel/cmdctl-keyfile.pem</code>.
    590. 

  590.       (A sample key is at
    591. 

  591.       <code class="filename">/usr/local/share/bind10-devel/cmdctl-keyfile.pem</code>.)
    592. 

  592.       It also uses a certificate located at
    593. 

  593.       <code class="filename">/usr/local/etc/bind10-devel/cmdctl-certfile.pem</code>.
    594. 

  594.       (A sample certificate is at
    595. 

  595.       <code class="filename">/usr/local/share/bind10-devel/cmdctl-certfile.pem</code>.)
    596. 

  596.       This may be a self-signed certificate or purchased from a
    597. 

  597.       certification authority.
    598. 

  598.     </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
    599. 

  599.       The HTTPS server doesn't support a certificate request from a
    600. 

  600.       client (at this time).
    601. 

  601. 

  602.       The <span class="command"><strong>b10-cmdctl</strong></span> daemon does not provide a
    603. 

  603.       public service. If any client wants to control BIND 10, then
    604. 

  604.       a certificate needs to be first received from the BIND 10
    605. 

  605.       administrator.
    606. 

  606.       The BIND 10 installation provides a sample PEM bundle that matches
    607. 

  607.       the sample key and certificate.
    608. 

  608.     </p></div><p>
    609. 

  609.       The <span class="command"><strong>b10-cmdctl</strong></span> daemon also requires
    610. 

  610.       the user account file located at
    611. 

  611.       <code class="filename">/usr/local/etc/bind10-devel/cmdctl-accounts.csv</code>.
    612. 

  612.       This comma-delimited file lists the accounts with a user name,
    613. 

  613.       hashed password, and salt.
    614. 

  614.       (A sample file is at
    615. 

  615.       <code class="filename">/usr/local/share/bind10-devel/cmdctl-accounts.csv</code>.
    616. 

  616.       It contains the user named <span class="quote">&#8220;<span class="quote">root</span>&#8221;</span> with the password
    617. 

  617.       <span class="quote">&#8220;<span class="quote">bind10</span>&#8221;</span>.)
    618. 

  618.     </p><p>
    619. 

  619.       The administrator may create a user account with the
    620. 

  620.       <span class="command"><strong>b10-cmdctl-usermgr</strong></span> tool.
    621. 

  621.     </p><p>
    622. 

  622.       By default the HTTPS server listens on the localhost port 8080.
    623. 

  623.       The port can be set by using the <code class="option">--port</code> command line option.
    624. 

  624.       The address to listen on can be set using the <code class="option">--address</code> command
    625. 

  625.       line argument.
    626. 

  626.       Each HTTPS connection is stateless and times out in 1200 seconds
    627. 

  627.       by default.  This can be
    628. 

  628.       redefined by using the <code class="option">--idle-timeout</code> command line argument.
    629. 

  629.     </p><div class="section" title="6.1. Configuration specification for b10-cmdctl"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="cmdctl.spec"></a>6.1. Configuration specification for b10-cmdctl</h2></div></div></div><p>
    630. 

  630.         The configuration items for <span class="command"><strong>b10-cmdctl</strong></span> are:
    631. 

  631.         <code class="varname">accounts_file</code> which defines the path to the
    632. 

  632.         user accounts database (the default is
    633. 

  633.         <code class="filename">/usr/local/etc/bind10-devel/cmdctl-accounts.csv</code>);
    634. 

  634.         <code class="varname">cert_file</code> which defines the path to the
    635. 

  635.         PEM certificate file (the default is
    636. 

  636.         <code class="filename">/usr/local/etc/bind10-devel/cmdctl-certfile.pem</code>);
    637. 

  637.         and
    638. 

  638. 	<code class="varname">key_file</code> which defines the path to the
    639. 

  639. 	PEM private key file (the default is
    640. 

  640.         <code class="filename">/usr/local/etc/bind10-devel/cmdctl-keyfile.pem</code>).
    641. 

  641.       </p></div></div><div class="chapter" title="Chapter 7. Control and configure user interface"><div class="titlepage"><div><div><h2 class="title"><a name="bindctl"></a>Chapter 7. Control and configure user interface</h2></div></div></div><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
    642. 

  642.       For this development prototype release, <span class="command"><strong>bindctl</strong></span>
    643. 

  643.       is the only user interface. It is expected that upcoming
    644. 

  644.       releases will provide another interactive command-line
    645. 

  645.       interface and a web-based interface for controlling and
    646. 

  646.       configuring BIND 10.
    647. 

  647.     </p></div><p>
    648. 

  648.       The <span class="command"><strong>bindctl</strong></span> tool provides an interactive
    649. 

  649.       prompt for configuring, controlling, and querying the BIND 10
    650. 

  650.       components.
    651. 

  651.       It communicates directly with a REST-ful interface over HTTPS
    652. 

  652.       provided by <span class="command"><strong>b10-cmdctl</strong></span>. It doesn't
    653. 

  653.       communicate to any other components directly.
    654. 

  654.     </p><p>
    655. 

  655.       Configuration changes are actually commands to
    656. 

  656.       <span class="command"><strong>b10-cfgmgr</strong></span>. So when <span class="command"><strong>bindctl</strong></span>
    657. 

  657.       sends a configuration, it is sent to <span class="command"><strong>b10-cmdctl</strong></span>
    658. 

  658.       (over a HTTPS connection); then <span class="command"><strong>b10-cmdctl</strong></span>
    659. 

  659.       sends the command (over a <span class="command"><strong>b10-msgq</strong></span> command
    660. 

  660.       channel) to <span class="command"><strong>b10-cfgmgr</strong></span> which then stores
    661. 

  661.       the details and relays (over a <span class="command"><strong>b10-msgq</strong></span> command
    662. 

  662.       channel) the configuration on to the specified module.
    663. 

  663.     </p><p>
    664. 

  664.     </p></div><div class="chapter" title="Chapter 8. Authoritative Server"><div class="titlepage"><div><div><h2 class="title"><a name="authserver"></a>Chapter 8. Authoritative Server</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#id1168229438312">8.1. Server Configurations</a></span></dt><dt><span class="section"><a href="#id1168229438638">8.2. Data Source Backends</a></span></dt><dd><dl><dt><span class="section"><a href="#in-memory-datasource">8.2.1. In-memory Data Source</a></span></dt><dt><span class="section"><a href="#in-memory-datasource-with-sqlite3-backend">8.2.2. In-memory Data Source with SQLite3 Backend</a></span></dt><dt><span class="section"><a href="#in-memory-datasource-loading">8.2.3. Reloading an In-memory Data Source</a></span></dt><dt><span class="section"><a href="#in-memory-datasource-disabling">8.2.4. Disabling In-memory Data Sources</a></span></dt></dl></dd><dt><span class="section"><a href="#id1168229438940">8.3. Loading Master Zones Files</a></span></dt></dl></div><p>
    665. 

  665.       The <span class="command"><strong>b10-auth</strong></span> is the authoritative DNS server.
    666. 

  666.       It supports EDNS0, DNSSEC, IPv6, and SQLite3 and in-memory zone
    667. 

  667.       data backends.
    668. 

  668.       Normally it is started by the <span class="command"><strong>bind10</strong></span> master
    669. 

  669.       process.
    670. 

  670.     </p><div class="section" title="8.1. Server Configurations"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id1168229438312"></a>8.1. Server Configurations</h2></div></div></div><p>
    671. 

  671.         <span class="command"><strong>b10-auth</strong></span> is configured via the
    672. 

  672.         <span class="command"><strong>b10-cfgmgr</strong></span> configuration manager.
    673. 

  673.         The module name is <span class="quote">&#8220;<span class="quote">Auth</span>&#8221;</span>.
    674. 

  674.         The configuration data items are:
    675. 

  675. 

  676.         </p><div class="variablelist"><dl><dt><span class="term">database_file</span></dt><dd>This is an optional string to define the path to find
    677. 

  677.                  the SQLite3 database file.
    678. 

  678. 

  679. Note: This may be a temporary setting because the DNS server
    680. 

  680. can use various data source backends.
    681. 

  681.               </dd><dt><span class="term">datasources</span></dt><dd>
    682. 

  682.       <code class="varname">datasources</code> configures data sources.
    683. 

  683.       The list items include:
    684. 

  684.       <code class="varname">type</code> to define the required data source type
    685. 

  685.       (such as <span class="quote">&#8220;<span class="quote">memory</span>&#8221;</span>);
    686. 

  686.       <code class="varname">class</code> to optionally select the class
    687. 

  687.       (it defaults to <span class="quote">&#8220;<span class="quote">IN</span>&#8221;</span>);
    688. 

  688.       and
    689. 

  689.       <code class="varname">zones</code> to define
    690. 

  690.       the <code class="varname">file</code> path name,
    691. 

  691.       the <code class="varname">filetype</code> (<span class="quote">&#8220;<span class="quote">sqlite3</span>&#8221;</span> to load
    692. 

  692.       from a SQLite3 database file or <span class="quote">&#8220;<span class="quote">text</span>&#8221;</span> to
    693. 

  693.       load from a master text file),
    694. 

  694.       and the <code class="varname">origin</code> (default domain).
    695. 

  695. 

  696.       By default, this is empty.
    697. 

  697. 

  698.       <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
    699. 

  699.         In this development version, currently this is only used for the
    700. 

  700.         memory data source.
    701. 

  701.         Only the IN class is supported at this time.
    702. 

  702.         By default, the memory data source is disabled.
    703. 

  703.         Also, currently the zone file must be canonical such as
    704. 

  704.         generated by <span class="command"><strong>named-compilezone -D</strong></span>, or
    705. 

  705.         must be an SQLite3 database.
    706. 

  706.       </p></div>
    707. 

  707. 

  708.               </dd><dt><span class="term">listen_on</span></dt><dd>
    709. 

  709.       <code class="varname">listen_on</code> is a list of addresses and ports for
    710. 

  710.       <span class="command"><strong>b10-auth</strong></span> to listen on.
    711. 

  711.       The list items are the <code class="varname">address</code> string
    712. 

  712.       and <code class="varname">port</code> number.
    713. 

  713.       By default, <span class="command"><strong>b10-auth</strong></span> listens on port 53
    714. 

  714.       on the IPv6 (::) and IPv4 (0.0.0.0) wildcard addresses.
    715. 

  715.       <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
    716. 

  716.           The default configuration is currently not appropriate for a multi-homed host.
    717. 

  717.           In case you have multiple public IP addresses, it is possible the
    718. 

  718.           query UDP packet comes through one interface and the answer goes out
    719. 

  719.           through another. The answer will probably be dropped by the client, as it
    720. 

  720.           has a different source address than the one it sent the query to. The
    721. 

  721.           client would fallback on TCP after several attempts, which works
    722. 

  722.           well in this situation, but is clearly not ideal.
    723. 

  723.         </p><p>
    724. 

  724.           There are plans to solve the problem such that the server handles
    725. 

  725.           it by itself. But until it is actually implemented, it is recommended to
    726. 

  726.           alter the configuration &#8212; remove the wildcard addresses and list all
    727. 

  727.           addresses explicitly. Then the server will answer on the same
    728. 

  728.           interface the request came on, preserving the correct address.
    729. 

  729.         </p></div>
    730. 

  730.               </dd><dt><span class="term">statistics-interval</span></dt><dd>
    731. 

  731.       <code class="varname">statistics-interval</code> is the timer interval
    732. 

  732.       in seconds for <span class="command"><strong>b10-auth</strong></span> to share its
    733. 

  733.       statistics information to
    734. 

  734.       <span class="citerefentry"><span class="refentrytitle">b10-stats</span>(8)</span>.
    735. 

  735.       Statistics updates can be disabled by setting this to 0.
    736. 

  736.       The default is 60.
    737. 

  737.               </dd></dl></div><p>
    738. 

  738. 

  739.       </p><p>
    740. 

  740. 

  741.         The configuration commands are:
    742. 

  742. 

  743.         </p><div class="variablelist"><dl><dt><span class="term">loadzone</span></dt><dd>
    744. 

  744.       <span class="command"><strong>loadzone</strong></span> tells <span class="command"><strong>b10-auth</strong></span>
    745. 

  745.       to load or reload a zone file. The arguments include:
    746. 

  746.       <code class="varname">class</code> which optionally defines the class
    747. 

  747.       (it defaults to <span class="quote">&#8220;<span class="quote">IN</span>&#8221;</span>);
    748. 

  748.       <code class="varname">origin</code> is the domain name of the zone;
    749. 

  749.       and
    750. 

  750.       <code class="varname">datasrc</code> optionally defines the type of datasource
    751. 

  751.       (it defaults to <span class="quote">&#8220;<span class="quote">memory</span>&#8221;</span>).
    752. 

  752. 

  753.       <div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
    754. 

  754.         In this development version, currently this only supports the
    755. 

  755.         IN class and the memory data source.
    756. 

  756.       </p></div>
    757. 

  757.               </dd><dt><span class="term">sendstats</span></dt><dd>
    758. 

  758.       <span class="command"><strong>sendstats</strong></span> tells <span class="command"><strong>b10-auth</strong></span>
    759. 

  759.       to send its statistics data to
    760. 

  760.       <span class="citerefentry"><span class="refentrytitle">b10-stats</span>(8)</span>
    761. 

  761.       immediately.
    762. 

  762.               </dd><dt><span class="term">shutdown</span></dt><dd>Stop the authoritative DNS server.
    763. 

  763.       This has an optional <code class="varname">pid</code> argument to
    764. 

  764.       select the process ID to stop.
    765. 

  765.       (Note that the BIND 10 boss process may restart this service
    766. 

  766.       if configured.)
    767. 

  767.               </dd></dl></div><p>
    768. 

  768. 

  769.       </p></div><div class="section" title="8.2. Data Source Backends"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id1168229438638"></a>8.2. Data Source Backends</h2></div></div></div><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
    770. 

  770.         For the development prototype release, <span class="command"><strong>b10-auth</strong></span>
    771. 

  771.         supports a SQLite3 data source backend and in-memory data source
    772. 

  772.         backend.
    773. 

  773.         Upcoming versions will be able to use multiple different
    774. 

  774.         data sources, such as MySQL and Berkeley DB.
    775. 

  775.       </p></div><p>
    776. 

  776.         By default, the SQLite3 backend uses the data file located at
    777. 

  777.         <code class="filename">/usr/local/var/bind10-devel/zone.sqlite3</code>.
    778. 

  778.         (The full path is what was defined at build configure time for
    779. 

  779.         <code class="option">--localstatedir</code>.
    780. 

  780.         The default is <code class="filename">/usr/local/var/</code>.)
    781. 

  781. 	This data file location may be changed by defining the
    782. 

  782. 	<span class="quote">&#8220;<span class="quote">database_file</span>&#8221;</span> configuration.
    783. 

  783.       </p><div class="section" title="8.2.1. In-memory Data Source"><div class="titlepage"><div><div><h3 class="title"><a name="in-memory-datasource"></a>8.2.1. In-memory Data Source</h3></div></div></div><p>
    784. 

  784. 

  785. 	  The following commands to <span class="command"><strong>bindctl</strong></span>
    786. 

  786. 	  provide an example of configuring an in-memory data
    787. 

  787. 	  source containing the <span class="quote">&#8220;<span class="quote">example.com</span>&#8221;</span> zone
    788. 

  788. 	  with the zone file named <span class="quote">&#8220;<span class="quote">example.com.zone</span>&#8221;</span>:
    789. 

  789. 

  790. 

  791. 

  792.           </p><pre class="screen">&gt; <strong class="userinput"><code>config add Auth/datasources</code></strong>
    793. 

  793. &gt; <strong class="userinput"><code>config set Auth/datasources[0]/type "<code class="option">memory</code>"</code></strong>
    794. 

  794. &gt; <strong class="userinput"><code>config add Auth/datasources[0]/zones</code></strong>
    795. 

  795. &gt; <strong class="userinput"><code>config set Auth/datasources[0]/zones[0]/origin "<code class="option">example.com</code>"</code></strong>
    796. 

  796. &gt; <strong class="userinput"><code>config set Auth/datasources[0]/zones[0]/file "<code class="option">example.com.zone</code>"</code></strong>
    797. 

  797. &gt; <strong class="userinput"><code>config commit</code></strong></pre><p>
    798. 

  798. 

  799. 	  The authoritative server will begin serving it immediately
    800. 

  800. 	  after the zone data is loaded from the master text file.
    801. 

  801. 	</p></div><div class="section" title="8.2.2. In-memory Data Source with SQLite3 Backend"><div class="titlepage"><div><div><h3 class="title"><a name="in-memory-datasource-with-sqlite3-backend"></a>8.2.2. In-memory Data Source with SQLite3 Backend</h3></div></div></div><p>
    802. 

  802. 

  803. 	  The following commands to <span class="command"><strong>bindctl</strong></span>
    804. 

  804. 	  provide an example of configuring an in-memory data
    805. 

  805. 	  source containing the <span class="quote">&#8220;<span class="quote">example.org</span>&#8221;</span> zone
    806. 

  806. 	  with a SQLite3 backend file named <span class="quote">&#8220;<span class="quote">example.org.sqlite3</span>&#8221;</span>:
    807. 

  807. 

  808. 

  809. 

  810.           </p><pre class="screen">&gt; <strong class="userinput"><code>config add Auth/datasources</code></strong>
    811. 

  811. &gt; <strong class="userinput"><code>config set Auth/datasources[1]/type "<code class="option">memory</code>"</code></strong>
    812. 

  812. &gt; <strong class="userinput"><code>config add Auth/datasources[1]/zones</code></strong>
    813. 

  813. &gt; <strong class="userinput"><code>config set Auth/datasources[1]/zones[0]/origin "<code class="option">example.org</code>"</code></strong>
    814. 

  814. &gt; <strong class="userinput"><code>config set Auth/datasources[1]/zones[0]/file "<code class="option">example.org.sqlite3</code>"</code></strong>
    815. 

  815. &gt; <strong class="userinput"><code>config set Auth/datasources[1]/zones[0]/filetype "<code class="option">sqlite3</code>"</code></strong>
    816. 

  816. &gt; <strong class="userinput"><code>config commit</code></strong></pre><p>
    817. 

  817. 

  818. 	  The authoritative server will begin serving it immediately
    819. 

  819. 	  after the zone data is loaded from the database file.
    820. 

  820. 	</p></div><div class="section" title="8.2.3. Reloading an In-memory Data Source"><div class="titlepage"><div><div><h3 class="title"><a name="in-memory-datasource-loading"></a>8.2.3. Reloading an In-memory Data Source</h3></div></div></div><p>
    821. 

  821. 	  Use the <span class="command"><strong>Auth loadzone</strong></span> command in
    822. 

  822. 	  <span class="command"><strong>bindctl</strong></span> to reload a changed master
    823. 

  823. 	  file into memory; for example:
    824. 

  824. 

  825. 	  </p><pre class="screen">&gt; <strong class="userinput"><code>Auth loadzone origin="example.com"</code></strong>
    826. 

  826. </pre><p>
    827. 

  827. 

  828. 	</p></div><div class="section" title="8.2.4. Disabling In-memory Data Sources"><div class="titlepage"><div><div><h3 class="title"><a name="in-memory-datasource-disabling"></a>8.2.4. Disabling In-memory Data Sources</h3></div></div></div><p>
    829. 

  829. 	By default, the memory data source is disabled; it must be
    830. 

  830. 	configured explicitly.  To disable all the in-memory zones,
    831. 

  831. 	specify a null list for <code class="varname">Auth/datasources</code>:
    832. 

  832. 

  833. 

  834. 

  835. 	  </p><pre class="screen">&gt; <strong class="userinput"><code>config set Auth/datasources/ []</code></strong>
    836. 

  836. &gt; <strong class="userinput"><code>config commit</code></strong></pre><p>
    837. 

  837. 	</p><p>
    838. 

  838.           The following example stops serving a specific zone:
    839. 

  839. 

  840. 	  </p><pre class="screen">&gt; <strong class="userinput"><code>config remove Auth/datasources[<code class="option">0</code>]/zones[<code class="option">0</code>]</code></strong>
    841. 

  841. &gt; <strong class="userinput"><code>config commit</code></strong></pre><p>
    842. 

  842. 

  843. 	  (Replace the list number(s) in
    844. 

  844. 	  <code class="varname">datasources[<em class="replaceable"><code>0</code></em>]</code>
    845. 

  845. 	  and/or <code class="varname">zones[<em class="replaceable"><code>0</code></em>]</code>
    846. 

  846. 	  for the relevant zone as needed.)
    847. 

  847. 

  848. 	</p></div></div><div class="section" title="8.3. Loading Master Zones Files"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id1168229438940"></a>8.3. Loading Master Zones Files</h2></div></div></div><p>
    849. 

  849.         RFC 1035 style DNS master zone files may imported
    850. 

  850.         into a BIND 10 SQLite3 data source by using the
    851. 

  851.         <span class="command"><strong>b10-loadzone</strong></span> utility.
    852. 

  852.       </p><p>
    853. 

  853.         <span class="command"><strong>b10-loadzone</strong></span> supports the following
    854. 

  854.         special directives (control entries):
    855. 

  855. 

  856.         </p><div class="variablelist"><dl><dt><span class="term">$INCLUDE</span></dt><dd>Loads an additional zone file. This may be recursive.
    857. 

  857.               </dd><dt><span class="term">$ORIGIN</span></dt><dd>Defines the relative domain name.
    858. 

  858.               </dd><dt><span class="term">$TTL</span></dt><dd>Defines the time-to-live value used for following
    859. 

  859.                 records that don't include a TTL.
    860. 

  860.               </dd></dl></div><p>
    861. 

  861. 

  862.       </p><p>
    863. 

  863.         The <code class="option">-o</code> argument may be used to define the
    864. 

  864.         default origin for loaded zone file records.
    865. 

  865.       </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
    866. 

  866.         In the development prototype release, only the SQLite3 back
    867. 

  867.         end is used by <span class="command"><strong>b10-loadzone</strong></span>.
    868. 

  868.         By default, it stores the zone data in
    869. 

  869.         <code class="filename">/usr/local/var/bind10-devel/zone.sqlite3</code>
    870. 

  870.         unless the <code class="option">-d</code> switch is used to set the
    871. 

  871.         database filename.
    872. 

  872.         Multiple zones are stored in a single SQLite3 zone database.
    873. 

  873.       </p></div><p>
    874. 

  874.         If you reload a zone already existing in the database,
    875. 

  875.         all records from that prior zone disappear and a whole new set
    876. 

  876.         appears.
    877. 

  877.       </p></div></div><div class="chapter" title="Chapter 9. Incoming Zone Transfers"><div class="titlepage"><div><div><h2 class="title"><a name="xfrin"></a>Chapter 9. Incoming Zone Transfers</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#id1168229439105">9.1. Configuration for Incoming Zone Transfers</a></span></dt><dt><span class="section"><a href="#id1168229439142">9.2. Enabling IXFR</a></span></dt><dt><span class="section"><a href="#zonemgr">9.3. Secondary Manager</a></span></dt><dt><span class="section"><a href="#id1168229439316">9.4. Trigger an Incoming Zone Transfer Manually</a></span></dt><dt><span class="section"><a href="#id1168229439342">9.5. Incoming Transfers with In-memory Datasource</a></span></dt></dl></div><p>
    878. 

  878.       Incoming zones are transferred using the <span class="command"><strong>b10-xfrin</strong></span>
    879. 

  879.       process which is started by <span class="command"><strong>bind10</strong></span>.
    880. 

  880.       When received, the zone is stored in the corresponding BIND 10
    881. 

  881.       data source, and its records can be served by
    882. 

  882.       <span class="command"><strong>b10-auth</strong></span>.
    883. 

  883.       In combination with <span class="command"><strong>b10-zonemgr</strong></span> (for
    884. 

  884.       automated SOA checks), this allows the BIND 10 server to
    885. 

  885.       provide <span class="emphasis"><em>secondary</em></span> service.
    886. 

  886.     </p><p>
    887. 

  887.       The <span class="command"><strong>b10-xfrin</strong></span> process supports both AXFR and
    888. 

  888.       IXFR.  Due to some implementation limitations of the current
    889. 

  889.       development release, however, it only tries AXFR by default,
    890. 

  890.       and care should be taken to enable IXFR.
    891. 

  891.     </p><div class="section" title="9.1. Configuration for Incoming Zone Transfers"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id1168229439105"></a>9.1. Configuration for Incoming Zone Transfers</h2></div></div></div><p>
    892. 

  892.         In practice, you need to specify a list of secondary zones to
    893. 

  893.         enable incoming zone transfers for these zones (you can still
    894. 

  894.         trigger a zone transfer manually, without a prior configuration
    895. 

  895.         (see below)).
    896. 

  896.       </p><p>
    897. 

  897.         For example, to enable zone transfers for a zone named "example.com"
    898. 

  898.         (whose master address is assumed to be 2001:db8::53 here),
    899. 

  899.         run the following at the <span class="command"><strong>bindctl</strong></span> prompt:
    900. 

  900. 

  901.       </p><pre class="screen">&gt; <strong class="userinput"><code>config add Xfrin/zones</code></strong>
    902. 

  902. &gt; <strong class="userinput"><code>config set Xfrin/zones[0]/name "<code class="option">example.com</code>"</code></strong>
    903. 

  903. &gt; <strong class="userinput"><code>config set Xfrin/zones[0]/master_addr "<code class="option">2001:db8::53</code>"</code></strong>
    904. 

  904. &gt; <strong class="userinput"><code>config commit</code></strong></pre><p>
    905. 

  905. 

  906.       (We assume there has been no zone configuration before).
    907. 

  907.       </p></div><div class="section" title="9.2. Enabling IXFR"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id1168229439142"></a>9.2. Enabling IXFR</h2></div></div></div><p>
    908. 

  908.         As noted above, <span class="command"><strong>b10-xfrin</strong></span> uses AXFR for
    909. 

  909.         zone transfers by default.  To enable IXFR for zone transfers
    910. 

  910.         for a particular zone, set the <strong class="userinput"><code>use_ixfr</code></strong>
    911. 

  911.         configuration parameter to <strong class="userinput"><code>true</code></strong>.
    912. 

  912.         In the above example of configuration sequence, you'll need
    913. 

  913.         to add the following before performing <strong class="userinput"><code>commit</code></strong>:
    914. 

  914.       </p><pre class="screen">&gt; <strong class="userinput"><code>config set Xfrin/zones[0]/use_ixfr true</code></strong></pre><p>
    915. 

  915.       </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
    916. 

  916.       One reason why IXFR is disabled by default in the current
    917. 

  917.       release is because it does not support automatic fallback from IXFR to
    918. 

  918.       AXFR when it encounters a primary server that doesn't support
    919. 

  919.       outbound IXFR (and, not many existing implementations support
    920. 

  920.       it).  Another, related reason is that it does not use AXFR even
    921. 

  921.       if it has no knowledge about the zone (like at the very first
    922. 

  922.       time the secondary server is set up).  IXFR requires the
    923. 

  923.       "current version" of the zone, so obviously it doesn't work
    924. 

  924.       in this situation and AXFR is the only workable choice.
    925. 

  925.       The current release of <span class="command"><strong>b10-xfrin</strong></span> does not
    926. 

  926.       make this selection automatically.
    927. 

  927.       These features will be implemented in a near future
    928. 

  928.       version, at which point we will enable IXFR by default.
    929. 

  929.       </p></div></div><div class="section" title="9.3. Secondary Manager"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="zonemgr"></a>9.3. Secondary Manager</h2></div></div></div><p>
    930. 

  930.         The <span class="command"><strong>b10-zonemgr</strong></span> process is started by
    931. 

  931.         <span class="command"><strong>bind10</strong></span>.
    932. 

  932.         It keeps track of SOA refresh, retry, and expire timers
    933. 

  933.         and other details for BIND 10 to perform as a slave.
    934. 

  934.         When the <span class="command"><strong>b10-auth</strong></span> authoritative DNS server
    935. 

  935.         receives a NOTIFY message, <span class="command"><strong>b10-zonemgr</strong></span>
    936. 

  936.         may tell <span class="command"><strong>b10-xfrin</strong></span> to do a refresh
    937. 

  937.         to start an inbound zone transfer.
    938. 

  938.         The secondary manager resets its counters when a new zone is
    939. 

  939.         transferred in.
    940. 

  940.       </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
    941. 

  941.         Access control (such as allowing notifies) is not yet provided.
    942. 

  942.         The primary/secondary service is not yet complete.
    943. 

  943.       </p></div><p>
    944. 

  944.         The following example shows using <span class="command"><strong>bindctl</strong></span>
    945. 

  945.         to configure the server to be a secondary for the example zone:
    946. 

  946. 

  947.       </p><pre class="screen">&gt; <strong class="userinput"><code>config add Zonemgr/secondary_zones</code></strong>
    948. 

  948. &gt; <strong class="userinput"><code>config set Zonemgr/secondary_zones[0]/name "<code class="option">example.com</code>"</code></strong>
    949. 

  949. &gt; <strong class="userinput"><code>config commit</code></strong></pre><p>
    950. 

  950. 

  951.       </p><p>
    952. 

  952.         If the zone does not exist in the data source already
    953. 

  953.         (i.e. no SOA record for it), <span class="command"><strong>b10-zonemgr</strong></span>
    954. 

  954.         will automatically tell <span class="command"><strong>b10-xfrin</strong></span>
    955. 

  955.         to transfer the zone in.
    956. 

  956.       </p></div><div class="section" title="9.4. Trigger an Incoming Zone Transfer Manually"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id1168229439316"></a>9.4. Trigger an Incoming Zone Transfer Manually</h2></div></div></div><p>
    957. 

  957.         To manually trigger a zone transfer to retrieve a remote zone,
    958. 

  958.         you may use the <span class="command"><strong>bindctl</strong></span> utility.
    959. 

  959.         For example, at the <span class="command"><strong>bindctl</strong></span> prompt run:
    960. 

  960. 

  961.         </p><pre class="screen">&gt; <strong class="userinput"><code>Xfrin retransfer zone_name="<code class="option">foo.example.org</code>" master=<code class="option">192.0.2.99</code></code></strong></pre><p>
    962. 

  962.       </p></div><div class="section" title="9.5. Incoming Transfers with In-memory Datasource"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id1168229439342"></a>9.5. Incoming Transfers with In-memory Datasource</h2></div></div></div><p>
    963. 

  963.         In the case of an incoming zone transfer, the received zone is
    964. 

  964.         first stored in the corresponding BIND 10 datasource. In
    965. 

  965.         case the secondary zone is served by an in-memory datasource
    966. 

  966.         with an SQLite3 backend, <span class="command"><strong>b10-auth</strong></span> is
    967. 

  967.         automatically sent a <code class="varname">loadzone</code> command to
    968. 

  968.         reload the corresponding zone into memory from the backend.
    969. 

  969.       </p><p>
    970. 

  970. 	The administrator doesn't have to do anything for
    971. 

  971. 	<span class="command"><strong>b10-auth</strong></span> to serve the new version of the
    972. 

  972. 	zone, except for the configuration such as the one described in
    973. 

  973. 	<a class="xref" href="#in-memory-datasource-with-sqlite3-backend" title="8.2.2. In-memory Data Source with SQLite3 Backend">Section 8.2.2, &#8220;In-memory Data Source with SQLite3 Backend&#8221;</a>.
    974. 

  974.       </p></div></div><div class="chapter" title="Chapter 10. Outbound Zone Transfers"><div class="titlepage"><div><div><h2 class="title"><a name="xfrout"></a>Chapter 10. Outbound Zone Transfers</h2></div></div></div><p>
    975. 

  975.       The <span class="command"><strong>b10-xfrout</strong></span> process is started by
    976. 

  976.       <span class="command"><strong>bind10</strong></span>.
    977. 

  977.       When the <span class="command"><strong>b10-auth</strong></span> authoritative DNS server
    978. 

  978.       receives an AXFR or IXFR request, <span class="command"><strong>b10-auth</strong></span>
    979. 

  979.       internally forwards the request to <span class="command"><strong>b10-xfrout</strong></span>,
    980. 

  980.       which handles the rest of this request processing.
    981. 

  981.       This is used to provide primary DNS service to share zones
    982. 

  982.       to secondary name servers.
    983. 

  983.       The <span class="command"><strong>b10-xfrout</strong></span> is also used to send
    984. 

  984.       NOTIFY messages to secondary servers.
    985. 

  985.     </p><p>
    986. 

  986.       A global or per zone <code class="option">transfer_acl</code> configuration
    987. 

  987.       can be used to control accessibility of the outbound zone
    988. 

  988.       transfer service.
    989. 

  989.       By default, <span class="command"><strong>b10-xfrout</strong></span> allows any clients to
    990. 

  990.       perform zone transfers for any zones:
    991. 

  991.     </p><pre class="screen">&gt; <strong class="userinput"><code>config show Xfrout/transfer_acl</code></strong>
    992. 

  992. Xfrout/transfer_acl[0]	{"action": "ACCEPT"}	any	(default)</pre><p>
    993. 

  993.       You can change this to, for example, rejecting all transfer
    994. 

  994.       requests by default while allowing requests for the transfer
    995. 

  995.       of zone "example.com" from 192.0.2.1 and 2001:db8::1 as follows:
    996. 

  996.     </p><pre class="screen">&gt; <strong class="userinput"><code>config set Xfrout/transfer_acl[0] {"action": "REJECT"}</code></strong>
    997. 

  997. &gt; <strong class="userinput"><code>config add Xfrout/zone_config</code></strong>
    998. 

  998. &gt; <strong class="userinput"><code>config set Xfrout/zone_config[0]/origin "example.com"</code></strong>
    999. 

  999. &gt; <strong class="userinput"><code>config set Xfrout/zone_config[0]/transfer_acl [{"action": "ACCEPT", "from": "192.0.2.1"},</code></strong>
    1000. 

  1000. <strong class="userinput"><code>                                                 {"action": "ACCEPT", "from": "2001:db8::1"}]</code></strong>
    1001. 

  1001. &gt; <strong class="userinput"><code>config commit</code></strong></pre><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
    1002. 

  1002.         In the above example the lines
    1003. 

  1003.         for <code class="option">transfer_acl</code> were divided for
    1004. 

  1004.         readability.  In the actual input it must be in a single line.
    1005. 

  1005.     </p></div><p>
    1006. 

  1006.       If you want to require TSIG in access control, a system wide TSIG
    1007. 

  1007.       "key ring" must be configured.
    1008. 

  1008.       For example, to change the previous example to allowing requests
    1009. 

  1009.       from 192.0.2.1 signed by a TSIG with a key name of
    1010. 

  1010.       "key.example", you'll need to do this:
    1011. 

  1011.     </p><pre class="screen">&gt; <strong class="userinput"><code>config set tsig_keys/keys ["key.example:&lt;base64-key&gt;"]</code></strong>
    1012. 

  1012. &gt; <strong class="userinput"><code>config set Xfrout/zone_config[0]/transfer_acl [{"action": "ACCEPT", "from": "192.0.2.1", "key": "key.example"}]</code></strong>
    1013. 

  1013. &gt; <strong class="userinput"><code>config commit</code></strong></pre><p>Both <span class="command"><strong>b10-xfrout</strong></span> and <span class="command"><strong>b10-auth</strong></span>
    1014. 

  1014.       will use the system wide keyring to check
    1015. 

  1015.       TSIGs in the incoming messages and to sign responses.</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
    1016. 

  1016.         The way to specify zone specific configuration (ACLs, etc) is
    1017. 

  1017.         likely to be changed.
    1018. 

  1018.     </p></div></div><div class="chapter" title="Chapter 11. Dynamic DNS Update"><div class="titlepage"><div><div><h2 class="title"><a name="ddns"></a>Chapter 11. Dynamic DNS Update</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#id1168229439633">11.1. Enabling Dynamic Update</a></span></dt><dt><span class="section"><a href="#id1168229439733">11.2. Access Control</a></span></dt><dt><span class="section"><a href="#id1168229439954">11.3. Miscellaneous Operational Issues</a></span></dt></dl></div><p>
    1019. 

  1019.       BIND 10 supports the server side of the Dynamic DNS Update
    1020. 

  1020.       (DDNS) protocol as defined in RFC 2136.
    1021. 

  1021.       This service is provided by the <span class="command"><strong>b10-ddns</strong></span>
    1022. 

  1022.       component, which is started by the <span class="command"><strong>bind10</strong></span>
    1023. 

  1023.       process if configured so.
    1024. 

  1024.     </p><p>
    1025. 

  1025.       When the <span class="command"><strong>b10-auth</strong></span> authoritative DNS server
    1026. 

  1026.       receives an UPDATE request, it internally forwards the request
    1027. 

  1027.       to <span class="command"><strong>b10-ddns</strong></span>, which handles the rest of
    1028. 

  1028.       this request processing.
    1029. 

  1029.       When the processing is completed, <span class="command"><strong>b10-ddns</strong></span>
    1030. 

  1030.       will send a response to the client as specified in RFC 2136
    1031. 

  1031.       (NOERROR for successful update, REFUSED if rejected due to
    1032. 

  1032.       ACL check, etc).
    1033. 

  1033.       If the zone has been changed as a result, it will internally
    1034. 

  1034.       notify <span class="command"><strong>b10-xfrout</strong></span> so that other secondary
    1035. 

  1035.       servers will be notified via the DNS NOTIFY protocol.
    1036. 

  1036.       In addition, if <span class="command"><strong>b10-auth</strong></span> serves the updated
    1037. 

  1037.       zone from its in-memory cache (as described in
    1038. 

  1038.       <a class="xref" href="#in-memory-datasource-with-sqlite3-backend" title="8.2.2. In-memory Data Source with SQLite3 Backend">Section 8.2.2, &#8220;In-memory Data Source with SQLite3 Backend&#8221;</a>),
    1039. 

  1039.       <span class="command"><strong>b10-ddns</strong></span> will also
    1040. 

  1040.       notify <span class="command"><strong>b10-auth</strong></span> so that <span class="command"><strong>b10-auth</strong></span>
    1041. 

  1041.       will re-cache the updated zone content.
    1042. 

  1042.     </p><p>
    1043. 

  1043.       The <span class="command"><strong>b10-ddns</strong></span> component supports requests over
    1044. 

  1044.       both UDP and TCP, and both IPv6 and IPv4; for TCP requests,
    1045. 

  1045.       however, it terminates the TCP connection immediately after
    1046. 

  1046.       each single request has been processed.  Clients cannot reuse the
    1047. 

  1047.       same TCP connection for multiple requests. (This is a current
    1048. 

  1048.       implementation limitation of <span class="command"><strong>b10-ddns</strong></span>.
    1049. 

  1049.       While RFC 2136 doesn't specify anything about such reuse of TCP
    1050. 

  1050.       connection, there is no reason for disallowing it as RFC 1035
    1051. 

  1051.       generally allows multiple requests sent over a single TCP
    1052. 

  1052.       connection.  BIND 9 supports such reuse.)
    1053. 

  1053.     </p><p>
    1054. 

  1054.       As of this writing <span class="command"><strong>b10-ddns</strong></span> does not support
    1055. 

  1055.       update forwarding for secondary zones.
    1056. 

  1056.       If it receives an update request for a secondary zone, it will
    1057. 

  1057.       immediately return a <span class="quote">&#8220;<span class="quote">not implemented</span>&#8221;</span> response.
    1058. 

  1058.       </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
    1059. 

  1059. 	  For feature completeness, update forwarding should be
    1060. 

  1060. 	  eventually supported.  But currently it's considered a lower
    1061. 

  1061. 	  priority task and there is no specific plan of implementing
    1062. 

  1062. 	  this feature.
    1063. 

  1063. 

  1064.       </p></div><p>
    1065. 

  1065.     </p><div class="section" title="11.1. Enabling Dynamic Update"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id1168229439633"></a>11.1. Enabling Dynamic Update</h2></div></div></div><p>
    1066. 

  1066.         First off, it must be made sure that a few components on which
    1067. 

  1067.         <span class="command"><strong>b10-ddns</strong></span> depends are configured to run,
    1068. 

  1068.         which are <span class="command"><strong>b10-auth</strong></span>
    1069. 

  1069.         and <span class="command"><strong>b10-zonemgr</strong></span>.
    1070. 

  1070.         In addition, <span class="command"><strong>b10-xfrout</strong></span> should also be
    1071. 

  1071.         configured to run; otherwise the notification after an update
    1072. 

  1072.         (see above) will fail with a timeout, suspending the DDNS
    1073. 

  1073.         service while <span class="command"><strong>b10-ddns</strong></span> waits for the
    1074. 

  1074.         response (see the description of the <a class="ulink" href="bind10-messages.html#DDNS_UPDATE_NOTIFY_FAIL" target="_top">DDNS_UPDATE_NOTIFY_FAIL</a>
    1075. 

  1075.         log message for further details).
    1076. 

  1076.         If BIND 10 is already configured to provide authoritative DNS
    1077. 

  1077.         service they should normally be configured to run already.
    1078. 

  1078.       </p><p>
    1079. 

  1079.         Second, for the obvious reason dynamic update requires that the
    1080. 

  1080.         underlying data source storing the zone data be writable.
    1081. 

  1081.         In the current implementation this means the zone must be stored
    1082. 

  1082.         in an SQLite3-based data source.
    1083. 

  1083. 	Also, in this development version, the <span class="command"><strong>b10-ddns</strong></span>
    1084. 

  1084. 	component configures itself with the data source referring to the
    1085. 

  1085.         <code class="varname">database_file</code> configuration parameter of
    1086. 

  1086.         <span class="command"><strong>b10-auth</strong></span>.
    1087. 

  1087.         So this information must be configured correctly before starting
    1088. 

  1088.         <span class="command"><strong>b10-ddns</strong></span>.
    1089. 

  1089. 

  1090.         </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
    1091. 

  1091.             The way to configure data sources is now being revised.
    1092. 

  1092.             Configuration on the data source for DDNS will be very
    1093. 

  1093.             likely to be changed in a backward incompatible manner in
    1094. 

  1094.             a near future version.
    1095. 

  1095.         </p></div><p>
    1096. 

  1096.       </p><p>
    1097. 

  1097. 	In general, if something goes wrong regarding the dependency
    1098. 

  1098. 	described above, <span class="command"><strong>b10-ddns</strong></span> will log the
    1099. 

  1099. 	related event at the warning or error level.
    1100. 

  1100. 	It's advisable to check the log message when you first enable
    1101. 

  1101. 	DDNS or if it doesn't work as you expect to see if there's any
    1102. 

  1102. 	warning or error log message.
    1103. 

  1103.       </p><p>
    1104. 

  1104.         Next, to enable the DDNS service, <span class="command"><strong>b10-ddns</strong></span>
    1105. 

  1105.         needs to be explicitly configured to run.
    1106. 

  1106.         It can be done by using the <span class="command"><strong>bindctl</strong></span>
    1107. 

  1107.         utility.  For example:
    1108. 

  1108.       </p><pre class="screen">
    1109. 

  1109. &gt; <strong class="userinput"><code>config add Boss/components b10-ddns</code></strong>
    1110. 

  1110. &gt; <strong class="userinput"><code>config set Boss/components/b10-ddns/address DDNS</code></strong>
    1111. 

  1111. &gt; <strong class="userinput"><code>config set Boss/components/b10-ddns/kind dispensable</code></strong>
    1112. 

  1112. &gt; <strong class="userinput"><code>config commit</code></strong>
    1113. 

  1113. </pre><p>
    1114. 

  1114.       </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
    1115. 

  1115. 	  In theory <code class="varname">kind</code> could be omitted because
    1116. 

  1116. 	  "dispensable" is its default.
    1117. 

  1117. 	  But there's some peculiar behavior (which should be a
    1118. 

  1118. 	  bug and should be fixed eventually; see Trac ticket #2064)
    1119. 

  1119. 	  with <span class="command"><strong>bindctl</strong></span> and you'll still need to
    1120. 

  1120. 	  specify that explicitly.  Likewise, <code class="varname">address</code>
    1121. 

  1121. 	  may look unnecessary because <span class="command"><strong>b10-ddns</strong></span>
    1122. 

  1122. 	  would start and work without specifying it.  But for it
    1123. 

  1123. 	  to shutdown gracefully this parameter should also be
    1124. 

  1124. 	  specified.
    1125. 

  1125.       </p></div><p>
    1126. 

  1126.       </p></div><div class="section" title="11.2. Access Control"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id1168229439733"></a>11.2. Access Control</h2></div></div></div><p>
    1127. 

  1127.         By default, <span class="command"><strong>b10-ddns</strong></span> rejects any update
    1128. 

  1128.         requests from any clients by returning a REFUSED response.
    1129. 

  1129.         To allow updates to take effect, an access control rule
    1130. 

  1130.         (called update ACL) with a policy allowing updates must explicitly be
    1131. 

  1131.         configured.
    1132. 

  1132.         Update ACL must be configured per zone basis in the
    1133. 

  1133.         <code class="varname">zones</code> configuration parameter of
    1134. 

  1134.         <span class="command"><strong>b10-ddns</strong></span>.
    1135. 

  1135.         This is a list of per-zone configurations regarding DDNS.
    1136. 

  1136.         Each list element consists of the following parameters:
    1137. 

  1137.         </p><div class="variablelist"><dl><dt><span class="term">origin</span></dt><dd>The zone's origin name</dd><dt><span class="term">class</span></dt><dd>The RR class of the zone
    1138. 

  1138.                 (normally <span class="quote">&#8220;<span class="quote">IN</span>&#8221;</span>, and in that case
    1139. 

  1139. 		can be omitted in configuration)</dd><dt><span class="term">update_acl</span></dt><dd>List of access control rules (ACL) for the zone</dd></dl></div><p>
    1140. 

  1140.         The syntax of the ACL is the same as ACLs for other
    1141. 

  1141.         components.
    1142. 

  1142.         Specific examples are given below.
    1143. 

  1143.       </p><p>
    1144. 

  1144.         In general, an update ACL rule that allows an update request
    1145. 

  1145.         should be configured with a TSIG key.
    1146. 

  1146.         This is an example update ACL that allows updates to the zone
    1147. 

  1147.         named <span class="quote">&#8220;<span class="quote">example.org</span>&#8221;</span> (of default RR class <span class="quote">&#8220;<span class="quote">IN</span>&#8221;</span>)
    1148. 

  1148.         from clients that send requests signed with a TSIG whose
    1149. 

  1149.         key name is "key.example.org" (and refuses all others):
    1150. 

  1150.       </p><pre class="screen">
    1151. 

  1151. &gt; <strong class="userinput"><code>config add DDNS/zones</code></strong>
    1152. 

  1152. &gt; <strong class="userinput"><code>config set DDNS/zones[0]/origin example.org</code></strong>
    1153. 

  1153. &gt; <strong class="userinput"><code>config add DDNS/zones[0]/update_acl {"action": "ACCEPT", "key": "key.example.org"}</code></strong>
    1154. 

  1154. &gt; <strong class="userinput"><code>config commit</code></strong>
    1155. 

  1155. </pre><p>
    1156. 

  1156.       The TSIG key must be configured system wide
    1157. 

  1157.       (see <a class="xref" href="#xfrout" title="Chapter 10. Outbound Zone Transfers">Chapter 10, <i>Outbound Zone Transfers</i></a>.)
    1158. 

  1158.       </p><p>
    1159. 

  1159.         Multiple rules can be specified in the ACL, and an ACL rule
    1160. 

  1160.         can consist of multiple constraints, such as a combination of
    1161. 

  1161.         IP address and TSIG.
    1162. 

  1162.         The following configuration sequence will add a new rule to
    1163. 

  1163.         the ACL created in the above example.  This additional rule
    1164. 

  1164. 	allows update requests sent from a client
    1165. 

  1165.         using TSIG key name of "key.example" (different from the
    1166. 

  1166.         key used in the previous example) and has an IPv6 address of ::1.
    1167. 

  1167.       </p><pre class="screen">
    1168. 

  1168. &gt; <strong class="userinput"><code>config add DDNS/zones[0]/update_acl {"action": "ACCEPT", "from": "::1", "key": "key.example"}</code></strong>
    1169. 

  1169. &gt; <strong class="userinput"><code>config show DDNS/zones[0]/update_acl</code></strong>
    1170. 

  1170. DDNS/zones[0]/update_acl[0]     {"action": "ACCEPT", "key": "key.example.org"} any (modified)
    1171. 

  1171. DDNS/zones[0]/update_acl[1]     {"action": "ACCEPT", "from": "::1", "key": "key.example"} any (modified)
    1172. 

  1172. &gt; <strong class="userinput"><code>config commit</code></strong>
    1173. 

  1173. </pre><p>
    1174. 

  1174.       (Note the "add" in the first line.  Before this sequence, we
    1175. 

  1175.       have had only entry in <code class="varname">zones[0]/update_acl</code>.
    1176. 

  1176.       The <span class="command"><strong>add</strong></span> command with a value (rule) adds
    1177. 

  1177.       a new entry and sets it to the given rule.
    1178. 

  1178. 

  1179.       Due to a limitation of the current implementation, it doesn't
    1180. 

  1180.       work if you first try to just add a new entry and then set it to
    1181. 

  1181.       a given rule.)
    1182. 

  1182.       </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
    1183. 

  1183.           The <span class="command"><strong>b10-ddns</strong></span> component accepts an ACL
    1184. 

  1184.           rule that just allows updates from a specific IP address
    1185. 

  1185.           (i.e., without requiring TSIG), but this is highly
    1186. 

  1186.           discouraged (remember that requests can be made over UDP and
    1187. 

  1187.           spoofing the source address of a UDP packet is often pretty
    1188. 

  1188.           easy).
    1189. 

  1189.           Unless you know what you are doing and that you can accept
    1190. 

  1190.           its consequence, any update ACL rule that allows updates
    1191. 

  1191.           should have a TSIG key in its constraints.
    1192. 

  1192.       </p></div><p>
    1193. 

  1193. 	The ACL rules will be checked in the listed order, and the
    1194. 

  1194. 	first matching one will apply.
    1195. 

  1195. 	If none of the rules matches, the default rule will apply,
    1196. 

  1196. 	which is rejecting any requests in the case of
    1197. 

  1197. 	<span class="command"><strong>b10-ddns</strong></span>.
    1198. 

  1198.       </p><p>
    1199. 

  1199. 	Other actions than "ACCEPT", namely "REJECT" and "DROP", can be
    1200. 

  1200. 	used, too.
    1201. 

  1201. 	See <a class="xref" href="#resolverserver" title="Chapter 12. Recursive Name Server">Chapter 12, <i>Recursive Name Server</i></a> about their effects.
    1202. 

  1202.       </p><p>
    1203. 

  1203.         Currently update ACL can only control updates per zone basis;
    1204. 

  1204.         it's not possible to specify access control with higher
    1205. 

  1205.         granularity such as for particular domain names or specific
    1206. 

  1206.         types of RRs.
    1207. 

  1207. 

  1208.       </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
    1209. 

  1209.         Contrary to what RFC 2136 (literally) specifies,
    1210. 

  1210.         <span class="command"><strong>b10-ddns</strong></span> checks the update ACL before
    1211. 

  1211.         checking the prerequisites of the update request.
    1212. 

  1212.         This is a deliberate implementation decision.
    1213. 

  1213.         This counter intuitive specification has been repeatedly
    1214. 

  1214.         discussed among implementers and in the IETF, and it is now
    1215. 

  1215.         widely agreed that it does not make sense to strictly follow
    1216. 

  1216.         that part of RFC.
    1217. 

  1217.         One known specific bad result of following the RFC is that it
    1218. 

  1218.         could leak information about which name or record exists or does not
    1219. 

  1219.         exist in the zone as a result of prerequisite checks even if a
    1220. 

  1220.         zone is somehow configured to reject normal queries from
    1221. 

  1221.         arbitrary clients.
    1222. 

  1222.         There have been other troubles that could have been avoided if
    1223. 

  1223.         the ACL could be checked before the prerequisite check.
    1224. 

  1224.       </p></div></div><div class="section" title="11.3. Miscellaneous Operational Issues"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id1168229439954"></a>11.3. Miscellaneous Operational Issues</h2></div></div></div><p>
    1225. 

  1225.         Unlike BIND 9, BIND 10 currently does not support automatic
    1226. 

  1226.         re-signing of DNSSEC-signed zone when it's updated via DDNS.
    1227. 

  1227.         It could be possible to re-sign the updated zone afterwards
    1228. 

  1228.         or make sure the update request also updates related DNSSEC
    1229. 

  1229.         records, but that will be pretty error-prone operation.
    1230. 

  1230.         In general, it's not advisable to allow DDNS for a signed zone
    1231. 

  1231.         at this moment.
    1232. 

  1232.       </p><p>
    1233. 

  1233.         Also unlike BIND 9, it's currently not possible
    1234. 

  1234.         to <span class="quote">&#8220;<span class="quote">freeze</span>&#8221;</span> a zone temporarily in order to
    1235. 

  1235.         suspend DDNS while you manually update the zone.
    1236. 

  1236.         If you need to make manual updates to a dynamic zone,
    1237. 

  1237.         you'll need to temporarily reject any updates to the zone via
    1238. 

  1238.         the update ACLs.
    1239. 

  1239.       </p><p>
    1240. 

  1240.         Dynamic updates are only applicable to primary zones.
    1241. 

  1241.         In order to avoid updating secondary zones via DDNS requests,
    1242. 

  1242.         <span class="command"><strong>b10-ddns</strong></span> refers to the
    1243. 

  1243.         <span class="quote">&#8220;<span class="quote">secondary_zones</span>&#8221;</span> configuration of
    1244. 

  1244.         <span class="command"><strong>b10-zonemgr</strong></span>.  Zones listed in
    1245. 

  1245.         <span class="quote">&#8220;<span class="quote">secondary_zones</span>&#8221;</span> will never be updated via DDNS
    1246. 

  1246.         regardless of the update ACL configuration;
    1247. 

  1247. 	<span class="command"><strong>b10-ddns</strong></span> will return a NOTAUTH (server
    1248. 

  1248.         not authoritative for the zone) response.
    1249. 

  1249.         If you have a "conceptual" secondary zone whose content is a
    1250. 

  1250.         copy of some external source but is not updated via the
    1251. 

  1251.         standard zone transfers and therefore not listed in
    1252. 

  1252.         <span class="quote">&#8220;<span class="quote">secondary_zones</span>&#8221;</span>, be careful not to allow DDNS
    1253. 

  1253.         for the zone; it would be quite likely to lead to inconsistent
    1254. 

  1254.         state between different servers.
    1255. 

  1255.         Normally this should not be a problem because the default
    1256. 

  1256.         update ACL rejects any update requests, but you may want to
    1257. 

  1257.         take an extra care about the configuration if you have such
    1258. 

  1258.         type of secondary zones.
    1259. 

  1259.       </p><p>
    1260. 

  1260.         The difference of two versions of a zone, before and after a
    1261. 

  1261.         DDNS transaction, is automatically recorded in the underlying
    1262. 

  1262.         data source, and can be retrieved in the form of outbound
    1263. 

  1263.         IXFR.
    1264. 

  1264.         This is done automatically; it does not require specific
    1265. 

  1265.         configuration to make this possible.
    1266. 

  1266.       </p></div></div><div class="chapter" title="Chapter 12. Recursive Name Server"><div class="titlepage"><div><div><h2 class="title"><a name="resolverserver"></a>Chapter 12. Recursive Name Server</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#id1168229440091">12.1. Access Control</a></span></dt><dt><span class="section"><a href="#id1168229440276">12.2. Forwarding</a></span></dt></dl></div><p>
    1267. 

  1267.       The <span class="command"><strong>b10-resolver</strong></span> process is started by
    1268. 

  1268.       <span class="command"><strong>bind10</strong></span>.
    1269. 

  1269. 

  1270.     </p><p>
    1271. 

  1271.       The main <span class="command"><strong>bind10</strong></span> process can be configured
    1272. 

  1272.       to select to run either the authoritative or resolver or both.
    1273. 

  1273.       By default, it doesn't start either one. You may change this using
    1274. 

  1274.       <span class="command"><strong>bindctl</strong></span>, for example:
    1275. 

  1275. 

  1276.       </p><pre class="screen">
    1277. 

  1277. &gt; <strong class="userinput"><code>config add Boss/components b10-resolver</code></strong>
    1278. 

  1278. &gt; <strong class="userinput"><code>config set Boss/components/b10-resolver/special resolver</code></strong>
    1279. 

  1279. &gt; <strong class="userinput"><code>config set Boss/components/b10-resolver/kind needed</code></strong>
    1280. 

  1280. &gt; <strong class="userinput"><code>config set Boss/components/b10-resolver/priority 10</code></strong>
    1281. 

  1281. &gt; <strong class="userinput"><code>config commit</code></strong>
    1282. 

  1282. </pre><p>
    1283. 

  1283. 

  1284.     </p><p>
    1285. 

  1285.        The master <span class="command"><strong>bind10</strong></span> will stop and start
    1286. 

  1286.        the desired services.
    1287. 

  1287.     </p><p>
    1288. 

  1288.       By default, the resolver listens on port 53 for 127.0.0.1 and ::1.
    1289. 

  1289.       The following example shows how it can be configured to
    1290. 

  1290.       listen on an additional address (and port):
    1291. 

  1291. 

  1292.       </p><pre class="screen">
    1293. 

  1293. &gt; <strong class="userinput"><code>config add Resolver/listen_on</code></strong>
    1294. 

  1294. &gt; <strong class="userinput"><code>config set Resolver/listen_on[<em class="replaceable"><code>2</code></em>]/address "192.168.1.1"</code></strong>
    1295. 

  1295. &gt; <strong class="userinput"><code>config set Resolver/listen_on[<em class="replaceable"><code>2</code></em>]/port 53</code></strong>
    1296. 

  1296. &gt; <strong class="userinput"><code>config commit</code></strong>
    1297. 

  1297. </pre><p>
    1298. 

  1298.     </p><p>(Replace the <span class="quote">&#8220;<span class="quote"><em class="replaceable"><code>2</code></em></span>&#8221;</span>
    1299. 

  1299.        as needed; run <span class="quote">&#8220;<span class="quote"><strong class="userinput"><code>config show
    1300. 

  1300.        Resolver/listen_on</code></strong></span>&#8221;</span> if needed.)</p><div class="section" title="12.1. Access Control"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id1168229440091"></a>12.1. Access Control</h2></div></div></div><p>
    1301. 

  1301.         By default, the <span class="command"><strong>b10-resolver</strong></span> daemon only accepts
    1302. 

  1302.         DNS queries from the localhost (127.0.0.1 and ::1).
    1303. 

  1303.         The <code class="option">Resolver/query_acl</code> configuration may
    1304. 

  1304.         be used to reject, drop, or allow specific IPs or networks.
    1305. 

  1305.         This configuration list is first match.
    1306. 

  1306.       </p><p>
    1307. 

  1307.         The configuration's <code class="option">action</code> item may be
    1308. 

  1308.         set to <span class="quote">&#8220;<span class="quote">ACCEPT</span>&#8221;</span> to allow the incoming query,
    1309. 

  1309.         <span class="quote">&#8220;<span class="quote">REJECT</span>&#8221;</span> to respond with a DNS REFUSED return
    1310. 

  1310.         code, or <span class="quote">&#8220;<span class="quote">DROP</span>&#8221;</span> to ignore the query without
    1311. 

  1311.         any response (such as a blackhole).  For more information,
    1312. 

  1312.         see the respective debugging messages:  <a class="ulink" href="bind10-messages.html#RESOLVER_QUERY_ACCEPTED" target="_top">RESOLVER_QUERY_ACCEPTED</a>,
    1313. 

  1313.         <a class="ulink" href="bind10-messages.html#RESOLVER_QUERY_REJECTED" target="_top">RESOLVER_QUERY_REJECTED</a>,
    1314. 

  1314.         and <a class="ulink" href="bind10-messages.html#RESOLVER_QUERY_DROPPED" target="_top">RESOLVER_QUERY_DROPPED</a>.
    1315. 

  1315.       </p><p>
    1316. 

  1316.         The required configuration's <code class="option">from</code> item is set
    1317. 

  1317.         to an IPv4 or IPv6 address, addresses with an network mask, or to
    1318. 

  1318.         the special lowercase keywords <span class="quote">&#8220;<span class="quote">any6</span>&#8221;</span> (for
    1319. 

  1319.         any IPv6 address) or <span class="quote">&#8220;<span class="quote">any4</span>&#8221;</span> (for any IPv4
    1320. 

  1320.         address).
    1321. 

  1321.       </p><p>
    1322. 

  1322.         For example to allow the <em class="replaceable"><code>192.168.1.0/24</code></em>
    1323. 

  1323.         network to use your recursive name server, at the
    1324. 

  1324.         <span class="command"><strong>bindctl</strong></span> prompt run:
    1325. 

  1325.       </p><pre class="screen">
    1326. 

  1326. &gt; <strong class="userinput"><code>config add Resolver/query_acl</code></strong>
    1327. 

  1327. &gt; <strong class="userinput"><code>config set Resolver/query_acl[<em class="replaceable"><code>2</code></em>]/action "ACCEPT"</code></strong>
    1328. 

  1328. &gt; <strong class="userinput"><code>config set Resolver/query_acl[<em class="replaceable"><code>2</code></em>]/from "<em class="replaceable"><code>192.168.1.0/24</code></em>"</code></strong>
    1329. 

  1329. &gt; <strong class="userinput"><code>config commit</code></strong>
    1330. 

  1330. </pre><p>(Replace the <span class="quote">&#8220;<span class="quote"><em class="replaceable"><code>2</code></em></span>&#8221;</span>
    1331. 

  1331.        as needed; run <span class="quote">&#8220;<span class="quote"><strong class="userinput"><code>config show
    1332. 

  1332.        Resolver/query_acl</code></strong></span>&#8221;</span> if needed.)</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>This prototype access control configuration
    1333. 

  1333.       syntax may be changed.</p></div></div><div class="section" title="12.2. Forwarding"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id1168229440276"></a>12.2. Forwarding</h2></div></div></div><p>
    1334. 

  1334. 

  1335.         To enable forwarding, the upstream address and port must be
    1336. 

  1336.         configured to forward queries to, such as:
    1337. 

  1337. 

  1338.         </p><pre class="screen">
    1339. 

  1339. &gt; <strong class="userinput"><code>config set Resolver/forward_addresses [{ "address": "<em class="replaceable"><code>192.168.1.1</code></em>", "port": 53 }]</code></strong>
    1340. 

  1340. &gt; <strong class="userinput"><code>config commit</code></strong>
    1341. 

  1341. </pre><p>
    1342. 

  1342. 

  1343.         (Replace <em class="replaceable"><code>192.168.1.1</code></em> to point to your
    1344. 

  1344.         full resolver.)
    1345. 

  1345.       </p><p>
    1346. 

  1346.         Normal iterative name service can be re-enabled by clearing the
    1347. 

  1347.         forwarding address(es); for example:
    1348. 

  1348. 

  1349.         </p><pre class="screen">
    1350. 

  1350. &gt; <strong class="userinput"><code>config set Resolver/forward_addresses []</code></strong>
    1351. 

  1351. &gt; <strong class="userinput"><code>config commit</code></strong>
    1352. 

  1352. </pre><p>
    1353. 

  1353.       </p></div></div><div class="chapter" title="Chapter 13. DHCPv4 Server"><div class="titlepage"><div><div><h2 class="title"><a name="dhcp4"></a>Chapter 13. DHCPv4 Server</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#dhcp4-usage">13.1. DHCPv4 Server Usage</a></span></dt><dt><span class="section"><a href="#dhcp4-config">13.2. DHCPv4 Server Configuration</a></span></dt><dt><span class="section"><a href="#dhcp4-std">13.3. Supported standards</a></span></dt><dt><span class="section"><a href="#dhcp4-limit">13.4. DHCPv4 Server Limitations</a></span></dt></dl></div><p>Dynamic Host Configuration Protocol for IPv4 (DHCP or
    1354. 

  1354.     DHCPv4) and Dynamic Host Configuration Protocol for IPv6 (DHCPv6)
    1355. 

  1355.     are protocols that allow one node (server) to provision
    1356. 

  1356.     configuration parameters to many hosts and devices (clients). To
    1357. 

  1357.     ease deployment in larger networks, additional nodes (relays) may
    1358. 

  1358.     be deployed that facilitate communication between servers and
    1359. 

  1359.     clients. Even though principles of both DHCPv4 and DHCPv6 are
    1360. 

  1360.     somewhat similar, these are two radically different
    1361. 

  1361.     protocols. BIND10 offers server implementations for both DHCPv4
    1362. 

  1362.     and DHCPv6. This chapter is about DHCP for IPv4. For a description
    1363. 

  1363.     of the DHCPv6 server, see <a class="xref" href="#dhcp6" title="Chapter 14. DHCPv6 Server">Chapter 14, <i>DHCPv6 Server</i></a>.</p><p>The DHCPv4 server component is currently under intense
    1364. 

  1364.     development. You may want to check out <a class="ulink" href="http://bind10.isc.org/wiki/Kea" target="_top">BIND10 DHCP (Kea) wiki</a>
    1365. 

  1365.     and recent posts on <a class="ulink" href="https://lists.isc.org/mailman/listinfo/bind10-dev" target="_top">BIND10
    1366. 

  1366.     developers mailing list</a>.</p><p>The DHCPv4 and DHCPv6 components in BIND10 architecture are
    1367. 

  1367.     internally code named <span class="quote">&#8220;<span class="quote">Kea</span>&#8221;</span>.</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
    1368. 

  1368.         As of December 2011, both DHCPv4 and DHCPv6 components are
    1369. 

  1369.         skeleton servers. That means that while they are capable of
    1370. 

  1370.         performing DHCP configuration, they are not fully functional
    1371. 

  1371.         yet. In particular, neither has functional lease
    1372. 

  1372.         databases. This means that they will assign the same, fixed,
    1373. 

  1373.         hardcoded addresses to any client that will ask. See <a class="xref" href="#dhcp4-limit" title="13.4. DHCPv4 Server Limitations">Section 13.4, &#8220;DHCPv4 Server Limitations&#8221;</a> and <a class="xref" href="#dhcp6-limit" title="14.4. DHCPv6 Server Limitations">Section 14.4, &#8220;DHCPv6 Server Limitations&#8221;</a> for
    1374. 

  1374.         detailed description.
    1375. 

  1375.       </p></div><div class="section" title="13.1. DHCPv4 Server Usage"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="dhcp4-usage"></a>13.1. DHCPv4 Server Usage</h2></div></div></div><p>BIND10 provides the DHCPv4 server component since December
    1376. 

  1376.       2011. It is a skeleton server and can be described as an early
    1377. 

  1377.       prototype that is not fully functional yet. It is mature enough
    1378. 

  1378.       to conduct first tests in lab environment, but it has
    1379. 

  1379.       significant limitations. See <a class="xref" href="#dhcp4-limit" title="13.4. DHCPv4 Server Limitations">Section 13.4, &#8220;DHCPv4 Server Limitations&#8221;</a> for
    1380. 

  1380.       details.
    1381. 

  1381.       </p><p>
    1382. 

  1382.         <span class="command"><strong>b10-dhcp4</strong></span> is a BIND10 component and is being
    1383. 

  1383.         run under BIND10 framework. To add a DHCPv4 process to the set of running
    1384. 

  1384.         BIND10 services, you can use following commands in <span class="command"><strong>bindctl</strong></span>:
    1385. 

  1385.         </p><pre class="screen">&gt; <strong class="userinput"><code>config add Boss/components b10-dhcp4</code></strong>
    1386. 

  1386. &gt; <strong class="userinput"><code>config set Boss/components/b10-dhcp4/kind dispensable</code></strong>
    1387. 

  1387. &gt; <strong class="userinput"><code>config commit</code></strong></pre><p>
    1388. 

  1388.          To shutdown running <span class="command"><strong>b10-dhcp4</strong></span>, please use the
    1389. 

  1389.          following command:
    1390. 

  1390.          </p><pre class="screen">&gt; <strong class="userinput"><code>Dhcp4 shutdown</code></strong></pre><p>
    1391. 

  1391.          or
    1392. 

  1392.          </p><pre class="screen">&gt; <strong class="userinput"><code>config remove Boss/components b10-dhcp4</code></strong>
    1393. 

  1393. &gt; <strong class="userinput"><code>config commit</code></strong></pre><p>
    1394. 

  1394.         At start, the server will detect available network interfaces
    1395. 

  1395.         and will attempt to open UDP sockets on all interfaces that
    1396. 

  1396.         are up, running, are not loopback, and have IPv4 address
    1397. 

  1397.         assigned.
    1398. 

  1398. 

  1399.         The server will then listen to incoming traffic. Currently
    1400. 

  1400.         supported client messages are DISCOVER and REQUEST. The server
    1401. 

  1401.         will respond to them with OFFER and ACK, respectively.
    1402. 

  1402. 

  1403.         Since the DHCPv4 server opens privileged ports, it requires root
    1404. 

  1404.         access. Make sure you run this daemon as root.</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
    1405. 

  1405.             Integration with <span class="command"><strong>bind10</strong></span> is
    1406. 

  1406.             planned. Ultimately, <span class="command"><strong>b10-dhcp4</strong></span> will not
    1407. 

  1407.             be started directly, but rather via
    1408. 

  1408.             <span class="command"><strong>bind10</strong></span>. Please be aware of this planned
    1409. 

  1409.             change.
    1410. 

  1410.           </p></div></div><div class="section" title="13.2. DHCPv4 Server Configuration"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="dhcp4-config"></a>13.2. DHCPv4 Server Configuration</h2></div></div></div><p>
    1411. 

  1411.         The DHCPv4 server does not have a lease database implemented yet
    1412. 

  1412.         nor any support for configuration, so every time the same set
    1413. 

  1413.         of configuration options (including the same fixed address)
    1414. 

  1414.         will be assigned every time.
    1415. 

  1415.       </p><p>
    1416. 

  1416.         At this stage of development, the only way to alter the server
    1417. 

  1417.         configuration is to tweak its source code. To do so, please
    1418. 

  1418.         edit src/bin/dhcp4/dhcp4_srv.cc file and modify following
    1419. 

  1419.         parameters and recompile:
    1420. 

  1420.         </p><pre class="screen">
    1421. 

  1421. const std::string HARDCODED_LEASE = "192.0.2.222"; // assigned lease
    1422. 

  1422. const std::string HARDCODED_NETMASK = "255.255.255.0";
    1423. 

  1423. const uint32_t    HARDCODED_LEASE_TIME = 60; // in seconds
    1424. 

  1424. const std::string HARDCODED_GATEWAY = "192.0.2.1";
    1425. 

  1425. const std::string HARDCODED_DNS_SERVER = "192.0.2.2";
    1426. 

  1426. const std::string HARDCODED_DOMAIN_NAME = "isc.example.com";
    1427. 

  1427. const std::string HARDCODED_SERVER_ID = "192.0.2.1";</pre><p>
    1428. 

  1428. 

  1429.         Lease database and configuration support is planned for 2012.
    1430. 

  1430.       </p></div><div class="section" title="13.3. Supported standards"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="dhcp4-std"></a>13.3. Supported standards</h2></div></div></div><p>The following standards and draft standards are currently
    1431. 

  1431.       supported:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">RFC2131: Supported messages are DISCOVER, OFFER,
    1432. 

  1432.             REQUEST, and ACK.</li><li class="listitem">RFC2132: Supported options are: PAD (0),
    1433. 

  1433.             END(255), Message Type(53), DHCP Server Identifier (54),
    1434. 

  1434.             Domain Name (15), DNS Servers (6), IP Address Lease Time
    1435. 

  1435.             (51), Subnet mask (1), and Routers (3).</li></ul></div></div><div class="section" title="13.4. DHCPv4 Server Limitations"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="dhcp4-limit"></a>13.4. DHCPv4 Server Limitations</h2></div></div></div><p>These are the current limitations of the DHCPv4 server
    1436. 

  1436.       software. Most of them are reflections of the early stage of
    1437. 

  1437.       development and should be treated as <span class="quote">&#8220;<span class="quote">not implemented
    1438. 

  1438.       yet</span>&#8221;</span>, rather than actual limitations.</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">During initial IPv4 node configuration, the
    1439. 

  1439.             server is expected to send packets to a node that does not
    1440. 

  1440.             have IPv4 address assigned yet. The server requires
    1441. 

  1441.             certain tricks (or hacks) to transmit such packets. This
    1442. 

  1442.             is not implemented yet, therefore DHCPv4 server supports
    1443. 

  1443.             relayed traffic only (that is, normal point to point
    1444. 

  1444.             communication).</li><li class="listitem"><span class="command"><strong>b10-dhcp4</strong></span> provides a single,
    1445. 

  1445.             fixed, hardcoded lease to any client that asks.  There is
    1446. 

  1446.             no lease manager implemented. If two clients request
    1447. 

  1447.             addresses, they will both get the same fixed
    1448. 

  1448.             address.</li><li class="listitem"><span class="command"><strong>b10-dhcp4</strong></span> does not support any
    1449. 

  1449.             configuration mechanisms yet. The whole configuration is
    1450. 

  1450.             currently hardcoded. The only way to tweak configuration
    1451. 

  1451.             is to directly modify source code. See see <a class="xref" href="#dhcp4-config" title="13.2. DHCPv4 Server Configuration">Section 13.2, &#8220;DHCPv4 Server Configuration&#8221;</a> for details.</li><li class="listitem">Upon start, the server will open sockets on all
    1452. 

  1452.             interfaces that are not loopback, are up and running and
    1453. 

  1453.             have IPv4 address.</li><li class="listitem">PRL (Parameter Request List, a list of options
    1454. 

  1454.             requested by a client) is currently ignored and server
    1455. 

  1455.             assigns DNS SERVER and DOMAIN NAME options.</li><li class="listitem"><span class="command"><strong>b10-dhcp4</strong></span> does not support
    1456. 

  1456.             BOOTP. That is a design choice. This limitation is
    1457. 

  1457.             permanent. If you have legacy nodes that can't use DHCP and
    1458. 

  1458.             require BOOTP support, please use latest version of ISC DHCP
    1459. 

  1459.             <a class="ulink" href="http://www.isc.org/software/dhcp" target="_top">http://www.isc.org/software/dhcp</a>.</li><li class="listitem">Interface detection is currently working on Linux
    1460. 

  1460.             only. See <a class="xref" href="#iface-detect" title="15.1. Interface detection">Section 15.1, &#8220;Interface detection&#8221;</a> for details.</li><li class="listitem"><span class="command"><strong>b10-dhcp4</strong></span> does not verify that
    1461. 

  1461.             assigned address is unused. According to RFC2131, the
    1462. 

  1462.             allocating server should verify that address is no used by
    1463. 

  1463.             sending ICMP echo request.</li><li class="listitem">Address renewal (RENEW), rebinding (REBIND),
    1464. 

  1464.             confirmation (CONFIRM), duplication report (DECLINE) and
    1465. 

  1465.             release (RELEASE) are not supported yet.</li><li class="listitem">DNS Update is not supported yet.</li><li class="listitem">-v (verbose) command line option is currently
    1466. 

  1466.             the default, and cannot be disabled.</li></ul></div></div></div><div class="chapter" title="Chapter 14. DHCPv6 Server"><div class="titlepage"><div><div><h2 class="title"><a name="dhcp6"></a>Chapter 14. DHCPv6 Server</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#dhcp6-usage">14.1. DHCPv6 Server Usage</a></span></dt><dt><span class="section"><a href="#dhcp6-config">14.2. DHCPv6 Server Configuration</a></span></dt><dt><span class="section"><a href="#dhcp6-std">14.3. Supported DHCPv6 Standards</a></span></dt><dt><span class="section"><a href="#dhcp6-limit">14.4. DHCPv6 Server Limitations</a></span></dt></dl></div><p>Dynamic Host Configuration Protocol for IPv6 (DHCPv6) is
    1467. 

  1467.     specified in RFC3315. BIND10 provides DHCPv6 server implementation
    1468. 

  1468.     that is described in this chapter. For a description of the DHCPv4
    1469. 

  1469.     server implementation, see <a class="xref" href="#dhcp4" title="Chapter 13. DHCPv4 Server">Chapter 13, <i>DHCPv4 Server</i></a>.
    1470. 

  1470.     </p><p>The DHCPv6 server component is currently under intense
    1471. 

  1471.     development. You may want to check out <a class="ulink" href="http://bind10.isc.org/wiki/Kea" target="_top">BIND10 DHCP (Kea) wiki</a>
    1472. 

  1472.     and recent posts on <a class="ulink" href="https://lists.isc.org/mailman/listinfo/bind10-dev" target="_top">BIND10
    1473. 

  1473.     developers mailing list</a>.</p><p>The DHCPv4 and DHCPv6 components in BIND10 architecture are
    1474. 

  1474.     internally code named <span class="quote">&#8220;<span class="quote">Kea</span>&#8221;</span>.</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
    1475. 

  1475.         As of December 2011, both DHCPv4 and DHCPv6 components are
    1476. 

  1476.         skeleton servers. That means that while they are capable of
    1477. 

  1477.         performing DHCP configuration, they are not fully functional
    1478. 

  1478.         yet. In particular, neither has functional lease
    1479. 

  1479.         databases. This means that they will assign the same, fixed,
    1480. 

  1480.         hardcoded addresses to any client that will ask. See <a class="xref" href="#dhcp4-limit" title="13.4. DHCPv4 Server Limitations">Section 13.4, &#8220;DHCPv4 Server Limitations&#8221;</a> and <a class="xref" href="#dhcp6-limit" title="14.4. DHCPv6 Server Limitations">Section 14.4, &#8220;DHCPv6 Server Limitations&#8221;</a> for
    1481. 

  1481.         detailed description.
    1482. 

  1482.       </p></div><div class="section" title="14.1. DHCPv6 Server Usage"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="dhcp6-usage"></a>14.1. DHCPv6 Server Usage</h2></div></div></div><p>
    1483. 

  1483.         BIND10 provides the DHCPv6 server component since September
    1484. 

  1484.         2011. It is a skeleton server and can be described as an early
    1485. 

  1485.         prototype that is not fully functional yet. It is mature
    1486. 

  1486.         enough to conduct first tests in lab environment, but it has
    1487. 

  1487.         significant limitations. See <a class="xref" href="#dhcp6-limit" title="14.4. DHCPv6 Server Limitations">Section 14.4, &#8220;DHCPv6 Server Limitations&#8221;</a> for
    1488. 

  1488.         details.
    1489. 

  1489.       </p><p>
    1490. 

  1490.         The DHCPv6 server is implemented as <span class="command"><strong>b10-dhcp6</strong></span>
    1491. 

  1491.         daemon. As it is not configurable yet, it is fully autonomous,
    1492. 

  1492.         that is it does not interact with <span class="command"><strong>b10-cfgmgr</strong></span>.
    1493. 

  1493.         To start DHCPv6 server, simply input:
    1494. 

  1494. 

  1495.         </p><pre class="screen">
    1496. 

  1496. #<strong class="userinput"><code>cd src/bin/dhcp6</code></strong>
    1497. 

  1497. #<strong class="userinput"><code>./b10-dhcp6</code></strong>
    1498. 

  1498. </pre><p>
    1499. 

  1499. 

  1500.         Depending on your installation, <span class="command"><strong>b10-dhcp6</strong></span>
    1501. 

  1501.         binary may reside in src/bin/dhcp6 in your source code
    1502. 

  1502.         directory, in /usr/local/bin/b10-dhcp6 or other directory
    1503. 

  1503.         you specified during compilation.
    1504. 

  1504. 

  1505.         At start, server will detect available network interfaces
    1506. 

  1506.         and will attempt to open UDP sockets on all interfaces that
    1507. 

  1507.         are up, running, are not loopback, are multicast-capable, and
    1508. 

  1508.         have IPv6 address assigned.
    1509. 

  1509. 

  1510.         The server will then listen to incoming traffic. Currently
    1511. 

  1511.         supported client messages are SOLICIT and REQUEST. The server
    1512. 

  1512.         will respond to them with ADVERTISE and REPLY, respectively.
    1513. 

  1513. 

  1514.         Since the DHCPv6 server opens privileged ports, it requires root
    1515. 

  1515.         access. Make sure you run this daemon as root.
    1516. 

  1516.       </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
    1517. 

  1517.             Integration with <span class="command"><strong>bind10</strong></span> is
    1518. 

  1518.             planned. Ultimately, <span class="command"><strong>b10-dhcp6</strong></span> will not
    1519. 

  1519.             be started directly, but rather via
    1520. 

  1520.             <span class="command"><strong>bind10</strong></span>. Please be aware of this planned
    1521. 

  1521.             change.
    1522. 

  1522.           </p></div></div><div class="section" title="14.2. DHCPv6 Server Configuration"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="dhcp6-config"></a>14.2. DHCPv6 Server Configuration</h2></div></div></div><p>
    1523. 

  1523.         The DHCPv6 server does not have lease database implemented yet
    1524. 

  1524.         or any support for configuration, so every time the same set
    1525. 

  1525.         of configuration options (including the same fixed address)
    1526. 

  1526.         will be assigned every time.
    1527. 

  1527.       </p><p>
    1528. 

  1528.         At this stage of development, the only way to alter server
    1529. 

  1529.         configuration is to tweak its source code. To do so, please
    1530. 

  1530.         edit src/bin/dhcp6/dhcp6_srv.cc file and modify following
    1531. 

  1531.         parameters and recompile:
    1532. 

  1532.         </p><pre class="screen">
    1533. 

  1533. const std::string HARDCODED_LEASE = "2001:db8:1::1234:abcd";
    1534. 

  1534. const uint32_t HARDCODED_T1 = 1500; // in seconds
    1535. 

  1535. const uint32_t HARDCODED_T2 = 2600; // in seconds
    1536. 

  1536. const uint32_t HARDCODED_PREFERRED_LIFETIME = 3600; // in seconds
    1537. 

  1537. const uint32_t HARDCODED_VALID_LIFETIME = 7200; // in seconds
    1538. 

  1538. const std::string HARDCODED_DNS_SERVER = "2001:db8:1::1";</pre><p>
    1539. 

  1539. 

  1540.         Lease database and configuration support is planned for 2012.
    1541. 

  1541.       </p></div><div class="section" title="14.3. Supported DHCPv6 Standards"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="dhcp6-std"></a>14.3. Supported DHCPv6 Standards</h2></div></div></div><p>The following standards and draft standards are currently
    1542. 

  1542.       supported:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">RFC3315: Supported messages are SOLICIT,
    1543. 

  1543.             ADVERTISE, REQUEST, and REPLY. Supported options are
    1544. 

  1544.             SERVER_ID, CLIENT_ID, IA_NA, and IAADDRESS.</li><li class="listitem">RFC3646: Supported option is DNS_SERVERS.</li></ul></div></div><div class="section" title="14.4. DHCPv6 Server Limitations"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="dhcp6-limit"></a>14.4. DHCPv6 Server Limitations</h2></div></div></div><p> These are the current limitations of the DHCPv6 server
    1545. 

  1545.       software. Most of them are reflections of the early stage of
    1546. 

  1546.       development and should be treated as <span class="quote">&#8220;<span class="quote">not implemented
    1547. 

  1547.       yet</span>&#8221;</span>, rather than actual limitations.</p><p>
    1548. 

  1548.       </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">Relayed traffic is not supported.</li><li class="listitem"><span class="command"><strong>b10-dhcp6</strong></span> provides a single,
    1549. 

  1549.           fixed, hardcoded lease to any client that asks. There is no
    1550. 

  1550.           lease manager implemented. If two clients request addresses,
    1551. 

  1551.           they will both get the same fixed address.</li><li class="listitem"><span class="command"><strong>b10-dhcp6</strong></span> does not support any
    1552. 

  1552.             configuration mechanisms yet. The whole configuration is
    1553. 

  1553.             currently hardcoded. The only way to tweak configuration
    1554. 

  1554.             is to directly modify source code. See see <a class="xref" href="#dhcp6-config" title="14.2. DHCPv6 Server Configuration">Section 14.2, &#8220;DHCPv6 Server Configuration&#8221;</a> for details.</li><li class="listitem">Upon start, the server will open sockets on all
    1555. 

  1555.           interfaces that are not loopback, are up, running and are
    1556. 

  1556.           multicast capable and have IPv6 address.  Support for
    1557. 

  1557.           multiple interfaces is not coded in reception routines yet,
    1558. 

  1558.           so if you are running this code on a machine that has many
    1559. 

  1559.           interfaces and <span class="command"><strong>b10-dhcp6</strong></span> happens to
    1560. 

  1560.           listen on wrong interface, the easiest way to work around
    1561. 

  1561.           this problem is to turn down other interfaces. This
    1562. 

  1562.           limitation will be fixed shortly.</li><li class="listitem">ORO (Option Request Option, a list of options
    1563. 

  1563.           requested by a client) is currently ignored and server
    1564. 

  1564.           assigns DNS SERVER option.</li><li class="listitem">Temporary addresses are not supported yet.</li><li class="listitem">Prefix delegation is not supported yet.</li><li class="listitem">Address renewal (RENEW), rebinding (REBIND),
    1565. 

  1565.           confirmation (CONFIRM), duplication report (DECLINE) and
    1566. 

  1566.           release (RELEASE) are not supported yet.</li><li class="listitem">DNS Update is not supported yet.</li><li class="listitem">Interface detection is currently working on Linux
    1567. 

  1567.           only. See <a class="xref" href="#iface-detect" title="15.1. Interface detection">Section 15.1, &#8220;Interface detection&#8221;</a> for details.</li><li class="listitem">-v (verbose) command line option is currently the
    1568. 

  1568.           default, and cannot be disabled.</li></ul></div><p>
    1569. 

  1569.       </p></div></div><div class="chapter" title="Chapter 15. libdhcp++ library"><div class="titlepage"><div><div><h2 class="title"><a name="libdhcp"></a>Chapter 15. libdhcp++ library</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#iface-detect">15.1. Interface detection</a></span></dt><dt><span class="section"><a href="#packet-handling">15.2. DHCPv4/DHCPv6 packet handling</a></span></dt></dl></div><p>libdhcp++ is a common library written in C++ that handles
    1570. 

  1570.     many DHCP-related tasks, like DHCPv4 and DHCPv6 packets parsing,
    1571. 

  1571.     manipulation and assembly, option parsing, manipulation and
    1572. 

  1572.     assembly, network interface detection and socket operations, like
    1573. 

  1573.     socket creations, data transmission and reception and socket
    1574. 

  1574.     closing.
    1575. 

  1575.     </p><p>
    1576. 

  1576.     While this library is currently used by
    1577. 

  1577.     <span class="command"><strong>b10-dhcp4</strong></span> and <span class="command"><strong>b10-dhcp6</strong></span>
    1578. 

  1578.     only, it is designed to be portable, universal library useful for
    1579. 

  1579.     any kind of DHCP-related software.
    1580. 

  1580.     </p><div class="section" title="15.1. Interface detection"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="iface-detect"></a>15.1. Interface detection</h2></div></div></div><p>Both DHCPv4 and DHCPv6 components share network
    1581. 

  1581.       interface detection routines. Interface detection is
    1582. 

  1582.       currently only supported on Linux systems.</p><p>For non-Linux systems, there is currently stub
    1583. 

  1583.       implementation provided. Interface manager detects loopback
    1584. 

  1584.       interfaces only as their name (lo or lo0) can be easily predicted.
    1585. 

  1585.       Please contact BIND10 development team if you are interested
    1586. 

  1586.       in running DHCP components on systems other than Linux.</p></div><div class="section" title="15.2. DHCPv4/DHCPv6 packet handling"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="packet-handling"></a>15.2. DHCPv4/DHCPv6 packet handling</h2></div></div></div><p>TODO: Describe packet handling here, with pointers to wiki</p></div></div><div class="chapter" title="Chapter 16. Statistics"><div class="titlepage"><div><div><h2 class="title"><a name="statistics"></a>Chapter 16. Statistics</h2></div></div></div><p>
    1587. 

  1587.       The <span class="command"><strong>b10-stats</strong></span> process is started by
    1588. 

  1588.       <span class="command"><strong>bind10</strong></span>.
    1589. 

  1589.       It periodically collects statistics data from various modules
    1590. 

  1590.       and aggregates it.
    1591. 

  1591. 

  1592.     </p><p>
    1593. 

  1593. 

  1594.        This stats daemon provides commands to identify if it is
    1595. 

  1595.        running, show specified or all statistics data, show specified
    1596. 

  1596.        or all statistics data schema, and set specified statistics
    1597. 

  1597.        data.
    1598. 

  1598. 

  1599.        For example, using <span class="command"><strong>bindctl</strong></span>:
    1600. 

  1600. 

  1601.        </p><pre class="screen">
    1602. 

  1602. &gt; <strong class="userinput"><code>Stats show</code></strong>
    1603. 

  1603. {
    1604. 

  1604.     "Auth": {
    1605. 

  1605.         "opcode.iquery": 0,
    1606. 

  1606.         "opcode.notify": 10,
    1607. 

  1607.         "opcode.query": 869617,
    1608. 

  1608.         ...
    1609. 

  1609.         "queries.tcp": 1749,
    1610. 

  1610.         "queries.udp": 867868
    1611. 

  1611.     },
    1612. 

  1612.     "Boss": {
    1613. 

  1613.         "boot_time": "2011-01-20T16:59:03Z"
    1614. 

  1614.     },
    1615. 

  1615.     "Stats": {
    1616. 

  1616.         "boot_time": "2011-01-20T16:59:05Z",
    1617. 

  1617.         "last_update_time": "2011-01-20T17:04:05Z",
    1618. 

  1618.         "lname": "4d3869d9_a@jreed.example.net",
    1619. 

  1619.         "report_time": "2011-01-20T17:04:06Z",
    1620. 

  1620.         "timestamp": 1295543046.823504
    1621. 

  1621.     }
    1622. 

  1622. }
    1623. 

  1623.        </pre><p>
    1624. 

  1624.     </p></div><div class="chapter" title="Chapter 17. Logging"><div class="titlepage"><div><div><h2 class="title"><a name="logging"></a>Chapter 17. Logging</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#id1168229440926">17.1. Logging configuration</a></span></dt><dd><dl><dt><span class="section"><a href="#id1168229440937">17.1.1. Loggers</a></span></dt><dt><span class="section"><a href="#id1168229441248">17.1.2. Output Options</a></span></dt><dt><span class="section"><a href="#id1168229441431">17.1.3. Example session</a></span></dt></dl></dd><dt><span class="section"><a href="#id1168229441640">17.2. Logging Message Format</a></span></dt></dl></div><div class="section" title="17.1. Logging configuration"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id1168229440926"></a>17.1. Logging configuration</h2></div></div></div><p>
    1625. 

  1625. 

  1626.         The logging system in BIND 10 is configured through the
    1627. 

  1627.         Logging module. All BIND 10 modules will look at the
    1628. 

  1628.         configuration in Logging to see what should be logged and
    1629. 

  1629.         to where.
    1630. 

  1630. 

  1631. 

  1632. 

  1633.       </p><div class="section" title="17.1.1. Loggers"><div class="titlepage"><div><div><h3 class="title"><a name="id1168229440937"></a>17.1.1. Loggers</h3></div></div></div><p>
    1634. 

  1634. 

  1635.           Within BIND 10, a message is logged through a component
    1636. 

  1636.           called a "logger". Different parts of BIND 10 log messages
    1637. 

  1637.           through different loggers, and each logger can be configured
    1638. 

  1638.           independently of one another.
    1639. 

  1639. 

  1640.         </p><p>
    1641. 

  1641. 

  1642.           In the Logging module, you can specify the configuration
    1643. 

  1643.           for zero or more loggers; any that are not specified will
    1644. 

  1644.           take appropriate default values.
    1645. 

  1645. 

  1646.         </p><p>
    1647. 

  1647. 

  1648.           The three most important elements of a logger configuration
    1649. 

  1649.           are the <code class="option">name</code> (the component that is
    1650. 

  1650.           generating the messages), the <code class="option">severity</code>
    1651. 

  1651.           (what to log), and the <code class="option">output_options</code>
    1652. 

  1652.           (where to log).
    1653. 

  1653. 

  1654.         </p><div class="section" title="17.1.1.1. name (string)"><div class="titlepage"><div><div><h4 class="title"><a name="id1168229440962"></a>17.1.1.1. name (string)</h4></div></div></div><p>
    1655. 

  1655.           Each logger in the system has a name, the name being that
    1656. 

  1656.           of the component using it to log messages. For instance,
    1657. 

  1657.           if you want to configure logging for the resolver module,
    1658. 

  1658.           you add an entry for a logger named <span class="quote">&#8220;<span class="quote">Resolver</span>&#8221;</span>. This
    1659. 

  1659.           configuration will then be used by the loggers in the
    1660. 

  1660.           Resolver module, and all the libraries used by it.
    1661. 

  1661.               </p><p>
    1662. 

  1662. 

  1663.           If you want to specify logging for one specific library
    1664. 

  1664.           within the module, you set the name to
    1665. 

  1665.           <em class="replaceable"><code>module.library</code></em>.  For example, the
    1666. 

  1666.           logger used by the nameserver address store component
    1667. 

  1667.           has the full name of <span class="quote">&#8220;<span class="quote">Resolver.nsas</span>&#8221;</span>. If
    1668. 

  1668.           there is no entry in Logging for a particular library,
    1669. 

  1669.           it will use the configuration given for the module.
    1670. 

  1670. 

  1671. 

  1672. 

  1673.         </p><p>
    1674. 

  1674. 

  1675. 

  1676. 

  1677.           To illustrate this, suppose you want the cache library
    1678. 

  1678.           to log messages of severity DEBUG, and the rest of the
    1679. 

  1679.           resolver code to log messages of severity INFO. To achieve
    1680. 

  1680.           this you specify two loggers, one with the name
    1681. 

  1681.           <span class="quote">&#8220;<span class="quote">Resolver</span>&#8221;</span> and severity INFO, and one with
    1682. 

  1682.           the name <span class="quote">&#8220;<span class="quote">Resolver.cache</span>&#8221;</span> with severity
    1683. 

  1683.           DEBUG. As there are no entries for other libraries (e.g.
    1684. 

  1684.           the nsas), they will use the configuration for the module
    1685. 

  1685.           (<span class="quote">&#8220;<span class="quote">Resolver</span>&#8221;</span>), so giving the desired behavior.
    1686. 

  1686. 

  1687.         </p><p>
    1688. 

  1688. 

  1689.           One special case is that of a module name of <span class="quote">&#8220;<span class="quote">*</span>&#8221;</span>
    1690. 

  1690.           (asterisks), which is interpreted as <span class="emphasis"><em>any</em></span>
    1691. 

  1691.           module. You can set global logging options by using this,
    1692. 

  1692.           including setting the logging configuration for a library
    1693. 

  1693.           that is used by multiple modules (e.g. <span class="quote">&#8220;<span class="quote">*.config</span>&#8221;</span>
    1694. 

  1694.           specifies the configuration library code in whatever
    1695. 

  1695.           module is using it).
    1696. 

  1696. 

  1697.         </p><p>
    1698. 

  1698. 

  1699.           If there are multiple logger specifications in the
    1700. 

  1700.           configuration that might match a particular logger, the
    1701. 

  1701.           specification with the more specific logger name takes
    1702. 

  1702.           precedence. For example, if there are entries for for
    1703. 

  1703.           both <span class="quote">&#8220;<span class="quote">*</span>&#8221;</span> and <span class="quote">&#8220;<span class="quote">Resolver</span>&#8221;</span>, the
    1704. 

  1704.           resolver module &#8212; and all libraries it uses &#8212;
    1705. 

  1705.           will log messages according to the configuration in the
    1706. 

  1706.           second entry (<span class="quote">&#8220;<span class="quote">Resolver</span>&#8221;</span>). All other modules
    1707. 

  1707.           will use the configuration of the first entry
    1708. 

  1708.           (<span class="quote">&#8220;<span class="quote">*</span>&#8221;</span>). If there was also a configuration
    1709. 

  1709.           entry for <span class="quote">&#8220;<span class="quote">Resolver.cache</span>&#8221;</span>, the cache library
    1710. 

  1710.           within the resolver would use that in preference to the
    1711. 

  1711.           entry for <span class="quote">&#8220;<span class="quote">Resolver</span>&#8221;</span>.
    1712. 

  1712. 

  1713.         </p><p>
    1714. 

  1714. 

  1715.           One final note about the naming. When specifying the
    1716. 

  1716.           module name within a logger, use the name of the module
    1717. 

  1717.           as specified in <span class="command"><strong>bindctl</strong></span>, e.g.
    1718. 

  1718.           <span class="quote">&#8220;<span class="quote">Resolver</span>&#8221;</span> for the resolver module,
    1719. 

  1719.           <span class="quote">&#8220;<span class="quote">Xfrout</span>&#8221;</span> for the xfrout module, etc. When
    1720. 

  1720.           the message is logged, the message will include the name
    1721. 

  1721.           of the logger generating the message, but with the module
    1722. 

  1722.           name replaced by the name of the process implementing
    1723. 

  1723.           the module (so for example, a message generated by the
    1724. 

  1724.           <span class="quote">&#8220;<span class="quote">Auth.cache</span>&#8221;</span> logger will appear in the output
    1725. 

  1725.           with a logger name of <span class="quote">&#8220;<span class="quote">b10-auth.cache</span>&#8221;</span>).
    1726. 

  1726. 

  1727.         </p></div><div class="section" title="17.1.1.2. severity (string)"><div class="titlepage"><div><div><h4 class="title"><a name="id1168229441130"></a>17.1.1.2. severity (string)</h4></div></div></div><p>
    1728. 

  1728. 

  1729.           This specifies the category of messages logged.
    1730. 

  1730.           Each message is logged with an associated severity which
    1731. 

  1731.           may be one of the following (in descending order of
    1732. 

  1732.           severity):
    1733. 

  1733.         </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"> FATAL </li><li class="listitem"> ERROR </li><li class="listitem"> WARN </li><li class="listitem"> INFO </li><li class="listitem"> DEBUG </li></ul></div><p>
    1734. 

  1734. 

  1735.           When the severity of a logger is set to one of these
    1736. 

  1736.           values, it will only log messages of that severity, and
    1737. 

  1737.           the severities above it. The severity may also be set to
    1738. 

  1738.           NONE, in which case all messages from that logger are
    1739. 

  1739.           inhibited.
    1740. 

  1740. 

  1741. 

  1742. 

  1743.         </p></div><div class="section" title="17.1.1.3. output_options (list)"><div class="titlepage"><div><div><h4 class="title"><a name="id1168229441180"></a>17.1.1.3. output_options (list)</h4></div></div></div><p>
    1744. 

  1744. 

  1745.           Each logger can have zero or more
    1746. 

  1746.           <code class="option">output_options</code>. These specify where log
    1747. 

  1747.           messages are sent to. These are explained in detail below.
    1748. 

  1748. 

  1749.         </p><p>
    1750. 

  1750. 

  1751.           The other options for a logger are:
    1752. 

  1752. 

  1753.         </p></div><div class="section" title="17.1.1.4. debuglevel (integer)"><div class="titlepage"><div><div><h4 class="title"><a name="id1168229441197"></a>17.1.1.4. debuglevel (integer)</h4></div></div></div><p>
    1754. 

  1754. 

  1755.           When a logger's severity is set to DEBUG, this value
    1756. 

  1756.           specifies what debug messages should be printed. It ranges
    1757. 

  1757.           from 0 (least verbose) to 99 (most verbose).
    1758. 

  1758.         </p><p>
    1759. 

  1759. 

  1760.           If severity for the logger is not DEBUG, this value is ignored.
    1761. 

  1761. 

  1762.         </p></div><div class="section" title="17.1.1.5. additive (true or false)"><div class="titlepage"><div><div><h4 class="title"><a name="id1168229441212"></a>17.1.1.5. additive (true or false)</h4></div></div></div><p>
    1763. 

  1763. 

  1764.           If this is true, the <code class="option">output_options</code> from
    1765. 

  1765.           the parent will be used. For example, if there are two
    1766. 

  1766.           loggers configured; <span class="quote">&#8220;<span class="quote">Resolver</span>&#8221;</span> and
    1767. 

  1767.           <span class="quote">&#8220;<span class="quote">Resolver.cache</span>&#8221;</span>, and <code class="option">additive</code>
    1768. 

  1768.           is true in the second, it will write the log messages
    1769. 

  1769.           not only to the destinations specified for
    1770. 

  1770.           <span class="quote">&#8220;<span class="quote">Resolver.cache</span>&#8221;</span>, but also to the destinations
    1771. 

  1771.           as specified in the <code class="option">output_options</code> in
    1772. 

  1772.           the logger named <span class="quote">&#8220;<span class="quote">Resolver</span>&#8221;</span>.
    1773. 

  1773. 

  1774. 

  1775. 

  1776.       </p></div></div><div class="section" title="17.1.2. Output Options"><div class="titlepage"><div><div><h3 class="title"><a name="id1168229441248"></a>17.1.2. Output Options</h3></div></div></div><p>
    1777. 

  1777. 

  1778.           The main settings for an output option are the
    1779. 

  1779.           <code class="option">destination</code> and a value called
    1780. 

  1780.           <code class="option">output</code>, the meaning of which depends on
    1781. 

  1781.           the destination that is set.
    1782. 

  1782. 

  1783.         </p><div class="section" title="17.1.2.1. destination (string)"><div class="titlepage"><div><div><h4 class="title"><a name="id1168229441264"></a>17.1.2.1. destination (string)</h4></div></div></div><p>
    1784. 

  1784. 

  1785.             The destination is the type of output. It can be one of:
    1786. 

  1786. 

  1787.           </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"> console </li><li class="listitem"> file </li><li class="listitem"> syslog </li></ul></div></div><div class="section" title="17.1.2.2. output (string)"><div class="titlepage"><div><div><h4 class="title"><a name="id1168229441296"></a>17.1.2.2. output (string)</h4></div></div></div><p>
    1788. 

  1788. 

  1789.           Depending on what is set as the output destination, this
    1790. 

  1790.           value is interpreted as follows:
    1791. 

  1791. 

  1792.         </p><div class="variablelist"><dl><dt><span class="term"><code class="option">destination</code> is <span class="quote">&#8220;<span class="quote">console</span>&#8221;</span></span></dt><dd><p>
    1793. 

  1793.                  The value of output must be one of <span class="quote">&#8220;<span class="quote">stdout</span>&#8221;</span>
    1794. 

  1794.                  (messages printed to standard output) or
    1795. 

  1795.                  <span class="quote">&#8220;<span class="quote">stderr</span>&#8221;</span> (messages printed to standard
    1796. 

  1796.                  error).
    1797. 

  1797.               </p><p>
    1798. 

  1798.                 Note: if output is set to <span class="quote">&#8220;<span class="quote">stderr</span>&#8221;</span> and a lot of
    1799. 

  1799.                 messages are produced in a short time (e.g. if the logging
    1800. 

  1800.                 level is set to DEBUG), you may occasionally see some messages
    1801. 

  1801.                 jumbled up together.  This is due to a combination of the way
    1802. 

  1802.                 that messages are written to the screen and the unbuffered
    1803. 

  1803.                 nature of the standard error stream.  If this occurs, it is
    1804. 

  1804.                 recommended that output be set to <span class="quote">&#8220;<span class="quote">stdout</span>&#8221;</span>.
    1805. 

  1805.               </p></dd><dt><span class="term"><code class="option">destination</code> is <span class="quote">&#8220;<span class="quote">file</span>&#8221;</span></span></dt><dd><p>
    1806. 

  1806.                 The value of output is interpreted as a file name;
    1807. 

  1807.                 log messages will be appended to this file.
    1808. 

  1808.               </p></dd><dt><span class="term"><code class="option">destination</code> is <span class="quote">&#8220;<span class="quote">syslog</span>&#8221;</span></span></dt><dd><p>
    1809. 

  1809.                 The value of output is interpreted as the
    1810. 

  1810.                 <span class="command"><strong>syslog</strong></span> facility (e.g.
    1811. 

  1811.                 <span class="emphasis"><em>local0</em></span>) that should be used
    1812. 

  1812.                 for log messages.
    1813. 

  1813.               </p></dd></dl></div><p>
    1814. 

  1814. 

  1815.           The other options for <code class="option">output_options</code> are:
    1816. 

  1816. 

  1817.         </p><div class="section" title="17.1.2.2.1. flush (true of false)"><div class="titlepage"><div><div><h5 class="title"><a name="id1168229441389"></a>17.1.2.2.1. flush (true of false)</h5></div></div></div><p>
    1818. 

  1818.             Flush buffers after each log message. Doing this will
    1819. 

  1819.             reduce performance but will ensure that if the program
    1820. 

  1820.             terminates abnormally, all messages up to the point of
    1821. 

  1821.             termination are output.
    1822. 

  1822.           </p></div><div class="section" title="17.1.2.2.2. maxsize (integer)"><div class="titlepage"><div><div><h5 class="title"><a name="id1168229441400"></a>17.1.2.2.2. maxsize (integer)</h5></div></div></div><p>
    1823. 

  1823.             Only relevant when destination is file, this is maximum
    1824. 

  1824.             file size of output files in bytes. When the maximum
    1825. 

  1825.             size is reached, the file is renamed and a new file opened.
    1826. 

  1826.             (For example, a ".1" is appended to the name &#8212;
    1827. 

  1827.             if a ".1" file exists, it is renamed ".2",
    1828. 

  1828.             etc.)
    1829. 

  1829.           </p><p>
    1830. 

  1830.             If this is 0, no maximum file size is used.
    1831. 

  1831.           </p></div><div class="section" title="17.1.2.2.3. maxver (integer)"><div class="titlepage"><div><div><h5 class="title"><a name="id1168229441413"></a>17.1.2.2.3. maxver (integer)</h5></div></div></div><p>
    1832. 

  1832.             Maximum number of old log files to keep around when
    1833. 

  1833.             rolling the output file. Only relevant when
    1834. 

  1834.             <code class="option">destination</code> is <span class="quote">&#8220;<span class="quote">file</span>&#8221;</span>.
    1835. 

  1835.           </p></div></div></div><div class="section" title="17.1.3. Example session"><div class="titlepage"><div><div><h3 class="title"><a name="id1168229441431"></a>17.1.3. Example session</h3></div></div></div><p>
    1836. 

  1836. 

  1837.           In this example we want to set the global logging to
    1838. 

  1838.           write to the file <code class="filename">/var/log/my_bind10.log</code>,
    1839. 

  1839.           at severity WARN. We want the authoritative server to
    1840. 

  1840.           log at DEBUG with debuglevel 40, to a different file
    1841. 

  1841.           (<code class="filename">/tmp/debug_messages</code>).
    1842. 

  1842. 

  1843.         </p><p>
    1844. 

  1844. 

  1845.           Start <span class="command"><strong>bindctl</strong></span>.
    1846. 

  1846. 

  1847.         </p><p>
    1848. 

  1848. 

  1849.            </p><pre class="screen">["login success "]
    1850. 

  1850. &gt; <strong class="userinput"><code>config show Logging</code></strong>
    1851. 

  1851. Logging/loggers	[]	list
    1852. 

  1852. </pre><p>
    1853. 

  1853. 

  1854.         </p><p>
    1855. 

  1855. 

  1856.           By default, no specific loggers are configured, in which
    1857. 

  1857.           case the severity defaults to INFO and the output is
    1858. 

  1858.           written to stderr.
    1859. 

  1859. 

  1860.         </p><p>
    1861. 

  1861. 

  1862.           Let's first add a default logger:
    1863. 

  1863. 

  1864.         </p><p>
    1865. 

  1865. 

  1866.           </p><pre class="screen"><strong class="userinput"><code>&gt; config add Logging/loggers</code></strong>
    1867. 

  1867. &gt; <strong class="userinput"><code>config show Logging</code></strong>
    1868. 

  1868. Logging/loggers/	list	(modified)
    1869. 

  1869. </pre><p>
    1870. 

  1870. 

  1871.         </p><p>
    1872. 

  1872. 

  1873.           The loggers value line changed to indicate that it is no
    1874. 

  1874.           longer an empty list:
    1875. 

  1875. 

  1876.         </p><p>
    1877. 

  1877. 

  1878.           </p><pre class="screen">&gt; <strong class="userinput"><code>config show Logging/loggers</code></strong>
    1879. 

  1879. Logging/loggers[0]/name	""	string	(default)
    1880. 

  1880. Logging/loggers[0]/severity	"INFO"	string	(default)
    1881. 

  1881. Logging/loggers[0]/debuglevel	0	integer	(default)
    1882. 

  1882. Logging/loggers[0]/additive	false	boolean	(default)
    1883. 

  1883. Logging/loggers[0]/output_options	[]	list	(default)
    1884. 

  1884. </pre><p>
    1885. 

  1885. 

  1886.         </p><p>
    1887. 

  1887. 

  1888.           The name is mandatory, so we must set it. We will also
    1889. 

  1889.           change the severity as well. Let's start with the global
    1890. 

  1890.           logger.
    1891. 

  1891. 

  1892.         </p><p>
    1893. 

  1893. 

  1894.           </p><pre class="screen">&gt; <strong class="userinput"><code>config set Logging/loggers[0]/name *</code></strong>
    1895. 

  1895. &gt; <strong class="userinput"><code>config set Logging/loggers[0]/severity WARN</code></strong>
    1896. 

  1896. &gt; <strong class="userinput"><code>config show Logging/loggers</code></strong>
    1897. 

  1897. Logging/loggers[0]/name	"*"	string	(modified)
    1898. 

  1898. Logging/loggers[0]/severity	"WARN"	string	(modified)
    1899. 

  1899. Logging/loggers[0]/debuglevel	0	integer	(default)
    1900. 

  1900. Logging/loggers[0]/additive	false	boolean	(default)
    1901. 

  1901. Logging/loggers[0]/output_options	[]	list	(default)
    1902. 

  1902. </pre><p>
    1903. 

  1903. 

  1904.         </p><p>
    1905. 

  1905. 

  1906.           Of course, we need to specify where we want the log
    1907. 

  1907.           messages to go, so we add an entry for an output option.
    1908. 

  1908. 

  1909.         </p><p>
    1910. 

  1910. 

  1911.           </p><pre class="screen">&gt; <strong class="userinput"><code> config add Logging/loggers[0]/output_options</code></strong>
    1912. 

  1912. &gt; <strong class="userinput"><code> config show Logging/loggers[0]/output_options</code></strong>
    1913. 

  1913. Logging/loggers[0]/output_options[0]/destination	"console"	string	(default)
    1914. 

  1914. Logging/loggers[0]/output_options[0]/output	"stdout"	string	(default)
    1915. 

  1915. Logging/loggers[0]/output_options[0]/flush	false	boolean	(default)
    1916. 

  1916. Logging/loggers[0]/output_options[0]/maxsize	0	integer	(default)
    1917. 

  1917. Logging/loggers[0]/output_options[0]/maxver	0	integer	(default)
    1918. 

  1918. </pre><p>
    1919. 

  1919. 

  1920. 

  1921.         </p><p>
    1922. 

  1922. 

  1923.           These aren't the values we are looking for.
    1924. 

  1924. 

  1925.         </p><p>
    1926. 

  1926. 

  1927.           </p><pre class="screen">&gt; <strong class="userinput"><code> config set Logging/loggers[0]/output_options[0]/destination file</code></strong>
    1928. 

  1928. &gt; <strong class="userinput"><code> config set Logging/loggers[0]/output_options[0]/output /var/log/bind10.log</code></strong>
    1929. 

  1929. &gt; <strong class="userinput"><code> config set Logging/loggers[0]/output_options[0]/maxsize 204800</code></strong>
    1930. 

  1930. &gt; <strong class="userinput"><code> config set Logging/loggers[0]/output_options[0]/maxver 8</code></strong>
    1931. 

  1931. </pre><p>
    1932. 

  1932. 

  1933.         </p><p>
    1934. 

  1934. 

  1935.           Which would make the entire configuration for this logger
    1936. 

  1936.           look like:
    1937. 

  1937. 

  1938.         </p><p>
    1939. 

  1939. 

  1940.           </p><pre class="screen">&gt; <strong class="userinput"><code> config show all Logging/loggers</code></strong>
    1941. 

  1941. Logging/loggers[0]/name	"*"	string	(modified)
    1942. 

  1942. Logging/loggers[0]/severity	"WARN"	string	(modified)
    1943. 

  1943. Logging/loggers[0]/debuglevel	0	integer	(default)
    1944. 

  1944. Logging/loggers[0]/additive	false	boolean	(default)
    1945. 

  1945. Logging/loggers[0]/output_options[0]/destination	"file"	string	(modified)
    1946. 

  1946. Logging/loggers[0]/output_options[0]/output	"/var/log/bind10.log"	string	(modified)
    1947. 

  1947. Logging/loggers[0]/output_options[0]/flush	false	boolean	(default)
    1948. 

  1948. Logging/loggers[0]/output_options[0]/maxsize	204800	integer	(modified)
    1949. 

  1949. Logging/loggers[0]/output_options[0]/maxver	8	integer	(modified)
    1950. 

  1950. </pre><p>
    1951. 

  1951. 

  1952.         </p><p>
    1953. 

  1953. 

  1954.           That looks OK, so let's commit it before we add the
    1955. 

  1955.           configuration for the authoritative server's logger.
    1956. 

  1956. 

  1957.         </p><p>
    1958. 

  1958. 

  1959.           </p><pre class="screen">&gt; <strong class="userinput"><code> config commit</code></strong></pre><p>
    1960. 

  1960. 

  1961.         </p><p>
    1962. 

  1962. 

  1963.           Now that we have set it, and checked each value along
    1964. 

  1964.           the way, adding a second entry is quite similar.
    1965. 

  1965. 

  1966.         </p><p>
    1967. 

  1967. 

  1968.           </p><pre class="screen">&gt; <strong class="userinput"><code> config add Logging/loggers</code></strong>
    1969. 

  1969. &gt; <strong class="userinput"><code> config set Logging/loggers[1]/name Auth</code></strong>
    1970. 

  1970. &gt; <strong class="userinput"><code> config set Logging/loggers[1]/severity DEBUG</code></strong>
    1971. 

  1971. &gt; <strong class="userinput"><code> config set Logging/loggers[1]/debuglevel 40</code></strong>
    1972. 

  1972. &gt; <strong class="userinput"><code> config add Logging/loggers[1]/output_options</code></strong>
    1973. 

  1973. &gt; <strong class="userinput"><code> config set Logging/loggers[1]/output_options[0]/destination file</code></strong>
    1974. 

  1974. &gt; <strong class="userinput"><code> config set Logging/loggers[1]/output_options[0]/output /tmp/auth_debug.log</code></strong>
    1975. 

  1975. &gt; <strong class="userinput"><code> config commit</code></strong>
    1976. 

  1976. </pre><p>
    1977. 

  1977. 

  1978.         </p><p>
    1979. 

  1979. 

  1980.           And that's it. Once we have found whatever it was we
    1981. 

  1981.           needed the debug messages for, we can simply remove the
    1982. 

  1982.           second logger to let the authoritative server use the
    1983. 

  1983.           same settings as the rest.
    1984. 

  1984. 

  1985.         </p><p>
    1986. 

  1986. 

  1987.           </p><pre class="screen">&gt; <strong class="userinput"><code> config remove Logging/loggers[1]</code></strong>
    1988. 

  1988. &gt; <strong class="userinput"><code> config commit</code></strong>
    1989. 

  1989. </pre><p>
    1990. 

  1990. 

  1991.         </p><p>
    1992. 

  1992. 

  1993.           And every module will now be using the values from the
    1994. 

  1994.           logger named <span class="quote">&#8220;<span class="quote">*</span>&#8221;</span>.
    1995. 

  1995. 

  1996.         </p></div></div><div class="section" title="17.2. Logging Message Format"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id1168229441640"></a>17.2. Logging Message Format</h2></div></div></div><p>
    1997. 

  1997.           Each message written by BIND 10 to the configured logging
    1998. 

  1998.           destinations comprises a number of components that identify
    1999. 

  1999.           the origin of the message and, if the message indicates
    2000. 

  2000.           a problem, information about the problem that may be
    2001. 

  2001.           useful in fixing it.
    2002. 

  2002.       </p><p>
    2003. 

  2003.           Consider the message below logged to a file:
    2004. 

  2004.           </p><pre class="screen">2011-06-15 13:48:22.034 ERROR [b10-resolver.asiolink]
    2005. 

  2005.     ASIODNS_OPENSOCK error 111 opening TCP socket to 127.0.0.1(53)</pre><p>
    2006. 

  2006.       </p><p>
    2007. 

  2007.         Note: the layout of messages written to the system logging
    2008. 

  2008.         file (syslog) may be slightly different.  This message has
    2009. 

  2009.         been split across two lines here for display reasons; in the
    2010. 

  2010.         logging file, it will appear on one line.)
    2011. 

  2011.       </p><p>
    2012. 

  2012.         The log message comprises a number of components:
    2013. 

  2013. 

  2014.           </p><div class="variablelist"><dl><dt><span class="term">2011-06-15 13:48:22.034</span></dt><dd><p>
    2015. 

  2015.               The date and time at which the message was generated.
    2016. 

  2016.           </p></dd><dt><span class="term">ERROR</span></dt><dd><p>
    2017. 

  2017.               The severity of the message.
    2018. 

  2018.           </p></dd><dt><span class="term">[b10-resolver.asiolink]</span></dt><dd><p>
    2019. 

  2019.             The source of the message.  This comprises two components:
    2020. 

  2020.             the BIND 10 process generating the message (in this
    2021. 

  2021.             case, <span class="command"><strong>b10-resolver</strong></span>) and the module
    2022. 

  2022.             within the program from which the message originated
    2023. 

  2023.             (which in the example is the asynchronous I/O link
    2024. 

  2024.             module, asiolink).
    2025. 

  2025.           </p></dd><dt><span class="term">ASIODNS_OPENSOCK</span></dt><dd><p>
    2026. 

  2026.             The message identification.  Every message in BIND 10
    2027. 

  2027.             has a unique identification, which can be used as an
    2028. 

  2028.             index into the <a class="ulink" href="bind10-messages.html" target="_top"><em class="citetitle">BIND 10 Messages
    2029. 

  2029.             Manual</em></a> (<a class="ulink" href="http://bind10.isc.org/docs/bind10-messages.html" target="_top">http://bind10.isc.org/docs/bind10-messages.html</a>) from which more information can be obtained.
    2030. 

  2030.           </p></dd><dt><span class="term">error 111 opening TCP socket to 127.0.0.1(53)</span></dt><dd><p>
    2031. 

  2031.               A brief description of the cause of the problem.
    2032. 

  2032.               Within this text, information relating to the condition
    2033. 

  2033.               that caused the message to be logged will be included.
    2034. 

  2034.               In this example, error number 111 (an operating
    2035. 

  2035.               system-specific error number) was encountered when
    2036. 

  2036.               trying to open a TCP connection to port 53 on the
    2037. 

  2037.               local system (address 127.0.0.1).  The next step
    2038. 

  2038.               would be to find out the reason for the failure by
    2039. 

  2039.               consulting your system's documentation to identify
    2040. 

  2040.               what error number 111 means.
    2041. 

  2041.           </p></dd></dl></div><p>
    2042. 

  2042.       </p></div></div></div></body></html>
    2043.