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

bind10-guide.html 150 KB
History Raw

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299130013011302130313041305130613071308130913101311131213131314131513161317131813191320132113221323132413251326132713281329133013311332133313341335133613371338133913401341134213431344134513461347134813491350135113521353135413551356135713581359136013611362136313641365136613671368136913701371137213731374137513761377137813791380138113821383138413851386138713881389139013911392139313941395139613971398139914001401140214031404140514061407140814091410141114121413141414151416141714181419142014211422142314241425142614271428142914301431143214331434143514361437143814391440144114421443144414451446144714481449145014511452145314541455145614571458145914601461146214631464146514661467146814691470147114721473147414751476147714781479148014811482148314841485148614871488148914901491149214931494149514961497149814991500150115021503150415051506150715081509151015111512151315141515151615171518151915201521152215231524152515261527152815291530153115321533153415351536153715381539154015411542154315441545154615471548154915501551155215531554155515561557155815591560156115621563156415651566156715681569157015711572157315741575157615771578157915801581158215831584158515861587158815891590159115921593159415951596159715981599160016011602160316041605160616071608160916101611161216131614161516161617161816191620162116221623162416251626162716281629163016311632163316341635163616371638163916401641164216431644164516461647164816491650165116521653165416551656165716581659166016611662166316641665166616671668166916701671167216731674167516761677167816791680168116821683168416851686168716881689169016911692169316941695169616971698169917001701170217031704170517061707170817091710171117121713171417151716171717181719172017211722172317241725172617271728172917301731173217331734173517361737173817391740174117421743174417451746174717481749175017511752175317541755175617571758175917601761176217631764176517661767176817691770177117721773177417751776177717781779178017811782178317841785178617871788178917901791179217931794179517961797179817991800180118021803180418051806180718081809181018111812181318141815181618171818181918201821182218231824182518261827182818291830183118321833183418351836183718381839184018411842184318441845184618471848184918501851185218531854185518561857185818591860186118621863186418651866186718681869187018711872187318741875187618771878187918801881188218831884188518861887188818891890189118921893189418951896189718981899190019011902190319041905190619071908190919101911191219131914191519161917191819191920192119221923192419251926192719281929193019311932193319341935193619371938193919401941194219431944194519461947194819491950195119521953195419551956195719581959196019611962196319641965196619671968196919701971197219731974197519761977197819791980198119821983198419851986198719881989199019911992199319941995199619971998199920002001200220032004200520062007200820092010201120122013 
  1. <html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>BIND 10 Guide</title><link rel="stylesheet" type="text/css" href="./bind10-guide.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.1"><meta name="description" content="BIND 10 is a framework that features Domain Name System (DNS) suite and Dynamic Host Configuration Protocol (DHCP) servers 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 20120405. 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="idp25968"></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.         20120405.</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 managed by Internet Systems Consortium (ISC). It
    5. 

  5.       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 20120405.
    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="#idp32752">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="#idp38240">1.1. Supported Platforms</a></span></dt><dt><span class="section"><a href="#required-software">1.2. Required Software</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="#build-requirements">2.1. Building Requirements</a></span></dt><dt><span class="section"><a href="#quickstart">2.2. Quick start</a></span></dt><dt><span class="section"><a href="#install">2.3. Installation from source</a></span></dt><dd><dl><dt><span class="section"><a href="#idp128960">2.3.1. Download Tar File</a></span></dt><dt><span class="section"><a href="#idp131696">2.3.2. Retrieve from Git</a></span></dt><dt><span class="section"><a href="#idp140672">2.3.3. Configure before the build</a></span></dt><dt><span class="section"><a href="#idp154016">2.3.4. Build</a></span></dt><dt><span class="section"><a href="#idp156000">2.3.5. Install</a></span></dt><dt><span class="section"><a href="#idp159168">2.3.6. Install Hierarchy</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 of started 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="#idp280304">8.1. Server Configurations</a></span></dt><dt><span class="section"><a href="#idp323936">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="#idp357152">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="#idp375360">9.1. Configuration for Incoming Zone Transfers</a></span></dt><dt><span class="section"><a href="#idp380704">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="#idp397792">9.4. Trigger an Incoming Zone Transfer Manually</a></span></dt><dt><span class="section"><a href="#idp401488">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="#idp433840">11.1. Enabling Dynamic Update</a></span></dt><dt><span class="section"><a href="#idp448128">11.2. Access Control</a></span></dt><dt><span class="section"><a href="#idp471872">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="#idp492912">12.1. Access Control</a></span></dt><dt><span class="section"><a href="#idp509632">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="#idp609968">17.1. Logging configuration</a></span></dt><dd><dl><dt><span class="section"><a href="#idp611664">17.1.1. Loggers</a></span></dt><dt><span class="section"><a href="#idp648032">17.1.2. Output Options</a></span></dt><dt><span class="section"><a href="#idp673088">17.1.3. Example session</a></span></dt></dl></dd><dt><span class="section"><a href="#idp704416">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="#idp193680"></a></dt></dl></div><div class="preface" title="Preface"><div class="titlepage"><div><div><h2 class="title"><a name="idp32752"></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="#idp38240">1.1. Supported Platforms</a></span></dt><dt><span class="section"><a href="#required-software">1.2. Required Software</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.  BIND 10 is written in C++ and Python
    19. 

  19.       and provides a modular environment for serving and maintaining DNS.
    20. 

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

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

  22.       provides forwarding.
    23. 

  23.     </p><p>
    24. 

  24.       This guide covers the experimental prototype of
    25. 

  25.       BIND 10 version 20120405.
    26. 

  26.     </p><div class="section" title="1.1. Supported Platforms"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp38240"></a>1.1. Supported Platforms</h2></div></div></div><p>
    27. 

  27.   BIND 10 builds have been tested on (in no particular order)
    28. 

  28.   Debian GNU/Linux 5 and unstable, Ubuntu 9.10, NetBSD 5,
    29. 

  29.   Solaris 10 and 11, FreeBSD 7 and 8, CentOS Linux 5.3,
    30. 

  30.   MacOS 10.6 and 10.7, and OpenBSD 5.1.
    31. 

  31. 

  32.   It has been tested on Sparc, i386, and amd64 hardware
    33. 

  33.   platforms.
    34. 

  34. 

  35.         It is planned for BIND 10 to build, install and run on
    36. 

  36.         Windows and standard Unix-type platforms.
    37. 

  37.       </p></div><div class="section" title="1.2. Required Software"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="required-software"></a>1.2. Required Software</h2></div></div></div><p>
    38. 

  38.         BIND 10 requires at least Python 3.1
    39. 

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

  40.         It has also been tested with Python 3.2.
    41. 

  41.       </p><p>
    42. 

  42.         BIND 10 uses the Botan crypto library for C++
    43. 

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

  44.         It requires at least Botan version 1.8.
    45. 

  45.       </p><p>
    46. 

  46.         BIND 10 uses the log4cplus C++ logging library
    47. 

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

  48.         It requires at least log4cplus version 1.0.3.
    49. 

  49.       </p><p>
    50. 

  50.         The authoritative DNS server uses SQLite3
    51. 

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

  52. 

  53.         It needs at least SQLite version 3.3.9.
    54. 

  54.       </p><p>
    55. 

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

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

  57.         components require the libpython3 library and the Python
    58. 

  58.         _sqlite3.so module (which is included with Python).
    59. 

  59.         The <span class="command"><strong>b10-stats-httpd</strong></span> component uses the
    60. 

  60.         Python pyexpat.so module.
    61. 

  61.         The Python modules need to be built for the corresponding Python 3.
    62. 

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

  63.           Some operating systems do not provide these dependencies
    64. 

  64.           in their default installation nor standard packages
    65. 

  65.           collections.
    66. 

  66.           You may need to install them separately.
    67. 

  67.         </p></div></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>
    68. 

  68.         BIND 10 is modular.  Part of this modularity is
    69. 

  69.         accomplished using multiple cooperating processes which, together,
    70. 

  70.         provide the server functionality.  This is a change from
    71. 

  71.         the previous generation of BIND software, which used a
    72. 

  72.         single process.
    73. 

  73.       </p><p>
    74. 

  74.         At first, running many different processes may seem confusing.
    75. 

  75.         However, these processes are started, stopped, and maintained
    76. 

  76.         by a single command, <span class="command"><strong>bind10</strong></span>.
    77. 

  77.         This command starts a master process which will start other
    78. 

  78.         processes as needed.
    79. 

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

  80.         command have names starting with "b10-", including:
    81. 

  81.       </p><p>
    82. 

  82. 

  83.         </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
    84. 

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

  85.               Authoritative DNS server.
    86. 

  86.               This process serves DNS requests.
    87. 

  87.             </li><li class="listitem">
    88. 

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

  89.               Configuration manager.
    90. 

  90.               This process maintains all of the configuration for BIND 10.
    91. 

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

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

  93.               Command and control service.
    94. 

  94.               This process allows external control of the BIND 10 system.
    95. 

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

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

  97.               Dynamic DNS update service.
    98. 

  98.               This process is used to handle incoming DNS update
    99. 

  99.               requests to allow granted clients to update zones
    100. 

  100. 	      for which BIND 10 is serving as a primary server.
    101. 

  101.             </li><li class="listitem">
    102. 

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

  103.               Message bus daemon.
    104. 

  104.               This process coordinates communication between all of the other
    105. 

  105.               BIND 10 processes.
    106. 

  106.             </li><li class="listitem">
    107. 

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

  108.               Recursive name server.
    109. 

  109.               This process handles incoming queries.
    110. 

  110. 

  111.             </li><li class="listitem">
    112. 

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

  113.               Socket creator daemon.
    114. 

  114.               This process creates sockets used by
    115. 

  115.               network-listening BIND 10 processes.
    116. 

  116.             </li><li class="listitem">
    117. 

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

  118.               Statistics collection daemon.
    119. 

  119.               This process collects and reports statistics data.
    120. 

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

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

  122.               HTTP server for statistics reporting.
    123. 

  123.               This process reports statistics data in XML format over HTTP.
    124. 

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

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

  126.               Incoming zone transfer service.
    127. 

  127.               This process is used to transfer a new copy
    128. 

  128.               of a zone into BIND 10, when acting as a secondary server.
    129. 

  129.             </li><li class="listitem">
    130. 

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

  131.               Outgoing zone transfer service.
    132. 

  132.               This process is used to handle transfer requests to
    133. 

  133.               send a local zone to a remote secondary server,
    134. 

  134.               when acting as a master server.
    135. 

  135.             </li><li class="listitem">
    136. 

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

  137.               Secondary manager.
    138. 

  138.               This process keeps track of timers and other
    139. 

  139.               necessary information for BIND 10 to act as a slave server.
    140. 

  140.             </li></ul></div><p>
    141. 

  141.       </p><p>
    142. 

  142.         These are ran automatically by <span class="command"><strong>bind10</strong></span>
    143. 

  143.         and do not need to be run manually.
    144. 

  144.       </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>
    145. 

  145.         Once BIND 10 is running, a few commands are used to interact
    146. 

  146.         directly with the system:
    147. 

  147.         </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
    148. 

  148.               <span class="command"><strong>bindctl</strong></span> &#8212;
    149. 

  149.               interactive administration interface.
    150. 

  150.               This is a low-level command-line tool which allows
    151. 

  151.               a developer or an experienced administrator to control
    152. 

  152.               BIND 10.
    153. 

  153.             </li><li class="listitem">
    154. 

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

  155.               zone file loader.
    156. 

  156.               This tool will load standard masterfile-format zone files into
    157. 

  157.               BIND 10.
    158. 

  158.             </li><li class="listitem">
    159. 

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

  160.               user access control.
    161. 

  161.               This tool allows an administrator to authorize additional users
    162. 

  162.               to manage BIND 10.
    163. 

  163.             </li></ul></div><p>
    164. 

  164.       </p></div><p>
    165. 

  165.       The tools and modules are covered in full detail in this guide.
    166. 

  166. 

  167.       In addition, manual pages are also provided in the default installation.
    168. 

  168.     </p><p>
    169. 

  169.       BIND 10 also provides libraries and programmer interfaces
    170. 

  170.       for C++ and Python for the message bus, configuration backend,
    171. 

  171.       and, of course, DNS. These include detailed developer
    172. 

  172.       documentation and code examples.
    173. 

  173. 

  174.     </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="#build-requirements">2.1. Building Requirements</a></span></dt><dt><span class="section"><a href="#quickstart">2.2. Quick start</a></span></dt><dt><span class="section"><a href="#install">2.3. Installation from source</a></span></dt><dd><dl><dt><span class="section"><a href="#idp128960">2.3.1. Download Tar File</a></span></dt><dt><span class="section"><a href="#idp131696">2.3.2. Retrieve from Git</a></span></dt><dt><span class="section"><a href="#idp140672">2.3.3. Configure before the build</a></span></dt><dt><span class="section"><a href="#idp154016">2.3.4. Build</a></span></dt><dt><span class="section"><a href="#idp156000">2.3.5. Install</a></span></dt><dt><span class="section"><a href="#idp159168">2.3.6. Install Hierarchy</a></span></dt></dl></dd></dl></div><div class="section" title="2.1. Building Requirements"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="build-requirements"></a>2.1. Building Requirements</h2></div></div></div><p>
    175. 

  175.           In addition to the run-time requirements, building BIND 10
    176. 

  176.           from source code requires various development include headers.
    177. 

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

  178.             Some operating systems have split their distribution packages into
    179. 

  179.             a run-time and a development package.  You will need to install
    180. 

  180.             the development package versions, which include header files and
    181. 

  181.             libraries, to build BIND 10 from source code.
    182. 

  182.           </p></div><p>
    183. 

  183.           Building from source code requires the Boost
    184. 

  184.           build-time headers
    185. 

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

  186.           At least Boost version 1.35 is required.
    187. 

  187.   
    188. 

  188.   
    189. 

  189.         </p><p>
    190. 

  190.           To build BIND 10, also install the Botan (at least version
    191. 

  191.           1.8) and the log4cplus (at least version 1.0.3)
    192. 

  192.           development include headers.
    193. 

  193.         </p><p>
    194. 

  194.           Building BIND 10 also requires a C++ compiler and
    195. 

  195.           standard development headers, make, and pkg-config.
    196. 

  196.           BIND 10 builds have been tested with GCC g++ 3.4.3, 4.1.2,
    197. 

  197.           4.1.3, 4.2.1, 4.3.2, and 4.4.1; Clang++ 2.8; and Sun C++ 5.10.
    198. 

  198.         </p><p>
    199. 

  199.           Visit the wiki at <a class="ulink" href="http://bind10.isc.org/wiki/SystemSpecificNotes" target="_top">http://bind10.isc.org/wiki/SystemSpecificNotes</a>
    200. 

  200.           for system-specific installation tips.
    201. 

  201.         </p></div><div class="section" title="2.2. Quick start"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="quickstart"></a>2.2. 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>
    202. 

  202.           This quickly covers the standard steps for installing
    203. 

  203.           and deploying BIND 10 as an authoritative name server using
    204. 

  204.           its defaults. For troubleshooting, full customizations and further
    205. 

  205.           details, see the respective chapters in the BIND 10 guide.
    206. 

  206.         </p></div><p>
    207. 

  207.         To quickly get started with BIND 10, follow these steps.
    208. 

  208.       </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
    209. 

  209.             Install required run-time and build dependencies.
    210. 

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

  211.             Download the BIND 10 source tar file from
    212. 

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

  213.           </li><li class="listitem"><p>Extract the tar file:
    214. 

  214.           </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>
    215. 

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

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

  217.   $ <strong class="userinput"><code>./configure</code></strong></pre><p>
    218. 

  218.           </p></li><li class="listitem"><p>Build it:
    219. 

  219.             </p><pre class="screen">$ <strong class="userinput"><code>make</code></strong></pre><p>
    220. 

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

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

  222.           </p></li><li class="listitem"><p>Start the server:
    223. 

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

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

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

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

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

  228.           </p></li><li class="listitem">
    229. 

  229.             Test the new zone.
    230. 

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

  231.         BIND 10 is open source software written in C++ and Python.
    232. 

  232.         It is freely available in source code form from ISC via
    233. 

  233.         the Git code revision control system or as a downloadable
    234. 

  234.         tar file. It may also be available in pre-compiled ready-to-use
    235. 

  235.         packages from operating system vendors.
    236. 

  236.       </p><div class="section" title="2.3.1. Download Tar File"><div class="titlepage"><div><div><h3 class="title"><a name="idp128960"></a>2.3.1. Download Tar File</h3></div></div></div><p>
    237. 

  237.           Downloading a release tar file is the recommended method to
    238. 

  238.           obtain the source code.
    239. 

  239.         </p><p>
    240. 

  240.           The BIND 10 releases are available as tar file downloads from
    241. 

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

  242.           Periodic development snapshots may also be available.
    243. 

  243.         </p></div><div class="section" title="2.3.2. Retrieve from Git"><div class="titlepage"><div><div><h3 class="title"><a name="idp131696"></a>2.3.2. Retrieve from Git</h3></div></div></div><p>
    244. 

  244.           Downloading this "bleeding edge" code is recommended only for
    245. 

  245.           developers or advanced users.  Using development code in a production
    246. 

  246.           environment is not recommended.
    247. 

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

  248.             When using source code retrieved via Git additional
    249. 

  249.             software will be required:  automake (v1.11 or newer),
    250. 

  250.             libtoolize, and autoconf (2.59 or newer).
    251. 

  251.             These may need to be installed.
    252. 

  252.           </p></div><p>
    253. 

  253.           The latest development code, including temporary experiments
    254. 

  254.           and un-reviewed code, is available via the BIND 10 code revision
    255. 

  255.           control system. This is powered by Git and all the BIND 10
    256. 

  256.           development is public.
    257. 

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

  258.         </p><p>
    259. 

  259.           The code can be checked out from
    260. 

  260.           <code class="filename">git://git.bind10.isc.org/bind10</code>;
    261. 

  261.           for example:
    262. 

  262. 

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

  264.         </p><p>
    265. 

  265.           When checking out the code from
    266. 

  266.           the code version control system, it doesn't include the
    267. 

  267.           generated configure script, Makefile.in files, nor the
    268. 

  268.           related configure files.
    269. 

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

  270.           with the <code class="option">--install</code> switch.
    271. 

  271.           This will run <span class="command"><strong>autoconf</strong></span>,
    272. 

  272.           <span class="command"><strong>aclocal</strong></span>,
    273. 

  273.           <span class="command"><strong>libtoolize</strong></span>,
    274. 

  274.           <span class="command"><strong>autoheader</strong></span>,
    275. 

  275.           <span class="command"><strong>automake</strong></span>,
    276. 

  276.           and related commands.
    277. 

  277.         </p></div><div class="section" title="2.3.3. Configure before the build"><div class="titlepage"><div><div><h3 class="title"><a name="idp140672"></a>2.3.3. Configure before the build</h3></div></div></div><p>
    278. 

  278.           BIND 10 uses the GNU Build System to discover build environment
    279. 

  279.           details.
    280. 

  280.           To generate the makefiles using the defaults, simply run:
    281. 

  281.           </p><pre class="screen">$ <strong class="userinput"><code>./configure</code></strong></pre><p>
    282. 

  282.         </p><p>
    283. 

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

  284.           switch to view the different options. The commonly-used options are:
    285. 

  285. 

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

  287.                 default is <code class="filename">/usr/local/</code>).
    288. 

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

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

  290.                 standard execution path.
    291. 

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

  292.                 Google Tests framework. Optionally this can define the
    293. 

  293.                 path to the gtest header files and library.
    294. 

  294.               </dd></dl></div><p>
    295. 

  295. 

  296.         </p><p>
    297. 

  297.           For example, the following configures it to
    298. 

  298.     find the Boost headers, find the
    299. 

  299.     Python interpreter, and sets the installation location:
    300. 

  300. 

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

  302.       --with-boost-include=/usr/pkg/include \
    303. 

  303.       --with-pythonpath=/usr/pkg/bin/python3.1 \
    304. 

  304.       --prefix=/opt/bind10</code></strong></pre><p>
    305. 

  305.         </p><p>
    306. 

  306.           If the configure fails, it may be due to missing or old
    307. 

  307.           dependencies.
    308. 

  308.         </p></div><div class="section" title="2.3.4. Build"><div class="titlepage"><div><div><h3 class="title"><a name="idp154016"></a>2.3.4. Build</h3></div></div></div><p>
    309. 

  309.     After the configure step is complete, to build the executables
    310. 

  310.     from the C++ code and prepare the Python scripts, run:
    311. 

  311. 

  312.           </p><pre class="screen">$ <strong class="userinput"><code>make</code></strong></pre><p>
    313. 

  313.         </p></div><div class="section" title="2.3.5. Install"><div class="titlepage"><div><div><h3 class="title"><a name="idp156000"></a>2.3.5. Install</h3></div></div></div><p>
    314. 

  314.           To install the BIND 10 executables, support files,
    315. 

  315.           and documentation, run:
    316. 

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

  317.         </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 class="section" title="2.3.6. Install Hierarchy"><div class="titlepage"><div><div><h3 class="title"><a name="idp159168"></a>2.3.6. Install Hierarchy</h3></div></div></div><p>
    318. 

  318.           The following is the layout of the complete BIND 10 installation:
    319. 

  319.           </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
    320. 

  320.                 <code class="filename">bin/</code> &#8212;
    321. 

  321.                 general tools and diagnostic clients.
    322. 

  322.               </li><li class="listitem">
    323. 

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

  324.               configuration files.
    325. 

  325.             </li><li class="listitem">
    326. 

  326.                 <code class="filename">lib/</code> &#8212;
    327. 

  327.                 libraries and python modules.
    328. 

  328.               </li><li class="listitem">
    329. 

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

  330.                 executables that a user wouldn't normally run directly and
    331. 

  331.                 are not run independently.
    332. 

  332.                 These are the BIND 10 modules which are daemons started by
    333. 

  333.                 the <span class="command"><strong>bind10</strong></span> tool.
    334. 

  334.               </li><li class="listitem">
    335. 

  335.                 <code class="filename">sbin/</code> &#8212;
    336. 

  336.                 commands used by the system administrator.
    337. 

  337.               </li><li class="listitem">
    338. 

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

  339.                 configuration specifications.
    340. 

  340.               </li><li class="listitem">
    341. 

  341.                 <code class="filename">share/man/</code> &#8212;
    342. 

  342.                 manual pages (online documentation).
    343. 

  343.               </li><li class="listitem">
    344. 

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

  345.                 data source and configuration databases.
    346. 

  346.               </li></ul></div><p>
    347. 

  347.         </p></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 of started processes</a></span></dt></dl></div><p>
    348. 

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

  349.       starts up the required processes.
    350. 

  350.       <span class="command"><strong>bind10</strong></span>
    351. 

  351.       will also restart some processes that exit unexpectedly.
    352. 

  352.       This is the only command needed to start the BIND 10 system.
    353. 

  353.     </p><p>
    354. 

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

  355.       <span class="command"><strong>bind10</strong></span> connects to it,
    356. 

  356.       runs the configuration manager, and reads its own configuration.
    357. 

  357.       Then it starts the other modules.
    358. 

  358.     </p><p>
    359. 

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

  360.       <span class="command"><strong>b10-cfgmgr</strong></span>
    361. 

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

  362.       provides the communication channel between every part of the system.
    363. 

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

  364.       module, if only to send information about themselves somewhere,
    365. 

  365.       but more importantly to ask about their own settings, and
    366. 

  366.       about other modules. The <span class="command"><strong>b10-sockcreator</strong></span> will
    367. 

  367.       allocate sockets for the rest of the system.
    368. 

  368.     </p><p>
    369. 

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

  370.       master process will also start up
    371. 

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

  372.       communicate with the system, and
    373. 

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

  374.     </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>
    375. 

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

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

  377.         get additional debugging or diagnostic output.
    378. 

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

  379.           If the setproctitle Python module is detected at start up,
    380. 

  380.           the process names for the Python-based daemons will be renamed
    381. 

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

  382.           This is not needed on some operating systems.
    383. 

  383.         </p></div></div><div class="section" title="3.2. Configuration of started processes"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="bind10.config"></a>3.2. Configuration of started processes</h2></div></div></div><p>
    384. 

  384.         The processes to be started can be configured, with the exception
    385. 

  385.         of the <span class="command"><strong>b10-sockcreator</strong></span>, <span class="command"><strong>b10-msgq</strong></span>
    386. 

  386.         and <span class="command"><strong>b10-cfgmgr</strong></span>.
    387. 

  387.       </p><p>
    388. 

  388.         The configuration is in the Boss/components section. Each element
    389. 

  389.         represents one component, which is an abstraction of a process
    390. 

  390.         (currently there's also one component which doesn't represent
    391. 

  391.         a process).
    392. 

  392.       </p><p>
    393. 

  393.         To add a process to the set, let's say the resolver (which not started
    394. 

  394.         by default), you would do this:
    395. 

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

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

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

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

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

  400.         Now, what it means. We add an entry called b10-resolver. It is both a
    401. 

  401.         name used to reference this component in the configuration and the
    402. 

  402.         name of the process to start. Then we set some parameters on how to
    403. 

  403.         start it.
    404. 

  404.       </p><p>
    405. 

  405.         The special one is for components that need some kind of special care
    406. 

  406.         during startup or shutdown. Unless specified, the component is started
    407. 

  407.         in usual way. This is the list of components that need to be started
    408. 

  408.         in a special way, with the value of special used for them:
    409. 

  409.         </p><div class="table"><a name="idp193680"></a><p class="title"><b>Table 3.1. </b></p><div class="table-contents"><table border="1"><colgroup><col align="left" class="component"><col align="left" class="special"><col align="left" class="description"></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 server</td></tr><tr><td align="left">b10-resolver</td><td align="left">resolver</td><td align="left">The resolver</td></tr><tr><td align="left">b10-cmdctl</td><td align="left">cmdctl</td><td align="left">The command control (remote control interface)</td></tr></tbody></table></div></div><p><br class="table-break">
    410. 

  410.       </p><p>
    411. 

  411.         The kind specifies how a failure of the component should
    412. 

  412.         be handled.  If it is set to <span class="quote">&#8220;<span class="quote">dispensable</span>&#8221;</span>
    413. 

  413.         (the default unless you set something else), it will get
    414. 

  414.         started again if it fails. If it is set to <span class="quote">&#8220;<span class="quote">needed</span>&#8221;</span>
    415. 

  415.         and it fails at startup, the whole <span class="command"><strong>bind10</strong></span>
    416. 

  416.         shuts down and exits with error exit code. But if it fails
    417. 

  417.         some time later, it is just started again. If you set it
    418. 

  418.         to <span class="quote">&#8220;<span class="quote">core</span>&#8221;</span>, you indicate that the system is
    419. 

  419.         not usable without the component and if such component
    420. 

  420.         fails, the system shuts down no matter when the failure
    421. 

  421.         happened.  This is the behaviour of the core components
    422. 

  422.         (the ones you can't turn off), but you can declare any
    423. 

  423.         other components as core as well if you wish (but you can
    424. 

  424.         turn these off, they just can't fail).
    425. 

  425.       </p><p>
    426. 

  426.         The priority defines order in which the components should start.
    427. 

  427.         The ones with higher number are started sooner than the ones with
    428. 

  428.         lower ones. If you don't set it, 0 (zero) is used as the priority.
    429. 

  429.         Usually, leaving it at the default is enough.
    430. 

  430.       </p><p>
    431. 

  431.         There are other parameters we didn't use in our example.
    432. 

  432.         One of them is <span class="quote">&#8220;<span class="quote">address</span>&#8221;</span>. It is the address
    433. 

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

  434.         message bus. The special components already know their
    435. 

  435.         address, but the usual ones don't. The address is by
    436. 

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

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

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

  439. 

  440.       </p><p>
    441. 

  441.         The last one is process. It is the name of the process to be started.
    442. 

  442.         It defaults to the name of the component if not set, but you can use
    443. 

  443.         this to override it.
    444. 

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

  445.           This system allows you to start the same component multiple times
    446. 

  446.           (by including it in the configuration with different names, but the
    447. 

  447.           same process setting). However, the rest of the system doesn't expect
    448. 

  448.           such a situation, so it would probably not do what you want. Such
    449. 

  449.           support is yet to be implemented.
    450. 

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

  451.           The configuration is quite powerful, but that includes
    452. 

  452.           a lot of space for mistakes. You could turn off the
    453. 

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

  454.           change it back the usual way, as it would require it to
    455. 

  455.           be running (you would have to find and edit the configuration
    456. 

  456.           directly).  Also, some modules might have dependencies:
    457. 

  457.           <span class="command"><strong>b10-stats-httpd</strong></span> needs
    458. 

  458.           <span class="command"><strong>b10-stats</strong></span>, <span class="command"><strong>b10-xfrout</strong></span>
    459. 

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

  460. 

  461. 

  462. 

  463.         </p><p>
    464. 

  464.           In short, you should think twice before disabling something here.
    465. 

  465.         </p></div><p>
    466. 

  466.         It is possible to start some components multiple times (currently
    467. 

  467.         <span class="command"><strong>b10-auth</strong></span> and <span class="command"><strong>b10-resolzer</strong></span>).
    468. 

  468.         You might want to do that to gain more performance (each one uses only
    469. 

  469.         single core). Just put multiple entries under different names, like
    470. 

  470.         this, with the same config:
    471. 

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

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

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

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

  475.       </p><p>
    476. 

  476.         However, this is work in progress and the support is not yet complete.
    477. 

  477.         For example, each resolver will have its own cache, each authoritative
    478. 

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

  479.         problems with locking the sqlite database, if used. The configuration
    480. 

  480.         might be changed to something more convenient in future.
    481. 

  481.       </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>
    482. 

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

  483.         message routing daemon to communicate with other BIND 10 components.
    484. 

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

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

  486.         Processes intercommunicate by sending messages on the command
    487. 

  487.         channel.
    488. 

  488.         Example messages include shutdown, get configurations, and set
    489. 

  489.         configurations.
    490. 

  490.         This Command Channel is not used for DNS message passing.
    491. 

  491.         It is used only to control and monitor the BIND 10 system.
    492. 

  492.       </p><p>
    493. 

  493.         Administrators do not communicate directly with the
    494. 

  494.         <span class="command"><strong>b10-msgq</strong></span> daemon.
    495. 

  495.         By default, BIND 10 uses port 9912 for the
    496. 

  496.         <span class="command"><strong>b10-msgq</strong></span> service.
    497. 

  497.         It listens on 127.0.0.1.
    498. 

  498.       </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>
    499. 

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

  500.          handles all BIND 10 system configuration.  It provides
    501. 

  501.          persistent storage for configuration, and notifies running
    502. 

  502.          modules of configuration changes.
    503. 

  503.       </p><p>
    504. 

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

  505.         daemons and other components receive their configurations
    506. 

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

  507.         command channel.
    508. 

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

  509.         uses a user interface to communicate with the configuration
    510. 

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

  511.         <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>.
    512. 

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

  513.           The development prototype release only provides
    514. 

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

  515.           <span class="command"><strong>b10-cmdctl</strong></span>.
    516. 

  516.           Upcoming releases will provide another interactive command-line
    517. 

  517.           interface and a web-based interface.
    518. 

  518.         </p></div><p>
    519. 

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

  520.         specifications and all current settings to the
    521. 

  521.         <span class="command"><strong>bindctl</strong></span> client (via
    522. 

  522.         <span class="command"><strong>b10-cmdctl</strong></span>).
    523. 

  523.       </p><p>
    524. 

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

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

  526.       </p><p>
    527. 

  527.         The stored configuration file is at
    528. 

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

  529.         (The full path is what was defined at build configure time for
    530. 

  530.         <code class="option">--localstatedir</code>.
    531. 

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

  532.         The format is loosely based on JSON and is directly parseable
    533. 

  533.         python, but this may change in a future version.
    534. 

  534.         This configuration data file is not manually edited by the
    535. 

  535.         administrator.
    536. 

  536.       </p><p>
    537. 

  537.       The configuration manager does not have any command line arguments.
    538. 

  538.       Normally it is not started manually, but is automatically
    539. 

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

  540.       (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>).
    541. 

  541.     </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>
    542. 

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

  543.       administrators and the BIND 10 system.
    544. 

  544.       It is a HTTPS server that uses standard HTTP Digest
    545. 

  545.       Authentication for username and password validation.
    546. 

  546.       It provides a REST-ful interface for accessing and controlling
    547. 

  547.       BIND 10.
    548. 

  548.     </p><p>
    549. 

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

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

  551.       running and what their configuration is (over the
    552. 

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

  553.       on HTTPS for clients &#8212; the user interface &#8212; such
    554. 

  554.       as <span class="command"><strong>bindctl</strong></span>.
    555. 

  555.     </p><p>
    556. 

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

  557.       (received from the user interface) to the specified component.
    558. 

  558.       Configuration changes are actually commands to
    559. 

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

  560.     </p><p>The HTTPS server requires a private key,
    561. 

  561.       such as a RSA PRIVATE KEY.
    562. 

  562.       The default location is at
    563. 

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

  564.       (A sample key is at
    565. 

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

  566.       It also uses a certificate located at
    567. 

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

  568.       (A sample certificate is at
    569. 

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

  570.       This may be a self-signed certificate or purchased from a
    571. 

  571.       certification authority.
    572. 

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

  573.       The HTTPS server doesn't support a certificate request from a
    574. 

  574.       client (at this time).
    575. 

  575. 

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

  577.       public service. If any client wants to control BIND 10, then
    578. 

  578.       a certificate needs to be first received from the BIND 10
    579. 

  579.       administrator.
    580. 

  580.       The BIND 10 installation provides a sample PEM bundle that matches
    581. 

  581.       the sample key and certificate.
    582. 

  582.     </p></div><p>
    583. 

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

  584.       the user account file located at
    585. 

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

  586.       This comma-delimited file lists the accounts with a user name,
    587. 

  587.       hashed password, and salt.
    588. 

  588.       (A sample file is at
    589. 

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

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

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

  592.     </p><p>
    593. 

  593.       The administrator may create a user account with the
    594. 

  594.       <span class="command"><strong>b10-cmdctl-usermgr</strong></span> tool.
    595. 

  595.     </p><p>
    596. 

  596.       By default the HTTPS server listens on the localhost port 8080.
    597. 

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

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

  599.       line argument.
    600. 

  600.       Each HTTPS connection is stateless and times out in 1200 seconds
    601. 

  601.       by default.  This can be
    602. 

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

  603.     </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>
    604. 

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

  605. key_file
    606. 

  606. cert_file
    607. 

  607. accounts_file
    608. 

  608.       </p><p>
    609. 

  609.         The control commands are:
    610. 

  610. print_settings
    611. 

  611. 

  612. 

  613. shutdown
    614. 

  614.       </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>
    615. 

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

  616.       is the only user interface. It is expected that upcoming
    617. 

  617.       releases will provide another interactive command-line
    618. 

  618.       interface and a web-based interface for controlling and
    619. 

  619.       configuring BIND 10.
    620. 

  620.     </p></div><p>
    621. 

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

  622.       prompt for configuring, controlling, and querying the BIND 10
    623. 

  623.       components.
    624. 

  624.       It communicates directly with a REST-ful interface over HTTPS
    625. 

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

  626.       communicate to any other components directly.
    627. 

  627.     </p><p>
    628. 

  628.       Configuration changes are actually commands to
    629. 

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

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

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

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

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

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

  635.       channel) the configuration on to the specified module.
    636. 

  636.     </p><p>
    637. 

  637.     </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="#idp280304">8.1. Server Configurations</a></span></dt><dt><span class="section"><a href="#idp323936">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="#idp357152">8.3. Loading Master Zones Files</a></span></dt></dl></div><p>
    638. 

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

  639.       It supports EDNS0 and DNSSEC. It supports IPv6.
    640. 

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

  641.       process.
    642. 

  642.     </p><div class="section" title="8.1. Server Configurations"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp280304"></a>8.1. Server Configurations</h2></div></div></div><p>
    643. 

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

  644.         <span class="command"><strong>b10-cfgmgr</strong></span> configuration manager.
    645. 

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

  646.         The configuration data items are:
    647. 

  647. 

  648.         </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
    649. 

  649.                  the SQLite3 database file.
    650. 

  650. 

  651. Note: Later the DNS server will use various data source backends.
    652. 

  652. This may be a temporary setting until then.
    653. 

  653.               </dd><dt><span class="term">datasources</span></dt><dd>
    654. 

  654.       <code class="varname">datasources</code> configures data sources.
    655. 

  655.       The list items include:
    656. 

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

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

  658.       <code class="varname">class</code> to optionally select the class
    659. 

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

  660.       and
    661. 

  661.       <code class="varname">zones</code> to define
    662. 

  662.       the <code class="varname">file</code> path name,
    663. 

  663.       the <code class="varname">filetype</code> (e.g., <code class="varname">sqlite3</code>),
    664. 

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

  665. 

  666.       By default, this is empty.
    667. 

  667. 

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

  669.         In this development version, currently this is only used for the
    670. 

  670.         memory data source.
    671. 

  671.         Only the IN class is supported at this time.
    672. 

  672.         By default, the memory data source is disabled.
    673. 

  673.         Also, currently the zone file must be canonical such as
    674. 

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

  675.         must be an SQLite3 database.
    676. 

  676.       </p></div>
    677. 

  677. 

  678.               </dd><dt><span class="term">listen_on</span></dt><dd>
    679. 

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

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

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

  682.       and <code class="varname">port</code> number.
    683. 

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

  684.       on the IPv6 (::) and IPv4 (0.0.0.0) wildcard addresses.
    685. 

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

  686.           The default configuration is currently not appropriate for a multi-homed host.
    687. 

  687.           In case you have multiple public IP addresses, it is possible the
    688. 

  688.           query UDP packet comes through one interface and the answer goes out
    689. 

  689.           through another. The answer will probably be dropped by the client, as it
    690. 

  690.           has a different source address than the one it sent the query to. The
    691. 

  691.           client would fallback on TCP after several attempts, which works
    692. 

  692.           well in this situation, but is clearly not ideal.
    693. 

  693.         </p><p>
    694. 

  694.           There are plans to solve the problem such that the server handles
    695. 

  695.           it by itself. But until it is actually implemented, it is recommended to
    696. 

  696.           alter the configuration &#8212; remove the wildcard addresses and list all
    697. 

  697.           addresses explicitly. Then the server will answer on the same
    698. 

  698.           interface the request came on, preserving the correct address.
    699. 

  699.         </p></div>
    700. 

  700.               </dd><dt><span class="term">statistics-interval</span></dt><dd>
    701. 

  701.       <code class="varname">statistics-interval</code> is the timer interval
    702. 

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

  703.       statistics information to
    704. 

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

  705.       Statistics updates can be disabled by setting this to 0.
    706. 

  706.       The default is 60.
    707. 

  707.               </dd></dl></div><p>
    708. 

  708. 

  709.       </p><p>
    710. 

  710. 

  711.         The configuration commands are:
    712. 

  712. 

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

  714.       <span class="command"><strong>loadzone</strong></span> tells <span class="command"><strong>b10-auth</strong></span>
    715. 

  715.       to load or reload a zone file. The arguments include:
    716. 

  716.       <code class="varname">class</code> which optionally defines the class
    717. 

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

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

  719.       and
    720. 

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

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

  722. 

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

  724.         In this development version, currently this only supports the
    725. 

  725.         IN class and the memory data source.
    726. 

  726.       </p></div>
    727. 

  727.               </dd><dt><span class="term">sendstats</span></dt><dd>
    728. 

  728.       <span class="command"><strong>sendstats</strong></span> tells <span class="command"><strong>b10-auth</strong></span>
    729. 

  729.       to send its statistics data to
    730. 

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

  731.       immediately.
    732. 

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

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

  734.       select the process ID to stop.
    735. 

  735.       (Note that the BIND 10 boss process may restart this service
    736. 

  736.       if configured.)
    737. 

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

  738. 

  739.       </p></div><div class="section" title="8.2. Data Source Backends"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp323936"></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>
    740. 

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

  741.         supports a SQLite3 data source backend and in-memory data source
    742. 

  742.         backend.
    743. 

  743.         Upcoming versions will be able to use multiple different
    744. 

  744.         data sources, such as MySQL and Berkeley DB.
    745. 

  745.       </p></div><p>
    746. 

  746.         By default, the SQLite3 backend uses the data file located at
    747. 

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

  748.         (The full path is what was defined at build configure time for
    749. 

  749.         <code class="option">--localstatedir</code>.
    750. 

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

  751. 	This data file location may be changed by defining the
    752. 

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

  753.       </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>
    754. 

  754. 

  755. 	  The following commands to <span class="command"><strong>bindctl</strong></span>
    756. 

  756. 	  provide an example of configuring an in-memory data
    757. 

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

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

  759. 

  760. 

  761. 

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

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

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

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

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

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

  768. 

  769. 	  The authoritative server will begin serving it immediately
    770. 

  770. 	  after it is loaded.
    771. 

  771. 	</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>
    772. 

  772. 

  773. 	  The following commands to <span class="command"><strong>bindctl</strong></span>
    774. 

  774. 	  provide an example of configuring an in-memory data
    775. 

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

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

  777. 

  778. 

  779. 

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

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

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

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

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

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

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

  787. 

  788. 	  The authoritative server will begin serving it immediately
    789. 

  789. 	  after it is loaded.
    790. 

  790. 	</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>
    791. 

  791. 	  Use the <span class="command"><strong>Auth loadzone</strong></span> command in
    792. 

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

  793. 	  file into memory; for example:
    794. 

  794. 

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

  796. </pre><p>
    797. 

  797. 

  798. 	</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>
    799. 

  799. 	By default, the memory data source is disabled; it must be
    800. 

  800. 	configured explicitly.  To disable all the in-memory zones,
    801. 

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

  802. 

  803. 

  804. 

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

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

  807. 	</p><p>
    808. 

  808.           The following example stops serving a specific zone:
    809. 

  809. 

  810. 	  </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>
    811. 

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

  812. 

  813. 	  (Replace the list number(s) in
    814. 

  814. 	  <code class="varname">datasources[<em class="replaceable"><code>0</code></em>]</code>
    815. 

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

  816. 	  for the relevant zone as needed.)
    817. 

  817. 

  818. 	</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="idp357152"></a>8.3. Loading Master Zones Files</h2></div></div></div><p>
    819. 

  819.         RFC 1035 style DNS master zone files may imported
    820. 

  820.         into a BIND 10 SQLite3 data source by using the
    821. 

  821.         <span class="command"><strong>b10-loadzone</strong></span> utility.
    822. 

  822.       </p><p>
    823. 

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

  824.         special directives (control entries):
    825. 

  825. 

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

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

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

  829.                 records that don't include a TTL.
    830. 

  830.               </dd></dl></div><p>
    831. 

  831. 

  832.       </p><p>
    833. 

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

  834.         default origin for loaded zone file records.
    835. 

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

  836.         In the development prototype release, only the SQLite3 back
    837. 

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

  838.         By default, it stores the zone data in
    839. 

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

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

  841.         database filename.
    842. 

  842.         Multiple zones are stored in a single SQLite3 zone database.
    843. 

  843.       </p></div><p>
    844. 

  844.         If you reload a zone already existing in the database,
    845. 

  845.         all records from that prior zone disappear and a whole new set
    846. 

  846.         appears.
    847. 

  847.       </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="#idp375360">9.1. Configuration for Incoming Zone Transfers</a></span></dt><dt><span class="section"><a href="#idp380704">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="#idp397792">9.4. Trigger an Incoming Zone Transfer Manually</a></span></dt><dt><span class="section"><a href="#idp401488">9.5. Incoming Transfers with In-memory Datasource</a></span></dt></dl></div><p>
    848. 

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

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

  850.       When received, the zone is stored in the corresponding BIND 10
    851. 

  851.       data source, and its records can be served by
    852. 

  852.       <span class="command"><strong>b10-auth</strong></span>.
    853. 

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

  854.       automated SOA checks), this allows the BIND 10 server to
    855. 

  855.       provide <span class="quote">&#8220;<span class="quote">secondary</span>&#8221;</span> service.
    856. 

  856.     </p><p>
    857. 

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

  858.       IXFR.  Due to some implementation limitations of the current
    859. 

  859.       development release, however, it only tries AXFR by default,
    860. 

  860.       and care should be taken to enable IXFR.
    861. 

  861.     </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="idp375360"></a>9.1. Configuration for Incoming Zone Transfers</h2></div></div></div><p>
    862. 

  862.         In practice, you need to specify a list of secondary zones to
    863. 

  863.         enable incoming zone transfers for these zones (you can still
    864. 

  864.         trigger a zone transfer manually, without a prior configuration
    865. 

  865.         (see below)).
    866. 

  866.       </p><p>
    867. 

  867.         For example, to enable zone transfers for a zone named "example.com"
    868. 

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

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

  870. 

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

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

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

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

  875. 

  876.       (We assume there has been no zone configuration before).
    877. 

  877.       </p></div><div class="section" title="9.2. Enabling IXFR"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp380704"></a>9.2. Enabling IXFR</h2></div></div></div><p>
    878. 

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

  879.         zone transfers by default.  To enable IXFR for zone transfers
    880. 

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

  881.         configuration parameter to <strong class="userinput"><code>true</code></strong>.
    882. 

  882.         In the above example of configuration sequence, you'll need
    883. 

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

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

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

  886.       One reason why IXFR is disabled by default in the current
    887. 

  887.       release is because it does not support automatic fallback from IXFR to
    888. 

  888.       AXFR when it encounters a primary server that doesn't support
    889. 

  889.       outbound IXFR (and, not many existing implementations support
    890. 

  890.       it).  Another, related reason is that it does not use AXFR even
    891. 

  891.       if it has no knowledge about the zone (like at the very first
    892. 

  892.       time the secondary server is set up).  IXFR requires the
    893. 

  893.       "current version" of the zone, so obviously it doesn't work
    894. 

  894.       in this situation and AXFR is the only workable choice.
    895. 

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

  896.       make this selection automatically.
    897. 

  897.       These features will be implemented in a near future
    898. 

  898.       version, at which point we will enable IXFR by default.
    899. 

  899.       </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>
    900. 

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

  901.         <span class="command"><strong>bind10</strong></span>.
    902. 

  902.         It keeps track of SOA refresh, retry, and expire timers
    903. 

  903.         and other details for BIND 10 to perform as a slave.
    904. 

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

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

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

  907.         to start an inbound zone transfer.
    908. 

  908.         The secondary manager resets its counters when a new zone is
    909. 

  909.         transferred in.
    910. 

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

  911.         Access control (such as allowing notifies) is not yet provided.
    912. 

  912.         The primary/secondary service is not yet complete.
    913. 

  913.       </p></div><p>
    914. 

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

  915.         to configure the server to be a secondary for the example zone:
    916. 

  916. 

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

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

  919. &gt; <strong class="userinput"><code>config set Zonemgr/secondary_zones[0]/class "<code class="option">IN</code>"</code></strong>
    920. 

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

  921. 

  922. 

  923. 

  924.       </p><p>
    925. 

  925.         If the zone does not exist in the data source already
    926. 

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

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

  928.         to transfer the zone in.
    929. 

  929.       </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="idp397792"></a>9.4. Trigger an Incoming Zone Transfer Manually</h2></div></div></div><p>
    930. 

  930.         To manually trigger a zone transfer to retrieve a remote zone,
    931. 

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

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

  933. 

  934.         </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>
    935. 

  935.       </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="idp401488"></a>9.5. Incoming Transfers with In-memory Datasource</h2></div></div></div><p>
    936. 

  936.         In the case of an incoming zone transfer, the received zone is
    937. 

  937.         first stored in the corresponding BIND 10 datasource. In
    938. 

  938.         case the secondary zone is served by an in-memory datasource
    939. 

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

  940.         automatically sent a <code class="varname">loadzone</code> command to
    941. 

  941.         reload the corresponding zone into memory from the backend.
    942. 

  942.       </p><p>
    943. 

  943. 	The administrator doesn't have to do anything for
    944. 

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

  945. 	zone, except for the configuration such as the one described in
    946. 

  946. 	<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>.
    947. 

  947.       </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>
    948. 

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

  949.       <span class="command"><strong>bind10</strong></span>.
    950. 

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

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

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

  953.       which handles the rest of request processing.
    954. 

  954.       This is used to provide primary DNS service to share zones
    955. 

  955.       to secondary name servers.
    956. 

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

  957.       NOTIFY messages to secondary servers.
    958. 

  958.     </p><p>
    959. 

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

  960.       can be used to control accessibility of the outbound zone
    961. 

  961.       transfer service.
    962. 

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

  963.       perform zone transfers for any zones:
    964. 

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

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

  966.       You can change this to, for example, rejecting all transfer
    967. 

  967.       requests by default while allowing requests for the transfer
    968. 

  968.       of zone "example.com" from 192.0.2.1 and 2001:db8::1 as follows:
    969. 

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

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

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

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

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

  974. &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>
    975. 

  975.         In the above example the lines
    976. 

  976.         for <code class="option">transfer_acl</code> were divided for
    977. 

  977.         readability.  In the actual input it must be in a single line.
    978. 

  978.     </p></div><p>
    979. 

  979.       If you want to require TSIG in access control, a system wide TSIG
    980. 

  980.       "key ring" must be configured.
    981. 

  981.       For example, to change the previous example to allowing requests
    982. 

  982.       from 192.0.2.1 signed by a TSIG with a key name of
    983. 

  983.       "key.example", you'll need to do this:
    984. 

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

  985. &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>
    986. 

  986. &gt; <strong class="userinput"><code>config commit</code></strong></pre><p>Both Xfrout and Auth will use the system wide keyring to check
    987. 

  987.     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>
    988. 

  988.         The way to specify zone specific configuration (ACLs, etc) is
    989. 

  989.         likely to be changed.
    990. 

  990.     </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="#idp433840">11.1. Enabling Dynamic Update</a></span></dt><dt><span class="section"><a href="#idp448128">11.2. Access Control</a></span></dt><dt><span class="section"><a href="#idp471872">11.3. Miscellaneous Operational Issues</a></span></dt></dl></div><p>
    991. 

  991.       BIND 10 supports the server side of the Dynamic DNS Update
    992. 

  992.       (DDNS) protocol as defined in RFC 2136.
    993. 

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

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

  995.       process if configured so.
    996. 

  996.     </p><p>
    997. 

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

  998.       receives an UPDATE request, it internally forwards the request
    999. 

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

  1000.       request processing.
    1001. 

  1001.       When the processing is completed <span class="command"><strong>b10-ddns</strong></span>
    1002. 

  1002.       will send a response to the client with the RCODE set to the
    1003. 

  1003.       value as specified in RFC 2136 (NOERROR for successful update,
    1004. 

  1004.       REFUSED if rejected due to ACL check, etc).
    1005. 

  1005.       If the zone has been changed as a result, it will internally
    1006. 

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

  1007.       servers will be notified via the DNS notify protocol.
    1008. 

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

  1009.       zone from its in-memory cache (as described in
    1010. 

  1010.       <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>),
    1011. 

  1011.       <span class="command"><strong>b10-ddns</strong></span> will also
    1012. 

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

  1013.       will re-cache the updated zone content.
    1014. 

  1014.     </p><p>
    1015. 

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

  1016.       both UDP and TCP, and both IPv6 and IPv4; for TCP requests,
    1017. 

  1017.       however, it terminates the TCP connection immediately after
    1018. 

  1018.       each single request has been processed.  Clients cannot reuse the
    1019. 

  1019.       same TCP connection for multiple requests. (This is a current
    1020. 

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

  1021.       While RFC 2136 doesn't specify anything about such reuse of TCP
    1022. 

  1022.       connection, there is no reason for disallowing it as RFC 1035
    1023. 

  1023.       generally allows multiple requests sent over a single TCP
    1024. 

  1024.       connection.  BIND 9 supports such reuse.)
    1025. 

  1025.     </p><p>
    1026. 

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

  1027.       update forwarding for secondary zones.
    1028. 

  1028.       If it receives an update request for a secondary zone, it will
    1029. 

  1029.       immediately return a response with an RCODE of NOTIMP.
    1030. 

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

  1031. 	  For feature completeness update forwarding should be
    1032. 

  1032. 	  eventually supported.  But right now it's considered a lower
    1033. 

  1033. 	  priority task and there is no specific plan of implementing
    1034. 

  1034. 	  this feature.
    1035. 

  1035. 

  1036.       </p></div><p>
    1037. 

  1037.     </p><div class="section" title="11.1. Enabling Dynamic Update"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp433840"></a>11.1. Enabling Dynamic Update</h2></div></div></div><p>
    1038. 

  1038.         First off, it must be made sure that a few components on which
    1039. 

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

  1040.         which are <span class="command"><strong>b10-auth</strong></span>
    1041. 

  1041.         and <span class="command"><strong>b10-zonemgr</strong></span>.
    1042. 

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

  1043.         configured to run; otherwise the notification after an update
    1044. 

  1044.         (see above) will fail with a timeout, suspending the DDNS
    1045. 

  1045.         service while <span class="command"><strong>b10-ddns</strong></span> waits for the
    1046. 

  1046.         response (see the description of the <a class="ulink" href="bind10-messages.html#DDNS_UPDATE_NOTIFY_FAIL" target="_top">DDNS_UPDATE_NOTIFY_FAIL</a>
    1047. 

  1047.         log message for further details).
    1048. 

  1048.         If BIND 10 is already configured to provide authoritative DNS
    1049. 

  1049.         service they should normally be configured to run already.
    1050. 

  1050.       </p><p>
    1051. 

  1051.         Second, for the obvious reason dynamic update requires that the
    1052. 

  1052.         underlying data source storing the zone data be writable.
    1053. 

  1053.         In the current implementation this means the zone must be stored
    1054. 

  1054.         in an SQLite3-based data source.
    1055. 

  1055.         Also, right now, the <span class="command"><strong>b10-ddns</strong></span> component
    1056. 

  1056.         configures itself with the data source referring to the
    1057. 

  1057.         <span class="quote">&#8220;<span class="quote">database_file</span>&#8221;</span> configuration parameter of
    1058. 

  1058.         <span class="command"><strong>b10-auth</strong></span>.
    1059. 

  1059.         So this information must be configured correctly before starting
    1060. 

  1060.         <span class="command"><strong>b10-ddns</strong></span>.
    1061. 

  1061. 

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

  1063.             The way to configure data sources is now being revised.
    1064. 

  1064.             Configuration on the data source for DDNS will be very
    1065. 

  1065.             likely to be changed in a backward incompatible manner in
    1066. 

  1066.             a near future version.
    1067. 

  1067.         </p></div><p>
    1068. 

  1068.       </p><p>
    1069. 

  1069. 	In general, if something goes wrong regarding the dependency
    1070. 

  1070. 	described above, <span class="command"><strong>b10-ddns</strong></span> will log the
    1071. 

  1071. 	related event at the warning or error level.
    1072. 

  1072. 	It's advisable to check the log message when you first enable
    1073. 

  1073. 	DDNS or if it doesn't work as you expect to see if there's any
    1074. 

  1074. 	warning or error log message.
    1075. 

  1075.       </p><p>
    1076. 

  1076.         Next, to enable the DDNS service, <span class="command"><strong>b10-ddns</strong></span>
    1077. 

  1077.         needs to be explicitly configured to run.
    1078. 

  1078.         It can be done by using the <span class="command"><strong>bindctl</strong></span>
    1079. 

  1079.         utility.  For example:
    1080. 

  1080.       </p><pre class="screen">
    1081. 

  1081. &gt; <strong class="userinput"><code>config add Boss/components b10-ddns</code></strong>
    1082. 

  1082. &gt; <strong class="userinput"><code>config set Boss/components/b10-ddns/address DDNS</code></strong>
    1083. 

  1083. &gt; <strong class="userinput"><code>config set Boss/components/b10-ddns/kind dispensable</code></strong>
    1084. 

  1084. &gt; <strong class="userinput"><code>config commit</code></strong>
    1085. 

  1085. </pre><p>
    1086. 

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

  1087. 	  In theory "kind" could be omitted because "dispensable" is its
    1088. 

  1088. 	  default.  But there's some peculiar behavior (which should
    1089. 

  1089. 	  be a bug and should be fixed eventually; see Trac ticket
    1090. 

  1090. 	  #2064) with bindctl and you'll still need to specify that explicitly.
    1091. 

  1091. 	  Likewise, "address" may look unnecessary because
    1092. 

  1092. 	  <span class="command"><strong>b10-ddns</strong></span> would start and work without
    1093. 

  1093. 	  specifying it.  But for it to shutdown gracefully this
    1094. 

  1094. 	  parameter should also be specified.
    1095. 

  1095.       </p></div><p>
    1096. 

  1096.       </p></div><div class="section" title="11.2. Access Control"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp448128"></a>11.2. Access Control</h2></div></div></div><p>
    1097. 

  1097.         By default <span class="command"><strong>b10-ddns</strong></span> rejects any update
    1098. 

  1098.         requests from any clients by returning a response with an RCODE
    1099. 

  1099.         of REFUSED.
    1100. 

  1100.         To allow updates to take effect, an access control rule
    1101. 

  1101.         (called update ACL) with a policy allowing updates must explicitly be
    1102. 

  1102.         configured.
    1103. 

  1103.         Update ACL must be configured per zone basis in the
    1104. 

  1104.         <span class="quote">&#8220;<span class="quote">zones</span>&#8221;</span> configuration parameter of
    1105. 

  1105.         <span class="command"><strong>b10-ddns</strong></span>.
    1106. 

  1106.         This is a list of per-zone configurations regarding DDNS.
    1107. 

  1107.         Each list element consists of the following parameters:
    1108. 

  1108.         </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
    1109. 

  1109.                 (normally <span class="quote">&#8220;<span class="quote">IN</span>&#8221;</span>, and in that case
    1110. 

  1110. 		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>
    1111. 

  1111.         The syntax of the ACL is the same as ACLs for other
    1112. 

  1112.         components.
    1113. 

  1113.         Specific examples are given below.
    1114. 

  1114.       </p><p>
    1115. 

  1115.         In general, an update ACL rule that allows an update request
    1116. 

  1116.         should be configured with a TSIG key.
    1117. 

  1117.         This is an example update ACL that allows updates to the zone
    1118. 

  1118.         named <span class="quote">&#8220;<span class="quote">example.org</span>&#8221;</span> of RR class <span class="quote">&#8220;<span class="quote">IN</span>&#8221;</span>
    1119. 

  1119.         from clients that send requests signed with a TSIG whose
    1120. 

  1120.         key name is "key.example.org" (and refuses all others):
    1121. 

  1121.       </p><pre class="screen">
    1122. 

  1122. &gt; <strong class="userinput"><code>config add DDNS/zones</code></strong>
    1123. 

  1123. &gt; <strong class="userinput"><code>config set DDNS/zones[0]/origin example.org</code></strong>
    1124. 

  1124. &gt; <strong class="userinput"><code>config set DDNS/zones[0]/class IN</code></strong>
    1125. 

  1125. (Note: "class" can be omitted)
    1126. 

  1126. &gt; <strong class="userinput"><code>config add DDNS/zones[0]/update_acl {"action": "ACCEPT", "key": "key.example.org"}</code></strong>
    1127. 

  1127. &gt; <strong class="userinput"><code>config commit</code></strong>
    1128. 

  1128. </pre><p>
    1129. 

  1129.       The TSIG key must be configured system wide
    1130. 

  1130.       (see <a class="xref" href="#xfrout" title="Chapter 10. Outbound Zone Transfers">Chapter 10, <i>Outbound Zone Transfers</i></a>.)
    1131. 

  1131.       </p><p>
    1132. 

  1132.         Multiple rules can be specified in the ACL, and an ACL rule
    1133. 

  1133.         can consist of multiple constraints, such as a combination of
    1134. 

  1134.         IP address and TSIG.
    1135. 

  1135.         The following configuration sequence will add a new rule to
    1136. 

  1136.         the ACL created in the above example.  This additional rule
    1137. 

  1137. 	allows update requests sent from a client
    1138. 

  1138.         using TSIG key name of "key.example" (different from the
    1139. 

  1139.         key used in the previous example) and has an IPv6 address of ::1.
    1140. 

  1140.       </p><pre class="screen">
    1141. 

  1141. &gt; <strong class="userinput"><code>config add DDNS/zones[0]/update_acl {"action": "ACCEPT", "from": "::1", "key": "key.example"}</code></strong>
    1142. 

  1142. &gt; <strong class="userinput"><code>config show DDNS/zones[0]/update_acl</code></strong>
    1143. 

  1143. DDNS/zones[0]/update_acl[0]     {"action": "ACCEPT", "key": "key.example.org"} any (modified)
    1144. 

  1144. DDNS/zones[0]/update_acl[1]     {"action": "ACCEPT", "from": "::1", "key": "key.example"} any (modified)
    1145. 

  1145. &gt; <strong class="userinput"><code>config commit</code></strong>
    1146. 

  1146. </pre><p>
    1147. 

  1147.       (Note the "add" in the first line.  Before this sequence, we
    1148. 

  1148.       have had only entry in zones[0]/update_acl.  The "add" command
    1149. 

  1149.       with a value (rule) adds a new entry and sets it to the given rule.
    1150. 

  1150.       Due to a limitation of the current implementation, it doesn't
    1151. 

  1151.       work if you first try to just add a new entry and then set it to
    1152. 

  1152.       a given rule).
    1153. 

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

  1154.           The <span class="command"><strong>b10-ddns</strong></span> component accepts an ACL
    1155. 

  1155.           rule that just allows updates from a specific IP address
    1156. 

  1156.           (i.e., without requiring TSIG), but this is highly
    1157. 

  1157.           discouraged (remember that requests can be made over UDP and
    1158. 

  1158.           spoofing the source address of a UDP packet is often pretty
    1159. 

  1159.           easy).
    1160. 

  1160.           Unless you know what you are doing and that you can accept
    1161. 

  1161.           its consequence, any update ACL rule that allows updates
    1162. 

  1162.           should have a TSIG key in its constraints.
    1163. 

  1163.       </p></div><p>
    1164. 

  1164. 	The ACL rules will be checked in the listed order, and the
    1165. 

  1165. 	first matching one will apply.
    1166. 

  1166. 	If none of the rules matches, the default rule will apply,
    1167. 

  1167. 	which is rejecting any requests in the case of
    1168. 

  1168. 	<span class="command"><strong>b10-ddns</strong></span>.
    1169. 

  1169.       </p><p>
    1170. 

  1170. 	Other actions than "ACCEPT", namely "REJECT" and "DROP", can be
    1171. 

  1171. 	used, too.
    1172. 

  1172. 	See <a class="xref" href="#resolverserver" title="Chapter 12. Recursive Name Server">Chapter 12, <i>Recursive Name Server</i></a> about their effects.
    1173. 

  1173.       </p><p>
    1174. 

  1174.         Currently update ACL can only control updates per zone basis;
    1175. 

  1175.         it's not possible to specify access control with higher
    1176. 

  1176.         granularity such as for particular domain names or specific
    1177. 

  1177.         types of RRs.
    1178. 

  1178. 

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

  1180.         Contrary to what RFC 2136 (literally) specifies,
    1181. 

  1181.         <span class="command"><strong>b10-ddns</strong></span> checks the update ACL before
    1182. 

  1182.         checking the prerequisites of the update request.
    1183. 

  1183.         This is a deliberate implementation decision.
    1184. 

  1184.         This counter intuitive specification has been repeatedly
    1185. 

  1185.         discussed among implementers and in the IETF, and it is now
    1186. 

  1186.         widely agreed that it does not make sense to strictly follow
    1187. 

  1187.         that part of RFC.
    1188. 

  1188.         One known specific bad result of following the RFC is that it
    1189. 

  1189.         could leak information about which name or record exists or does not
    1190. 

  1190.         exist in the zone as a result of prerequisite checks even if a
    1191. 

  1191.         zone is somehow configured to reject normal queries from
    1192. 

  1192.         arbitrary clients.
    1193. 

  1193.         There have been other troubles that could have been avoided if
    1194. 

  1194.         the ACL could be checked before the prerequisite check.
    1195. 

  1195.       </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="idp471872"></a>11.3. Miscellaneous Operational Issues</h2></div></div></div><p>
    1196. 

  1196.         Unlike BIND 9, BIND 10 currently does not support automatic
    1197. 

  1197.         resigning of DNSSEC-signed zone when it's updated via DDNS.
    1198. 

  1198.         It could be possible to resign the updated zone afterwards
    1199. 

  1199.         or make sure the update request also updates related DNSSEC
    1200. 

  1200.         records, but that will be pretty error-prone operation.
    1201. 

  1201.         In general, it's not advisable to allow DDNS for a signed zone
    1202. 

  1202.         at this moment.
    1203. 

  1203.       </p><p>
    1204. 

  1204.         Also unlike BIND 9, it's currently not possible
    1205. 

  1205.         to <span class="quote">&#8220;<span class="quote">freeze</span>&#8221;</span> a zone temporarily in order to
    1206. 

  1206.         suspend DDNS while you manually update the zone.
    1207. 

  1207.         If you need to make manual updates to a dynamic zone,
    1208. 

  1208.         you'll need to temporarily reject any updates to the zone via
    1209. 

  1209.         the update ACLs.
    1210. 

  1210.       </p><p>
    1211. 

  1211.         Dynamic updates are only applicable to primary zones.
    1212. 

  1212.         In order to avoid updating secondary zones via DDNS requests,
    1213. 

  1213.         <span class="command"><strong>b10-ddns</strong></span> refers to the
    1214. 

  1214.         <span class="quote">&#8220;<span class="quote">secondary_zones</span>&#8221;</span> configuration of
    1215. 

  1215.         <span class="command"><strong>b10-zonemgr</strong></span>.  Zones listed in
    1216. 

  1216.         <span class="quote">&#8220;<span class="quote">secondary_zones</span>&#8221;</span> will never be updated via DDNS
    1217. 

  1217.         regardless of the update ACL configuration;
    1218. 

  1218. 	<span class="command"><strong>b10-ddns</strong></span> will return a response with an
    1219. 

  1219. 	RCODE of NOTAUTH as specified in RFC 2136.
    1220. 

  1220.         If you have a "conceptual" secondary zone whose content is a
    1221. 

  1221.         copy of some external source but is not updated via the
    1222. 

  1222.         standard zone transfers and therefore not listed in
    1223. 

  1223.         <span class="quote">&#8220;<span class="quote">secondary_zones</span>&#8221;</span>, be careful not to allow DDNS
    1224. 

  1224.         for the zone; it would be quite likely to lead to inconsistent
    1225. 

  1225.         state between different servers.
    1226. 

  1226.         Normally this should not be a problem because the default
    1227. 

  1227.         update ACL rejects any update requests, but you may want to
    1228. 

  1228.         take an extra care about the configuration if you have such
    1229. 

  1229.         type of secondary zones.
    1230. 

  1230.       </p><p>
    1231. 

  1231.         The difference of two versions of a zone, before and after a
    1232. 

  1232.         DDNS transaction, is automatically recorded in the underlying
    1233. 

  1233.         data source, and can be retrieved in the form of outbound
    1234. 

  1234.         IXFR.
    1235. 

  1235.         This is done automatically; it does not require specific
    1236. 

  1236.         configuration to make this possible.
    1237. 

  1237.       </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="#idp492912">12.1. Access Control</a></span></dt><dt><span class="section"><a href="#idp509632">12.2. Forwarding</a></span></dt></dl></div><p>
    1238. 

  1238.       The <span class="command"><strong>b10-resolver</strong></span> process is started by
    1239. 

  1239.       <span class="command"><strong>bind10</strong></span>.
    1240. 

  1240. 

  1241.     </p><p>
    1242. 

  1242.       The main <span class="command"><strong>bind10</strong></span> process can be configured
    1243. 

  1243.       to select to run either the authoritative or resolver or both.
    1244. 

  1244.       By default, it doesn't start either one. You may change this using
    1245. 

  1245.       <span class="command"><strong>bindctl</strong></span>, for example:
    1246. 

  1246. 

  1247.       </p><pre class="screen">
    1248. 

  1248. &gt; <strong class="userinput"><code>config add Boss/components b10-resolver</code></strong>
    1249. 

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

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

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

  1252. &gt; <strong class="userinput"><code>config commit</code></strong>
    1253. 

  1253. </pre><p>
    1254. 

  1254. 

  1255.     </p><p>
    1256. 

  1256.        The master <span class="command"><strong>bind10</strong></span> will stop and start
    1257. 

  1257.        the desired services.
    1258. 

  1258.     </p><p>
    1259. 

  1259.       By default, the resolver listens on port 53 for 127.0.0.1 and ::1.
    1260. 

  1260.       The following example shows how it can be configured to
    1261. 

  1261.       listen on an additional address (and port):
    1262. 

  1262. 

  1263.       </p><pre class="screen">
    1264. 

  1264. &gt; <strong class="userinput"><code>config add Resolver/listen_on</code></strong>
    1265. 

  1265. &gt; <strong class="userinput"><code>config set Resolver/listen_on[<em class="replaceable"><code>2</code></em>]/address "192.168.1.1"</code></strong>
    1266. 

  1266. &gt; <strong class="userinput"><code>config set Resolver/listen_on[<em class="replaceable"><code>2</code></em>]/port 53</code></strong>
    1267. 

  1267. &gt; <strong class="userinput"><code>config commit</code></strong>
    1268. 

  1268. </pre><p>
    1269. 

  1269.     </p><p>(Replace the <span class="quote">&#8220;<span class="quote"><em class="replaceable"><code>2</code></em></span>&#8221;</span>
    1270. 

  1270.        as needed; run <span class="quote">&#8220;<span class="quote"><strong class="userinput"><code>config show
    1271. 

  1271.        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="idp492912"></a>12.1. Access Control</h2></div></div></div><p>
    1272. 

  1272.         By default, the <span class="command"><strong>b10-resolver</strong></span> daemon only accepts
    1273. 

  1273.         DNS queries from the localhost (127.0.0.1 and ::1).
    1274. 

  1274.         The <code class="option">Resolver/query_acl</code> configuration may
    1275. 

  1275.         be used to reject, drop, or allow specific IPs or networks.
    1276. 

  1276.         This configuration list is first match.
    1277. 

  1277.       </p><p>
    1278. 

  1278.         The configuration's <code class="option">action</code> item may be
    1279. 

  1279.         set to <span class="quote">&#8220;<span class="quote">ACCEPT</span>&#8221;</span> to allow the incoming query,
    1280. 

  1280.         <span class="quote">&#8220;<span class="quote">REJECT</span>&#8221;</span> to respond with a DNS REFUSED return
    1281. 

  1281.         code, or <span class="quote">&#8220;<span class="quote">DROP</span>&#8221;</span> to ignore the query without
    1282. 

  1282.         any response (such as a blackhole).  For more information,
    1283. 

  1283.         see the respective debugging messages:  <a class="ulink" href="bind10-messages.html#RESOLVER_QUERY_ACCEPTED" target="_top">RESOLVER_QUERY_ACCEPTED</a>,
    1284. 

  1284.         <a class="ulink" href="bind10-messages.html#RESOLVER_QUERY_REJECTED" target="_top">RESOLVER_QUERY_REJECTED</a>,
    1285. 

  1285.         and <a class="ulink" href="bind10-messages.html#RESOLVER_QUERY_DROPPED" target="_top">RESOLVER_QUERY_DROPPED</a>.
    1286. 

  1286.       </p><p>
    1287. 

  1287.         The required configuration's <code class="option">from</code> item is set
    1288. 

  1288.         to an IPv4 or IPv6 address, addresses with an network mask, or to
    1289. 

  1289.         the special lowercase keywords <span class="quote">&#8220;<span class="quote">any6</span>&#8221;</span> (for
    1290. 

  1290.         any IPv6 address) or <span class="quote">&#8220;<span class="quote">any4</span>&#8221;</span> (for any IPv4
    1291. 

  1291.         address).
    1292. 

  1292.       </p><p>
    1293. 

  1293.         For example to allow the <em class="replaceable"><code>192.168.1.0/24</code></em>
    1294. 

  1294.         network to use your recursive name server, at the
    1295. 

  1295.         <span class="command"><strong>bindctl</strong></span> prompt run:
    1296. 

  1296.       </p><pre class="screen">
    1297. 

  1297. &gt; <strong class="userinput"><code>config add Resolver/query_acl</code></strong>
    1298. 

  1298. &gt; <strong class="userinput"><code>config set Resolver/query_acl[<em class="replaceable"><code>2</code></em>]/action "ACCEPT"</code></strong>
    1299. 

  1299. &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>
    1300. 

  1300. &gt; <strong class="userinput"><code>config commit</code></strong>
    1301. 

  1301. </pre><p>(Replace the <span class="quote">&#8220;<span class="quote"><em class="replaceable"><code>2</code></em></span>&#8221;</span>
    1302. 

  1302.        as needed; run <span class="quote">&#8220;<span class="quote"><strong class="userinput"><code>config show
    1303. 

  1303.        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
    1304. 

  1304.       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="idp509632"></a>12.2. Forwarding</h2></div></div></div><p>
    1305. 

  1305. 

  1306.         To enable forwarding, the upstream address and port must be
    1307. 

  1307.         configured to forward queries to, such as:
    1308. 

  1308. 

  1309.         </p><pre class="screen">
    1310. 

  1310. &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>
    1311. 

  1311. &gt; <strong class="userinput"><code>config commit</code></strong>
    1312. 

  1312. </pre><p>
    1313. 

  1313. 

  1314.         (Replace <em class="replaceable"><code>192.168.1.1</code></em> to point to your
    1315. 

  1315.         full resolver.)
    1316. 

  1316.       </p><p>
    1317. 

  1317.         Normal iterative name service can be re-enabled by clearing the
    1318. 

  1318.         forwarding address(es); for example:
    1319. 

  1319. 

  1320.         </p><pre class="screen">
    1321. 

  1321. &gt; <strong class="userinput"><code>config set Resolver/forward_addresses []</code></strong>
    1322. 

  1322. &gt; <strong class="userinput"><code>config commit</code></strong>
    1323. 

  1323. </pre><p>
    1324. 

  1324.       </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
    1325. 

  1325.     DHCPv4) and Dynamic Host Configuration Protocol for IPv6 (DHCPv6)
    1326. 

  1326.     are protocols that allow one node (server) to provision
    1327. 

  1327.     configuration parameters to many hosts and devices (clients). To
    1328. 

  1328.     ease deployment in larger networks, additional nodes (relays) may
    1329. 

  1329.     be deployed that facilitate communication between servers and
    1330. 

  1330.     clients. Even though principles of both DHCPv4 and DHCPv6 are
    1331. 

  1331.     somewhat similar, these are two radically different
    1332. 

  1332.     protocols. BIND10 offers server implementations for both DHCPv4
    1333. 

  1333.     and DHCPv6. This chapter is about DHCP for IPv4. For a description
    1334. 

  1334.     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
    1335. 

  1335.     development. You may want to check out <a class="ulink" href="http://bind10.isc.org/wiki/Kea" target="_top">BIND10 DHCP (Kea) wiki</a>
    1336. 

  1336.     and recent posts on <a class="ulink" href="https://lists.isc.org/mailman/listinfo/bind10-dev" target="_top">BIND10
    1337. 

  1337.     developers mailing list</a>.</p><p>The DHCPv4 and DHCPv6 components in BIND10 architecture are
    1338. 

  1338.     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>
    1339. 

  1339.         As of December 2011, both DHCPv4 and DHCPv6 components are
    1340. 

  1340.         skeleton servers. That means that while they are capable of
    1341. 

  1341.         performing DHCP configuration, they are not fully functional
    1342. 

  1342.         yet. In particular, neither has functional lease
    1343. 

  1343.         databases. This means that they will assign the same, fixed,
    1344. 

  1344.         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
    1345. 

  1345.         detailed description.
    1346. 

  1346.       </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
    1347. 

  1347.       2011. It is a skeleton server and can be described as an early
    1348. 

  1348.       prototype that is not fully functional yet. It is mature enough
    1349. 

  1349.       to conduct first tests in lab environment, but it has
    1350. 

  1350.       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
    1351. 

  1351.       details.
    1352. 

  1352.       </p><p>
    1353. 

  1353.         <span class="command"><strong>b10-dhcp4</strong></span> is a BIND10 component and is being
    1354. 

  1354.         run under BIND10 framework. To add a DHCPv4 process to the set of running
    1355. 

  1355.         BIND10 services, you can use following commands in <span class="command"><strong>bindctl</strong></span>:
    1356. 

  1356.         </p><pre class="screen">&gt; <strong class="userinput"><code>config add Boss/components b10-dhcp4</code></strong>
    1357. 

  1357. &gt; <strong class="userinput"><code>config set Boss/components/b10-dhcp4/kind dispensable</code></strong>
    1358. 

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

  1359.          To shutdown running <span class="command"><strong>b10-dhcp4</strong></span>, please use the
    1360. 

  1360.          following command:
    1361. 

  1361.          </p><pre class="screen">&gt; <strong class="userinput"><code>Dhcp4 shutdown</code></strong></pre><p>
    1362. 

  1362.          or
    1363. 

  1363.          </p><pre class="screen">&gt; <strong class="userinput"><code>config remove Boss/components b10-dhcp4</code></strong>
    1364. 

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

  1365.         At start, the server will detect available network interfaces
    1366. 

  1366.         and will attempt to open UDP sockets on all interfaces that
    1367. 

  1367.         are up, running, are not loopback, and have IPv4 address
    1368. 

  1368.         assigned.
    1369. 

  1369. 

  1370.         The server will then listen to incoming traffic. Currently
    1371. 

  1371.         supported client messages are DISCOVER and REQUEST. The server
    1372. 

  1372.         will respond to them with OFFER and ACK, respectively.
    1373. 

  1373. 

  1374.         Since the DHCPv4 server opens privileged ports, it requires root
    1375. 

  1375.         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>
    1376. 

  1376.             Integration with <span class="command"><strong>bind10</strong></span> is
    1377. 

  1377.             planned. Ultimately, <span class="command"><strong>b10-dhcp4</strong></span> will not
    1378. 

  1378.             be started directly, but rather via
    1379. 

  1379.             <span class="command"><strong>bind10</strong></span>. Please be aware of this planned
    1380. 

  1380.             change.
    1381. 

  1381.           </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>
    1382. 

  1382.         The DHCPv4 server does not have a lease database implemented yet
    1383. 

  1383.         nor any support for configuration, so every time the same set
    1384. 

  1384.         of configuration options (including the same fixed address)
    1385. 

  1385.         will be assigned every time.
    1386. 

  1386.       </p><p>
    1387. 

  1387.         At this stage of development, the only way to alter the server
    1388. 

  1388.         configuration is to tweak its source code. To do so, please
    1389. 

  1389.         edit src/bin/dhcp4/dhcp4_srv.cc file and modify following
    1390. 

  1390.         parameters and recompile:
    1391. 

  1391.         </p><pre class="screen">
    1392. 

  1392. const std::string HARDCODED_LEASE = "192.0.2.222"; // assigned lease
    1393. 

  1393. const std::string HARDCODED_NETMASK = "255.255.255.0";
    1394. 

  1394. const uint32_t    HARDCODED_LEASE_TIME = 60; // in seconds
    1395. 

  1395. const std::string HARDCODED_GATEWAY = "192.0.2.1";
    1396. 

  1396. const std::string HARDCODED_DNS_SERVER = "192.0.2.2";
    1397. 

  1397. const std::string HARDCODED_DOMAIN_NAME = "isc.example.com";
    1398. 

  1398. const std::string HARDCODED_SERVER_ID = "192.0.2.1";</pre><p>
    1399. 

  1399. 

  1400.         Lease database and configuration support is planned for 2012.
    1401. 

  1401.       </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
    1402. 

  1402.       supported:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">RFC2131: Supported messages are DISCOVER, OFFER,
    1403. 

  1403.             REQUEST, and ACK.</li><li class="listitem">RFC2132: Supported options are: PAD (0),
    1404. 

  1404.             END(255), Message Type(53), DHCP Server Identifier (54),
    1405. 

  1405.             Domain Name (15), DNS Servers (6), IP Address Lease Time
    1406. 

  1406.             (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
    1407. 

  1407.       software. Most of them are reflections of the early stage of
    1408. 

  1408.       development and should be treated as <span class="quote">&#8220;<span class="quote">not implemented
    1409. 

  1409.       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
    1410. 

  1410.             server is expected to send packets to a node that does not
    1411. 

  1411.             have IPv4 address assigned yet. The server requires
    1412. 

  1412.             certain tricks (or hacks) to transmit such packets. This
    1413. 

  1413.             is not implemented yet, therefore DHCPv4 server supports
    1414. 

  1414.             relayed traffic only (that is, normal point to point
    1415. 

  1415.             communication).</li><li class="listitem"><span class="command"><strong>b10-dhcp4</strong></span> provides a single,
    1416. 

  1416.             fixed, hardcoded lease to any client that asks.  There is
    1417. 

  1417.             no lease manager implemented. If two clients request
    1418. 

  1418.             addresses, they will both get the same fixed
    1419. 

  1419.             address.</li><li class="listitem"><span class="command"><strong>b10-dhcp4</strong></span> does not support any
    1420. 

  1420.             configuration mechanisms yet. The whole configuration is
    1421. 

  1421.             currently hardcoded. The only way to tweak configuration
    1422. 

  1422.             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
    1423. 

  1423.             interfaces that are not loopback, are up and running and
    1424. 

  1424.             have IPv4 address.</li><li class="listitem">PRL (Parameter Request List, a list of options
    1425. 

  1425.             requested by a client) is currently ignored and server
    1426. 

  1426.             assigns DNS SERVER and DOMAIN NAME options.</li><li class="listitem"><span class="command"><strong>b10-dhcp4</strong></span> does not support
    1427. 

  1427.             BOOTP. That is a design choice. This limitation is
    1428. 

  1428.             permanent. If you have legacy nodes that can't use DHCP and
    1429. 

  1429.             require BOOTP support, please use latest version of ISC DHCP
    1430. 

  1430.             <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
    1431. 

  1431.             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
    1432. 

  1432.             assigned address is unused. According to RFC2131, the
    1433. 

  1433.             allocating server should verify that address is no used by
    1434. 

  1434.             sending ICMP echo request.</li><li class="listitem">Address renewal (RENEW), rebinding (REBIND),
    1435. 

  1435.             confirmation (CONFIRM), duplication report (DECLINE) and
    1436. 

  1436.             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
    1437. 

  1437.             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
    1438. 

  1438.     specified in RFC3315. BIND10 provides DHCPv6 server implementation
    1439. 

  1439.     that is described in this chapter. For a description of the DHCPv4
    1440. 

  1440.     server implementation, see <a class="xref" href="#dhcp4" title="Chapter 13. DHCPv4 Server">Chapter 13, <i>DHCPv4 Server</i></a>.
    1441. 

  1441.     </p><p>The DHCPv6 server component is currently under intense
    1442. 

  1442.     development. You may want to check out <a class="ulink" href="http://bind10.isc.org/wiki/Kea" target="_top">BIND10 DHCP (Kea) wiki</a>
    1443. 

  1443.     and recent posts on <a class="ulink" href="https://lists.isc.org/mailman/listinfo/bind10-dev" target="_top">BIND10
    1444. 

  1444.     developers mailing list</a>.</p><p>The DHCPv4 and DHCPv6 components in BIND10 architecture are
    1445. 

  1445.     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>
    1446. 

  1446.         As of December 2011, both DHCPv4 and DHCPv6 components are
    1447. 

  1447.         skeleton servers. That means that while they are capable of
    1448. 

  1448.         performing DHCP configuration, they are not fully functional
    1449. 

  1449.         yet. In particular, neither has functional lease
    1450. 

  1450.         databases. This means that they will assign the same, fixed,
    1451. 

  1451.         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
    1452. 

  1452.         detailed description.
    1453. 

  1453.       </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>
    1454. 

  1454.         BIND10 provides the DHCPv6 server component since September
    1455. 

  1455.         2011. It is a skeleton server and can be described as an early
    1456. 

  1456.         prototype that is not fully functional yet. It is mature
    1457. 

  1457.         enough to conduct first tests in lab environment, but it has
    1458. 

  1458.         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
    1459. 

  1459.         details.
    1460. 

  1460.       </p><p>
    1461. 

  1461.         The DHCPv6 server is implemented as <span class="command"><strong>b10-dhcp6</strong></span>
    1462. 

  1462.         daemon. As it is not configurable yet, it is fully autonomous,
    1463. 

  1463.         that is it does not interact with <span class="command"><strong>b10-cfgmgr</strong></span>.
    1464. 

  1464.         To start DHCPv6 server, simply input:
    1465. 

  1465. 

  1466.         </p><pre class="screen">
    1467. 

  1467. #<strong class="userinput"><code>cd src/bin/dhcp6</code></strong>
    1468. 

  1468. #<strong class="userinput"><code>./b10-dhcp6</code></strong>
    1469. 

  1469. </pre><p>
    1470. 

  1470. 

  1471.         Depending on your installation, <span class="command"><strong>b10-dhcp6</strong></span>
    1472. 

  1472.         binary may reside in src/bin/dhcp6 in your source code
    1473. 

  1473.         directory, in /usr/local/bin/b10-dhcp6 or other directory
    1474. 

  1474.         you specified during compilation.
    1475. 

  1475. 

  1476.         At start, server will detect available network interfaces
    1477. 

  1477.         and will attempt to open UDP sockets on all interfaces that
    1478. 

  1478.         are up, running, are not loopback, are multicast-capable, and
    1479. 

  1479.         have IPv6 address assigned.
    1480. 

  1480. 

  1481.         The server will then listen to incoming traffic. Currently
    1482. 

  1482.         supported client messages are SOLICIT and REQUEST. The server
    1483. 

  1483.         will respond to them with ADVERTISE and REPLY, respectively.
    1484. 

  1484. 

  1485.         Since the DHCPv6 server opens privileged ports, it requires root
    1486. 

  1486.         access. Make sure you run this daemon as root.
    1487. 

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

  1488.             Integration with <span class="command"><strong>bind10</strong></span> is
    1489. 

  1489.             planned. Ultimately, <span class="command"><strong>b10-dhcp6</strong></span> will not
    1490. 

  1490.             be started directly, but rather via
    1491. 

  1491.             <span class="command"><strong>bind10</strong></span>. Please be aware of this planned
    1492. 

  1492.             change.
    1493. 

  1493.           </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>
    1494. 

  1494.         The DHCPv6 server does not have lease database implemented yet
    1495. 

  1495.         or any support for configuration, so every time the same set
    1496. 

  1496.         of configuration options (including the same fixed address)
    1497. 

  1497.         will be assigned every time.
    1498. 

  1498.       </p><p>
    1499. 

  1499.         At this stage of development, the only way to alter server
    1500. 

  1500.         configuration is to tweak its source code. To do so, please
    1501. 

  1501.         edit src/bin/dhcp6/dhcp6_srv.cc file and modify following
    1502. 

  1502.         parameters and recompile:
    1503. 

  1503.         </p><pre class="screen">
    1504. 

  1504. const std::string HARDCODED_LEASE = "2001:db8:1::1234:abcd";
    1505. 

  1505. const uint32_t HARDCODED_T1 = 1500; // in seconds
    1506. 

  1506. const uint32_t HARDCODED_T2 = 2600; // in seconds
    1507. 

  1507. const uint32_t HARDCODED_PREFERRED_LIFETIME = 3600; // in seconds
    1508. 

  1508. const uint32_t HARDCODED_VALID_LIFETIME = 7200; // in seconds
    1509. 

  1509. const std::string HARDCODED_DNS_SERVER = "2001:db8:1::1";</pre><p>
    1510. 

  1510. 

  1511.         Lease database and configuration support is planned for 2012.
    1512. 

  1512.       </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
    1513. 

  1513.       supported:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">RFC3315: Supported messages are SOLICIT,
    1514. 

  1514.             ADVERTISE, REQUEST, and REPLY. Supported options are
    1515. 

  1515.             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
    1516. 

  1516.       software. Most of them are reflections of the early stage of
    1517. 

  1517.       development and should be treated as <span class="quote">&#8220;<span class="quote">not implemented
    1518. 

  1518.       yet</span>&#8221;</span>, rather than actual limitations.</p><p>
    1519. 

  1519.       </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,
    1520. 

  1520.           fixed, hardcoded lease to any client that asks. There is no
    1521. 

  1521.           lease manager implemented. If two clients request addresses,
    1522. 

  1522.           they will both get the same fixed address.</li><li class="listitem"><span class="command"><strong>b10-dhcp6</strong></span> does not support any
    1523. 

  1523.             configuration mechanisms yet. The whole configuration is
    1524. 

  1524.             currently hardcoded. The only way to tweak configuration
    1525. 

  1525.             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
    1526. 

  1526.           interfaces that are not loopback, are up, running and are
    1527. 

  1527.           multicast capable and have IPv6 address.  Support for
    1528. 

  1528.           multiple interfaces is not coded in reception routines yet,
    1529. 

  1529.           so if you are running this code on a machine that has many
    1530. 

  1530.           interfaces and <span class="command"><strong>b10-dhcp6</strong></span> happens to
    1531. 

  1531.           listen on wrong interface, the easiest way to work around
    1532. 

  1532.           this problem is to turn down other interfaces. This
    1533. 

  1533.           limitation will be fixed shortly.</li><li class="listitem">ORO (Option Request Option, a list of options
    1534. 

  1534.           requested by a client) is currently ignored and server
    1535. 

  1535.           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),
    1536. 

  1536.           confirmation (CONFIRM), duplication report (DECLINE) and
    1537. 

  1537.           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
    1538. 

  1538.           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
    1539. 

  1539.           default, and cannot be disabled.</li></ul></div><p>
    1540. 

  1540.       </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
    1541. 

  1541.     many DHCP-related tasks, like DHCPv4 and DHCPv6 packets parsing,
    1542. 

  1542.     manipulation and assembly, option parsing, manipulation and
    1543. 

  1543.     assembly, network interface detection and socket operations, like
    1544. 

  1544.     socket creations, data transmission and reception and socket
    1545. 

  1545.     closing.
    1546. 

  1546.     </p><p>
    1547. 

  1547.     While this library is currently used by
    1548. 

  1548.     <span class="command"><strong>b10-dhcp4</strong></span> and <span class="command"><strong>b10-dhcp6</strong></span>
    1549. 

  1549.     only, it is designed to be portable, universal library useful for
    1550. 

  1550.     any kind of DHCP-related software.
    1551. 

  1551.     </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
    1552. 

  1552.       interface detection routines. Interface detection is
    1553. 

  1553.       currently only supported on Linux systems.</p><p>For non-Linux systems, there is currently stub
    1554. 

  1554.       implementation provided. Interface manager detects loopback
    1555. 

  1555.       interfaces only as their name (lo or lo0) can be easily predicted.
    1556. 

  1556.       Please contact BIND10 development team if you are interested
    1557. 

  1557.       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>
    1558. 

  1558.       The <span class="command"><strong>b10-stats</strong></span> process is started by
    1559. 

  1559.       <span class="command"><strong>bind10</strong></span>.
    1560. 

  1560.       It periodically collects statistics data from various modules
    1561. 

  1561.       and aggregates it.
    1562. 

  1562. 

  1563.     </p><p>
    1564. 

  1564. 

  1565.        This stats daemon provides commands to identify if it is
    1566. 

  1566.        running, show specified or all statistics data, show specified
    1567. 

  1567.        or all statistics data schema, and set specified statistics
    1568. 

  1568.        data.
    1569. 

  1569. 

  1570.        For example, using <span class="command"><strong>bindctl</strong></span>:
    1571. 

  1571. 

  1572.        </p><pre class="screen">
    1573. 

  1573. &gt; <strong class="userinput"><code>Stats show</code></strong>
    1574. 

  1574. {
    1575. 

  1575.     "Auth": {
    1576. 

  1576.         "opcode.iquery": 0,
    1577. 

  1577.         "opcode.notify": 10,
    1578. 

  1578.         "opcode.query": 869617,
    1579. 

  1579.         ...
    1580. 

  1580.         "queries.tcp": 1749,
    1581. 

  1581.         "queries.udp": 867868
    1582. 

  1582.     },
    1583. 

  1583.     "Boss": {
    1584. 

  1584.         "boot_time": "2011-01-20T16:59:03Z"
    1585. 

  1585.     },
    1586. 

  1586.     "Stats": {
    1587. 

  1587.         "boot_time": "2011-01-20T16:59:05Z",
    1588. 

  1588.         "last_update_time": "2011-01-20T17:04:05Z",
    1589. 

  1589.         "lname": "4d3869d9_a@jreed.example.net",
    1590. 

  1590.         "report_time": "2011-01-20T17:04:06Z",
    1591. 

  1591.         "timestamp": 1295543046.823504
    1592. 

  1592.     }
    1593. 

  1593. }
    1594. 

  1594.        </pre><p>
    1595. 

  1595.     </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="#idp609968">17.1. Logging configuration</a></span></dt><dd><dl><dt><span class="section"><a href="#idp611664">17.1.1. Loggers</a></span></dt><dt><span class="section"><a href="#idp648032">17.1.2. Output Options</a></span></dt><dt><span class="section"><a href="#idp673088">17.1.3. Example session</a></span></dt></dl></dd><dt><span class="section"><a href="#idp704416">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="idp609968"></a>17.1. Logging configuration</h2></div></div></div><p>
    1596. 

  1596. 

  1597.         The logging system in BIND 10 is configured through the
    1598. 

  1598.         Logging module. All BIND 10 modules will look at the
    1599. 

  1599.         configuration in Logging to see what should be logged and
    1600. 

  1600.         to where.
    1601. 

  1601. 

  1602. 

  1603. 

  1604.       </p><div class="section" title="17.1.1. Loggers"><div class="titlepage"><div><div><h3 class="title"><a name="idp611664"></a>17.1.1. Loggers</h3></div></div></div><p>
    1605. 

  1605. 

  1606.           Within BIND 10, a message is logged through a component
    1607. 

  1607.           called a "logger". Different parts of BIND 10 log messages
    1608. 

  1608.           through different loggers, and each logger can be configured
    1609. 

  1609.           independently of one another.
    1610. 

  1610. 

  1611.         </p><p>
    1612. 

  1612. 

  1613.           In the Logging module, you can specify the configuration
    1614. 

  1614.           for zero or more loggers; any that are not specified will
    1615. 

  1615.           take appropriate default values.
    1616. 

  1616. 

  1617.         </p><p>
    1618. 

  1618. 

  1619.           The three most important elements of a logger configuration
    1620. 

  1620.           are the <code class="option">name</code> (the component that is
    1621. 

  1621.           generating the messages), the <code class="option">severity</code>
    1622. 

  1622.           (what to log), and the <code class="option">output_options</code>
    1623. 

  1623.           (where to log).
    1624. 

  1624. 

  1625.         </p><div class="section" title="17.1.1.1. name (string)"><div class="titlepage"><div><div><h4 class="title"><a name="idp615424"></a>17.1.1.1. name (string)</h4></div></div></div><p>
    1626. 

  1626.           Each logger in the system has a name, the name being that
    1627. 

  1627.           of the component using it to log messages. For instance,
    1628. 

  1628.           if you want to configure logging for the resolver module,
    1629. 

  1629.           you add an entry for a logger named <span class="quote">&#8220;<span class="quote">Resolver</span>&#8221;</span>. This
    1630. 

  1630.           configuration will then be used by the loggers in the
    1631. 

  1631.           Resolver module, and all the libraries used by it.
    1632. 

  1632.               </p><p>
    1633. 

  1633. 

  1634.           If you want to specify logging for one specific library
    1635. 

  1635.           within the module, you set the name to
    1636. 

  1636.           <em class="replaceable"><code>module.library</code></em>.  For example, the
    1637. 

  1637.           logger used by the nameserver address store component
    1638. 

  1638.           has the full name of <span class="quote">&#8220;<span class="quote">Resolver.nsas</span>&#8221;</span>. If
    1639. 

  1639.           there is no entry in Logging for a particular library,
    1640. 

  1640.           it will use the configuration given for the module.
    1641. 

  1641. 

  1642. 

  1643. 

  1644.         </p><p>
    1645. 

  1645. 

  1646. 

  1647. 

  1648.           To illustrate this, suppose you want the cache library
    1649. 

  1649.           to log messages of severity DEBUG, and the rest of the
    1650. 

  1650.           resolver code to log messages of severity INFO. To achieve
    1651. 

  1651.           this you specify two loggers, one with the name
    1652. 

  1652.           <span class="quote">&#8220;<span class="quote">Resolver</span>&#8221;</span> and severity INFO, and one with
    1653. 

  1653.           the name <span class="quote">&#8220;<span class="quote">Resolver.cache</span>&#8221;</span> with severity
    1654. 

  1654.           DEBUG. As there are no entries for other libraries (e.g.
    1655. 

  1655.           the nsas), they will use the configuration for the module
    1656. 

  1656.           (<span class="quote">&#8220;<span class="quote">Resolver</span>&#8221;</span>), so giving the desired behavior.
    1657. 

  1657. 

  1658.         </p><p>
    1659. 

  1659. 

  1660.           One special case is that of a module name of <span class="quote">&#8220;<span class="quote">*</span>&#8221;</span>
    1661. 

  1661.           (asterisks), which is interpreted as <span class="emphasis"><em>any</em></span>
    1662. 

  1662.           module. You can set global logging options by using this,
    1663. 

  1663.           including setting the logging configuration for a library
    1664. 

  1664.           that is used by multiple modules (e.g. <span class="quote">&#8220;<span class="quote">*.config</span>&#8221;</span>
    1665. 

  1665.           specifies the configuration library code in whatever
    1666. 

  1666.           module is using it).
    1667. 

  1667. 

  1668.         </p><p>
    1669. 

  1669. 

  1670.           If there are multiple logger specifications in the
    1671. 

  1671.           configuration that might match a particular logger, the
    1672. 

  1672.           specification with the more specific logger name takes
    1673. 

  1673.           precedence. For example, if there are entries for for
    1674. 

  1674.           both <span class="quote">&#8220;<span class="quote">*</span>&#8221;</span> and <span class="quote">&#8220;<span class="quote">Resolver</span>&#8221;</span>, the
    1675. 

  1675.           resolver module &#8212; and all libraries it uses &#8212;
    1676. 

  1676.           will log messages according to the configuration in the
    1677. 

  1677.           second entry (<span class="quote">&#8220;<span class="quote">Resolver</span>&#8221;</span>). All other modules
    1678. 

  1678.           will use the configuration of the first entry
    1679. 

  1679.           (<span class="quote">&#8220;<span class="quote">*</span>&#8221;</span>). If there was also a configuration
    1680. 

  1680.           entry for <span class="quote">&#8220;<span class="quote">Resolver.cache</span>&#8221;</span>, the cache library
    1681. 

  1681.           within the resolver would use that in preference to the
    1682. 

  1682.           entry for <span class="quote">&#8220;<span class="quote">Resolver</span>&#8221;</span>.
    1683. 

  1683. 

  1684.         </p><p>
    1685. 

  1685. 

  1686.           One final note about the naming. When specifying the
    1687. 

  1687.           module name within a logger, use the name of the module
    1688. 

  1688.           as specified in <span class="command"><strong>bindctl</strong></span>, e.g.
    1689. 

  1689.           <span class="quote">&#8220;<span class="quote">Resolver</span>&#8221;</span> for the resolver module,
    1690. 

  1690.           <span class="quote">&#8220;<span class="quote">Xfrout</span>&#8221;</span> for the xfrout module, etc. When
    1691. 

  1691.           the message is logged, the message will include the name
    1692. 

  1692.           of the logger generating the message, but with the module
    1693. 

  1693.           name replaced by the name of the process implementing
    1694. 

  1694.           the module (so for example, a message generated by the
    1695. 

  1695.           <span class="quote">&#8220;<span class="quote">Auth.cache</span>&#8221;</span> logger will appear in the output
    1696. 

  1696.           with a logger name of <span class="quote">&#8220;<span class="quote">b10-auth.cache</span>&#8221;</span>).
    1697. 

  1697. 

  1698.         </p></div><div class="section" title="17.1.1.2. severity (string)"><div class="titlepage"><div><div><h4 class="title"><a name="idp631472"></a>17.1.1.2. severity (string)</h4></div></div></div><p>
    1699. 

  1699. 

  1700.           This specifies the category of messages logged.
    1701. 

  1701.           Each message is logged with an associated severity which
    1702. 

  1702.           may be one of the following (in descending order of
    1703. 

  1703.           severity):
    1704. 

  1704.         </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>
    1705. 

  1705. 

  1706.           When the severity of a logger is set to one of these
    1707. 

  1707.           values, it will only log messages of that severity, and
    1708. 

  1708.           the severities above it. The severity may also be set to
    1709. 

  1709.           NONE, in which case all messages from that logger are
    1710. 

  1710.           inhibited.
    1711. 

  1711. 

  1712. 

  1713. 

  1714.         </p></div><div class="section" title="17.1.1.3. output_options (list)"><div class="titlepage"><div><div><h4 class="title"><a name="idp638448"></a>17.1.1.3. output_options (list)</h4></div></div></div><p>
    1715. 

  1715. 

  1716.           Each logger can have zero or more
    1717. 

  1717.           <code class="option">output_options</code>. These specify where log
    1718. 

  1718.           messages are sent to. These are explained in detail below.
    1719. 

  1719. 

  1720.         </p><p>
    1721. 

  1721. 

  1722.           The other options for a logger are:
    1723. 

  1723. 

  1724.         </p></div><div class="section" title="17.1.1.4. debuglevel (integer)"><div class="titlepage"><div><div><h4 class="title"><a name="idp640720"></a>17.1.1.4. debuglevel (integer)</h4></div></div></div><p>
    1725. 

  1725. 

  1726.           When a logger's severity is set to DEBUG, this value
    1727. 

  1727.           specifies what debug messages should be printed. It ranges
    1728. 

  1728.           from 0 (least verbose) to 99 (most verbose).
    1729. 

  1729.         </p><p>
    1730. 

  1730. 

  1731.           If severity for the logger is not DEBUG, this value is ignored.
    1732. 

  1732. 

  1733.         </p></div><div class="section" title="17.1.1.5. additive (true or false)"><div class="titlepage"><div><div><h4 class="title"><a name="idp643104"></a>17.1.1.5. additive (true or false)</h4></div></div></div><p>
    1734. 

  1734. 

  1735.           If this is true, the <code class="option">output_options</code> from
    1736. 

  1736.           the parent will be used. For example, if there are two
    1737. 

  1737.           loggers configured; <span class="quote">&#8220;<span class="quote">Resolver</span>&#8221;</span> and
    1738. 

  1738.           <span class="quote">&#8220;<span class="quote">Resolver.cache</span>&#8221;</span>, and <code class="option">additive</code>
    1739. 

  1739.           is true in the second, it will write the log messages
    1740. 

  1740.           not only to the destinations specified for
    1741. 

  1741.           <span class="quote">&#8220;<span class="quote">Resolver.cache</span>&#8221;</span>, but also to the destinations
    1742. 

  1742.           as specified in the <code class="option">output_options</code> in
    1743. 

  1743.           the logger named <span class="quote">&#8220;<span class="quote">Resolver</span>&#8221;</span>.
    1744. 

  1744. 

  1745. 

  1746. 

  1747.       </p></div></div><div class="section" title="17.1.2. Output Options"><div class="titlepage"><div><div><h3 class="title"><a name="idp648032"></a>17.1.2. Output Options</h3></div></div></div><p>
    1748. 

  1748. 

  1749.           The main settings for an output option are the
    1750. 

  1750.           <code class="option">destination</code> and a value called
    1751. 

  1751.           <code class="option">output</code>, the meaning of which depends on
    1752. 

  1752.           the destination that is set.
    1753. 

  1753. 

  1754.         </p><div class="section" title="17.1.2.1. destination (string)"><div class="titlepage"><div><div><h4 class="title"><a name="idp650112"></a>17.1.2.1. destination (string)</h4></div></div></div><p>
    1755. 

  1755. 

  1756.             The destination is the type of output. It can be one of:
    1757. 

  1757. 

  1758.           </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="idp654176"></a>17.1.2.2. output (string)</h4></div></div></div><p>
    1759. 

  1759. 

  1760.           Depending on what is set as the output destination, this
    1761. 

  1761.           value is interpreted as follows:
    1762. 

  1762. 

  1763.         </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>
    1764. 

  1764.                  The value of output must be one of <span class="quote">&#8220;<span class="quote">stdout</span>&#8221;</span>
    1765. 

  1765.                  (messages printed to standard output) or
    1766. 

  1766.                  <span class="quote">&#8220;<span class="quote">stderr</span>&#8221;</span> (messages printed to standard
    1767. 

  1767.                  error).
    1768. 

  1768.               </p><p>
    1769. 

  1769.                 Note: if output is set to <span class="quote">&#8220;<span class="quote">stderr</span>&#8221;</span> and a lot of
    1770. 

  1770.                 messages are produced in a short time (e.g. if the logging
    1771. 

  1771.                 level is set to DEBUG), you may occasionally see some messages
    1772. 

  1772.                 jumbled up together.  This is due to a combination of the way
    1773. 

  1773.                 that messages are written to the screen and the unbuffered
    1774. 

  1774.                 nature of the standard error stream.  If this occurs, it is
    1775. 

  1775.                 recommended that output be set to <span class="quote">&#8220;<span class="quote">stdout</span>&#8221;</span>.
    1776. 

  1776.               </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>
    1777. 

  1777.                 The value of output is interpreted as a file name;
    1778. 

  1778.                 log messages will be appended to this file.
    1779. 

  1779.               </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>
    1780. 

  1780.                 The value of output is interpreted as the
    1781. 

  1781.                 <span class="command"><strong>syslog</strong></span> facility (e.g.
    1782. 

  1782.                 <span class="emphasis"><em>local0</em></span>) that should be used
    1783. 

  1783.                 for log messages.
    1784. 

  1784.               </p></dd></dl></div><p>
    1785. 

  1785. 

  1786.           The other options for <code class="option">output_options</code> are:
    1787. 

  1787. 

  1788.         </p><div class="section" title="17.1.2.2.1. flush (true of false)"><div class="titlepage"><div><div><h5 class="title"><a name="idp667136"></a>17.1.2.2.1. flush (true of false)</h5></div></div></div><p>
    1789. 

  1789.             Flush buffers after each log message. Doing this will
    1790. 

  1790.             reduce performance but will ensure that if the program
    1791. 

  1791.             terminates abnormally, all messages up to the point of
    1792. 

  1792.             termination are output.
    1793. 

  1793.           </p></div><div class="section" title="17.1.2.2.2. maxsize (integer)"><div class="titlepage"><div><div><h5 class="title"><a name="idp668576"></a>17.1.2.2.2. maxsize (integer)</h5></div></div></div><p>
    1794. 

  1794.             Only relevant when destination is file, this is maximum
    1795. 

  1795.             file size of output files in bytes. When the maximum
    1796. 

  1796.             size is reached, the file is renamed and a new file opened.
    1797. 

  1797.             (For example, a ".1" is appended to the name &#8212;
    1798. 

  1798.             if a ".1" file exists, it is renamed ".2",
    1799. 

  1799.             etc.)
    1800. 

  1800.           </p><p>
    1801. 

  1801.             If this is 0, no maximum file size is used.
    1802. 

  1802.           </p></div><div class="section" title="17.1.2.2.3. maxver (integer)"><div class="titlepage"><div><div><h5 class="title"><a name="idp670640"></a>17.1.2.2.3. maxver (integer)</h5></div></div></div><p>
    1803. 

  1803.             Maximum number of old log files to keep around when
    1804. 

  1804.             rolling the output file. Only relevant when
    1805. 

  1805.             <code class="option">destination</code> is <span class="quote">&#8220;<span class="quote">file</span>&#8221;</span>.
    1806. 

  1806.           </p></div></div></div><div class="section" title="17.1.3. Example session"><div class="titlepage"><div><div><h3 class="title"><a name="idp673088"></a>17.1.3. Example session</h3></div></div></div><p>
    1807. 

  1807. 

  1808.           In this example we want to set the global logging to
    1809. 

  1809.           write to the file <code class="filename">/var/log/my_bind10.log</code>,
    1810. 

  1810.           at severity WARN. We want the authoritative server to
    1811. 

  1811.           log at DEBUG with debuglevel 40, to a different file
    1812. 

  1812.           (<code class="filename">/tmp/debug_messages</code>).
    1813. 

  1813. 

  1814.         </p><p>
    1815. 

  1815. 

  1816.           Start <span class="command"><strong>bindctl</strong></span>.
    1817. 

  1817. 

  1818.         </p><p>
    1819. 

  1819. 

  1820.            </p><pre class="screen">["login success "]
    1821. 

  1821. &gt; <strong class="userinput"><code>config show Logging</code></strong>
    1822. 

  1822. Logging/loggers	[]	list
    1823. 

  1823. </pre><p>
    1824. 

  1824. 

  1825.         </p><p>
    1826. 

  1826. 

  1827.           By default, no specific loggers are configured, in which
    1828. 

  1828.           case the severity defaults to INFO and the output is
    1829. 

  1829.           written to stderr.
    1830. 

  1830. 

  1831.         </p><p>
    1832. 

  1832. 

  1833.           Let's first add a default logger:
    1834. 

  1834. 

  1835.         </p><p>
    1836. 

  1836. 

  1837.           </p><pre class="screen"><strong class="userinput"><code>&gt; config add Logging/loggers</code></strong>
    1838. 

  1838. &gt; <strong class="userinput"><code>config show Logging</code></strong>
    1839. 

  1839. Logging/loggers/	list	(modified)
    1840. 

  1840. </pre><p>
    1841. 

  1841. 

  1842.         </p><p>
    1843. 

  1843. 

  1844.           The loggers value line changed to indicate that it is no
    1845. 

  1845.           longer an empty list:
    1846. 

  1846. 

  1847.         </p><p>
    1848. 

  1848. 

  1849.           </p><pre class="screen">&gt; <strong class="userinput"><code>config show Logging/loggers</code></strong>
    1850. 

  1850. Logging/loggers[0]/name	""	string	(default)
    1851. 

  1851. Logging/loggers[0]/severity	"INFO"	string	(default)
    1852. 

  1852. Logging/loggers[0]/debuglevel	0	integer	(default)
    1853. 

  1853. Logging/loggers[0]/additive	false	boolean	(default)
    1854. 

  1854. Logging/loggers[0]/output_options	[]	list	(default)
    1855. 

  1855. </pre><p>
    1856. 

  1856. 

  1857.         </p><p>
    1858. 

  1858. 

  1859.           The name is mandatory, so we must set it. We will also
    1860. 

  1860.           change the severity as well. Let's start with the global
    1861. 

  1861.           logger.
    1862. 

  1862. 

  1863.         </p><p>
    1864. 

  1864. 

  1865.           </p><pre class="screen">&gt; <strong class="userinput"><code>config set Logging/loggers[0]/name *</code></strong>
    1866. 

  1866. &gt; <strong class="userinput"><code>config set Logging/loggers[0]/severity WARN</code></strong>
    1867. 

  1867. &gt; <strong class="userinput"><code>config show Logging/loggers</code></strong>
    1868. 

  1868. Logging/loggers[0]/name	"*"	string	(modified)
    1869. 

  1869. Logging/loggers[0]/severity	"WARN"	string	(modified)
    1870. 

  1870. Logging/loggers[0]/debuglevel	0	integer	(default)
    1871. 

  1871. Logging/loggers[0]/additive	false	boolean	(default)
    1872. 

  1872. Logging/loggers[0]/output_options	[]	list	(default)
    1873. 

  1873. </pre><p>
    1874. 

  1874. 

  1875.         </p><p>
    1876. 

  1876. 

  1877.           Of course, we need to specify where we want the log
    1878. 

  1878.           messages to go, so we add an entry for an output option.
    1879. 

  1879. 

  1880.         </p><p>
    1881. 

  1881. 

  1882.           </p><pre class="screen">&gt; <strong class="userinput"><code> config add Logging/loggers[0]/output_options</code></strong>
    1883. 

  1883. &gt; <strong class="userinput"><code> config show Logging/loggers[0]/output_options</code></strong>
    1884. 

  1884. Logging/loggers[0]/output_options[0]/destination	"console"	string	(default)
    1885. 

  1885. Logging/loggers[0]/output_options[0]/output	"stdout"	string	(default)
    1886. 

  1886. Logging/loggers[0]/output_options[0]/flush	false	boolean	(default)
    1887. 

  1887. Logging/loggers[0]/output_options[0]/maxsize	0	integer	(default)
    1888. 

  1888. Logging/loggers[0]/output_options[0]/maxver	0	integer	(default)
    1889. 

  1889. </pre><p>
    1890. 

  1890. 

  1891. 

  1892.         </p><p>
    1893. 

  1893. 

  1894.           These aren't the values we are looking for.
    1895. 

  1895. 

  1896.         </p><p>
    1897. 

  1897. 

  1898.           </p><pre class="screen">&gt; <strong class="userinput"><code> config set Logging/loggers[0]/output_options[0]/destination file</code></strong>
    1899. 

  1899. &gt; <strong class="userinput"><code> config set Logging/loggers[0]/output_options[0]/output /var/log/bind10.log</code></strong>
    1900. 

  1900. &gt; <strong class="userinput"><code> config set Logging/loggers[0]/output_options[0]/maxsize 204800</code></strong>
    1901. 

  1901. &gt; <strong class="userinput"><code> config set Logging/loggers[0]/output_options[0]/maxver 8</code></strong>
    1902. 

  1902. </pre><p>
    1903. 

  1903. 

  1904.         </p><p>
    1905. 

  1905. 

  1906.           Which would make the entire configuration for this logger
    1907. 

  1907.           look like:
    1908. 

  1908. 

  1909.         </p><p>
    1910. 

  1910. 

  1911.           </p><pre class="screen">&gt; <strong class="userinput"><code> config show all Logging/loggers</code></strong>
    1912. 

  1912. Logging/loggers[0]/name	"*"	string	(modified)
    1913. 

  1913. Logging/loggers[0]/severity	"WARN"	string	(modified)
    1914. 

  1914. Logging/loggers[0]/debuglevel	0	integer	(default)
    1915. 

  1915. Logging/loggers[0]/additive	false	boolean	(default)
    1916. 

  1916. Logging/loggers[0]/output_options[0]/destination	"file"	string	(modified)
    1917. 

  1917. Logging/loggers[0]/output_options[0]/output	"/var/log/bind10.log"	string	(modified)
    1918. 

  1918. Logging/loggers[0]/output_options[0]/flush	false	boolean	(default)
    1919. 

  1919. Logging/loggers[0]/output_options[0]/maxsize	204800	integer	(modified)
    1920. 

  1920. Logging/loggers[0]/output_options[0]/maxver	8	integer	(modified)
    1921. 

  1921. </pre><p>
    1922. 

  1922. 

  1923.         </p><p>
    1924. 

  1924. 

  1925.           That looks OK, so let's commit it before we add the
    1926. 

  1926.           configuration for the authoritative server's logger.
    1927. 

  1927. 

  1928.         </p><p>
    1929. 

  1929. 

  1930.           </p><pre class="screen">&gt; <strong class="userinput"><code> config commit</code></strong></pre><p>
    1931. 

  1931. 

  1932.         </p><p>
    1933. 

  1933. 

  1934.           Now that we have set it, and checked each value along
    1935. 

  1935.           the way, adding a second entry is quite similar.
    1936. 

  1936. 

  1937.         </p><p>
    1938. 

  1938. 

  1939.           </p><pre class="screen">&gt; <strong class="userinput"><code> config add Logging/loggers</code></strong>
    1940. 

  1940. &gt; <strong class="userinput"><code> config set Logging/loggers[1]/name Auth</code></strong>
    1941. 

  1941. &gt; <strong class="userinput"><code> config set Logging/loggers[1]/severity DEBUG</code></strong>
    1942. 

  1942. &gt; <strong class="userinput"><code> config set Logging/loggers[1]/debuglevel 40</code></strong>
    1943. 

  1943. &gt; <strong class="userinput"><code> config add Logging/loggers[1]/output_options</code></strong>
    1944. 

  1944. &gt; <strong class="userinput"><code> config set Logging/loggers[1]/output_options[0]/destination file</code></strong>
    1945. 

  1945. &gt; <strong class="userinput"><code> config set Logging/loggers[1]/output_options[0]/output /tmp/auth_debug.log</code></strong>
    1946. 

  1946. &gt; <strong class="userinput"><code> config commit</code></strong>
    1947. 

  1947. </pre><p>
    1948. 

  1948. 

  1949.         </p><p>
    1950. 

  1950. 

  1951.           And that's it. Once we have found whatever it was we
    1952. 

  1952.           needed the debug messages for, we can simply remove the
    1953. 

  1953.           second logger to let the authoritative server use the
    1954. 

  1954.           same settings as the rest.
    1955. 

  1955. 

  1956.         </p><p>
    1957. 

  1957. 

  1958.           </p><pre class="screen">&gt; <strong class="userinput"><code> config remove Logging/loggers[1]</code></strong>
    1959. 

  1959. &gt; <strong class="userinput"><code> config commit</code></strong>
    1960. 

  1960. </pre><p>
    1961. 

  1961. 

  1962.         </p><p>
    1963. 

  1963. 

  1964.           And every module will now be using the values from the
    1965. 

  1965.           logger named <span class="quote">&#8220;<span class="quote">*</span>&#8221;</span>.
    1966. 

  1966. 

  1967.         </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="idp704416"></a>17.2. Logging Message Format</h2></div></div></div><p>
    1968. 

  1968.           Each message written by BIND 10 to the configured logging
    1969. 

  1969.           destinations comprises a number of components that identify
    1970. 

  1970.           the origin of the message and, if the message indicates
    1971. 

  1971.           a problem, information about the problem that may be
    1972. 

  1972.           useful in fixing it.
    1973. 

  1973.       </p><p>
    1974. 

  1974.           Consider the message below logged to a file:
    1975. 

  1975.           </p><pre class="screen">2011-06-15 13:48:22.034 ERROR [b10-resolver.asiolink]
    1976. 

  1976.     ASIODNS_OPENSOCK error 111 opening TCP socket to 127.0.0.1(53)</pre><p>
    1977. 

  1977.       </p><p>
    1978. 

  1978.         Note: the layout of messages written to the system logging
    1979. 

  1979.         file (syslog) may be slightly different.  This message has
    1980. 

  1980.         been split across two lines here for display reasons; in the
    1981. 

  1981.         logging file, it will appear on one line.)
    1982. 

  1982.       </p><p>
    1983. 

  1983.         The log message comprises a number of components:
    1984. 

  1984. 

  1985.           </p><div class="variablelist"><dl><dt><span class="term">2011-06-15 13:48:22.034</span></dt><dd><p>
    1986. 

  1986.               The date and time at which the message was generated.
    1987. 

  1987.           </p></dd><dt><span class="term">ERROR</span></dt><dd><p>
    1988. 

  1988.               The severity of the message.
    1989. 

  1989.           </p></dd><dt><span class="term">[b10-resolver.asiolink]</span></dt><dd><p>
    1990. 

  1990.             The source of the message.  This comprises two components:
    1991. 

  1991.             the BIND 10 process generating the message (in this
    1992. 

  1992.             case, <span class="command"><strong>b10-resolver</strong></span>) and the module
    1993. 

  1993.             within the program from which the message originated
    1994. 

  1994.             (which in the example is the asynchronous I/O link
    1995. 

  1995.             module, asiolink).
    1996. 

  1996.           </p></dd><dt><span class="term">ASIODNS_OPENSOCK</span></dt><dd><p>
    1997. 

  1997.             The message identification.  Every message in BIND 10
    1998. 

  1998.             has a unique identification, which can be used as an
    1999. 

  1999.             index into the <a class="ulink" href="bind10-messages.html" target="_top"><em class="citetitle">BIND 10 Messages
    2000. 

  2000.             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.
    2001. 

  2001.           </p></dd><dt><span class="term">error 111 opening TCP socket to 127.0.0.1(53)</span></dt><dd><p>
    2002. 

  2002.               A brief description of the cause of the problem.
    2003. 

  2003.               Within this text, information relating to the condition
    2004. 

  2004.               that caused the message to be logged will be included.
    2005. 

  2005.               In this example, error number 111 (an operating
    2006. 

  2006.               system-specific error number) was encountered when
    2007. 

  2007.               trying to open a TCP connection to port 53 on the
    2008. 

  2008.               local system (address 127.0.0.1).  The next step
    2009. 

  2009.               would be to find out the reason for the failure by
    2010. 

  2010.               consulting your system's documentation to identify
    2011. 

  2011.               what error number 111 means.
    2012. 

  2012.           </p></dd></dl></div><p>
    2013. 

  2013.       </p></div></div></div></body></html>
    2014.