~samiam/MaraDNS

ref: 3.5.0002 MaraDNS/deadwood-github/INSTALL.txt -rw-r--r-- 8.7 KiB View raw
db09084f — Sam Trenholme MaraDNS release 3.5.0002 3 months ago
                                                                                
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
Deadwood is a recursive DNS program that is supported for two platforms:
Windows 10 (via MinGW) and CentOS 7.

This program may or may not work on other platforms; it is not supported
on other platforms in the sense that I am not able to effectively
answer any questions about running Deadwood on said platform (but see
"Other platforms" below).

The rest of this document deals with how to compile this code in CentOS 7,
followed by a section on how to compile this code in Windows 10.

==CentOS 7==

To compile this program in CentOS 7, first set the environmental variable
FLAGS to the flags you wish to give the compiler.  For example, with
gcc, you probably want to make the compile-time flags "-O3" unless you
are making this as small as possible for an embedded system.

To set the flags to be "-O3" using a POSIX-compliant shell (Bash, ash, etc.):

	export FLAGS='-O3'

Once the compile-time flags are set, the next step is to compile the
program.  If in Scientific Linux 6, enter the src directory and use 'make' 
to do this:

	cd src/
	make -f Makefile.sl6

There is a single program compiled, Deadwood.  Place this program where
it can be used.  For example, to place this program in the directory
/usr/local/bin, as root:

	cp Deadwood /usr/local/bin
	cd /usr/local/bin

Return back to the directory with this file. 

The next step is to install the man page for Deadwood.  
Here is one way to do this as root:

	cd doc/
	cp Deadwood.1 /usr/local/share/man/man1

Of course, you may want to start up this program and run it as a 
daemon when the system starts up.  First, look at the text file
dwood3rc (in the doc/ directory) and edit it.  Then, make
this file /etc/dwood3rc.  For example:

	nano -w dwood3rc
	cp dwood3rc /etc

You will also want to make a directory for Deadwood.  This is the
chroot_dir parameter in the dwood3rc file, and by default points to
/etc/deadwood:

	mkdir /etc/deadwood
	chown 99:99 /etc/deadwood
	
Deadwood doesn't have any daemonization capability; this is handled
by a separate program I wrote for MaraDNS, 'duende'.  This program
is in the tools/ directory, and needs to be compiled separately
from Deadwood.  

	cd tools/
	make
	cp duende /usr/local/bin
	mkdir /etc/maradns
	mkdir /etc/maradns/logger

The directory /etc/maradns/logger is needed for duende to run.

Now, you will want to edit your system start-up scripts to start up
Deadwood.  To do this in Scientific Linux 6, make a file with the name
/etc/init.d/deadwood with the following content:

#!/bin/sh
case "$1" in
  start)
        /usr/local/bin/duende /usr/local/bin/Deadwood
        ;;
  stop)
        killall Deadwood
        ;;
esac
# End of startup script

Make sure /etc/init.d/deadwood can be run as a program:
	
	chmod 755 /etc/init.d/deadwood

Then, you will want to have this script be run at system boot time:

	cd /etc/rc.d/rc3.d/
	ln -s ../init.d/deadwood S61deadwood
	cd /etc/rc.d/rc5.d/
	ln -s ../init.d/deadwood S61deadwood

Note that system startup is variable between distributions and the above
steps may not work if you're not using Scientific Linux 6.  If you wish
help with using Deadwood with another version of Linux or *NIX, you are
on your own.  Feel free to fork the MaraDNS Github repository, but
please do not name any such ports "MaraDNS".

It is possible to compile Deadwood with IPv6 support.  See the file 
doc/compile.options for details

==WINDOWS 10==

The simplest way to run this program in Windows 10 is to use the
prebuilt binary (.exe file) which should be in the same place as
the place where you obtained this source code, with a name like
"Deadwood-3-5-XXXX-win32.zip".

The way I compile this program is by using a Windows XP virtual machine
with MinGW-3.4.2 (which does not run in Windows 10) and MSYS-1.0.10.  
These programs are available at the following location:

	http://samiam.org/software 

Note that Windows 7 is the most recent version of Windows to still run
this compiler.

Once MinGW is set up, to compile the Deadwood service, enter the "src/"
directory and run the following commands:

	export FLAGS=-O3
	make -f Makefile.mingw342

