aboutsummaryrefslogtreecommitdiff
path: root/doc/nssync.texi
blob: 103ae7dae89559bdef118f25a5654600d079c216 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
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
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
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
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
\input texinfo @c -*-texinfo-*-
@smallbook
@c %**start of header
@setfilename nssync.info
@settitle Nssync
@c %**end of header
@setchapternewpage odd

@defcodeindex pr
@defcodeindex op
@defcodeindex kw
@defcodeindex fl

@syncodeindex fn cp
@syncodeindex vr cp
@syncodeindex ky cp
@syncodeindex pg cp
@syncodeindex tp cp
@syncodeindex op cp
@syncodeindex pr cp
@syncodeindex kw cp
@syncodeindex fl cp

@include version.texi
@set PACKAGE nssync
@set PROGNAME nssync
@ifinfo
@dircategory System Administration Utilities
@direntry
* nssync: (nssync).              A restricted user shell.
@end direntry
@end ifinfo

@copying
Published by the Free Software Foundation,
51 Franklin Street, Fifth Floor,
Boston, MA 02110-1301 USA 

Copyright @copyright{} 2011-2017 Sergey Poznyakoff

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, an no specific Front- or Back-Cover texts. 
@end copying
                                   
@titlepage
@title NSSYNC
@subtitle version @value{VERSION}, @value{UPDATED}
@author Sergey Poznyakoff
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@ifnothtml
@page
@summarycontents
@end ifnothtml

@page
@contents

@ifnottex
@node Top
@top Nssync
@ifclear WEBDOCS
This edition of the @cite{nssync Manual}, last updated @value{UPDATED},
documents @command{nssync} Version @value{VERSION}.
@end ifclear
@end ifnottex

@menu
* Intro::
* Overview::
* Configuration File::
* Nssync Configuration::
* Invocation::
* Exit Codes::
* Reporting Bugs::       How to Report a Bug.

Appendices

@ifhtml
@ifset WEBDOCS
* Downloads::
* This Manual in Other Formats::
@end ifset
@end ifhtml
* Copying This Manual::  The GNU Free Documentation License.
* Concept Index::        Index of Concepts.

@detailmenu
@end detailmenu
@end menu

@node Intro
@chapter Introduction

