b10-zonemgr.xml 8.45 KB
Newer Older
1
2
3
4
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
               "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
	       [<!ENTITY mdash "&#8212;">]>
<!--
5
 - Copyright (C) 2010-2011  Internet Systems Consortium, Inc. ("ISC")
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
 -
 - Permission to use, copy, modify, and/or distribute this software for any
 - purpose with or without fee is hereby granted, provided that the above
 - copyright notice and this permission notice appear in all copies.
 -
 - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
 - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
 - AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
 - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
 - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
 - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 - PERFORMANCE OF THIS SOFTWARE.
-->

<refentry>

  <refentryinfo>
23
    <date>December 8, 2011</date>
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
  </refentryinfo>

  <refmeta>
    <refentrytitle>b10-zonemgr</refentrytitle>
    <manvolnum>8</manvolnum>
    <refmiscinfo>BIND10</refmiscinfo>
  </refmeta>

  <refnamediv>
    <refname>b10-zonemgr</refname>
    <refpurpose>BIND 10 Secondary zone manager</refpurpose>
  </refnamediv>

  <docinfo>
    <copyright>
39
      <year>2010-2011</year>
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
      <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
    </copyright>
  </docinfo>

  <refsynopsisdiv>
    <cmdsynopsis>
      <command>b10-zonemgr</command>
      <arg><option>-v</option></arg>
      <arg><option>--verbose</option></arg>
    </cmdsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>DESCRIPTION</title>
    <para>The <command>b10-zonemgr</command> daemon, also known
      as the BIND 10 secondary manager, keeps track of timers
      and other information necessary for BIND 10 to act as a DNS slave.
      Normally it is started by the
      <citerefentry><refentrytitle>bind10</refentrytitle><manvolnum>8</manvolnum></citerefentry>
      boss process.
    </para>

    <para>
      This daemon communicates with BIND 10 over a
      <citerefentry><refentrytitle>b10-msgq</refentrytitle><manvolnum>8</manvolnum></citerefentry>
      C-Channel connection.  If this connection is not established,
      <command>b10-zonemgr</command> will exit.
<!-- TODO what if connection closes later, will b10-zonemgr exit? -->
    </para>

    <para>
     <command>b10-zonemgr</command> receives its configurations from
<citerefentry><refentrytitle>b10-cfgmgr</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
    </para>

<!--

            self._send_command(XFRIN_MODULE_NAME, ZONE_NOTIFY_COMMAND, param) 
            self._clear_zone_notifier_master(zone_name_class)
        # Send refresh command to xfrin module
        else:
            param = {"zone_name" : zone_name_class[0],
                     "zone_class" : zone_name_class[1]
                    }
            self._send_command(XFRIN_MODULE_NAME, ZONE_REFRESH_COMMAND, param)

-->

  </refsect1>

  <refsect1>
    <title>CONFIGURATION AND COMMANDS</title>
    <para>
93
      The configurable settings are:
94
    </para>
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109

    <para>
      <varname>lowerbound_refresh</varname>
      defines the minimum SOA REFRESH time in seconds.
      The default is 10.
    </para>

    <para>
      <varname>lowerbound_retry</varname>
      defines the minimum SOA RETRY time in seconds.
      The default is 5.
    </para>

    <para>
      <varname>refresh_jitter</varname>
110
111
112
      is used to provide a time range for randomizing the refresh
      and retry timers to help avoid many zones needing to do a refresh
      or retry at the same time.
113
      This value is a real number.
114
115
116
117
      The maximum amount is 0.5 (the new timer will be within
      half the original time).
      The default is 0.25 (up to a quarter sooner).
      Set to 0 to disable this jitter.
118
119
120
121
    </para>

    <para>
      <varname>reload_jitter</varname>
122
123
<!--      is used to provide a slight random variation -->
<!-- TODO: ask what the purpose of this is and why 0.75. -->
124
125
126
127
128
129
130
131
132
      This value is a real number.
      The default is 0.75.
    </para>
<!-- TODO: needs to be documented -->
<!-- TODO:      Set to 0 to disable the jitter.   -->
<!-- what does 0 do? -->
<!-- TODO: no max? -->

<!-- TODO: remove this. This is old removed config
133
134
135
136
137
138
139
140
141
142
143
144
145
146
    <para>
      <varname>jitter_scope</varname>
      defines the random jitter range subtracted from the refresh
      and retry timers to avoid many zones from refreshing at the
      same time.
      The refresh or retry time actually used is a random time
      between the defined refresh or retry time and it multiplied
      by the <varname>jitter_scope</varname>.
      This is re-evaluated after each refresh or retry.
      This value is a real number and the maximum is 0.5 (half of the
      refresh or retry time).
      The default is 0.25.
      Set to 0 to disable the jitter.
    </para>
