README 6.34 KB
Newer Older
Jeremy C. Reed's avatar
Jeremy C. Reed committed
1 2 3 4 5
This is the source for the development version of BIND 10.

BIND is the popular implementation of a DNS server, developer
interfaces, and DNS tools. BIND 10 is a rewrite of BIND 9. BIND 10
is written in C++ and Python and provides a modular environment
6
for serving, maintaining, and developing DNS.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
7 8 9 10

BIND10-devel is new development leading up to the production
BIND 10 release. It contains prototype code and experimental
interfaces. Nevertheless it is ready to use now for testing the
11 12
new BIND 10 infrastructure ideas. The Year 2 milestones of the
five year plan are described here:
Jeremy C. Reed's avatar
Jeremy C. Reed committed
13

14
	https://bind10.isc.org/wiki/Year2Milestones
Jeremy C. Reed's avatar
Jeremy C. Reed committed
15

16 17 18 19
This release includes the bind10 master process, b10-msgq message
bus, b10-auth authoritative DNS server (with SQLite3 backend),
b10-cmdctl remote control daemon, b10-cfgmgr configuration manager,
b10-xfrin AXFR inbound service, b10-xfrout outgoing AXFR service,
20 21
b10-zonemgr secondary manager, and a new libdns++ library for C++
with a python wrapper.
Jeremy C. Reed's avatar
Jeremy C. Reed committed
22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38

Documentation is included and also available via the BIND 10
website at http://bind10.isc.org/

The latest released source may be downloaded from:

        ftp://ftp.isc.org/isc/bind10/

Users and developers are encouraged to participate on the BIND 10
mailing lists:

        https://lists.isc.org/mailman/listinfo/bind10-users
        https://lists.isc.org/mailman/listinfo/bind10-dev

Bugs may be reported as tickets via the developers website:

        http://bind10.isc.org/
39

40 41
BUILDING

42 43 44
See the Guide for detailed installation directions at
doc/guide/bind10-guide.html.

45 46
Simple build instructions:

47 48
  ./configure
  make
49

50
If building from Subversion repository, run:
Jeremy C. Reed's avatar
Jeremy C. Reed committed
51 52 53 54 55

  autoreconf --install

before running ./configure

56 57 58
Requires autoconf 2.59 or newer.

Use automake-1.11 or better for working Python 3.1 tests.
59 60 61 62
Alternatively, you could manually specify an absolute path to python
executable by the --with-pythonpath option of the configure script,
e.g.,
% ./configure --with-pythonpath=/usr/local/bin/python3.1
63

64 65 66 67 68 69 70 71 72 73 74 75 76
Operating-System specific tips:

- FreeBSD
  You may need to install a python binding for sqlite3 by hand.  A
  sample procedure is as follows:
  - add the following to /etc/make.conf
    PYTHON_VERSION=3.1
  - build and install the python binding from ports, assuming the top
    directory of the ports system is /usr/ports
  % cd /usr/ports/databases/py-sqlite3/
  % make
  % sudo make install

77 78
INSTALLATION

79 80 81
Install with:

  make install
82

83 84 85 86
TESTS

The tests use the googletests framework for C++. It is available
from http://code.google.com/p/googletest/.  To enable the tests,
87
configure BIND 10 with: 
88

89
  ./configure --with-gtest
90 91 92

Then run "make check" to run these tests.

93 94
TEST COVERAGE

95 96
The code coverage report for the C++ tests uses LCOV. It is available
from http://ltp.sourceforge.net/. To generate your own HTML report,
97 98 99
first configure BIND 10 with:
 
  ./configure --with-lcov
100

101 102
Doing code coverage tests:

103
  make coverage
104 105
	Does the following:

106
  make clean-coverage
107 108
	Zeroes the lcov code coverage counters and removes the coverage HTML.

109
  make perform-coverage
110 111
	Runs the C++ tests (using googletests framework).

