Accueil Explorer Aide
Connexion
zorun
/
kea
1
0
Fork 0
Fichiers Tickets 0 Pull Requests 0 Wiki
Aborescence: 0a9b4b2a90
Branches Tags
kea
/
doc
/
guide
/
bind10-guide.html

bind10-guide.html 154 KB
Historique Raw

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

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

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

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

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

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

  7.       and DHCPv6 servers.
    8. 

  8.       </p><p>
    9. 

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

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

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

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

  13.         </p></div></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="preface"><a href="#idp32704">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="#idp38720">1.1. Supported Platforms</a></span></dt><dt><span class="section"><a href="#required-software">1.2. Required Software at Run-time</a></span></dt><dt><span class="section"><a href="#starting_stopping">1.3. Starting and Stopping the Server</a></span></dt><dt><span class="section"><a href="#managing_once_running">1.4. Managing BIND 10</a></span></dt></dl></dd><dt><span class="chapter"><a href="#installation">2. Installation</a></span></dt><dd><dl><dt><span class="section"><a href="#packages">2.1. Packages</a></span></dt><dt><span class="section"><a href="#install-hierarchy">2.2. Install Hierarchy</a></span></dt><dt><span class="section"><a href="#build-requirements">2.3. Building Requirements</a></span></dt><dt><span class="section"><a href="#quickstart">2.4. Quick start</a></span></dt><dt><span class="section"><a href="#install">2.5. Installation from source</a></span></dt><dd><dl><dt><span class="section"><a href="#idp146688">2.5.1. Download Tar File</a></span></dt><dt><span class="section"><a href="#idp149472">2.5.2. Retrieve from Git</a></span></dt><dt><span class="section"><a href="#idp158496">2.5.3. Configure before the build</a></span></dt><dt><span class="section"><a href="#idp171840">2.5.4. Build</a></span></dt><dt><span class="section"><a href="#idp173824">2.5.5. Install</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#bind10">3. Starting BIND10 with <span class="command"><strong>bind10</strong></span></a></span></dt><dd><dl><dt><span class="section"><a href="#start">3.1. Starting BIND 10</a></span></dt><dt><span class="section"><a href="#bind10.config">3.2. Configuration to start processes</a></span></dt></dl></dd><dt><span class="chapter"><a href="#msgq">4. Command channel</a></span></dt><dt><span class="chapter"><a href="#cfgmgr">5. Configuration manager</a></span></dt><dt><span class="chapter"><a href="#cmdctl">6. Remote control daemon</a></span></dt><dd><dl><dt><span class="section"><a href="#cmdctl.spec">6.1. Configuration specification for b10-cmdctl</a></span></dt></dl></dd><dt><span class="chapter"><a href="#bindctl">7. Control and configure user interface</a></span></dt><dt><span class="chapter"><a href="#authserver">8. Authoritative Server</a></span></dt><dd><dl><dt><span class="section"><a href="#idp288016">8.1. Server Configurations</a></span></dt><dt><span class="section"><a href="#datasrc">8.2. Data Source Backends</a></span></dt><dd><dl><dt><span class="section"><a href="#datasource-types">8.2.1. Data source types</a></span></dt><dt><span class="section"><a href="#datasrc-examples">8.2.2. Examples</a></span></dt></dl></dd><dt><span class="section"><a href="#idp357664">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="#idp375872">9.1. Configuration for Incoming Zone Transfers</a></span></dt><dt><span class="section"><a href="#idp381216">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="#idp396992">9.4. Trigger an Incoming Zone Transfer Manually</a></span></dt><dt><span class="section"><a href="#idp400688">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="#idp434672">11.1. Enabling Dynamic Update</a></span></dt><dt><span class="section"><a href="#idp450256">11.2. Access Control</a></span></dt><dt><span class="section"><a href="#idp475168">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="#idp496224">12.1. Access Control</a></span></dt><dt><span class="section"><a href="#idp512960">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="#idp611696">17.1. Logging configuration</a></span></dt><dd><dl><dt><span class="section"><a href="#idp613392">17.1.1. Loggers</a></span></dt><dt><span class="section"><a href="#idp649760">17.1.2. Output Options</a></span></dt><dt><span class="section"><a href="#idp674816">17.1.3. Example session</a></span></dt></dl></dd><dt><span class="section"><a href="#idp705584">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="#idp200656">Special startup components</a></dt></dl></div><div class="preface" title="Preface"><div class="titlepage"><div><div><h2 class="title"><a name="idp32704"></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="#idp38720">1.1. Supported Platforms</a></span></dt><dt><span class="section"><a href="#required-software">1.2. Required Software at Run-time</a></span></dt><dt><span class="section"><a href="#starting_stopping">1.3. Starting and Stopping the Server</a></span></dt><dt><span class="section"><a href="#managing_once_running">1.4. Managing BIND 10</a></span></dt></dl></div><p>
    16. 

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

  17.       interfaces, and DNS tools.
    18. 

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

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

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

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

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

  23.       provides forwarding.
    24. 

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

  25.     </p><p>
    26. 

  26.       This guide covers the experimental prototype of
    27. 

  27.       BIND 10 version 20120712.
    28. 

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

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

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

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

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

  33. 

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

  35.   platforms.
    36. 

  36. 

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

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

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

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

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

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

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

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

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

  46.       </p><p>
    47. 

  47.         BIND 10 requires at least Python 3.1
    48. 

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

  49.         It also works with Python 3.2.
    50. 

  50.       </p><p>
    51. 

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

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

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

  54.       </p><p>
    55. 

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

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

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

  58. 

  59.       </p><p>
    60. 

  60.         The authoritative DNS server uses SQLite3
    61. 

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

  62. 

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

  64.       </p><p>
    65. 

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

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

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

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

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

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

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

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

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

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

  75.         single process.
    76. 

  76.       </p><p>
    77. 

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

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

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

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

  81.         processes as needed.
    82. 

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

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

  84.       </p><p>
    85. 

  85. 

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

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

  88.               Authoritative DNS server.
    89. 

  89.               This process serves DNS requests.
    90. 

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

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

  92.               Configuration manager.
    93. 

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

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

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

  96.               Command and control service.
    97. 

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

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

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

  100.               Dynamic DNS update service.
    101. 

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

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

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

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

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

  106.               Message bus daemon.
    107. 

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

  108.               BIND 10 processes.
    109. 

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

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

  111.               Recursive name server.
    112. 

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

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

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

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

  116.               Socket creator daemon.
    117. 

  117.               This process creates sockets used by
    118. 

  118.               network-listening BIND 10 processes.
    119. 

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

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

  121.               Statistics collection daemon.
    122. 

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

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

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

  125.               HTTP server for statistics reporting.
    126. 

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

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

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

  129.               Incoming zone transfer service.
    130. 

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

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

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

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

  134.               Outgoing zone transfer service.
    135. 

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

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

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

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

  139.               Secondary zone manager.
    140. 

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

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

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

  143.       </p><p>
    144. 

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

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

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

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

  148.         directly with the system:
    149. 

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

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

  151.               Interactive administration interface.
    152. 

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

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

  154.               BIND 10.
    155. 

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

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

  157.               Zone file loader.
    158. 

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

  159.               BIND 10.
    160. 

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

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

  162.               User access control.
    163. 

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

  164.               to manage BIND 10.
    165. 

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

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

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

  168. 

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

  170.     </p><p>
    171. 

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

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

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

  174.       documentation and code examples.
    175. 

  175. 

  176. 

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

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

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

  180.         the BIND 10 suite.
    181. 

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

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

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

  184.       </p><p>
    185. 

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

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

  187.         all the prerequisite packages.
    188. 

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

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

  190.         complete BIND 10 installation:
    191. 

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

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

  193.               general tools and diagnostic clients.
    194. 

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

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

  196.             configuration files.
    197. 

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

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

  199.               libraries and python modules.
    200. 

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

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

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

  203.               are not run independently.
    204. 

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

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

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

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

  208.               commands used by the system administrator.
    209. 

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

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

  211.               configuration specifications.
    212. 

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

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

  214.               this guide and other supplementary documentation.
    215. 

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

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

  217.               manual pages (online documentation).
    218. 

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

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

  220.               data source and configuration databases.
    221. 

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

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

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

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

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

  226.           program development tools.
    227. 

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

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

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

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

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

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

  233.           Building from source code requires the Boost
    234. 

  234.           build-time headers
    235. 

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

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

  237.   
    238. 

  238.   
    239. 

  239.         </p><p>
    240. 

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

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

  242.           development include headers.
    243. 

  243.         </p><p>
    244. 

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

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

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

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

  248.         </p><p>
    249. 

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

  250.           for system-specific installation tips.
    251. 

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  279.             Test the new zone.
    280. 

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

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

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

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

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

  285.         packages from operating system vendors.)
    286. 

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

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

  288.           obtain the source code.
    289. 

  289.         </p><p>
    290. 

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

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

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

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

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

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

  296.           environment is not recommended.
    297. 

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

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

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

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

  301.             These may need to be installed.
    302. 

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

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

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

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

  306.           development is public.
    307. 

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

  308.           branch.
    309. 

  309.         </p><p>
    310. 

  310.           The code can be checked out from
    311. 

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

  312.           for example:
    313. 

  313. 

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

  315.         </p><p>
    316. 

  316.           When checking out the code from
    317. 

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

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

  319.           related build files.
    320. 

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

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

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

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

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

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

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

  327.           and related commands.
    328. 

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

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

  330.           details.
    331. 

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

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

  333.         </p><p>
    334. 

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

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

  336. 

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

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

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

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

  341.                 standard execution path.
    342. 

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

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

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

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

  346. 

  347.         </p><p>
    348. 

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

  349.     find the Boost headers, find the
    350. 

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

  351. 

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

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

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

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

  356.         </p><p>
    357. 

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

  358.           dependencies.
    359. 

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

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

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

  362. 

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

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

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

  366.           and documentation, run:
    367. 

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

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

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

  370.       starts up the required processes.
    371. 

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

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

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

  374.     </p><p>
    375. 

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

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

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

  378.       Then it starts the other modules.
    379. 

  379.     </p><p>
    380. 

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

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

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

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

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

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

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

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

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

  389.       network services.
    390. 

  390.     </p><p>
    391. 

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

  392.       master process will also start up
    393. 

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

  394.       communicate with the system, and
    395. 

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

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

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

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

  399.         get additional debugging or diagnostic output.
    400. 

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

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

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

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

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

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

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

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

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

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

  410. 	components.
    411. 

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

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

  413. 	an abstraction of a process.
    414. 

  414.       </p><p>
    415. 

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

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

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

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

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

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

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

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

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

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

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

  426. 	how to start it.
    427. 

  427.       </p><p>
    428. 

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

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

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

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

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

  433. 	for them:
    434. 

  434. 

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

  436.       </p><p>
    437. 

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  451. 	can't fail).
    452. 

  452.       </p><p>
    453. 

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

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

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

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

  457. 	it at the default is enough.
    458. 

  458.       </p><p>
    459. 

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

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

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

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

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

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

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

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

  467. 

  468.       </p><p>
    469. 

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

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

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

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

  473.         executable name.)
    474. 

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

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

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

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

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

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

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

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

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

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

  484. 

  485. 

  486. 

  487.         </p><p>
    488. 

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

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

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

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

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

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

  494.         this, with the same config:
    495. 

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

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

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

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

  499.       </p><p>
    500. 

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

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

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

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

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

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

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

  507. 	implemented.
    508. 

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

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

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

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

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

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

  514.         channel.
    515. 

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

  516.         configurations.
    517. 

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

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

  519.       </p><p>
    520. 

  520.         Administrators do not communicate directly with the
    521. 

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

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

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

  524.         for this interprocess communication.
    525. 

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

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

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

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

  529.          modules of configuration changes.
    530. 

  530.       </p><p>
    531. 

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

  532.         daemons and other components receive their configurations
    533. 

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

  534.         command channel.
    535. 

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

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

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

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

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

  540.           The development prototype release only provides
    541. 

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

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

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

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

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

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

  547.         specifications and all current settings to the
    548. 

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

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

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

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

  552.       </p><p>
    553. 

  553.         The stored configuration file is at
    554. 

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

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

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

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

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

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

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

  561.         administrator.
    562. 

  562.       </p><p>
    563. 

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

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

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

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

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

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

  569.       administrators and the BIND 10 system.
    570. 

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

  571.       Authentication for username and password validation.
    572. 

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

  573.       BIND 10.
    574. 

  574.     </p><p>
    575. 

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

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

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

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

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

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

  581.     </p><p>
    582. 

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

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

  584.       Configuration changes are actually commands to
    585. 

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

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

  587.       such as a RSA PRIVATE KEY.
    588. 

  588.       The default location is at
    589. 

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

  590.       (A sample key is at
    591. 

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

  592.       It also uses a certificate located at
    593. 

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

  594.       (A sample certificate is at
    595. 

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

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

  597.       certification authority.
    598. 

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

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

  600.       client (at this time).
    601. 

  601. 

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

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

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

  605.       administrator.
    606. 

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

  607.       the sample key and certificate.
    608. 

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

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

  610.       the user account file located at
    611. 

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

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

  613.       hashed password, and salt.
    614. 

  614.       (A sample file is at
    615. 

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

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

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

  618.     </p><p>
    619. 

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

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

  621.     </p><p>
    622. 

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

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

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

  625.       line argument.
    626. 

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

  627.       by default.  This can be
    628. 

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

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

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

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

  632.         user accounts database (the default is
    633. 

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

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

  635.         PEM certificate file (the default is
    636. 

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

  637.         and
    638. 

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

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

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

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

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

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

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

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

  646.       configuring BIND 10.
    647. 

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

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

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

  650.       components.
    651. 

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

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

  653.       communicate to any other components directly.
    654. 

  654.     </p><p>
    655. 

  655.       Configuration changes are actually commands to
    656. 

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

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

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

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

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

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

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

  663.     </p><p>
    664. 

  664.     </p></div><div class="chapter" title="Chapter 8. Authoritative Server"><div class="titlepage"><div><div><h2 class="title"><a name="authserver"></a>Chapter 8. Authoritative Server</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#idp288016">8.1. Server Configurations</a></span></dt><dt><span class="section"><a href="#datasrc">8.2. Data Source Backends</a></span></dt><dd><dl><dt><span class="section"><a href="#datasource-types">8.2.1. Data source types</a></span></dt><dt><span class="section"><a href="#datasrc-examples">8.2.2. Examples</a></span></dt></dl></dd><dt><span class="section"><a href="#idp357664">8.3. Loading Master Zones Files</a></span></dt></dl></div><p>
    665. 

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

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

  667.       data backends.
    668. 

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

  669.       process.
    670. 

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

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

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

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

  674.         The configuration data items are:
    675. 

  675. 

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

  677.                  the SQLite3 database file.
    678. 

  678. 

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

  680. can use various data source backends.
    681. 

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

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

  683.       The list items include:
    684. 

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

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

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

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

  688.       and
    689. 

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

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

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

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

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

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

  695. 

  696.       By default, this is empty.
    697. 

  697. 

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

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

  700.         memory data source.
    701. 

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

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

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

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

  705.         must be an SQLite3 database.
    706. 

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

  707. 

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  723.         </p><p>
    724. 

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

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

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

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

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

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

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

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

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

  733.       statistics information to
    734. 

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

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

  736.       The default is 60.
    737. 

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

  738. 

  739.       </p><p>
    740. 

  740. 

  741.         The configuration commands are:
    742. 

  742. 

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

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

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

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

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

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

  749.       and
    750. 

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

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

  752. 

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

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

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

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

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

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

  759.       to send its statistics data to
    760. 

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

  761.       immediately.
    762. 

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

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

  764.       select the process ID to stop.
    765. 

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

  766.       if configured.)
    767. 

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

  768. 

  769.       </p></div><div class="section" title="8.2. Data Source Backends"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="datasrc"></a>8.2. Data Source Backends</h2></div></div></div><p>
    770. 

  770.         Bind 10 has the concept of data sources. A data source is a place
    771. 

  771.         where authoritative zone data reside and where they can be served
    772. 

  772.         from. This can be a master file, a database or something completely
    773. 

  773.         different.
    774. 

  774.       </p><p>
    775. 

  775.         Once a query arrives, <span class="command"><strong>b10-auth</strong></span> goes through a
    776. 

  776.         configured list of data sources and finds the one containing a best
    777. 

  777.         matching zone. From the equally good ones, the first one is taken.
    778. 

  778.         This data source is then used to answer the query.
    779. 

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

  780.         In the development prototype release, <span class="command"><strong>b10-auth</strong></span>
    781. 

  781.         can serve data from a SQLite3 data source backend and from master
    782. 

  782.         files.
    783. 

  783.         Upcoming versions will be able to use multiple different
    784. 

  784.         data sources, such as MySQL and Berkeley DB.
    785. 

  785.       </p></div><p>
    786. 

  786.         The configuration is located in data_sources/classes. Each item there
    787. 

  787.         represents one RR class and a list used to answer queries for that
    788. 

  788.         class. The default contains two classes. The CH class contains a static
    789. 

  789.         data source &#8212; one that serves things like
    790. 

  790.         <span class="quote">&#8220;<span class="quote">AUTHORS.BIND.</span>&#8221;</span>. The IN class contains single SQLite3
    791. 

  791.         data source with database file located at
    792. 

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

  793.       </p><p>
    794. 

  794.         Each data source has several options. The first one is
    795. 

  795.         <code class="varname">type</code>, which specifies the type of data source to
    796. 

  796.         use. Valid types include the ones listed below, but bind10 uses
    797. 

  797.         dynamically loaded modules for them, so there may be more in your
    798. 

  798.         case. This option is mandatory.
    799. 

  799.       </p><p>
    800. 

  800.         Another option is <code class="varname">params</code>. This option is type
    801. 

  801.         specific; it holds different data depending on the type
    802. 

  802.         above. Also, depending on the type, it could be possible to omit it.
    803. 

  803.       </p><p>
    804. 

  804.         There are two options related to the so-called cache. If you enable
    805. 

  805.         cache, zone data from the data source are loaded into memory.
    806. 

  806.         Then, when answering a query, <span class="command"><strong>b10-auth</strong></span> looks
    807. 

  807.         into the memory only instead of the data source, which speeds
    808. 

  808.         answering up. The first option is <code class="varname">cache-enable</code>,
    809. 

  809.         a boolean value turning the cache on and off (off is the default).
    810. 

  810.         The second one, <code class="varname">cache-zones</code>, is a list of zone
    811. 

  811.         origins to load into in-memory. Remember that zones in the data source
    812. 

  812.         not listed here will not be loaded and will not be available at all.
    813. 

  813.       </p><div class="section" title="8.2.1. Data source types"><div class="titlepage"><div><div><h3 class="title"><a name="datasource-types"></a>8.2.1. Data source types</h3></div></div></div><p>
    814. 

  814.           As mentioned, the type used by default is <span class="quote">&#8220;<span class="quote">sqlite3</span>&#8221;</span>.
    815. 

  815.           It has single configuration option inside <code class="varname">params</code>
    816. 

  816.           &#8212; <code class="varname">database_file</code>, which contains the path
    817. 

  817.           to the sqlite3 file containing the data.
    818. 

  818.         </p><p>
    819. 

  819.           Another type is called <span class="quote">&#8220;<span class="quote">MasterFiles</span>&#8221;</span>. This one is
    820. 

  820.           slightly special. The data are stored in RFC1034 master files.
    821. 

  821.           Because answering directly from them would be impractical,
    822. 

  822.           this type mandates the cache to be enabled. Also, the list of
    823. 

  823.           zones (<code class="varname">cache-zones</code>) should be omitted. The
    824. 

  824.           <code class="varname">params</code> is a dictionary mapping from zone
    825. 

  825.           origins to the files they reside in.
    826. 

  826.         </p></div><div class="section" title="8.2.2. Examples"><div class="titlepage"><div><div><h3 class="title"><a name="datasrc-examples"></a>8.2.2. Examples</h3></div></div></div><p>
    827. 

  827.           As this is one of the more complex configurations of Bind10,
    828. 

  828.           we show some examples. They all assume they start with default
    829. 

  829.           configuration.
    830. 

  830.         </p><p>
    831. 

  831.           First, let's disable the static data source
    832. 

  832.           (<span class="quote">&#8220;<span class="quote">VERSION.BIND</span>&#8221;</span> and friends). As it is the only
    833. 

  833.           data source in the CH class, we can remove the whole class.
    834. 

  834. 

  835.           </p><pre class="screen">&gt; <strong class="userinput"><code>config remove data_sources/classes CH</code></strong>
    836. 

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

  837.         </p><p>
    838. 

  838.           Another one, let's say our default data source contains zones
    839. 

  839.           <span class="quote">&#8220;<span class="quote">example.org.</span>&#8221;</span> and <span class="quote">&#8220;<span class="quote">example.net.</span>&#8221;</span>.
    840. 

  840.           We want them to be served from memory to make the answering
    841. 

  841.           faster.
    842. 

  842. 

  843.           </p><pre class="screen">&gt; <strong class="userinput"><code>config set data_sources/classes/IN[0]/cache-enable true</code></strong>
    844. 

  844. &gt; <strong class="userinput"><code>config add data_sources/classes/IN[0]/cache-zones example.org.</code></strong>
    845. 

  845. &gt; <strong class="userinput"><code>config add data_sources/classes/IN[0]/cache-zones example.net.</code></strong>
    846. 

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

  847. 

  848.           Now every time the zone in the data source is changed by the
    849. 

  849.           operator, Bind10 needs to be told to reload it, by
    850. 

  850.           </p><pre class="screen">&gt; <strong class="userinput"><code>Auth loadzone example.org</code></strong></pre><p>
    851. 

  851.           You don't need to do this when the zone is modified by
    852. 

  852.           XfrIn, it does so automatically.
    853. 

  853.         </p><p>
    854. 

  854.           Now, the last example is when there are master files we want to
    855. 

  855.           serve in addition to whatever is inside the sqlite3 database.
    856. 

  856. 

  857.           </p><pre class="screen">&gt; <strong class="userinput"><code>config add data_sources/classes/IN</code></strong>
    858. 

  858. &gt; <strong class="userinput"><code>config set data_sources/classes/IN[1]/type MasterFiles</code></strong>
    859. 

  859. &gt; <strong class="userinput"><code>config set data_sources/classes/IN[1]/cache-enable true</code></strong>
    860. 

  860. &gt; <strong class="userinput"><code>config set data_sources/classes/IN[1]/params { "example.org": "/path/to/example.org", "example.com": "/path/to/example.com" }</code></strong>
    861. 

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

  862. 

  863.           Initially, a map value has to be set, but this value may be an
    864. 

  864.           empty map. After that, key/value pairs can be added with 'config
    865. 

  865.           add' and keys can be removed with 'config remove'. The initial
    866. 

  866.           value may be an empty map, but it has to be set before zones are
    867. 

  867.           added or removed.
    868. 

  868. 

  869.           </p><pre class="screen">
    870. 

  870. &gt; <strong class="userinput"><code>config set data_sources/classes/IN[1]/params {}</code></strong>
    871. 

  871. &gt; <strong class="userinput"><code>config add data_sources/classes/IN[1]/params another.example.org /path/to/another.example.org</code></strong>
    872. 

  872. &gt; <strong class="userinput"><code>config add data_sources/classes/IN[1]/params another.example.com /path/to/another.example.com</code></strong>
    873. 

  873. &gt; <strong class="userinput"><code>config remove data_sources/classes/IN[1]/params another.example.org</code></strong>
    874. 

  874.           </pre><p>
    875. 

  875. 

  876.           <span class="command"><strong>bindctl</strong></span>. To reload a zone, you the same command
    877. 

  877.           as above.
    878. 

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

  879.         There's also <code class="varname">Auth/database_file</code> configuration
    880. 

  880.         variable, pointing to a sqlite3 database file. This is no longer
    881. 

  881.         used by <span class="command"><strong>b10-auth</strong></span>, but it is left in place for
    882. 

  882.         now, since other modules use it. Once <span class="command"><strong>b10-xfrin</strong></span>,
    883. 

  883.         <span class="command"><strong>b10-xfrout</strong></span> and <span class="command"><strong>b10-ddns</strong></span>
    884. 

  884.         are ported to the new configuration, this will disappear. But for
    885. 

  885.         now, make sure that if you use any of these modules, the new
    886. 

  886.         and old configuration correspond. The defaults are consistent, so
    887. 

  887.         unless you tweaked either the new or the old configuration, you're
    888. 

  888.         good.
    889. 

  889.       </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="idp357664"></a>8.3. Loading Master Zones Files</h2></div></div></div><p>
    890. 

  890.         RFC 1035 style DNS master zone files may imported
    891. 

  891.         into a BIND 10 SQLite3 data source by using the
    892. 

  892.         <span class="command"><strong>b10-loadzone</strong></span> utility.
    893. 

  893.       </p><p>
    894. 

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

  895.         special directives (control entries):
    896. 

  896. 

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

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

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

  900.                 records that don't include a TTL.
    901. 

  901.               </dd></dl></div><p>
    902. 

  902. 

  903.       </p><p>
    904. 

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

  905.         default origin for loaded zone file records.
    906. 

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

  907.         In the development prototype release, only the SQLite3 back
    908. 

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

  909.         By default, it stores the zone data in
    910. 

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

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

  912.         database filename.
    913. 

  913.         Multiple zones are stored in a single SQLite3 zone database.
    914. 

  914.       </p></div><p>
    915. 

  915.         If you reload a zone already existing in the database,
    916. 

  916.         all records from that prior zone disappear and a whole new set
    917. 

  917.         appears.
    918. 

  918.       </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="#idp375872">9.1. Configuration for Incoming Zone Transfers</a></span></dt><dt><span class="section"><a href="#idp381216">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="#idp396992">9.4. Trigger an Incoming Zone Transfer Manually</a></span></dt><dt><span class="section"><a href="#idp400688">9.5. Incoming Transfers with In-memory Datasource</a></span></dt></dl></div><p>
    919. 

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

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

  921.       When received, the zone is stored in the corresponding BIND 10
    922. 

  922.       data source, and its records can be served by
    923. 

  923.       <span class="command"><strong>b10-auth</strong></span>.
    924. 

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

  925.       automated SOA checks), this allows the BIND 10 server to
    926. 

  926.       provide <span class="emphasis"><em>secondary</em></span> service.
    927. 

  927.     </p><p>
    928. 

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

  929.       IXFR.  Due to some implementation limitations of the current
    930. 

  930.       development release, however, it only tries AXFR by default,
    931. 

  931.       and care should be taken to enable IXFR.
    932. 

  932.     </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="idp375872"></a>9.1. Configuration for Incoming Zone Transfers</h2></div></div></div><p>
    933. 

  933.         In practice, you need to specify a list of secondary zones to
    934. 

  934.         enable incoming zone transfers for these zones (you can still
    935. 

  935.         trigger a zone transfer manually, without a prior configuration
    936. 

  936.         (see below)).
    937. 

  937.       </p><p>
    938. 

  938.         For example, to enable zone transfers for a zone named "example.com"
    939. 

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

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

  941. 

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

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

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

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

  946. 

  947.       (We assume there has been no zone configuration before).
    948. 

  948.       </p></div><div class="section" title="9.2. Enabling IXFR"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp381216"></a>9.2. Enabling IXFR</h2></div></div></div><p>
    949. 

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

  950.         zone transfers by default.  To enable IXFR for zone transfers
    951. 

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

  952.         configuration parameter to <strong class="userinput"><code>true</code></strong>.
    953. 

  953.         In the above example of configuration sequence, you'll need
    954. 

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

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

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

  957.       One reason why IXFR is disabled by default in the current
    958. 

  958.       release is because it does not support automatic fallback from IXFR to
    959. 

  959.       AXFR when it encounters a primary server that doesn't support
    960. 

  960.       outbound IXFR (and, not many existing implementations support
    961. 

  961.       it).  Another, related reason is that it does not use AXFR even
    962. 

  962.       if it has no knowledge about the zone (like at the very first
    963. 

  963.       time the secondary server is set up).  IXFR requires the
    964. 

  964.       "current version" of the zone, so obviously it doesn't work
    965. 

  965.       in this situation and AXFR is the only workable choice.
    966. 

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

  967.       make this selection automatically.
    968. 

  968.       These features will be implemented in a near future
    969. 

  969.       version, at which point we will enable IXFR by default.
    970. 

  970.       </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>
    971. 

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

  972.         <span class="command"><strong>bind10</strong></span>.
    973. 

  973.         It keeps track of SOA refresh, retry, and expire timers
    974. 

  974.         and other details for BIND 10 to perform as a slave.
    975. 

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

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

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

  978.         to start an inbound zone transfer.
    979. 

  979.         The secondary manager resets its counters when a new zone is
    980. 

  980.         transferred in.
    981. 

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

  982.         Access control (such as allowing notifies) is not yet provided.
    983. 

  983.         The primary/secondary service is not yet complete.
    984. 

  984.       </p></div><p>
    985. 

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

  986.         to configure the server to be a secondary for the example zone:
    987. 

  987. 

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

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

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

  991. 

  992.       </p><p>
    993. 

  993.         If the zone does not exist in the data source already
    994. 

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

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

  996.         to transfer the zone in.
    997. 

  997.       </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="idp396992"></a>9.4. Trigger an Incoming Zone Transfer Manually</h2></div></div></div><p>
    998. 

  998.         To manually trigger a zone transfer to retrieve a remote zone,
    999. 

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

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

  1001. 

  1002.         </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>
    1003. 

  1003.       </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="idp400688"></a>9.5. Incoming Transfers with In-memory Datasource</h2></div></div></div><p>
    1004. 

  1004.         In the case of an incoming zone transfer, the received zone is
    1005. 

  1005.         first stored in the corresponding BIND 10 datasource. In
    1006. 

  1006.         case the secondary zone is served by an in-memory datasource
    1007. 

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

  1008.         automatically sent a <code class="varname">loadzone</code> command to
    1009. 

  1009.         reload the corresponding zone into memory from the backend.
    1010. 

  1010.       </p><p>
    1011. 

  1011. 	The administrator doesn't have to do anything for
    1012. 

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

  1013. 	zone, except for the configuration such as the one described in
    1014. 

  1014. 	<a class="xref" href="#datasrc" title="8.2. Data Source Backends">Section 8.2, &#8220;Data Source Backends&#8221;</a>.
    1015. 

  1015.       </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>
    1016. 

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

  1017.       <span class="command"><strong>bind10</strong></span>.
    1018. 

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

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

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

  1021.       which handles the rest of this request processing.
    1022. 

  1022.       This is used to provide primary DNS service to share zones
    1023. 

  1023.       to secondary name servers.
    1024. 

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

  1025.       NOTIFY messages to secondary servers.
    1026. 

  1026.     </p><p>
    1027. 

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

  1028.       can be used to control accessibility of the outbound zone
    1029. 

  1029.       transfer service.
    1030. 

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

  1031.       perform zone transfers for any zones:
    1032. 

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

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

  1034.       You can change this to, for example, rejecting all transfer
    1035. 

  1035.       requests by default while allowing requests for the transfer
    1036. 

  1036.       of zone "example.com" from 192.0.2.1 and 2001:db8::1 as follows:
    1037. 

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

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

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

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

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

  1042. &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>
    1043. 

  1043.         In the above example the lines
    1044. 

  1044.         for <code class="option">transfer_acl</code> were divided for
    1045. 

  1045.         readability.  In the actual input it must be in a single line.
    1046. 

  1046.     </p></div><p>
    1047. 

  1047.       If you want to require TSIG in access control, a system wide TSIG
    1048. 

  1048.       "key ring" must be configured.
    1049. 

  1049.       For example, to change the previous example to allowing requests
    1050. 

  1050.       from 192.0.2.1 signed by a TSIG with a key name of
    1051. 

  1051.       "key.example", you'll need to do this:
    1052. 

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

  1053. &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>
    1054. 

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

  1055.       will use the system wide keyring to check
    1056. 

  1056.       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>
    1057. 

  1057.         The way to specify zone specific configuration (ACLs, etc) is
    1058. 

  1058.         likely to be changed.
    1059. 

  1059.     </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="#idp434672">11.1. Enabling Dynamic Update</a></span></dt><dt><span class="section"><a href="#idp450256">11.2. Access Control</a></span></dt><dt><span class="section"><a href="#idp475168">11.3. Miscellaneous Operational Issues</a></span></dt></dl></div><p>
    1060. 

  1060.       BIND 10 supports the server side of the Dynamic DNS Update
    1061. 

  1061.       (DDNS) protocol as defined in RFC 2136.
    1062. 

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

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

  1064.       process if configured so.
    1065. 

  1065.     </p><p>
    1066. 

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

  1067.       receives an UPDATE request, it internally forwards the request
    1068. 

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

  1069.       this request processing.
    1070. 

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

  1071.       will send a response to the client as specified in RFC 2136
    1072. 

  1072.       (NOERROR for successful update, REFUSED if rejected due to
    1073. 

  1073.       ACL check, etc).
    1074. 

  1074.       If the zone has been changed as a result, it will internally
    1075. 

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

  1076.       servers will be notified via the DNS NOTIFY protocol.
    1077. 

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

  1078.       zone (as described in
    1079. 

  1079.       <a class="xref" href="#datasrc" title="8.2. Data Source Backends">Section 8.2, &#8220;Data Source Backends&#8221;</a>),
    1080. 

  1080.       <span class="command"><strong>b10-ddns</strong></span> will also
    1081. 

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

  1082.       will re-cache the updated zone content if necessary.
    1083. 

  1083.     </p><p>
    1084. 

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

  1085.       both UDP and TCP, and both IPv6 and IPv4; for TCP requests,
    1086. 

  1086.       however, it terminates the TCP connection immediately after
    1087. 

  1087.       each single request has been processed.  Clients cannot reuse the
    1088. 

  1088.       same TCP connection for multiple requests. (This is a current
    1089. 

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

  1090.       While RFC 2136 doesn't specify anything about such reuse of TCP
    1091. 

  1091.       connection, there is no reason for disallowing it as RFC 1035
    1092. 

  1092.       generally allows multiple requests sent over a single TCP
    1093. 

  1093.       connection.  BIND 9 supports such reuse.)
    1094. 

  1094.     </p><p>
    1095. 

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

  1096.       update forwarding for secondary zones.
    1097. 

  1097.       If it receives an update request for a secondary zone, it will
    1098. 

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

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

  1100. 	  For feature completeness, update forwarding should be
    1101. 

  1101. 	  eventually supported.  But currently it's considered a lower
    1102. 

  1102. 	  priority task and there is no specific plan of implementing
    1103. 

  1103. 	  this feature.
    1104. 

  1104. 

  1105.       </p></div><p>
    1106. 

  1106.     </p><div class="section" title="11.1. Enabling Dynamic Update"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp434672"></a>11.1. Enabling Dynamic Update</h2></div></div></div><p>
    1107. 

  1107.         First off, it must be made sure that a few components on which
    1108. 

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

  1109.         which are <span class="command"><strong>b10-auth</strong></span>
    1110. 

  1110.         and <span class="command"><strong>b10-zonemgr</strong></span>.
    1111. 

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

  1112.         configured to run; otherwise the notification after an update
    1113. 

  1113.         (see above) will fail with a timeout, suspending the DDNS
    1114. 

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

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

  1116.         log message for further details).
    1117. 

  1117.         If BIND 10 is already configured to provide authoritative DNS
    1118. 

  1118.         service they should normally be configured to run already.
    1119. 

  1119.       </p><p>
    1120. 

  1120.         Second, for the obvious reason dynamic update requires that the
    1121. 

  1121.         underlying data source storing the zone data be writable.
    1122. 

  1122.         In the current implementation this means the zone must be stored
    1123. 

  1123.         in an SQLite3-based data source.
    1124. 

  1124. 	Also, in this development version, the <span class="command"><strong>b10-ddns</strong></span>
    1125. 

  1125. 	component configures itself with the data source referring to the
    1126. 

  1126.         <code class="varname">database_file</code> configuration parameter of
    1127. 

  1127.         <span class="command"><strong>b10-auth</strong></span>.
    1128. 

  1128.         So this information must be configured correctly before starting
    1129. 

  1129.         <span class="command"><strong>b10-ddns</strong></span>.
    1130. 

  1130. 

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

  1132.             The way to configure data sources is now being revised.
    1133. 

  1133.             Configuration on the data source for DDNS will be very
    1134. 

  1134.             likely to be changed in a backward incompatible manner in
    1135. 

  1135.             a near future version.
    1136. 

  1136.         </p></div><p>
    1137. 

  1137.       </p><p>
    1138. 

  1138. 	In general, if something goes wrong regarding the dependency
    1139. 

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

  1140. 	related event at the warning or error level.
    1141. 

  1141. 	It's advisable to check the log message when you first enable
    1142. 

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

  1143. 	warning or error log message.
    1144. 

  1144.       </p><p>
    1145. 

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

  1146.         needs to be explicitly configured to run.
    1147. 

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

  1148.         utility.  For example:
    1149. 

  1149.       </p><pre class="screen">
    1150. 

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

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

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

  1153. &gt; <strong class="userinput"><code>config commit</code></strong>
    1154. 

  1154. </pre><p>
    1155. 

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

  1156. 	  In theory <code class="varname">kind</code> could be omitted because
    1157. 

  1157. 	  "dispensable" is its default.
    1158. 

  1158. 	  But there's some peculiar behavior (which should be a
    1159. 

  1159. 	  bug and should be fixed eventually; see Trac ticket #2064)
    1160. 

  1160. 	  with <span class="command"><strong>bindctl</strong></span> and you'll still need to
    1161. 

  1161. 	  specify that explicitly.  Likewise, <code class="varname">address</code>
    1162. 

  1162. 	  may look unnecessary because <span class="command"><strong>b10-ddns</strong></span>
    1163. 

  1163. 	  would start and work without specifying it.  But for it
    1164. 

  1164. 	  to shutdown gracefully this parameter should also be
    1165. 

  1165. 	  specified.
    1166. 

  1166.       </p></div><p>
    1167. 

  1167.       </p></div><div class="section" title="11.2. Access Control"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp450256"></a>11.2. Access Control</h2></div></div></div><p>
    1168. 

  1168.         By default, <span class="command"><strong>b10-ddns</strong></span> rejects any update
    1169. 

  1169.         requests from any clients by returning a REFUSED response.
    1170. 

  1170.         To allow updates to take effect, an access control rule
    1171. 

  1171.         (called update ACL) with a policy allowing updates must explicitly be
    1172. 

  1172.         configured.
    1173. 

  1173.         Update ACL must be configured per zone basis in the
    1174. 

  1174.         <code class="varname">zones</code> configuration parameter of
    1175. 

  1175.         <span class="command"><strong>b10-ddns</strong></span>.
    1176. 

  1176.         This is a list of per-zone configurations regarding DDNS.
    1177. 

  1177.         Each list element consists of the following parameters:
    1178. 

  1178.         </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
    1179. 

  1179.                 (normally <span class="quote">&#8220;<span class="quote">IN</span>&#8221;</span>, and in that case
    1180. 

  1180. 		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>
    1181. 

  1181.         The syntax of the ACL is the same as ACLs for other
    1182. 

  1182.         components.
    1183. 

  1183.         Specific examples are given below.
    1184. 

  1184.       </p><p>
    1185. 

  1185.         In general, an update ACL rule that allows an update request
    1186. 

  1186.         should be configured with a TSIG key.
    1187. 

  1187.         This is an example update ACL that allows updates to the zone
    1188. 

  1188.         named <span class="quote">&#8220;<span class="quote">example.org</span>&#8221;</span> (of default RR class <span class="quote">&#8220;<span class="quote">IN</span>&#8221;</span>)
    1189. 

  1189.         from clients that send requests signed with a TSIG whose
    1190. 

  1190.         key name is "key.example.org" (and refuses all others):
    1191. 

  1191.       </p><pre class="screen">
    1192. 

  1192. &gt; <strong class="userinput"><code>config add DDNS/zones</code></strong>
    1193. 

  1193. &gt; <strong class="userinput"><code>config set DDNS/zones[0]/origin example.org</code></strong>
    1194. 

  1194. &gt; <strong class="userinput"><code>config add DDNS/zones[0]/update_acl {"action": "ACCEPT", "key": "key.example.org"}</code></strong>
    1195. 

  1195. &gt; <strong class="userinput"><code>config commit</code></strong>
    1196. 

  1196. </pre><p>
    1197. 

  1197.       The TSIG key must be configured system wide
    1198. 

  1198.       (see <a class="xref" href="#xfrout" title="Chapter 10. Outbound Zone Transfers">Chapter 10, <i>Outbound Zone Transfers</i></a>.)
    1199. 

  1199.       </p><p>
    1200. 

  1200.         Multiple rules can be specified in the ACL, and an ACL rule
    1201. 

  1201.         can consist of multiple constraints, such as a combination of
    1202. 

  1202.         IP address and TSIG.
    1203. 

  1203.         The following configuration sequence will add a new rule to
    1204. 

  1204.         the ACL created in the above example.  This additional rule
    1205. 

  1205. 	allows update requests sent from a client
    1206. 

  1206.         using TSIG key name of "key.example" (different from the
    1207. 

  1207.         key used in the previous example) and has an IPv6 address of ::1.
    1208. 

  1208.       </p><pre class="screen">
    1209. 

  1209. &gt; <strong class="userinput"><code>config add DDNS/zones[0]/update_acl {"action": "ACCEPT", "from": "::1", "key": "key.example"}</code></strong>
    1210. 

  1210. &gt; <strong class="userinput"><code>config show DDNS/zones[0]/update_acl</code></strong>
    1211. 

  1211. DDNS/zones[0]/update_acl[0]     {"action": "ACCEPT", "key": "key.example.org"} any (modified)
    1212. 

  1212. DDNS/zones[0]/update_acl[1]     {"action": "ACCEPT", "from": "::1", "key": "key.example"} any (modified)
    1213. 

  1213. &gt; <strong class="userinput"><code>config commit</code></strong>
    1214. 

  1214. </pre><p>
    1215. 

  1215.       (Note the "add" in the first line.  Before this sequence, we
    1216. 

  1216.       have had only entry in <code class="varname">zones[0]/update_acl</code>.
    1217. 

  1217.       The <span class="command"><strong>add</strong></span> command with a value (rule) adds
    1218. 

  1218.       a new entry and sets it to the given rule.
    1219. 

  1219. 

  1220.       Due to a limitation of the current implementation, it doesn't
    1221. 

  1221.       work if you first try to just add a new entry and then set it to
    1222. 

  1222.       a given rule.)
    1223. 

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

  1224.           The <span class="command"><strong>b10-ddns</strong></span> component accepts an ACL
    1225. 

  1225.           rule that just allows updates from a specific IP address
    1226. 

  1226.           (i.e., without requiring TSIG), but this is highly
    1227. 

  1227.           discouraged (remember that requests can be made over UDP and
    1228. 

  1228.           spoofing the source address of a UDP packet is often pretty
    1229. 

  1229.           easy).
    1230. 

  1230.           Unless you know what you are doing and that you can accept
    1231. 

  1231.           its consequence, any update ACL rule that allows updates
    1232. 

  1232.           should have a TSIG key in its constraints.
    1233. 

  1233.       </p></div><p>
    1234. 

  1234. 	The ACL rules will be checked in the listed order, and the
    1235. 

  1235. 	first matching one will apply.
    1236. 

  1236. 	If none of the rules matches, the default rule will apply,
    1237. 

  1237. 	which is rejecting any requests in the case of
    1238. 

  1238. 	<span class="command"><strong>b10-ddns</strong></span>.
    1239. 

  1239.       </p><p>
    1240. 

  1240. 	Other actions than "ACCEPT", namely "REJECT" and "DROP", can be
    1241. 

  1241. 	used, too.
    1242. 

  1242. 	See <a class="xref" href="#resolverserver" title="Chapter 12. Recursive Name Server">Chapter 12, <i>Recursive Name Server</i></a> about their effects.
    1243. 

  1243.       </p><p>
    1244. 

  1244.         Currently update ACL can only control updates per zone basis;
    1245. 

  1245.         it's not possible to specify access control with higher
    1246. 

  1246.         granularity such as for particular domain names or specific
    1247. 

  1247.         types of RRs.
    1248. 

  1248. 

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

  1250.         Contrary to what RFC 2136 (literally) specifies,
    1251. 

  1251.         <span class="command"><strong>b10-ddns</strong></span> checks the update ACL before
    1252. 

  1252.         checking the prerequisites of the update request.
    1253. 

  1253.         This is a deliberate implementation decision.
    1254. 

  1254.         This counter intuitive specification has been repeatedly
    1255. 

  1255.         discussed among implementers and in the IETF, and it is now
    1256. 

  1256.         widely agreed that it does not make sense to strictly follow
    1257. 

  1257.         that part of RFC.
    1258. 

  1258.         One known specific bad result of following the RFC is that it
    1259. 

  1259.         could leak information about which name or record exists or does not
    1260. 

  1260.         exist in the zone as a result of prerequisite checks even if a
    1261. 

  1261.         zone is somehow configured to reject normal queries from
    1262. 

  1262.         arbitrary clients.
    1263. 

  1263.         There have been other troubles that could have been avoided if
    1264. 

  1264.         the ACL could be checked before the prerequisite check.
    1265. 

  1265.       </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="idp475168"></a>11.3. Miscellaneous Operational Issues</h2></div></div></div><p>
    1266. 

  1266.         Unlike BIND 9, BIND 10 currently does not support automatic
    1267. 

  1267.         re-signing of DNSSEC-signed zone when it's updated via DDNS.
    1268. 

  1268.         It could be possible to re-sign the updated zone afterwards
    1269. 

  1269.         or make sure the update request also updates related DNSSEC
    1270. 

  1270.         records, but that will be pretty error-prone operation.
    1271. 

  1271.         In general, it's not advisable to allow DDNS for a signed zone
    1272. 

  1272.         at this moment.
    1273. 

  1273.       </p><p>
    1274. 

  1274.         Also unlike BIND 9, it's currently not possible
    1275. 

  1275.         to <span class="quote">&#8220;<span class="quote">freeze</span>&#8221;</span> a zone temporarily in order to
    1276. 

  1276.         suspend DDNS while you manually update the zone.
    1277. 

  1277.         If you need to make manual updates to a dynamic zone,
    1278. 

  1278.         you'll need to temporarily reject any updates to the zone via
    1279. 

  1279.         the update ACLs.
    1280. 

  1280.       </p><p>
    1281. 

  1281.         Dynamic updates are only applicable to primary zones.
    1282. 

  1282.         In order to avoid updating secondary zones via DDNS requests,
    1283. 

  1283.         <span class="command"><strong>b10-ddns</strong></span> refers to the
    1284. 

  1284.         <span class="quote">&#8220;<span class="quote">secondary_zones</span>&#8221;</span> configuration of
    1285. 

  1285.         <span class="command"><strong>b10-zonemgr</strong></span>.  Zones listed in
    1286. 

  1286.         <span class="quote">&#8220;<span class="quote">secondary_zones</span>&#8221;</span> will never be updated via DDNS
    1287. 

  1287.         regardless of the update ACL configuration;
    1288. 

  1288. 	<span class="command"><strong>b10-ddns</strong></span> will return a NOTAUTH (server
    1289. 

  1289.         not authoritative for the zone) response.
    1290. 

  1290.         If you have a "conceptual" secondary zone whose content is a
    1291. 

  1291.         copy of some external source but is not updated via the
    1292. 

  1292.         standard zone transfers and therefore not listed in
    1293. 

  1293.         <span class="quote">&#8220;<span class="quote">secondary_zones</span>&#8221;</span>, be careful not to allow DDNS
    1294. 

  1294.         for the zone; it would be quite likely to lead to inconsistent
    1295. 

  1295.         state between different servers.
    1296. 

  1296.         Normally this should not be a problem because the default
    1297. 

  1297.         update ACL rejects any update requests, but you may want to
    1298. 

  1298.         take an extra care about the configuration if you have such
    1299. 

  1299.         type of secondary zones.
    1300. 

  1300.       </p><p>
    1301. 

  1301.         The difference of two versions of a zone, before and after a
    1302. 

  1302.         DDNS transaction, is automatically recorded in the underlying
    1303. 

  1303.         data source, and can be retrieved in the form of outbound
    1304. 

  1304.         IXFR.
    1305. 

  1305.         This is done automatically; it does not require specific
    1306. 

  1306.         configuration to make this possible.
    1307. 

  1307.       </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="#idp496224">12.1. Access Control</a></span></dt><dt><span class="section"><a href="#idp512960">12.2. Forwarding</a></span></dt></dl></div><p>
    1308. 

  1308.       The <span class="command"><strong>b10-resolver</strong></span> process is started by
    1309. 

  1309.       <span class="command"><strong>bind10</strong></span>.
    1310. 

  1310. 

  1311.     </p><p>
    1312. 

  1312.       The main <span class="command"><strong>bind10</strong></span> process can be configured
    1313. 

  1313.       to select to run either the authoritative or resolver or both.
    1314. 

  1314.       By default, it doesn't start either one. You may change this using
    1315. 

  1315.       <span class="command"><strong>bindctl</strong></span>, for example:
    1316. 

  1316. 

  1317.       </p><pre class="screen">
    1318. 

  1318. &gt; <strong class="userinput"><code>config add Boss/components b10-resolver</code></strong>
    1319. 

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

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

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

  1322. &gt; <strong class="userinput"><code>config commit</code></strong>
    1323. 

  1323. </pre><p>
    1324. 

  1324. 

  1325.     </p><p>
    1326. 

  1326.        The master <span class="command"><strong>bind10</strong></span> will stop and start
    1327. 

  1327.        the desired services.
    1328. 

  1328.     </p><p>
    1329. 

  1329.       By default, the resolver listens on port 53 for 127.0.0.1 and ::1.
    1330. 

  1330.       The following example shows how it can be configured to
    1331. 

  1331.       listen on an additional address (and port):
    1332. 

  1332. 

  1333.       </p><pre class="screen">
    1334. 

  1334. &gt; <strong class="userinput"><code>config add Resolver/listen_on</code></strong>
    1335. 

  1335. &gt; <strong class="userinput"><code>config set Resolver/listen_on[<em class="replaceable"><code>2</code></em>]/address "192.168.1.1"</code></strong>
    1336. 

  1336. &gt; <strong class="userinput"><code>config set Resolver/listen_on[<em class="replaceable"><code>2</code></em>]/port 53</code></strong>
    1337. 

  1337. &gt; <strong class="userinput"><code>config commit</code></strong>
    1338. 

  1338. </pre><p>
    1339. 

  1339.     </p><p>(Replace the <span class="quote">&#8220;<span class="quote"><em class="replaceable"><code>2</code></em></span>&#8221;</span>
    1340. 

  1340.        as needed; run <span class="quote">&#8220;<span class="quote"><strong class="userinput"><code>config show
    1341. 

  1341.        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="idp496224"></a>12.1. Access Control</h2></div></div></div><p>
    1342. 

  1342.         By default, the <span class="command"><strong>b10-resolver</strong></span> daemon only accepts
    1343. 

  1343.         DNS queries from the localhost (127.0.0.1 and ::1).
    1344. 

  1344.         The <code class="option">Resolver/query_acl</code> configuration may
    1345. 

  1345.         be used to reject, drop, or allow specific IPs or networks.
    1346. 

  1346.         This configuration list is first match.
    1347. 

  1347.       </p><p>
    1348. 

  1348.         The configuration's <code class="option">action</code> item may be
    1349. 

  1349.         set to <span class="quote">&#8220;<span class="quote">ACCEPT</span>&#8221;</span> to allow the incoming query,
    1350. 

  1350.         <span class="quote">&#8220;<span class="quote">REJECT</span>&#8221;</span> to respond with a DNS REFUSED return
    1351. 

  1351.         code, or <span class="quote">&#8220;<span class="quote">DROP</span>&#8221;</span> to ignore the query without
    1352. 

  1352.         any response (such as a blackhole).  For more information,
    1353. 

  1353.         see the respective debugging messages:  <a class="ulink" href="bind10-messages.html#RESOLVER_QUERY_ACCEPTED" target="_top">RESOLVER_QUERY_ACCEPTED</a>,
    1354. 

  1354.         <a class="ulink" href="bind10-messages.html#RESOLVER_QUERY_REJECTED" target="_top">RESOLVER_QUERY_REJECTED</a>,
    1355. 

  1355.         and <a class="ulink" href="bind10-messages.html#RESOLVER_QUERY_DROPPED" target="_top">RESOLVER_QUERY_DROPPED</a>.
    1356. 

  1356.       </p><p>
    1357. 

  1357.         The required configuration's <code class="option">from</code> item is set
    1358. 

  1358.         to an IPv4 or IPv6 address, addresses with an network mask, or to
    1359. 

  1359.         the special lowercase keywords <span class="quote">&#8220;<span class="quote">any6</span>&#8221;</span> (for
    1360. 

  1360.         any IPv6 address) or <span class="quote">&#8220;<span class="quote">any4</span>&#8221;</span> (for any IPv4
    1361. 

  1361.         address).
    1362. 

  1362.       </p><p>
    1363. 

  1363.         For example to allow the <em class="replaceable"><code>192.168.1.0/24</code></em>
    1364. 

  1364.         network to use your recursive name server, at the
    1365. 

  1365.         <span class="command"><strong>bindctl</strong></span> prompt run:
    1366. 

  1366.       </p><pre class="screen">
    1367. 

  1367. &gt; <strong class="userinput"><code>config add Resolver/query_acl</code></strong>
    1368. 

  1368. &gt; <strong class="userinput"><code>config set Resolver/query_acl[<em class="replaceable"><code>2</code></em>]/action "ACCEPT"</code></strong>
    1369. 

  1369. &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>
    1370. 

  1370. &gt; <strong class="userinput"><code>config commit</code></strong>
    1371. 

  1371. </pre><p>(Replace the <span class="quote">&#8220;<span class="quote"><em class="replaceable"><code>2</code></em></span>&#8221;</span>
    1372. 

  1372.        as needed; run <span class="quote">&#8220;<span class="quote"><strong class="userinput"><code>config show
    1373. 

  1373.        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
    1374. 

  1374.       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="idp512960"></a>12.2. Forwarding</h2></div></div></div><p>
    1375. 

  1375. 

  1376.         To enable forwarding, the upstream address and port must be
    1377. 

  1377.         configured to forward queries to, such as:
    1378. 

  1378. 

  1379.         </p><pre class="screen">
    1380. 

  1380. &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>
    1381. 

  1381. &gt; <strong class="userinput"><code>config commit</code></strong>
    1382. 

  1382. </pre><p>
    1383. 

  1383. 

  1384.         (Replace <em class="replaceable"><code>192.168.1.1</code></em> to point to your
    1385. 

  1385.         full resolver.)
    1386. 

  1386.       </p><p>
    1387. 

  1387.         Normal iterative name service can be re-enabled by clearing the
    1388. 

  1388.         forwarding address(es); for example:
    1389. 

  1389. 

  1390.         </p><pre class="screen">
    1391. 

  1391. &gt; <strong class="userinput"><code>config set Resolver/forward_addresses []</code></strong>
    1392. 

  1392. &gt; <strong class="userinput"><code>config commit</code></strong>
    1393. 

  1393. </pre><p>
    1394. 

  1394.       </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
    1395. 

  1395.     DHCPv4) and Dynamic Host Configuration Protocol for IPv6 (DHCPv6)
    1396. 

  1396.     are protocols that allow one node (server) to provision
    1397. 

  1397.     configuration parameters to many hosts and devices (clients). To
    1398. 

  1398.     ease deployment in larger networks, additional nodes (relays) may
    1399. 

  1399.     be deployed that facilitate communication between servers and
    1400. 

  1400.     clients. Even though principles of both DHCPv4 and DHCPv6 are
    1401. 

  1401.     somewhat similar, these are two radically different
    1402. 

  1402.     protocols. BIND10 offers server implementations for both DHCPv4
    1403. 

  1403.     and DHCPv6. This chapter is about DHCP for IPv4. For a description
    1404. 

  1404.     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
    1405. 

  1405.     development. You may want to check out <a class="ulink" href="http://bind10.isc.org/wiki/Kea" target="_top">BIND10 DHCP (Kea) wiki</a>
    1406. 

  1406.     and recent posts on <a class="ulink" href="https://lists.isc.org/mailman/listinfo/bind10-dev" target="_top">BIND10
    1407. 

  1407.     developers mailing list</a>.</p><p>The DHCPv4 and DHCPv6 components in BIND10 architecture are
    1408. 

  1408.     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>
    1409. 

  1409.         As of December 2011, both DHCPv4 and DHCPv6 components are
    1410. 

  1410.         skeleton servers. That means that while they are capable of
    1411. 

  1411.         performing DHCP configuration, they are not fully functional
    1412. 

  1412.         yet. In particular, neither has functional lease
    1413. 

  1413.         databases. This means that they will assign the same, fixed,
    1414. 

  1414.         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
    1415. 

  1415.         detailed description.
    1416. 

  1416.       </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
    1417. 

  1417.       2011. It is a skeleton server and can be described as an early
    1418. 

  1418.       prototype that is not fully functional yet. It is mature enough
    1419. 

  1419.       to conduct first tests in lab environment, but it has
    1420. 

  1420.       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
    1421. 

  1421.       details.
    1422. 

  1422.       </p><p>
    1423. 

  1423.         <span class="command"><strong>b10-dhcp4</strong></span> is a BIND10 component and is being
    1424. 

  1424.         run under BIND10 framework. To add a DHCPv4 process to the set of running
    1425. 

  1425.         BIND10 services, you can use following commands in <span class="command"><strong>bindctl</strong></span>:
    1426. 

  1426.         </p><pre class="screen">&gt; <strong class="userinput"><code>config add Boss/components b10-dhcp4</code></strong>
    1427. 

  1427. &gt; <strong class="userinput"><code>config set Boss/components/b10-dhcp4/kind dispensable</code></strong>
    1428. 

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

  1429.          To shutdown running <span class="command"><strong>b10-dhcp4</strong></span>, please use the
    1430. 

  1430.          following command:
    1431. 

  1431.          </p><pre class="screen">&gt; <strong class="userinput"><code>Dhcp4 shutdown</code></strong></pre><p>
    1432. 

  1432.          or
    1433. 

  1433.          </p><pre class="screen">&gt; <strong class="userinput"><code>config remove Boss/components b10-dhcp4</code></strong>
    1434. 

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

  1435.         During start-up the server will detect available network interfaces
    1436. 

  1436.         and will attempt to open UDP sockets on all interfaces that
    1437. 

  1437.         are up, running, are not loopback, and have IPv4 address
    1438. 

  1438.         assigned.
    1439. 

  1439. 

  1440.         The server will then listen to incoming traffic. Currently
    1441. 

  1441.         supported client messages are DISCOVER and REQUEST. The server
    1442. 

  1442.         will respond to them with OFFER and ACK, respectively.
    1443. 

  1443. 

  1444.         Since the DHCPv4 server opens privileged ports, it requires root
    1445. 

  1445.         access. Make sure you run this daemon as root.
    1446. 

  1446.       </p></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>
    1447. 

  1447.         The DHCPv4 server does not have a lease database implemented yet
    1448. 

  1448.         nor any support for configuration, so every time the same set
    1449. 

  1449.         of configuration options (including the same fixed address)
    1450. 

  1450.         will be assigned every time.
    1451. 

  1451.       </p><p>
    1452. 

  1452.         At this stage of development, the only way to alter the server
    1453. 

  1453.         configuration is to tweak its source code. To do so, please
    1454. 

  1454.         edit src/bin/dhcp4/dhcp4_srv.cc file and modify following
    1455. 

  1455.         parameters and recompile:
    1456. 

  1456.         </p><pre class="screen">
    1457. 

  1457. const std::string HARDCODED_LEASE = "192.0.2.222"; // assigned lease
    1458. 

  1458. const std::string HARDCODED_NETMASK = "255.255.255.0";
    1459. 

  1459. const uint32_t    HARDCODED_LEASE_TIME = 60; // in seconds
    1460. 

  1460. const std::string HARDCODED_GATEWAY = "192.0.2.1";
    1461. 

  1461. const std::string HARDCODED_DNS_SERVER = "192.0.2.2";
    1462. 

  1462. const std::string HARDCODED_DOMAIN_NAME = "isc.example.com";
    1463. 

  1463. const std::string HARDCODED_SERVER_ID = "192.0.2.1";</pre><p>
    1464. 

  1464. 

  1465.         Lease database and configuration support is planned for 2012.
    1466. 

  1466.       </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
    1467. 

  1467.       supported:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">RFC2131: Supported messages are DISCOVER, OFFER,
    1468. 

  1468.             REQUEST, and ACK.</li><li class="listitem">RFC2132: Supported options are: PAD (0),
    1469. 

  1469.             END(255), Message Type(53), DHCP Server Identifier (54),
    1470. 

  1470.             Domain Name (15), DNS Servers (6), IP Address Lease Time
    1471. 

  1471.             (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
    1472. 

  1472.       software. Most of them are reflections of the early stage of
    1473. 

  1473.       development and should be treated as <span class="quote">&#8220;<span class="quote">not implemented
    1474. 

  1474.       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
    1475. 

  1475.             server is expected to send packets to a node that does not
    1476. 

  1476.             have IPv4 address assigned yet. The server requires
    1477. 

  1477.             certain tricks (or hacks) to transmit such packets. This
    1478. 

  1478.             is not implemented yet, therefore DHCPv4 server supports
    1479. 

  1479.             relayed traffic only (that is, normal point to point
    1480. 

  1480.             communication).</li><li class="listitem"><span class="command"><strong>b10-dhcp4</strong></span> provides a single,
    1481. 

  1481.             fixed, hardcoded lease to any client that asks.  There is
    1482. 

  1482.             no lease manager implemented. If two clients request
    1483. 

  1483.             addresses, they will both get the same fixed
    1484. 

  1484.             address.</li><li class="listitem"><span class="command"><strong>b10-dhcp4</strong></span> does not support any
    1485. 

  1485.             configuration mechanisms yet. The whole configuration is
    1486. 

  1486.             currently hardcoded. The only way to tweak configuration
    1487. 

  1487.             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
    1488. 

  1488.             interfaces that are not loopback, are up and running and
    1489. 

  1489.             have IPv4 address.</li><li class="listitem">PRL (Parameter Request List, a list of options
    1490. 

  1490.             requested by a client) is currently ignored and server
    1491. 

  1491.             assigns DNS SERVER and DOMAIN NAME options.</li><li class="listitem"><span class="command"><strong>b10-dhcp4</strong></span> does not support
    1492. 

  1492.             BOOTP. That is a design choice. This limitation is
    1493. 

  1493.             permanent. If you have legacy nodes that can't use DHCP and
    1494. 

  1494.             require BOOTP support, please use latest version of ISC DHCP
    1495. 

  1495.             <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
    1496. 

  1496.             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
    1497. 

  1497.             assigned address is unused. According to RFC2131, the
    1498. 

  1498.             allocating server should verify that address is no used by
    1499. 

  1499.             sending ICMP echo request.</li><li class="listitem">Address renewal (RENEW), rebinding (REBIND),
    1500. 

  1500.             confirmation (CONFIRM), duplication report (DECLINE) and
    1501. 

  1501.             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
    1502. 

  1502.             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
    1503. 

  1503.     specified in RFC3315. BIND10 provides DHCPv6 server implementation
    1504. 

  1504.     that is described in this chapter. For a description of the DHCPv4
    1505. 

  1505.     server implementation, see <a class="xref" href="#dhcp4" title="Chapter 13. DHCPv4 Server">Chapter 13, <i>DHCPv4 Server</i></a>.
    1506. 

  1506.     </p><p>The DHCPv6 server component is currently under intense
    1507. 

  1507.     development. You may want to check out <a class="ulink" href="http://bind10.isc.org/wiki/Kea" target="_top">BIND10 DHCP (Kea) wiki</a>
    1508. 

  1508.     and recent posts on <a class="ulink" href="https://lists.isc.org/mailman/listinfo/bind10-dev" target="_top">BIND10
    1509. 

  1509.     developers mailing list</a>.</p><p>The DHCPv4 and DHCPv6 components in BIND10 architecture are
    1510. 

  1510.     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>
    1511. 

  1511.         As of December 2011, both DHCPv4 and DHCPv6 components are
    1512. 

  1512.         skeleton servers. That means that while they are capable of
    1513. 

  1513.         performing DHCP configuration, they are not fully functional
    1514. 

  1514.         yet. In particular, neither has functional lease
    1515. 

  1515.         databases. This means that they will assign the same, fixed,
    1516. 

  1516.         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
    1517. 

  1517.         detailed description.
    1518. 

  1518.       </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>
    1519. 

  1519.         BIND10 provides the DHCPv6 server component since September
    1520. 

  1520.         2011. It is a skeleton server and can be described as an early
    1521. 

  1521.         prototype that is not fully functional yet. It is mature
    1522. 

  1522.         enough to conduct first tests in lab environment, but it has
    1523. 

  1523.         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
    1524. 

  1524.         details.
    1525. 

  1525.       </p><p>
    1526. 

  1526.         <span class="command"><strong>b10-dhcp6</strong></span> is a BIND10 component and is being
    1527. 

  1527.         run under BIND10 framework. To add a DHCPv6 process to the set of running
    1528. 

  1528.         BIND10 services, you can use following commands in <span class="command"><strong>bindctl</strong></span>:
    1529. 

  1529.         </p><pre class="screen">&gt; <strong class="userinput"><code>config add Boss/components b10-dhcp6</code></strong>
    1530. 

  1530. &gt; <strong class="userinput"><code>config set Boss/components/b10-dhcp6/kind dispensable</code></strong>
    1531. 

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

  1532.       </p><p>
    1533. 

  1533.          To shutdown running <span class="command"><strong>b10-dhcp6</strong></span>, please use the
    1534. 

  1534.          following command:
    1535. 

  1535.          </p><pre class="screen">&gt; <strong class="userinput"><code>Dhcp6 shutdown</code></strong></pre><p>
    1536. 

  1536.          or
    1537. 

  1537.          </p><pre class="screen">&gt; <strong class="userinput"><code>config remove Boss/components b10-dhcp6</code></strong>
    1538. 

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

  1539.        </p><p>
    1540. 

  1540.         During start-up the server will detect available network interfaces
    1541. 

  1541.         and will attempt to open UDP sockets on all interfaces that
    1542. 

  1542.         are up, running, are not loopback, are multicast-capable, and
    1543. 

  1543.         have IPv6 address assigned.
    1544. 

  1544. 

  1545.         The server will then listen to incoming traffic. Currently
    1546. 

  1546.         supported client messages are SOLICIT and REQUEST. The server
    1547. 

  1547.         will respond to them with ADVERTISE and REPLY, respectively.
    1548. 

  1548. 

  1549.         Since the DHCPv6 server opens privileged ports, it requires root
    1550. 

  1550.         access. Make sure you run this daemon as root.
    1551. 

  1551.       </p></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>
    1552. 

  1552.         The DHCPv6 server does not have lease database implemented yet
    1553. 

  1553.         or any support for configuration, so every time the same set
    1554. 

  1554.         of configuration options (including the same fixed address)
    1555. 

  1555.         will be assigned every time.
    1556. 

  1556.       </p><p>
    1557. 

  1557.         At this stage of development, the only way to alter server
    1558. 

  1558.         configuration is to tweak its source code. To do so, please
    1559. 

  1559.         edit src/bin/dhcp6/dhcp6_srv.cc file, modify the following
    1560. 

  1560.         parameters and recompile:
    1561. 

  1561.         </p><pre class="screen">
    1562. 

  1562. const std::string HARDCODED_LEASE = "2001:db8:1::1234:abcd";
    1563. 

  1563. const uint32_t HARDCODED_T1 = 1500; // in seconds
    1564. 

  1564. const uint32_t HARDCODED_T2 = 2600; // in seconds
    1565. 

  1565. const uint32_t HARDCODED_PREFERRED_LIFETIME = 3600; // in seconds
    1566. 

  1566. const uint32_t HARDCODED_VALID_LIFETIME = 7200; // in seconds
    1567. 

  1567. const std::string HARDCODED_DNS_SERVER = "2001:db8:1::1";</pre><p>
    1568. 

  1568. 

  1569.         Lease database and configuration support is planned for 2012.
    1570. 

  1570.       </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
    1571. 

  1571.       supported:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">RFC3315: Supported messages are SOLICIT,
    1572. 

  1572.             ADVERTISE, REQUEST, and REPLY. Supported options are
    1573. 

  1573.             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
    1574. 

  1574.       software. Most of them are reflections of the early stage of
    1575. 

  1575.       development and should be treated as <span class="quote">&#8220;<span class="quote">not implemented
    1576. 

  1576.       yet</span>&#8221;</span>, rather than actual limitations.</p><p>
    1577. 

  1577.       </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,
    1578. 

  1578.           fixed, hardcoded lease to any client that asks. There is no
    1579. 

  1579.           lease manager implemented. If two clients request addresses,
    1580. 

  1580.           they will both get the same fixed address.</li><li class="listitem"><span class="command"><strong>b10-dhcp6</strong></span> does not support any
    1581. 

  1581.             configuration mechanisms yet. The whole configuration is
    1582. 

  1582.             currently hardcoded. The only way to tweak configuration
    1583. 

  1583.             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
    1584. 

  1584.           interfaces that are not loopback, are up, running and are
    1585. 

  1585.           multicast capable and have IPv6 address.  Support for
    1586. 

  1586.           multiple interfaces is not coded in reception routines yet,
    1587. 

  1587.           so if you are running this code on a machine that has many
    1588. 

  1588.           interfaces and <span class="command"><strong>b10-dhcp6</strong></span> happens to
    1589. 

  1589.           listen on wrong interface, the easiest way to work around
    1590. 

  1590.           this problem is to turn down other interfaces. This
    1591. 

  1591.           limitation will be fixed shortly.</li><li class="listitem">ORO (Option Request Option, a list of options
    1592. 

  1592.           requested by a client) is currently ignored and server
    1593. 

  1593.           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),
    1594. 

  1594.           confirmation (CONFIRM), duplication report (DECLINE) and
    1595. 

  1595.           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
    1596. 

  1596.           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
    1597. 

  1597.           default, and cannot be disabled.</li></ul></div><p>
    1598. 

  1598.       </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
    1599. 

  1599.     many DHCP-related tasks, like DHCPv4 and DHCPv6 packets parsing,
    1600. 

  1600.     manipulation and assembly, option parsing, manipulation and
    1601. 

  1601.     assembly, network interface detection and socket operations, like
    1602. 

  1602.     socket creations, data transmission and reception and socket
    1603. 

  1603.     closing.
    1604. 

  1604.     </p><p>
    1605. 

  1605.     While this library is currently used by
    1606. 

  1606.     <span class="command"><strong>b10-dhcp4</strong></span> and <span class="command"><strong>b10-dhcp6</strong></span>
    1607. 

  1607.     only, it is designed to be portable, universal library useful for
    1608. 

  1608.     any kind of DHCP-related software.
    1609. 

  1609.     </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
    1610. 

  1610.       interface detection routines. Interface detection is
    1611. 

  1611.       currently only supported on Linux systems.</p><p>For non-Linux systems, there is currently stub
    1612. 

  1612.       implementation provided. Interface manager detects loopback
    1613. 

  1613.       interfaces only as their name (lo or lo0) can be easily predicted.
    1614. 

  1614.       Please contact BIND10 development team if you are interested
    1615. 

  1615.       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>
    1616. 

  1616.       The <span class="command"><strong>b10-stats</strong></span> process is started by
    1617. 

  1617.       <span class="command"><strong>bind10</strong></span>.
    1618. 

  1618.       It periodically collects statistics data from various modules
    1619. 

  1619.       and aggregates it.
    1620. 

  1620. 

  1621.     </p><p>
    1622. 

  1622. 

  1623.        This stats daemon provides commands to identify if it is
    1624. 

  1624.        running, show specified or all statistics data, and show specified
    1625. 

  1625.        or all statistics data schema.
    1626. 

  1626. 

  1627.        For example, using <span class="command"><strong>bindctl</strong></span>:
    1628. 

  1628. 

  1629.        </p><pre class="screen">
    1630. 

  1630. &gt; <strong class="userinput"><code>Stats show</code></strong>
    1631. 

  1631. {
    1632. 

  1632.     "Auth": {
    1633. 

  1633.         "opcode.iquery": 0,
    1634. 

  1634.         "opcode.notify": 10,
    1635. 

  1635.         "opcode.query": 869617,
    1636. 

  1636.         ...
    1637. 

  1637.         "queries.tcp": 1749,
    1638. 

  1638.         "queries.udp": 867868
    1639. 

  1639.     },
    1640. 

  1640.     "Boss": {
    1641. 

  1641.         "boot_time": "2011-01-20T16:59:03Z"
    1642. 

  1642.     },
    1643. 

  1643.     "Stats": {
    1644. 

  1644.         "boot_time": "2011-01-20T16:59:05Z",
    1645. 

  1645.         "last_update_time": "2011-01-20T17:04:05Z",
    1646. 

  1646.         "lname": "4d3869d9_a@jreed.example.net",
    1647. 

  1647.         "report_time": "2011-01-20T17:04:06Z",
    1648. 

  1648.         "timestamp": 1295543046.823504
    1649. 

  1649.     }
    1650. 

  1650. }
    1651. 

  1651.        </pre><p>
    1652. 

  1652.     </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="#idp611696">17.1. Logging configuration</a></span></dt><dd><dl><dt><span class="section"><a href="#idp613392">17.1.1. Loggers</a></span></dt><dt><span class="section"><a href="#idp649760">17.1.2. Output Options</a></span></dt><dt><span class="section"><a href="#idp674816">17.1.3. Example session</a></span></dt></dl></dd><dt><span class="section"><a href="#idp705584">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="idp611696"></a>17.1. Logging configuration</h2></div></div></div><p>
    1653. 

  1653. 

  1654.         The logging system in BIND 10 is configured through the
    1655. 

  1655.         Logging module. All BIND 10 modules will look at the
    1656. 

  1656.         configuration in Logging to see what should be logged and
    1657. 

  1657.         to where.
    1658. 

  1658. 

  1659. 

  1660. 

  1661.       </p><div class="section" title="17.1.1. Loggers"><div class="titlepage"><div><div><h3 class="title"><a name="idp613392"></a>17.1.1. Loggers</h3></div></div></div><p>
    1662. 

  1662. 

  1663.           Within BIND 10, a message is logged through a component
    1664. 

  1664.           called a "logger". Different parts of BIND 10 log messages
    1665. 

  1665.           through different loggers, and each logger can be configured
    1666. 

  1666.           independently of one another.
    1667. 

  1667. 

  1668.         </p><p>
    1669. 

  1669. 

  1670.           In the Logging module, you can specify the configuration
    1671. 

  1671.           for zero or more loggers; any that are not specified will
    1672. 

  1672.           take appropriate default values.
    1673. 

  1673. 

  1674.         </p><p>
    1675. 

  1675. 

  1676.           The three most important elements of a logger configuration
    1677. 

  1677.           are the <code class="option">name</code> (the component that is
    1678. 

  1678.           generating the messages), the <code class="option">severity</code>
    1679. 

  1679.           (what to log), and the <code class="option">output_options</code>
    1680. 

  1680.           (where to log).
    1681. 

  1681. 

  1682.         </p><div class="section" title="17.1.1.1. name (string)"><div class="titlepage"><div><div><h4 class="title"><a name="idp617152"></a>17.1.1.1. name (string)</h4></div></div></div><p>
    1683. 

  1683.           Each logger in the system has a name, the name being that
    1684. 

  1684.           of the component using it to log messages. For instance,
    1685. 

  1685.           if you want to configure logging for the resolver module,
    1686. 

  1686.           you add an entry for a logger named <span class="quote">&#8220;<span class="quote">Resolver</span>&#8221;</span>. This
    1687. 

  1687.           configuration will then be used by the loggers in the
    1688. 

  1688.           Resolver module, and all the libraries used by it.
    1689. 

  1689.               </p><p>
    1690. 

  1690. 

  1691.           If you want to specify logging for one specific library
    1692. 

  1692.           within the module, you set the name to
    1693. 

  1693.           <em class="replaceable"><code>module.library</code></em>.  For example, the
    1694. 

  1694.           logger used by the nameserver address store component
    1695. 

  1695.           has the full name of <span class="quote">&#8220;<span class="quote">Resolver.nsas</span>&#8221;</span>. If
    1696. 

  1696.           there is no entry in Logging for a particular library,
    1697. 

  1697.           it will use the configuration given for the module.
    1698. 

  1698. 

  1699. 

  1700. 

  1701.         </p><p>
    1702. 

  1702. 

  1703. 

  1704. 

  1705.           To illustrate this, suppose you want the cache library
    1706. 

  1706.           to log messages of severity DEBUG, and the rest of the
    1707. 

  1707.           resolver code to log messages of severity INFO. To achieve
    1708. 

  1708.           this you specify two loggers, one with the name
    1709. 

  1709.           <span class="quote">&#8220;<span class="quote">Resolver</span>&#8221;</span> and severity INFO, and one with
    1710. 

  1710.           the name <span class="quote">&#8220;<span class="quote">Resolver.cache</span>&#8221;</span> with severity
    1711. 

  1711.           DEBUG. As there are no entries for other libraries (e.g.
    1712. 

  1712.           the nsas), they will use the configuration for the module
    1713. 

  1713.           (<span class="quote">&#8220;<span class="quote">Resolver</span>&#8221;</span>), so giving the desired behavior.
    1714. 

  1714. 

  1715.         </p><p>
    1716. 

  1716. 

  1717.           One special case is that of a module name of <span class="quote">&#8220;<span class="quote">*</span>&#8221;</span>
    1718. 

  1718.           (asterisks), which is interpreted as <span class="emphasis"><em>any</em></span>
    1719. 

  1719.           module. You can set global logging options by using this,
    1720. 

  1720.           including setting the logging configuration for a library
    1721. 

  1721.           that is used by multiple modules (e.g. <span class="quote">&#8220;<span class="quote">*.config</span>&#8221;</span>
    1722. 

  1722.           specifies the configuration library code in whatever
    1723. 

  1723.           module is using it).
    1724. 

  1724. 

  1725.         </p><p>
    1726. 

  1726. 

  1727.           If there are multiple logger specifications in the
    1728. 

  1728.           configuration that might match a particular logger, the
    1729. 

  1729.           specification with the more specific logger name takes
    1730. 

  1730.           precedence. For example, if there are entries for for
    1731. 

  1731.           both <span class="quote">&#8220;<span class="quote">*</span>&#8221;</span> and <span class="quote">&#8220;<span class="quote">Resolver</span>&#8221;</span>, the
    1732. 

  1732.           resolver module &#8212; and all libraries it uses &#8212;
    1733. 

  1733.           will log messages according to the configuration in the
    1734. 

  1734.           second entry (<span class="quote">&#8220;<span class="quote">Resolver</span>&#8221;</span>). All other modules
    1735. 

  1735.           will use the configuration of the first entry
    1736. 

  1736.           (<span class="quote">&#8220;<span class="quote">*</span>&#8221;</span>). If there was also a configuration
    1737. 

  1737.           entry for <span class="quote">&#8220;<span class="quote">Resolver.cache</span>&#8221;</span>, the cache library
    1738. 

  1738.           within the resolver would use that in preference to the
    1739. 

  1739.           entry for <span class="quote">&#8220;<span class="quote">Resolver</span>&#8221;</span>.
    1740. 

  1740. 

  1741.         </p><p>
    1742. 

  1742. 

  1743.           One final note about the naming. When specifying the
    1744. 

  1744.           module name within a logger, use the name of the module
    1745. 

  1745.           as specified in <span class="command"><strong>bindctl</strong></span>, e.g.
    1746. 

  1746.           <span class="quote">&#8220;<span class="quote">Resolver</span>&#8221;</span> for the resolver module,
    1747. 

  1747.           <span class="quote">&#8220;<span class="quote">Xfrout</span>&#8221;</span> for the xfrout module, etc. When
    1748. 

  1748.           the message is logged, the message will include the name
    1749. 

  1749.           of the logger generating the message, but with the module
    1750. 

  1750.           name replaced by the name of the process implementing
    1751. 

  1751.           the module (so for example, a message generated by the
    1752. 

  1752.           <span class="quote">&#8220;<span class="quote">Auth.cache</span>&#8221;</span> logger will appear in the output
    1753. 

  1753.           with a logger name of <span class="quote">&#8220;<span class="quote">b10-auth.cache</span>&#8221;</span>).
    1754. 

  1754. 

  1755.         </p></div><div class="section" title="17.1.1.2. severity (string)"><div class="titlepage"><div><div><h4 class="title"><a name="idp633200"></a>17.1.1.2. severity (string)</h4></div></div></div><p>
    1756. 

  1756. 

  1757.           This specifies the category of messages logged.
    1758. 

  1758.           Each message is logged with an associated severity which
    1759. 

  1759.           may be one of the following (in descending order of
    1760. 

  1760.           severity):
    1761. 

  1761.         </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>
    1762. 

  1762. 

  1763.           When the severity of a logger is set to one of these
    1764. 

  1764.           values, it will only log messages of that severity, and
    1765. 

  1765.           the severities above it. The severity may also be set to
    1766. 

  1766.           NONE, in which case all messages from that logger are
    1767. 

  1767.           inhibited.
    1768. 

  1768. 

  1769. 

  1770. 

  1771.         </p></div><div class="section" title="17.1.1.3. output_options (list)"><div class="titlepage"><div><div><h4 class="title"><a name="idp640176"></a>17.1.1.3. output_options (list)</h4></div></div></div><p>
    1772. 

  1772. 

  1773.           Each logger can have zero or more
    1774. 

  1774.           <code class="option">output_options</code>. These specify where log
    1775. 

  1775.           messages are sent to. These are explained in detail below.
    1776. 

  1776. 

  1777.         </p><p>
    1778. 

  1778. 

  1779.           The other options for a logger are:
    1780. 

  1780. 

  1781.         </p></div><div class="section" title="17.1.1.4. debuglevel (integer)"><div class="titlepage"><div><div><h4 class="title"><a name="idp642448"></a>17.1.1.4. debuglevel (integer)</h4></div></div></div><p>
    1782. 

  1782. 

  1783.           When a logger's severity is set to DEBUG, this value
    1784. 

  1784.           specifies what debug messages should be printed. It ranges
    1785. 

  1785.           from 0 (least verbose) to 99 (most verbose).
    1786. 

  1786.         </p><p>
    1787. 

  1787. 

  1788.           If severity for the logger is not DEBUG, this value is ignored.
    1789. 

  1789. 

  1790.         </p></div><div class="section" title="17.1.1.5. additive (true or false)"><div class="titlepage"><div><div><h4 class="title"><a name="idp644832"></a>17.1.1.5. additive (true or false)</h4></div></div></div><p>
    1791. 

  1791. 

  1792.           If this is true, the <code class="option">output_options</code> from
    1793. 

  1793.           the parent will be used. For example, if there are two
    1794. 

  1794.           loggers configured; <span class="quote">&#8220;<span class="quote">Resolver</span>&#8221;</span> and
    1795. 

  1795.           <span class="quote">&#8220;<span class="quote">Resolver.cache</span>&#8221;</span>, and <code class="option">additive</code>
    1796. 

  1796.           is true in the second, it will write the log messages
    1797. 

  1797.           not only to the destinations specified for
    1798. 

  1798.           <span class="quote">&#8220;<span class="quote">Resolver.cache</span>&#8221;</span>, but also to the destinations
    1799. 

  1799.           as specified in the <code class="option">output_options</code> in
    1800. 

  1800.           the logger named <span class="quote">&#8220;<span class="quote">Resolver</span>&#8221;</span>.
    1801. 

  1801. 

  1802. 

  1803. 

  1804.       </p></div></div><div class="section" title="17.1.2. Output Options"><div class="titlepage"><div><div><h3 class="title"><a name="idp649760"></a>17.1.2. Output Options</h3></div></div></div><p>
    1805. 

  1805. 

  1806.           The main settings for an output option are the
    1807. 

  1807.           <code class="option">destination</code> and a value called
    1808. 

  1808.           <code class="option">output</code>, the meaning of which depends on
    1809. 

  1809.           the destination that is set.
    1810. 

  1810. 

  1811.         </p><div class="section" title="17.1.2.1. destination (string)"><div class="titlepage"><div><div><h4 class="title"><a name="idp651840"></a>17.1.2.1. destination (string)</h4></div></div></div><p>
    1812. 

  1812. 

  1813.             The destination is the type of output. It can be one of:
    1814. 

  1814. 

  1815.           </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="idp655904"></a>17.1.2.2. output (string)</h4></div></div></div><p>
    1816. 

  1816. 

  1817.           Depending on what is set as the output destination, this
    1818. 

  1818.           value is interpreted as follows:
    1819. 

  1819. 

  1820.         </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>
    1821. 

  1821.                  The value of output must be one of <span class="quote">&#8220;<span class="quote">stdout</span>&#8221;</span>
    1822. 

  1822.                  (messages printed to standard output) or
    1823. 

  1823.                  <span class="quote">&#8220;<span class="quote">stderr</span>&#8221;</span> (messages printed to standard
    1824. 

  1824.                  error).
    1825. 

  1825.               </p><p>
    1826. 

  1826.                 Note: if output is set to <span class="quote">&#8220;<span class="quote">stderr</span>&#8221;</span> and a lot of
    1827. 

  1827.                 messages are produced in a short time (e.g. if the logging
    1828. 

  1828.                 level is set to DEBUG), you may occasionally see some messages
    1829. 

  1829.                 jumbled up together.  This is due to a combination of the way
    1830. 

  1830.                 that messages are written to the screen and the unbuffered
    1831. 

  1831.                 nature of the standard error stream.  If this occurs, it is
    1832. 

  1832.                 recommended that output be set to <span class="quote">&#8220;<span class="quote">stdout</span>&#8221;</span>.
    1833. 

  1833.               </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>
    1834. 

  1834.                 The value of output is interpreted as a file name;
    1835. 

  1835.                 log messages will be appended to this file.
    1836. 

  1836.               </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>
    1837. 

  1837.                 The value of output is interpreted as the
    1838. 

  1838.                 <span class="command"><strong>syslog</strong></span> facility (e.g.
    1839. 

  1839.                 <span class="emphasis"><em>local0</em></span>) that should be used
    1840. 

  1840.                 for log messages.
    1841. 

  1841.               </p></dd></dl></div><p>
    1842. 

  1842. 

  1843.           The other options for <code class="option">output_options</code> are:
    1844. 

  1844. 

  1845.         </p><div class="section" title="17.1.2.2.1. flush (true of false)"><div class="titlepage"><div><div><h5 class="title"><a name="idp668864"></a>17.1.2.2.1. flush (true of false)</h5></div></div></div><p>
    1846. 

  1846.             Flush buffers after each log message. Doing this will
    1847. 

  1847.             reduce performance but will ensure that if the program
    1848. 

  1848.             terminates abnormally, all messages up to the point of
    1849. 

  1849.             termination are output.
    1850. 

  1850.           </p></div><div class="section" title="17.1.2.2.2. maxsize (integer)"><div class="titlepage"><div><div><h5 class="title"><a name="idp670304"></a>17.1.2.2.2. maxsize (integer)</h5></div></div></div><p>
    1851. 

  1851.             Only relevant when destination is file, this is maximum
    1852. 

  1852.             file size of output files in bytes. When the maximum
    1853. 

  1853.             size is reached, the file is renamed and a new file opened.
    1854. 

  1854.             (For example, a ".1" is appended to the name &#8212;
    1855. 

  1855.             if a ".1" file exists, it is renamed ".2",
    1856. 

  1856.             etc.)
    1857. 

  1857.           </p><p>
    1858. 

  1858.             If this is 0, no maximum file size is used.
    1859. 

  1859.           </p></div><div class="section" title="17.1.2.2.3. maxver (integer)"><div class="titlepage"><div><div><h5 class="title"><a name="idp672368"></a>17.1.2.2.3. maxver (integer)</h5></div></div></div><p>
    1860. 

  1860.             Maximum number of old log files to keep around when
    1861. 

  1861.             rolling the output file. Only relevant when
    1862. 

  1862.             <code class="option">destination</code> is <span class="quote">&#8220;<span class="quote">file</span>&#8221;</span>.
    1863. 

  1863.           </p></div></div></div><div class="section" title="17.1.3. Example session"><div class="titlepage"><div><div><h3 class="title"><a name="idp674816"></a>17.1.3. Example session</h3></div></div></div><p>
    1864. 

  1864. 

  1865.           In this example we want to set the global logging to
    1866. 

  1866.           write to the file <code class="filename">/var/log/my_bind10.log</code>,
    1867. 

  1867.           at severity WARN. We want the authoritative server to
    1868. 

  1868.           log at DEBUG with debuglevel 40, to a different file
    1869. 

  1869.           (<code class="filename">/tmp/debug_messages</code>).
    1870. 

  1870. 

  1871.         </p><p>
    1872. 

  1872. 

  1873.           Start <span class="command"><strong>bindctl</strong></span>.
    1874. 

  1874. 

  1875.         </p><p>
    1876. 

  1876. 

  1877.            </p><pre class="screen">["login success "]
    1878. 

  1878. &gt; <strong class="userinput"><code>config show Logging</code></strong>
    1879. 

  1879. Logging/loggers	[]	list
    1880. 

  1880. </pre><p>
    1881. 

  1881. 

  1882.         </p><p>
    1883. 

  1883. 

  1884.           By default, no specific loggers are configured, in which
    1885. 

  1885.           case the severity defaults to INFO and the output is
    1886. 

  1886.           written to stderr.
    1887. 

  1887. 

  1888.         </p><p>
    1889. 

  1889. 

  1890.           Let's first add a default logger:
    1891. 

  1891. 

  1892.         </p><p>
    1893. 

  1893. 

  1894.           </p><pre class="screen"><strong class="userinput"><code>&gt; config add Logging/loggers</code></strong>
    1895. 

  1895. &gt; <strong class="userinput"><code>config show Logging</code></strong>
    1896. 

  1896. Logging/loggers/	list	(modified)
    1897. 

  1897. </pre><p>
    1898. 

  1898. 

  1899.         </p><p>
    1900. 

  1900. 

  1901.           The loggers value line changed to indicate that it is no
    1902. 

  1902.           longer an empty list:
    1903. 

  1903. 

  1904.         </p><p>
    1905. 

  1905. 

  1906.           </p><pre class="screen">&gt; <strong class="userinput"><code>config show Logging/loggers</code></strong>
    1907. 

  1907. Logging/loggers[0]/name	""	string	(default)
    1908. 

  1908. Logging/loggers[0]/severity	"INFO"	string	(default)
    1909. 

  1909. Logging/loggers[0]/debuglevel	0	integer	(default)
    1910. 

  1910. Logging/loggers[0]/additive	false	boolean	(default)
    1911. 

  1911. Logging/loggers[0]/output_options	[]	list	(default)
    1912. 

  1912. </pre><p>
    1913. 

  1913. 

  1914.         </p><p>
    1915. 

  1915. 

  1916.           The name is mandatory, so we must set it. We will also
    1917. 

  1917.           change the severity as well. Let's start with the global
    1918. 

  1918.           logger.
    1919. 

  1919. 

  1920.         </p><p>
    1921. 

  1921. 

  1922.           </p><pre class="screen">&gt; <strong class="userinput"><code>config set Logging/loggers[0]/name *</code></strong>
    1923. 

  1923. &gt; <strong class="userinput"><code>config set Logging/loggers[0]/severity WARN</code></strong>
    1924. 

  1924. &gt; <strong class="userinput"><code>config show Logging/loggers</code></strong>
    1925. 

  1925. Logging/loggers[0]/name	"*"	string	(modified)
    1926. 

  1926. Logging/loggers[0]/severity	"WARN"	string	(modified)
    1927. 

  1927. Logging/loggers[0]/debuglevel	0	integer	(default)
    1928. 

  1928. Logging/loggers[0]/additive	false	boolean	(default)
    1929. 

  1929. Logging/loggers[0]/output_options	[]	list	(default)
    1930. 

  1930. </pre><p>
    1931. 

  1931. 

  1932.         </p><p>
    1933. 

  1933. 

  1934.           Of course, we need to specify where we want the log
    1935. 

  1935.           messages to go, so we add an entry for an output option.
    1936. 

  1936. 

  1937.         </p><p>
    1938. 

  1938. 

  1939.           </p><pre class="screen">&gt; <strong class="userinput"><code> config add Logging/loggers[0]/output_options</code></strong>
    1940. 

  1940. &gt; <strong class="userinput"><code> config show Logging/loggers[0]/output_options</code></strong>
    1941. 

  1941. Logging/loggers[0]/output_options[0]/destination	"console"	string	(default)
    1942. 

  1942. Logging/loggers[0]/output_options[0]/output	"stdout"	string	(default)
    1943. 

  1943. Logging/loggers[0]/output_options[0]/flush	false	boolean	(default)
    1944. 

  1944. Logging/loggers[0]/output_options[0]/maxsize	0	integer	(default)
    1945. 

  1945. Logging/loggers[0]/output_options[0]/maxver	0	integer	(default)
    1946. 

  1946. </pre><p>
    1947. 

  1947. 

  1948. 

  1949.         </p><p>
    1950. 

  1950. 

  1951.           These aren't the values we are looking for.
    1952. 

  1952. 

  1953.         </p><p>
    1954. 

  1954. 

  1955.           </p><pre class="screen">&gt; <strong class="userinput"><code> config set Logging/loggers[0]/output_options[0]/destination file</code></strong>
    1956. 

  1956. &gt; <strong class="userinput"><code> config set Logging/loggers[0]/output_options[0]/output /var/log/bind10.log</code></strong>
    1957. 

  1957. &gt; <strong class="userinput"><code> config set Logging/loggers[0]/output_options[0]/maxsize 204800</code></strong>
    1958. 

  1958. &gt; <strong class="userinput"><code> config set Logging/loggers[0]/output_options[0]/maxver 8</code></strong>
    1959. 

  1959. </pre><p>
    1960. 

  1960. 

  1961.         </p><p>
    1962. 

  1962. 

  1963.           Which would make the entire configuration for this logger
    1964. 

  1964.           look like:
    1965. 

  1965. 

  1966.         </p><p>
    1967. 

  1967. 

  1968.           </p><pre class="screen">&gt; <strong class="userinput"><code> config show all Logging/loggers</code></strong>
    1969. 

  1969. Logging/loggers[0]/name	"*"	string	(modified)
    1970. 

  1970. Logging/loggers[0]/severity	"WARN"	string	(modified)
    1971. 

  1971. Logging/loggers[0]/debuglevel	0	integer	(default)
    1972. 

  1972. Logging/loggers[0]/additive	false	boolean	(default)
    1973. 

  1973. Logging/loggers[0]/output_options[0]/destination	"file"	string	(modified)
    1974. 

  1974. Logging/loggers[0]/output_options[0]/output	"/var/log/bind10.log"	string	(modified)
    1975. 

  1975. Logging/loggers[0]/output_options[0]/flush	false	boolean	(default)
    1976. 

  1976. Logging/loggers[0]/output_options[0]/maxsize	204800	integer	(modified)
    1977. 

  1977. Logging/loggers[0]/output_options[0]/maxver	8	integer	(modified)
    1978. 

  1978. </pre><p>
    1979. 

  1979. 

  1980.         </p><p>
    1981. 

  1981. 

  1982.           That looks OK, so let's commit it before we add the
    1983. 

  1983.           configuration for the authoritative server's logger.
    1984. 

  1984. 

  1985.         </p><p>
    1986. 

  1986. 

  1987.           </p><pre class="screen">&gt; <strong class="userinput"><code> config commit</code></strong></pre><p>
    1988. 

  1988. 

  1989.         </p><p>
    1990. 

  1990. 

  1991.           Now that we have set it, and checked each value along
    1992. 

  1992.           the way, adding a second entry is quite similar.
    1993. 

  1993. 

  1994.         </p><p>
    1995. 

  1995. 

  1996.           </p><pre class="screen">&gt; <strong class="userinput"><code> config add Logging/loggers</code></strong>
    1997. 

  1997. &gt; <strong class="userinput"><code> config set Logging/loggers[1]/name Auth</code></strong>
    1998. 

  1998. &gt; <strong class="userinput"><code> config set Logging/loggers[1]/severity DEBUG</code></strong>
    1999. 

  1999. &gt; <strong class="userinput"><code> config set Logging/loggers[1]/debuglevel 40</code></strong>
    2000. 

  2000. &gt; <strong class="userinput"><code> config add Logging/loggers[1]/output_options</code></strong>
    2001. 

  2001. &gt; <strong class="userinput"><code> config set Logging/loggers[1]/output_options[0]/destination file</code></strong>
    2002. 

  2002. &gt; <strong class="userinput"><code> config set Logging/loggers[1]/output_options[0]/output /tmp/auth_debug.log</code></strong>
    2003. 

  2003. &gt; <strong class="userinput"><code> config commit</code></strong>
    2004. 

  2004. </pre><p>
    2005. 

  2005. 

  2006.         </p><p>
    2007. 

  2007. 

  2008.           And that's it. Once we have found whatever it was we
    2009. 

  2009.           needed the debug messages for, we can simply remove the
    2010. 

  2010.           second logger to let the authoritative server use the
    2011. 

  2011.           same settings as the rest.
    2012. 

  2012. 

  2013.         </p><p>
    2014. 

  2014. 

  2015.           </p><pre class="screen">&gt; <strong class="userinput"><code> config remove Logging/loggers[1]</code></strong>
    2016. 

  2016. &gt; <strong class="userinput"><code> config commit</code></strong>
    2017. 

  2017. </pre><p>
    2018. 

  2018. 

  2019.         </p><p>
    2020. 

  2020. 

  2021.           And every module will now be using the values from the
    2022. 

  2022.           logger named <span class="quote">&#8220;<span class="quote">*</span>&#8221;</span>.
    2023. 

  2023. 

  2024.         </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="idp705584"></a>17.2. Logging Message Format</h2></div></div></div><p>
    2025. 

  2025.           Each message written by BIND 10 to the configured logging
    2026. 

  2026.           destinations comprises a number of components that identify
    2027. 

  2027.           the origin of the message and, if the message indicates
    2028. 

  2028.           a problem, information about the problem that may be
    2029. 

  2029.           useful in fixing it.
    2030. 

  2030.       </p><p>
    2031. 

  2031.           Consider the message below logged to a file:
    2032. 

  2032.           </p><pre class="screen">2011-06-15 13:48:22.034 ERROR [b10-resolver.asiolink]
    2033. 

  2033.     ASIODNS_OPENSOCK error 111 opening TCP socket to 127.0.0.1(53)</pre><p>
    2034. 

  2034.       </p><p>
    2035. 

  2035.         Note: the layout of messages written to the system logging
    2036. 

  2036.         file (syslog) may be slightly different.  This message has
    2037. 

  2037.         been split across two lines here for display reasons; in the
    2038. 

  2038.         logging file, it will appear on one line.)
    2039. 

  2039.       </p><p>
    2040. 

  2040.         The log message comprises a number of components:
    2041. 

  2041. 

  2042.           </p><div class="variablelist"><dl><dt><span class="term">2011-06-15 13:48:22.034</span></dt><dd><p>
    2043. 

  2043.               The date and time at which the message was generated.
    2044. 

  2044.           </p></dd><dt><span class="term">ERROR</span></dt><dd><p>
    2045. 

  2045.               The severity of the message.
    2046. 

  2046.           </p></dd><dt><span class="term">[b10-resolver.asiolink]</span></dt><dd><p>
    2047. 

  2047.             The source of the message.  This comprises two components:
    2048. 

  2048.             the BIND 10 process generating the message (in this
    2049. 

  2049.             case, <span class="command"><strong>b10-resolver</strong></span>) and the module
    2050. 

  2050.             within the program from which the message originated
    2051. 

  2051.             (which in the example is the asynchronous I/O link
    2052. 

  2052.             module, asiolink).
    2053. 

  2053.           </p></dd><dt><span class="term">ASIODNS_OPENSOCK</span></dt><dd><p>
    2054. 

  2054.             The message identification.  Every message in BIND 10
    2055. 

  2055.             has a unique identification, which can be used as an
    2056. 

  2056.             index into the <a class="ulink" href="bind10-messages.html" target="_top"><em class="citetitle">BIND 10 Messages
    2057. 

  2057.             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.
    2058. 

  2058.           </p></dd><dt><span class="term">error 111 opening TCP socket to 127.0.0.1(53)</span></dt><dd><p>
    2059. 

  2059.               A brief description of the cause of the problem.
    2060. 

  2060.               Within this text, information relating to the condition
    2061. 

  2061.               that caused the message to be logged will be included.
    2062. 

  2062.               In this example, error number 111 (an operating
    2063. 

  2063.               system-specific error number) was encountered when
    2064. 

  2064.               trying to open a TCP connection to port 53 on the
    2065. 

  2065.               local system (address 127.0.0.1).  The next step
    2066. 

  2066.               would be to find out the reason for the failure by
    2067. 

  2067.               consulting your system's documentation to identify
    2068. 

  2068.               what error number 111 means.
    2069. 

  2069.           </p></dd></dl></div><p>
    2070. 

  2070.       </p></div></div></div></body></html>
    2071.