.TH DNSCTL 8 "August 2007" "OpenFWTK"
.SH NAME
dnsctl \- djb's dnscache configuration control program
.SH SYNOPSIS
.B dnsctl
.sp
.SH DESCRIPTION
.IX  "dnsctl"  ""  "\(em djb's dnscache configuration control program"
.I dnsctl 
is a configuration control program which allows D.J. Bernstein's 
.I dnscache
utility to be controlled via
.BR "netperm-table (5)"
configuration.
.PP
As djb's license is quite restrictive, it is not possible to distribute
modified versions of 
.I dnscache .
That's why
.I dnsctl
was created: to have configuration unified.
.PP
The 
.RB dnsctl
program should be run every time its configuration in
.IR netperm-table
gets updated. On start, the program reads the
.IR netperm-table
and translates appropriate rules to
.I dnscache
configuration.
.PP
.SH OPTIONS
.SS Command Line Options
None.
.PP
.SS Configuration Options
The program reads configuration rules from the
.IR "/usr/local/etc/netperm-table" .
It reads all rules using the
.B dnsctl
,
.B *
(wildcard) keywords and 
.I instances
specified in the main configuration. The proxy reads the
.I netperm-table
from top to bottom.  If there are multiple rules in the table that
could apply for a particular attribute, the proxy uses the
first one that it finds. Each
.I instance
starts reading configuration from the beginning with its own tag and uses 
.B "dnsctl"
tag after the end of the instance configuration was reached. See
.BR "netperm-table"  (5)
for a more complete explanation of 
.I netperm-table
syntax and precedence.
.PP
The program recognizes the following attributes:
.TP
.BI "base " "directory"
Specifies 
.I "djb daemontools"
configuration base directory to which running copies of
.I dnscache
are relative.
.RS
.TP
.I directory
Specifies absolute unix directory path.
.RE
.TP
.BI "instances " "instance [instance...]" 
rules specify 
.I dnscache
instance tags which follow.
.PP
Each instance configuration consists of:
.TP
.BI "bind " ip-address
Specifies instance bind address.
.RS
.TP
.I ip-address
IPv4 address to bind.
.RE
.TP
.BI "zone " zone-name " -servers " "server [server..]"
Specifies forward or reverse zone and master forwarders for it.
.RS
.TP
.I zone-name
Name of the zone, p.e. 
.B "alphacomplex.int"
,
.B "0.0.10.in-addr.arpa"
.
.TP
.I server
Master DNS server for specified zone (IPv4 address)
.RE
.TP
.BI "default-servers " "server [server..]"
Specifies default master forwarder for zones not listed expicitly.
.RS
.TP
.I server
Default master DNS server (IPv4 address)
.RE
.TP
.BI "hosts " "ip [ip..]"
Specifies client IPs permitted to perform DNS requests to the instance.
.RS
.TP
.I ip
IPv4 address of host or network (partial, like 192.168).
Please note that 
.IR host
parameter syntax differs form traditional
.IR netperm-table
\.
.SH EXAMPLES
Sample configuration providing two 
.I dnscache
instances: 
.B dnscache-int
serving 
.B 10.0.0 
network on 
.B 10.0.0.1 
interface and
.B dnscache-local
serving firewall machine itself.
.sp 1
.nf
.na
.RS
dnsctl:		base PREFIX/var/djbtools
dnsctl:		instances dnscache-int dnscache-local
dnscache-int:	bind 10.0.0.1
dnscache-int:	hosts 10.0.0
dnscache-local:	bind 127.0.0.1
dnscache-local:	hosts 127.0.0.1
# Zone sources are common for both instances
dnsctl:		zone alpha.int -server 10.0.0.2
dnsctl:		zone 0.0.10.in-addr.arpa -server 10.0.0.2
dnsctl:		default-servers 17.15.1.2 17.15.1.3

.RE
.fa
.fi
.SH FILES
.IP /usr/local/etc/netperm-table
The network permissions file contains configuration information
for the Firewall Toolkit, including dnsctl.
.SH BUGS
.I dnsctl
does not share exactly the same syntax with other OpenFWTK tools.
Sorry, djb tools are tricky.
.sp
Report bugs to arkenoi@gmail.com or fwtk-users@buoy.com mailing list.
Include a complete example, explaining what you expected to happen and what actually
happened.  Be sure to indicate the type of system (operating system,
hardware, etc.) you are using, as well as the version of dnsctl.
.SH AUTHOR
ArkanoiD.
.SH SEE ALSO
.BR netperm-table "(5), " rc "(8), "authsrv "(8), "netacl "(8), " "http:/cr.yp.to " "(djbdns and daemontools home)"