BIND, the most frequently used DNS server, normally keeps its zone
data in @dfn{zone files}.  This approach becomes inconvenient when the
number of zones grows beyond a certain limit.  When this happens, the
obvious solution is to move all data to a database and make
@command{named} read it from there.  Recent versions of BIND include
@dfn{dynamically loadable zones} (@dfn{DLZ}) feature@footnote{See
@uref{http://bind-dlz.sourceforge.net/}.}, which makes it possible to 
use such databases directly.  However, DLZ has problems of its own,
one of them being that it is unable to propagate glue
records@footnote{See:
@uref{http://@/permalink.gmane.org/@/gmane.network.dns.bind9.dlz/@/2078},
@uref{http://blog.gmane.org/@/gmane.network.dns.bind9.dlz/@/month=20110101}.}.

The @command{nssync} utility provides an alternative solution, which
makes it possible to keep your zone data in an SQL@footnote{As of
version @value{VERSION} only MySQL is supported.} database without
using DLZ and with glue records working.

It does so by periodically polling the database to determine which
data have changed recently and converting the database into BIND zone
files.

@ifhtml
@ifset WEBDOCS
This edition of the @cite{nssync manual}, last updated @value{UPDATED},
documents @command{nssync} Version @value{VERSION}.  It is
available in various formats.  @xref{This Manual in Other Formats}, to
select another format.
@end ifset
@end ifhtml

@node Overview
@chapter Overview
The @command{nssync} utility is normally started periodically from
crontab.  Upon startup it reads its configuration file, which supplies
the necessary program settings.  Then, if the settings require so, it
verifies that no other copy of the @command{nssync} is already
running.  Further on, it parses the @command{named} configuration file
@file{named.conf} to determine several settings needed for its further
operation, in particular, the value of the @samp{directory} statement
in the @samp{options} block.

@cindex synchronization block
Once these preliminary operations are over, @command{nssync} starts
its main task.  Its configuration file defines, among other data, one
or more @dfn{synchronization blocks}.  Each such block defines SQL
statements which return information about DNS zones as well as the
location of @command{named} configuration file where the @code{zone}
statements for these zones are to be stored (it is supposed that this
file is included somewhere in the main @file{named.conf} file).  For
each synchronization block, the utility retrieves the zone data from
the database and formats them into separate zone files.  Each of these
files is then compared to an already existing one (locations of the
zone files are defined in the synchronization block they pertain to).
If the files differ, new zone file replaces the old one and a flag is
set indicating that the @command{named} daemon needs to be restarted
in order to read new configuration.

When this stage is finished, @command{nssync} reloads the name server
(if required) and exits.

Several command line options can be supplied in order to modify the
program's behavior.  In particular, it is possible to check the
configuration file syntax or even instruct the utility to do
everything, except modifying the zone files (a so-called @dfn{dry-run
mode}).  This allows you to debug your configuration before actually
starting using @command{nssync}.

@node Configuration File
@chapter Configuration File
@findex nssync.conf
@command{Nssync} reads its settings from a configuration file
@file{nssync.conf} located normally in the system configuration
directory (usually @file{/etc} or @file{/usr/local/etc}, depending on
compile-time options).

This chapter describes the syntax of that file in general.  The
chapter that follows describes the @command{nssync}-specific
settings in detail.

@raisesections
@include grecs-syntax.texi
@lowersections

@node Nssync Configuration
@chapter Nssync Configuration

@menu
* General Settings::
* SQL Access::
* Synchronization Block::
@end menu

@node General Settings
@section General Settings
These settings modify the behavior of @command{nssync} as a whole.

@deffn {Configuration} pidfile @var{file}
At startup, check if @var{file} already exists and is owned by an existing
process.  Exit if so.  Use this statement to avoid accidentally
running two copies of @command{nssync} simultaneously.
@end deffn

@deffn {Configuration} tempdir @var{dir}
Sets the name for the temporary directory.  This is a directory where
@command{nssync} creates temporary zone files.  The argument must
point to an existing directory.
@end deffn

@deffn {Configuration} check-ns @var{bool}
If set to @code{true}, @command{nssync} will check the list of NS
servers prior to creating a zone file.  The file will be created only
if IPv4 address of one of the servers matches one of the IP addresses
of the host on which @command{nssync} is run.
@end deffn

@deffn {Configuration} named-conf @var{file}
Defines the full pathname of the @command{named} configuration file.
Default is @file{/etc/named.conf}.
@end deffn

@deffn {Configuration} bind-include-path @var{list}
Sets include search path for @code{include} directives found in BIND
configuration.  The argument is either a single directory or a list of
directories (@pxref{Statements, list}).
@end deffn

@anchor{zonefile-pattern}
@deffn {Configuration} zonefile-pattern @var{pat}
Defines the pattern for zone file names.  The name of each zone
file is created by expanding variable references in the @var{pat}
argument.  The following variable references are defined:

@table @asis
@item $zone
@itemx $@{zone@}
Name of the zone, without the trailing dot.

@item $synctag
@itemx $@{synctag@}
Zone synchronization tag (@pxref{Synchronization Block}).
@end table

Both notations (with and without braces) are equivalent.  The notation
with curly braces should be used if the reference is immediately
followed by a letter.

The default zone file pattern is @samp{$zone.$synctag}.
@end deffn

@anchor{zone-conf}
@deffn {Configuration} zone-conf @var{pat}
Defines the pattern for @dfn{zone configuration file}, i.e. a file
containing @code{zone} statements.

The handling of @var{pat} is similar to that in @code{zonefile-pattern},
except that only the @samp{$synctag} reference is defined.
@end deffn

@deffn {Configuration} compare-command @var{cmd}
Defines a command to be used for comparing two zone files.  The
@var{cmd} must be a command taking two files as its arguments and
returning 0 if they are the same or non-zero if they differ.
@command{Nssync} uses this command to determine whether a particular
zone has changed.  The following @dfn{variable references} are
expanded in @var{cmd}:

@table @asis
@item $oldfile
@itemx $@{oldfile@}
Old zone file.

@item $newfile
@item $@{newfile@}
New zone file.
@end table

The default @code{compare-command} value is:

@example
cmp $oldfile $newfile > /dev/null
@end example
@end deffn

@deffn {Configuration} reload-command @var{cmd}
Defines a command to reload the nameserver.  The default is
@samp{/usr/sbin/rndc reload}.
@end deffn

@node SQL Access
@section SQL Access
The following statements define the database server and the database
to use:

@deffn {Configuration} host @var{hostname}[:@var{port-or-socket}]
Defines the SQL server IP and port.  The @var{hostname} can be either
the server IP address or its hostname.  The @var{port-or-socket} part,
if supplied, can be either the number of TCP port to use instead of
the default 3306 or the full pathname of the UNIX socket.  In the
latter case @var{hostname} is effectively ignored.
@end deffn

@deffn {Configuration} database @var{name}
Sets the database name.
@end deffn

@deffn {Configuration} ssl-ca @var{file}
Defines the name of the Certificate Authority (CA) file.
@end deffn

There are two ways to supply database access credentials.  The
simplest one is by using @code{user} and @code{password} statements:

@deffn {Configuration} user @var{name}
Sets SQL user name.
@end deffn

@deffn {Configuration} password @var{arg}
Sets SQL user password.
@end deffn

The drawback of this approach is that the password appears in
plaintext, which means the permissions of the @file{nssync.conf} file
must be tightened so as to avoid its compromise.

The following two statements provide an alternative, more safe and
flexible way of setting access credentials:

@deffn {Configuration} sql-config-file @var{file}
Read MySQL configuration from the @dfn{option file} @var{file}. 
@ifhtml
See @uref{http://dev.mysql.com/doc/refman/5.0/en/option-files.html,
option files},
@end ifhtml
@ifnothtml
@xref{option-files, Using Option Files,,mysql,MySQL Manual},
@end ifnothtml
for a description of MySQL option file format.
@end deffn

@deffn {Configuration} sql-config-group @var{name}
Read the named group from the SQL configuration file.
@end deffn

To illustrate their use, suppose your @file{nssync.conf} file contains
the following:

@example
sql-config-file /etc/nssync.my;
sql-config-group nssync;
@end example

The the @file{/etc/nssync.my} will contain the actual SQL access
configuration, which can look as in the example below:

@example
[nssync]
socket = /var/db/mysql.sock
database = dns 
user = root
pass = guessme
@end example

@anchor{slave-status-file}
@deffn {Configuration} slave-status-file @var{file}
Use this statement if @command{nssync} reads data from a slave
database.  It allows you to avoid recreating zone files if the
database information has not changed since the previous run.

If this statement is present, @command{nssync} will save the state of
the SQL slave in @var{file}.  Upon startup, it will read these data
and compare them with the current state.  If they are the same, it
will exit immediately.
@end deffn

@node Synchronization Block
@section Synchronization Block
@kindex sync
@cindex synchronization block
@cindex synchronization tag
A @dfn{synchronization block} defines a set of zones to be
synchronized from the database and configures SQL statements which
return the zone data.  This set is identified by @dfn{synchronization
tag}, supplied as the argument to the @code{sync} statement:

@example
# @r{Define a synchronization block}.
sync @var{tag} @{
  # @r{zone configuration file}
  zone-conf @var{pat};
  # @r{pattern for new zone file names}
  zonefile-pattern @var{pat};
  # @r{add these statements to each generated zone file}
  add-statements @var{text};
  # @r{a query for retrieving SOA records}
  soa-query @var{string};
  # @r{a query for retrieving NS and similar records}
  ns-query @var{string};
  # @r{a query for retrieving the rest of RRs}
  rr-query @var{string};
  # @r{a query for retrieving RRs from reverse delegation zones}
  rev-rr-query @var{string};
@}
@end example

Statements within the @code{sync} block configure the zones:

@deffn {Configuration} zone-conf @var{pat}
Defines the pattern for the name of zone configuration file for zones
in this synchronization block.  If not supplied, the global
@code{zone-conf} statement will be used instead (@pxref{zone-conf}).
@end deffn

@deffn {Configuration} zonefile-pattern @var{pat}
Defines the pattern for zone file names.  If not supplied, the global
@code{zonefile-pattern} statement will be used instead
(@pxref{zonefile-pattern}).
@end deffn

@deffn {Configuration} add-statements @var{text}
Append @var{text} to each generated zone statement.  For example, the
following can be used to redefine forwarders and query ACLs for zones
in this synchronization block:

@example
add-statements <<EOT
  forwarders @{ /* empty */ @};
  allow-query @{ local-query-only; @};
EOT;
@end example

Notice the use of the @dfn{here-document} construct.
@end deffn

The following statements define which zones pertain to this particular
synchronization block:

@deffn {Configuration} soa-query @var{string}
A query for retrieving SOA records.
@end deffn

@deffn {Configuration} ns-query @var{string}
A query for retrieving NS and similar records.  Use the @samp{$zone}
reference for the zone name.
@end deffn

@deffn {Configuration} rr-query @var{string}
A query for retrieving the rest of RRs.  Use the @samp{$zone}
reference for the zone name.
@end deffn

@deffn {Configuration} rev-rr-query @var{string}
A query for retrieving RRs from reverse delegation zones.  Use the @samp{$zone}
reference for the zone name.
@end deffn

Here is an example of a working @code{sync} directive:

@example
sync external @{
  zone-conf "/var/namedb/nssync/zones.external";
  zonefile-pattern "/var/namedb/external/db.$@{zone@}";
  
  soa-query    "select zone, ttl, type, data, resp_person, "
               "serial, refresh, retry, expire, minimum "
               "from dns_soa where type='SOA' "
               "and view='external' order by zone";
               
  ns-query     "select ttl, type, data "
               "from dns_soa where zone='$zone' "
               "and type<>'SOA' and view='external'";
               
  rr-query     "select host, ttl, type, mx_priority, "
               "case when type='TXT' then "
               "concat('\"', data, '\"') "
               "else data end "
               "from dns_records "
               "where zone='$zone' and view='external' "
               "order by 1";
               
  rev-rr-query "select host, ttl, type, mx_priority, "
               "case when type='TXT' then "
               "concat('\"', data, '\"') "
               "else data end "
               "from dns_records "
               "where zone='$zone' and view='external' "
               "order by cast(host as unsigned)";
@}
@end example

@node Invocation
@chapter Invocation

The @command{nssync} is normally invoked periodically from a crontab,
e.g.:

@example
@group
@ifhtml
*/5 * * * *  /usr/sbin/nssync | /usr/bin/logger -t nssync -p local1.err
@end ifhtml
@ifnothtml
*/5 * * * *  /usr/sbin/nssync | \
  /usr/bin/logger -t nssync -p local1.err
@end ifnothtml
@end group  
@end example

The following table summarizes available command line options:

@table @option
@item -E
Preprocess configuration file and exit.

@item -c @var{file}
@itemx --config-file=@var{file}
Use @var{file} instead of the default configuration file.

@item -f
@itemx --force
Proceed even if slave status has not changed (@pxref{slave-status-file}).

@item -n
@itemx --dry-run
Do nothing, print almost everything; implies @option{--debug
--stderr}.  Use additional @option{--debug} options to get even more
info.

@item -t
@itemx --lint
Parse configuration file and exit.  The return status is 0 if the
syntax is OK, and 78 if errors were detected (@pxref{Exit Codes}).

@item -D @var{symbol}=@var{value}
@itemx --define=@var{symbol}[=@var{value}]
Define a preprocessor symbol.

@item -I @var{dir}
@itemx --include-directory=@var{dir}
Add include directory.

@item --no-preprocessor
Disable preprocessing.

@item --preprocessor=@var{command}
Use @var{command} instead of the default preprocessor.

@item -d
@itemx --debug
Increase debug level.

@item -X
@itemx --debug-lexer
Debug configuration file lexer.

@item -x
@itemx --debug-parser
Debug configuration file parser.

@item --config-help
Show configuration file summary

@item -V
@item --version
Print program version.

@item -h
@item --help
Give this help list.

@item --usage
Give a short usage message.
@end table

@node Exit Codes
@chapter Exit Codes

  Apart from issuing a descriptive error message, @command{nssync}
attempts to indicate the reason of its termination by its error code.
As usual, a zero exit code indicates normal termination.  The table
below summarizes all possible error codes.   For each error code, it
indicates its decimal value and its symbolic name from
@file{include/sysexits.h} (if available).

@table @asis
@item 0
@itemx EX_OK
Program terminated correctly.

@item 64
@itemx EX_USAGE
The program was invoked incorrectly, e.g. an invalid option was given,
or an erroneous argument was supplied to an option.

@item 69
@itemx EX_UNAVAILABLE
The program exited due to some error not otherwise described in this
table.

@item 70
@item EX_SOFTWARE
Some internal software error occurred.

@item 78
@itemx EX_CONFIG
An error in the configuration file was detected.
@end table

@node Reporting Bugs
@chapter How to Report a Bug

  Email bug reports to @email{gray+nssync@@gnu.org.ua}.  Please include a
detailed description of the bug and information about the conditions
under which it occurs, so we can reproduce it.  To facilitate the
task, the following list shows the basic set of information that is
needed in order to find the bug:

@itemize
@item Package version you use.  
@item A detailed description of the bug.
@item Conditions under which the bug appears.
@item It is often helpful to send the contents of @file{config.log}
file along with your bug report. This file is created after running
@command{./configure} in the @file{nssync} source root directory.
@end itemize

@ifhtml
@ifset WEBDOCS
@node Downloads
@chapter Downloads
@html
<!--#include virtual="downloads.html" -->
@end html

@node This Manual in Other Formats
@appendix This Manual in Other Formats
@html
<!--#include virtual="manual/formats.html" -->
@end html
@end ifset
@end ifhtml

@node Copying This Manual
@appendix GNU Free Documentation License
@include fdl.texi

@node Concept Index
@unnumbered Concept Index

This is a general index of all issues discussed in this manual.

@printindex cp

@bye

Return to:

Send suggestions and report system problems to the System administrator.