147
148
-->

149
150
151
152
153
154
    <para>
      <varname>max_transfer_timeout</varname>
      defines the maximum amount of time in seconds for a transfer.
<!-- TODO: what is the purpose of this? -->
      The default is 14400 (4 hours).
    </para>
155

156
157
158
159
<!-- TODO: this duplicates list in Xfrin too -->
    <para>
      <varname>secondary_zones</varname> is a list of slave zones
      that the <command>b10-zonemgr</command> should keep timers for.
160
161
162
      The list items include the <varname>name</varname> (which
      defines the zone name) and the <varname>class</varname>
      (which defaults to <quote>IN</quote>).
163
164
165
166
167
168
169
170
    </para>

    <para>
      (A deprecated configuration is <varname>jitter_scope</varname>
      which is superceded by <varname>refresh_jitter</varname>
      and <varname>reload_jitter</varname>.)
    </para>

171
172
173
174
175
176
<!-- TODO: formating -->
    <para>
      The configuration commands are:
    </para>
    <para>
      <command>notify</command> (sent by
177
178
      <citerefentry><refentrytitle>b10-auth</refentrytitle><manvolnum>8</manvolnum></citerefentry>)
      tells <command>b10-zonemgr</command>
179
180
181
182
      the zone name and class, and the IP address for the master
      (source of the NOTIFY message).
      This will set the zone's refresh time to now.
<!-- TODO reword this -->
183
184
      This is an internal command and not exposed to the administrator.
<!-- not defined in spec -->
185
186
187
188
189
190
191
192
193
    </para>

    <para>
      <command>shutdown</command> exits <command>b10-zonemgr</command>.
      (Note that the BIND 10 boss process will restart this service.)
    </para>

    <para>
      <command>zone_new_data_ready</command> is sent from
194
195
196
197
      <citerefentry><refentrytitle>b10-xfrin</refentrytitle><manvolnum>8</manvolnum></citerefentry>
      to indicate that the zone transferred in successfully.
      This is an internal command and not exposed to the administrator.
<!-- not defined in spec -->
198
199
200
201
    </para>

    <para>
      <command>zone_xfrin_failed</command> is sent from
202
203
      <citerefentry><refentrytitle>b10-xfrin</refentrytitle><manvolnum>8</manvolnum></citerefentry>
      to indicate a failure (such as a transfer-in was incomplete).
204
205
206
207
208
      The refresh timer for the zone is reset.
<!--
        """Set zone next refresh time after zone refresh fail.
           now + retry*3/4 <= next_refresh_time <= now + retry
-->
209
210
      This is an internal command and not exposed to the administrator.
<!-- not defined in spec -->
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
    </para>

  </refsect1>

<!--
  <refsect1>
    <title>OPTIONS</title>

    <para>The arguments are as follows:</para>

    <variablelist>
      <varlistentry>
        <term><option></option></term>
        <listitem><para>
        </para></listitem>
      </varlistentry>

    </variablelist>

  </refsect1>
-->

  <refsect1>
    <title>SEE ALSO</title>
    <para>
      <citerefentry>
        <refentrytitle>b10-auth</refentrytitle><manvolnum>8</manvolnum>
      </citerefentry>,
      <citerefentry>
        <refentrytitle>b10-cfgmgr</refentrytitle><manvolnum>8</manvolnum>
      </citerefentry>,
      <citerefentry>
        <refentrytitle>b10-msgq</refentrytitle><manvolnum>8</manvolnum>
      </citerefentry>,
      <citerefentry>
        <refentrytitle>b10-xfrin</refentrytitle><manvolnum>8</manvolnum>
      </citerefentry>,
      <citerefentry>
        <refentrytitle>bind10</refentrytitle><manvolnum>8</manvolnum>
      </citerefentry>,
      <citetitle>BIND 10 Guide</citetitle>.
    </para>
  </refsect1>

  <refsect1>
    <title>HISTORY</title>
    <para>
      The <command>b10-zonemgr</command> daemon was designed in July 2010
      by CNNIC for the ISC BIND 10 project.
    </para>
  </refsect1>
</refentry><!--
 - Local variables:
 - mode: sgml
 - End:
-->