Once this is done, there will be a file called Deadwood.exe, which is
a Windows service.  First, find a suitable directory on your file system
to install Deadwood, such as "c:\Program Files\Deadwood\"

At this point, one needs to use a cmd prompt with administrator privileges.

To open up an admin cmd prompt:

* Go to the start menu and search for "cmd"

* When found, right click on it and run "cmd" as an administrator

Once this administrative "cmd" prompt is opened, it is necessary to
install Deadwood.  Here is how to install the service:

	Deadwood --install

Before you can run the service, you will need a file named "dwood3rc.txt"
for Deadwood to read its parameters from.  An example file is in 
doc\Windows\dwood3rc.txt

You need to make a file with random text in it called secret.txt.

Once these two files are in place, and properly configured, Deadwood
can be started:

	net start Deadwood

(You can also start it from Control Panel -> Administrative Tools -> Services)

Deadwood, at this point, should automatically start whenever the system is 
booted.

Deadwood uses a file to store messages called "dwlog.txt" (without the
quotes) in the same directory where Deadwood is started.  If there are
any errors that make it so Deadwood can not start, they should be noted
in this log file.

To stop Deadwood:

	net stop Deadwood

(Or from the Services control panel if you prefer mousing it)

Deadwood will write its cache to a file (if specified) when stopped as a
service.

Deadwood service provides DNS-over-UDP and DNS-over-TCP support; note
that DNS packets too long to fit in a 512-byte UDP packet are not cached.
Deadwood goes to some effort to shorten packets longer than 512 bytes
long before giving up and telling the user the remote packet has been
truncated.

It should be possible to remove the Deadwood service:

	Deadwood --remove 

If one wishes to uninstall Deadwood.

==OTHER PLATFORMS==

Just because Deadwood is only fully supported in CentOS 7 and Windows
10 doesn't mean Deadwood doesn't run on other platforms. It just means
that, if you wish to run Deadwood on another platform, it's up to you
to make the port. Feel free to fork the MaraDNS Github repository,
but please do not name any such ports "MaraDNS".

I have made the code portable; there should not be any endian issues
(this has not been tested since I don't have access to a big-endian
computer) nor non-standard libraries needed to compile this; I ensure
Deadwood compiles with no warnings when compiled with -Wall in GCC 3,
GCC 4.3, and GCC 4.4.

Note that Deadwood uses stdint.h, which some non-standards-compilant
proprietary compilers (Microsoft, *cough* *cough*) may not have.  If you
wish to compile Deadwood with one of these compilers, please find a
version of stdint.h for your compiler; I know there is a pstdint.h out
there that works with most Microsoft and Borland compilers.

Note also that some UNIX systems, such as Mac OS X, do not have the
POSIX-compliant clock_gettime() call, which is used so Deadwood can retry
more quickly when a DNS server upstream does not reply to our query.
To compile Deadwood on a UNIX system without clock_gettime(), use the
"Makefile.fallback" file.  From the src/ directory:

	make -f Makefile.fallback

The Makefile.sl6 file should work on other Linux variants, as well as
other *NIX clones, but no guarantees.  For example, there is a Cygwin
Makefile included in the "src/" directory; while I haven't tested
this in a while, I once verified that Deadwood 2.4 compiles in Cygwin
without problem.  This may even make it possible to have a version of
Deadwood in Windows with IPv6 support; I believe Cygwin 1.7 and later
have IPv6 and it might be possible to compile in IPv6 this way.  Again,
if this is something you're interested in, feel free to fork the MaraDNS
Github repository, but please do not name any such ports "MaraDNS".

Please note that Deadwood's behavior is undefined should malloc()
fail.  If using Deadwood in an environment where malloc() may return
NULL, please replace the dw_malloc() macro with a function that can
properly handle a malloc() failure.

Also note that Deadwood performs a large number of malloc()s and free()s
during its operation, and may have issues in embedded environments with
simplistic malloc() implementations which can not handle a program 
allocating then freeing a lot of small blocks of memory.

==SUPPORT==

The only Deadwood support provided is bug fixes.  To report a bug, post
an issue on GitHub:
	
	https://github.com/samboy/MaraDNS/issues