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

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/
40

41
42
BUILDING

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

46
47
Simple build instructions:

48
49
  ./configure
  make
50

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

  autoreconf --install

before running ./configure

57
58
59
Requires autoconf 2.59 or newer.

Use automake-1.11 or better for working Python 3.1 tests.
60
61
62
63
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
64

65
66
67
68
69
70
71
72
73
74
75
76
77
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

78
79
INSTALLATION

80
81
82
Install with:

  make install
83

84
85
86
87
TESTS

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

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

Then run "make check" to run these tests.

94
95
TEST COVERAGE

96
97
98
99
100
Code coverage reports may be generated using make. These are
based on running on the unit tests. The resulting reports are placed
in coverage-cpp-html and coverage-python-html directories for C++
and Python, respectively.

101
The code coverage report for the C++ tests uses LCOV. It is available
102
from http://ltp.sourceforge.net/. To generate the HTML report,
103
104
105
first configure BIND 10 with:
 
  ./configure --with-lcov
106

107
108
109
110
111
112
The code coverage report for the Python tests uses coverage.py (aka
pycoverage). It is available from http://nedbatchelder.com/code/coverage/.
To generate the HTML report, first configure BIND 10 with:

  ./configure --with-pycoverage

113
114
Doing code coverage tests:

115
  make coverage
116
	Does the clean, perform, and report targets for C++ and Python.
117

118
  make clean-coverage
119
120
	Zeroes the code coverage counters and removes the HTML reports
	for C++ and Python.
121

122
  make perform-coverage
123
124
	Runs the C++ (using the googletests framework) and Python
	tests.
125

126
  make report-coverage
127
128
129
130
131
132
133
134
135
136
137
138
139
	Generates the coverage reports in HTML for C++ and Python.

  make clean-cpp-coverage
	Zeroes the code coverage counters and removes the HTML report
	for the C++ tests.

  make clean-python-coverage
	Zeroes the code coverage counters and removes the HTML report
	for the Python tests.

  make report-cpp-coverage
	Generates the coverage report in HTML for C++, excluding
	some unrelated headers.  The HTML reports are placed in a
140
	directory called coverage-cpp-html/.
141
142
143

  make report-python-coverage
	Generates the coverage report in HTML for Python. The HTML
144
	reports are placed in a directory called coverage-python-html/.
145

146
147
148
149
150
DEVELOPERS

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

151
152
RUNNING

153
154
155
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:
156

157
158
159
160
  /usr/local/sbin/bind10

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

162
163
164
165
166
167
 ./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.
168
169
170

CONFIGURATION

171
Commands can be given through the bindctl tool.
172

Jeremy C. Reed's avatar
Jeremy C. Reed committed
173
The server must be running for bindctl to work.
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193

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
194
config diff: Show the changes that have not been committed yet
195

Jeremy C. Reed's avatar
Jeremy C. Reed committed
196

197
198
EXAMPLE SESSION

199
~> bindctl
200
["login success "] login as root
Jelte Jansen's avatar
Jelte Jansen committed
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
> 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)
228
> config show
Jelte Jansen's avatar
Jelte Jansen committed
229
Xfrin/	module	
230
231
Auth/	module	
Boss/	module	
Jelte Jansen's avatar
Jelte Jansen committed
232
233
> config show Xfrin
transfers_in:	10	integer	
234
235
> config go Auth
/Auth> config show
Jelte Jansen's avatar
Jelte Jansen committed
236
237
238
database_file:	None	string	
/Auth> config set database_file /tmp/bind10_zones.db
/Auth> config commit
239
/Auth> config go /
Jelte Jansen's avatar
Jelte Jansen committed
240
241
242
243
244
245
246
> 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
247
> config diff
Jelte Jansen's avatar
Jelte Jansen committed
248
249
{'Auth': {'database_file': 'foobar'}}
> config revert
250
251
252
> config diff
{}
> quit