112
  make report-coverage
Jeremy C. Reed's avatar
Jeremy C. Reed committed
113 114
	Generates the coverage HTML, excluding some unrelated headers.
	The HTML reports are placed in a directory called coverage/.
115

116 117 118 119 120
DEVELOPERS

The generated run_*.sh scripts available in the src/bin directories
are for running the code using the source tree.

121 122
RUNNING

123 124 125
You can start the BIND 10 processes by running bind10 which is
installed to the sbin directory under the installation prefix.
The default location is:
126

127 128 129 130
  /usr/local/sbin/bind10

For development work, you can also run the bind10 services from the
source tree:
131

132 133 134 135 136 137
 ./src/bin/bind10/run_bind10.sh 

(Which will use the modules and configurations also from the source
tree.)

The server will listen on port 5300 for DNS requests.
138 139 140

CONFIGURATION

141
Commands can be given through the bindctl tool.
142

Jeremy C. Reed's avatar
Jeremy C. Reed committed
143
The server must be running for bindctl to work.
144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163

The following configuration commands are available

help: show the different command modules
<module> help: show the commands for module
<module> <command> help: show info for the command


config show [identifier]: Show the currently set values. If no identifier is
                          given, the current location is used. If a config
                          option is a list or a map, the value is not
                          shown directly, but must be requested separately.
config go [identifier]:   Go to the given location within the configuration.
config set [identifier] <value>: Set a configuration value.
config unset [identifier]: Remove a value (reverts to default if the option
                           is mandatory).
config add [identifier] <value>: add a value to a list
config remove [identifier] <value>: remove a value from a list 
config revert:	Revert all changes that have not been committed
config commit: Commit all changes
164
config diff: Show the changes that have not been committed yet
165 166 167

EXAMPLE SESSION

168
~> bindctl
169
["login success "] login as root
Jelte Jansen's avatar
Jelte Jansen committed
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
> help
BindCtl, verstion 0.1
usage: <module name> <command name> [param1 = value1 [, param2 = value2]]
Type Tab character to get the hint of module/command/paramters.
Type "help(? h)" for help on bindctl.
Type "<module_name> help" for help on the specific module.
Type "<module_name> <command_name> help" for help on the specific command.

Available module names: 
	 help 	Get help for bindctl
	 config 	Configuration commands
	 Xfrin 	same here
	 Auth 	same here
	 Boss 	same here
> config help
Module  config 	Configuration commands 
Available commands:
	 help 	(Get help for module)
	 show 	(Show configuration)
	 add 	(Add entry to configuration list)
	 remove 	(Remove entry from configuration list)
	 set 	(Set a configuration value)
	 unset 	(Unset a configuration value)
	 diff 	(Show all local changes)
	 revert 	(Revert all local changes)
	 commit 	(Commit all local changes)
	 go 	(Go to a specific configuration part)
197
> config show
Jelte Jansen's avatar
Jelte Jansen committed
198
Xfrin/	module	
199 200
Auth/	module	
Boss/	module	
Jelte Jansen's avatar
Jelte Jansen committed
201 202
> config show Xfrin
transfers_in:	10	integer	
203 204
> config go Auth
/Auth> config show
Jelte Jansen's avatar
Jelte Jansen committed
205 206 207
database_file:	None	string	
/Auth> config set database_file /tmp/bind10_zones.db
/Auth> config commit
208
/Auth> config go /
Jelte Jansen's avatar
Jelte Jansen committed
209 210 211 212 213 214 215
> config show Auth/
database_file:	/tmp/bind10_zones.db	string	
> config diff
{}
> config set Auth/foobar
Error: missing identifier or value
> config set Auth/database_file foobar
216
> config diff
Jelte Jansen's avatar
Jelte Jansen committed
217 218
{'Auth': {'database_file': 'foobar'}}
> config revert
219 220 221
> config diff
{}
> quit