-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathINSTALL.html
1323 lines (1050 loc) · 39.4 KB
/
INSTALL.html
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
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<title>
GnuDIP Release 2.3.5 - INSTALL File
</title>
<base target="_blank">
</head>
<body bgcolor=white>
<table><tr valign=middle><td>
<img align=middle src="gnudip/html/gnudip.jpg" alt="GnuDIP Logo" border=0 height=60 width=113>
</td><td>
<h1>GnuDIP Release 2.3.5 - INSTALL File</h1>
</table>
<hr>
<h3>Preliminary Steps</h3>
<ol>
<li>
Become familiar with the set of low privilege UNIX user IDs used for running
daemons on your system.
<p>
Many UNIX systems use a very simple system. There is a user ID named
<code>nobody</code>. The <code>nobody</code> user ID cannot be logged in to.
It can only be reached through the "<code>root</code>" user ID. It also has
its own group. A process running under this ID will only be able to read files
that are "world readable", and only able to modify or delete files that are
"world writable".
<p>
Within this set up it is common practice to run the BIND
<code>named</code> daemon as user <code>nobody</code>. Also, the sample
configuration file that comes with the Apache web server source will run all
CGI scripts as user <code>nobody</code>.
<p>
Some systems (apparently Red Hat does this) have several "<code>nobody</code>"
user ID-s. Each daemon that can be run as a low privilege user gets its own
user ID.
<p>
In these instructions, we assume that there is a single <code>nobody</code>
user ID. When we refer to the <code>nobody</code> user ID, the reader should
substitute the appropriate user ID for the daemon being discussed.
<p><li>
Move the directory <a href="gnudip/"><code>gnudip</code></a>
to <code>/usr/local</code> (or <code>/opt</code>, or wherever you wish -
we will assume <code>/usr/local</code> in what follows).
If you copy this directory instead,
be careful that the file ownerships of the files in
the <a href="gnudip/etc/"><code>gnudip/etc/</code></a>
directory do not change.
</ol>
<h3>The "MiniDIP" Alternative</h3>
<blockquote>
This package includes a bare bones version of GnuDIP with no database
or web tool. There is a <u>single configuration file</u>, which includes the list
of host names and their passwords.
<p>
The <a href="gnudip/sbin/minidip.pl"><code>minidip.pl</code></a>
Perl script is a <code>(X)INETD</code> daemon address update server program.
The <a href="gnudip/lib/miniupdt.pm"><code>miniupdt.pm</code></a>
Perl script is a CGI address update server program.
They use <a href="gnudip/etc/minidip.conf"><code>minidip.conf</code></a>
in the GnuDIP configuration directory as the configuration file.
The <code>(X)INETD</code> daemon allow the name of the configuration file
to be overridden using command argument.
<p>
The <code>BIND</code> setup (this option does not support "back ends"
- see below) is the same as for the full GnuDIP software.
<p>
The <code>(X)INETD</code> daemon setup is the same as for the
standard GnuDIP <code>(X)INETD</code> daemon.
<p>
The CGI setup is also the same as for the standard GnuDIP CGI, if it is
acceptable to have "<code>/gnudip/cgi-bin/miniupdt.cgi</code>"
as the URL for the CGI. Otherwise you will need to use "<code>ScriptAlias</code>"
definitions to suit your needs.
<p>
Combining
<a href="gnudip/sbin/minidip.pl"><code>minidip.pl</code></a>
and
<a href="gnudip/lib/miniupdt.pm"><code>miniupdt.pm</code></a>
with the
<a href="gnudip/sbin/multinsupd.pl"><code>multinsupd.pl</code></a>
script discussed below in "Linking Non-GnuDIP Host Names to a GnuDIP Host Name"
can provide a great deal of functionality.
</blockquote>
<h3>Upgrading an Existing MySQL Database</h3>
<ol>
<li>
If you have an existing GnuDIP MySQL database, upgrade this GnuDIP database. Note that
there have been no database changes since release 2.3.0.
<p>
Start the MySQL client using:
<pre>
# mysql -p
</pre>
Follow the contents of
<a href="upgrade.mysql"><code>upgrade.mysql</code></a> to do the <u>first part</u> the
upgrade.
<p>
Or you can read and edit the contents of <code>upgrade.mysql</code>, setting the
MySQL database name, and then use:
<pre>
# mysql -fvp < upgrade.mysql
</pre>
<p>
The <code>upgrade.mysql</code> file is designed to upgrade from either
either release 2.1.2 or release 2.2.x when used in this "automatic" way.
In the latter case however, <u>some error messages</u> may be produced.
<p>
Scan the GnuDIP database and generate the statements to complete the database
upgrade using:
<pre>
# <a href="gnudip/sbin/gdipdbcnv.pl">/usr/local/gnudip/sbin/gdipdbcnv.pl</a> database localhost user password > myupgrade.mysql
</pre>
The arguments are the MySQL database name, the server running MySQL, and the
user name and password to connect to MySQL with, respectively. Read and understand the
file that <code>gdipdbcnv.pl</code> produced:
<ul>
<li>
There will be statements to delete and recreate the contents of the
<code>globalprefs</code> table.
<p><li>
If you used
<code>DOMAIN_TYPE='GLOBAL'</code> in Release 2.1.2
(which is no longer an option - see
<a href="release.html">
<code>release.html</code></a>), then the value of the <code>domain</code>
column will be the empty string for each row of the <code>users</code> table. The statements
generated by <code>gdipdbcnv.pl</code> will replace each such row with several replacement
rows - one for each domain.
</ul>
<p>
When you have examined these MySQL statements, run them using:
<pre>
# mysql -p < myupgrade.mysql
</pre>
</ol>
<h3>New Database Set Up</h3>
<ol>
<li>
If you have no existing GnuDIP database and <b>wish to use MySQL</b>, create a new
GnuDIP MySQL database.
<p>
Start the MySQL client using:
<pre>
# mysql -p
</pre>
Follow the contents of
<a href="gnudip.mysql"><code>gnudip.mysql</code></a> to define the MySQL database and user.
<p>
Or you can read and edit the contents of <code>gnudip.mysql</code> setting the
MySQL database name, and the user name and password to connect to MySQL with,
and then use:
<pre>
# mysql -vp < gnudip.mysql
</pre>
<p><li>
If you have no existing GnuDIP database and <b>wish to use the Linux/UNIX file system</b>,
create a new GnuDIP "flat file" database.
<p>
Delete the two UNIX symbolic links
<code>/usr/local/gnudip/lib/dbprefs.pm</code> and
<code>/usr/local/gnudip/lib/dbusers.pm</code>.
By default these point to
<code>/usr/local/gnudip/lib/dbprefs_mysql.pm</code> and
<code>/usr/local/gnudip/lib/dbusers_mysql.pm</code>, respectively,
which contain the code to handle MySQL.
<p>
Recreate these links using:
<pre>
# ln -s dbprefs_flat.pm /usr/local/gnudip/lib/dbprefs.pm
# ln -s dbusers_flat.pm /usr/local/gnudip/lib/dbusers.pm
</pre>
<p>
By default, <code>dbprefs_flat.pm</code> uses a file named
<code>/usr/local/gnudip/run/database/globalprefs</code>,
and <code>dbusers_flat.pm</code> uses a directory named
<code>/usr/local/gnudip/run/database/users</code>.
<p>
The directories
<code>/usr/local/gnudip/run/database</code> and
<code>/usr/local/gnudip/run/database/users</code>
are already set up.
These directories must be readable and writable only by the owner and owned
by user "<code>nobody</code>" (the "<code>nobody</code>" that Apache will
run the GnuDIP CGI script as - see step one above). The processes that create
and update files in these directories will be running as that user.
<p>
These names can be changed in
<a href="gnudip/etc/gnudip.conf"><code>/usr/local/gnudip/etc/gnudip.conf</code></a>.
<p><li>
If you have no existing GnuDIP database and <b>wish to use PostgreSQL</b>,
create a new GnuDIP PostgreSQL database.
<p>
Delete the three UNIX symbolic links
<code>/usr/local/gnudip/lib/dbcxore.pm</code>,
<code>/usr/local/gnudip/lib/dbprefs.pm</code> and
<code>/usr/local/gnudip/lib/dbusers.pm</code>.
By default these point to
<code>/usr/local/gnudip/lib/dbcore_mysql.pm</code>,
<code>/usr/local/gnudip/lib/dbprefs_mysql.pm</code> and
<code>/usr/local/gnudip/lib/dbusers_mysql.pm</code>, respectively,
which contain the code to handle MySQL.
<p>
Recreate these links using:
<pre>
# ln -s dbcore_pgsql.pm /usr/local/gnudip/lib/dbcore.pm
# ln -s dbprefs_pgsql.pm /usr/local/gnudip/lib/dbprefs.pm
# ln -s dbusers_pgsql.pm /usr/local/gnudip/lib/dbusers.pm
</pre>
<p>
Start the PostgreSQL client using:
<pre>
# psql -U postgres template1
</pre>
Follow the contents of
<a href="gnudip.pgsql"><code>gnudip.pgsql</code></a> to define the PostgreSQL database
and user.
<p>
Or you can read and edit the contents of <code>gnudip.pgsql</code> setting the
PostgreSQL database name, and the user name and password to connect to PostgreSQL with,
and then use:
<pre>
# psql -U postgres template1 -f gnudip.pgsql
</pre>
<p><li>
You may change from one type of GnuDIP database to another by using the scripts
<a href="gnudip/sbin/gdipunld.pl"><code>gnudip/sbin/gdipunld.pl</code></a>
and
<a href="gnudip/sbin/gdipreld.pl"><code>gnudip/sbin/gdipreld.pl</code></a>
to dump and restore your <u>user</u> database:
<pre>
# gdipunld.pl -h
usage: gdipunld.pl [ -h | [ [-o | -a] outfile ] ]
usage: Dumps the users table to a flat file.
usage: -h: Print this usage message.
usage: -o: Specify file to write output to.
usage: -a: Specify file to append output to.
# gdipreld.pl -h
usage: gdipreld.pl [ -h | [ -i infile ] ]
usage: Loads the users table from a flat file.
usage: -h: Print this usage message.
usage: -i: Specify file to read from.
</pre>
<p>
You will have to re-enter system settings and domains by hand.
</ol>
<h3>DNS Server Set Up</h3>
<ol>
<li>
If you are using a legacy version of BIND that cannot be updated using
the dynamic DNS protocol by <code>nsupdate</code>, or
<a href="http://tinydns.org/">tinydns</a>,
you must set up the GnuDIP "back end" scripts. This is
discussed in <a href="BACKEND.html">BACKEND.html</a>.
<p><li>
<p>
Otherwise choose a zone or zones, and get BIND setup for dynamic updates
for these zones.
<p>
The description provided in the next four steps shows one way to achieve
this for one zone and key. For other configuration options please read
the BIND 8 or BIND 9 documentation.
<p><li>
<p>
Generate the key files required by the <code>nsupdate</code> command.
This will at the same time generate a "TSIG key" which you will later
have to use in configuring the <code>named</code> daemon.
<p>
For BIND 8 use "<code>dnskeygen</code>" to generate key files.
This goes something like this sample:
<blockquote>
<pre>
# dnskeygen -H 128 -h -n gnudip-key
** Adding dot to the name to make it fully qualified domain name**
Generating 128 bit HMAC-MD5 Key for gnudip-key.
Generated 128 bit Key for gnudip-key. id=0 alg=157 flags=513
# ls
Kgnudip-key.+157+00000.key Kgnudip-key.+157+00000.private
# cat Kgnudip-key.+157+00000.private
Private-key-format: v1.2
Algorithm: 157 (HMAC)
Key: fegHlhVt3opPIiK8V4cjLw==
# cat Kgnudip-key.+157+00000.key
gnudip-key. IN KEY 513 3 157 fegHlhVt3opPIiK8V4cjLw==
</pre>
</blockquote>
<p>
For BIND 9 use "<code>dnssec-keygen</code>" to generate key files.
This goes something like this sample:
<blockquote>
<pre>
# dnssec-keygen -a hmac-md5 -b 128 -n HOST gnudip-key
Kgnudip-key.+157+36000
# ls
Kgnudip-key.+157+36000.key Kgnudip-key.+157+36000.private
# cat Kgnudip-key.+157+36000.private
Private-key-format: v1.2
Algorithm: 157 (HMAC)
Key: fegHlhVt3opPIiK8V4cjLw==
# cat Kgnudip-key.+157+36000.key
gnudip-key. IN KEY 513 3 157 fegHlhVt3opPIiK8V4cjLw==
</pre>
</blockquote>
<p>
For both Bind 8 and 9, examine the files that were generated to
determine the key that was generated. In the examples above this
key is:
<blockquote><pre>
fegHlhVt3opPIiK8V4cjLw==
</pre></blockquote>
You will <u>use this key later to configure your BIND <code>named</code>
daemon</u>, to control dynamic update access to the GnuDIP dynamic zone.
<p>
Move the key files generated to
<a href="gnudip/etc/"><code>/usr/local/gnudip/etc/</code></a>.
Remove the samples that are already there.
These files should not be writable by anyone.
These files should be readable only by the owner and owned
by user "<code>nobody</code>" (the "<code>nobody</code>" that Apache will
run the GnuDIP CGI script as - see step one above). The <code>nsupdate</code>
command which will read these files will be running as that user.
<p><li>
<p>
Update the definition of the "<code>nsupdate</code>" parameter in the
<a href="gnudip/etc/gnudip.conf"><code>/usr/local/gnudip/etc/gnudip.conf</code></a>
file.
<p>
For BIND 8 follow this sample:
<blockquote>
<pre>
# BIND nsupdate command
nsupdate = /usr/bin/nsupdate -v -k /usr/local/gnudip/etc:gnudip-key.
</pre>
</blockquote>
Note that the trailing period ("<code>.</code>") is required.
<p>
For BIND 9 follow this sample:
<blockquote>
<pre>
# BIND nsupdate command
nsupdate = /usr/bin/nsupdate -v -k /usr/local/gnudip/etc/Kgnudip-key.+157+36000.private
</pre>
Or you could do:
<pre>
# BIND nsupdate command
nsupdate = /usr/bin/nsupdate -v
nsupdate = -k /usr/local/gnudip/etc/Kgnudip-key.+157+36000.private
</pre>
</blockquote>
<p>
Note that parameter names in <code>gnudip.conf</code> may appear more than once.
The values are concatentated with an intervening blank.
<p>
As shown above, the command line options for <code>nsupdate</code>
differ between BIND 8 and BIND 9. However, the <code>nsupdate</code> standard
input commands generated by GnuDIP are compatible with either BIND 8 or
BIND 9.
<p><li>
<p>
Now you must configure the target BIND <code>named</code> daemon to contain
the key generated above, and also of course your GnuDIP dynamic zone.
<p>
Note that <u>the <code>named</code> daemon may run on a different machine than
the machine that will run the GnuDIP CGI (and thereby the <code>nsupdate</code>
command)</u>. The <code>nsupdate</code> command determines
what DNS server to send its update request
to by doing a DNS lookup for the "<code>SOA</code>" record for the domain name whose
information is being updated. The <code>SOA</code> record identifies the master DNS
server for this domain name. <b>The <code>nsupdate</code> command will send the
update request to the master DNS server for the domain</b>.
<p>
Recall that the sample TSIG key generated above was:
<blockquote><pre>
fegHlhVt3opPIiK8V4cjLw==
</pre></blockquote>
<p>
Create a file called <code>gnudip-keyfile</code> in your <code>named</code>
configuration directory.
This file should not be writable by anyone. This file should be readable only
by the owner and owned by user "<code>nobody</code>"
(the "<code>nobody</code>" that the <code>named</code> daemon will run
as - see step one above).
The file <code>gnudip-keyfile</code> should contain something like this sample:
<pre>
key gnudip-key {
algorithm hmac-md5;
// the TSIG key
secret "fegHlhVt3opPIiK8V4cjLw==";
};
</pre>
Note that <u>the contents of this file are entirely different from the files
created during key generation</u> above. This is not a copy of one of those files.
You will have to <u>create this file manually</u>. The sample key
"<code>fegHlhVt3opPIiK8V4cjLw==</code>" must be replaced by the key that you
generated.
<p>
Now you must add a section to define the GnuDIP dynamic zone in your
<code>named.conf</code> file.
<p>
For BIND 8 the new section would look something like:
<blockquote>
<pre>
// include definition of GnuDIP update key
include "gnudip-keyfile";
// define GnuDIP dynamic DNS zone
zone "dyn.you.net" in {
type master;
file "run/zone-dyn.you.net";
allow-query { any; };
allow-update { key gnudip-key; };
};
</pre>
</blockquote>
<p>
For BIND 9 the new section would look something like:
<blockquote>
<pre>
// include definition of GnuDIP update key
include "gnudip-keyfile";
// define GnuDIP dynamic DNS zone
zone "dyn.you.net" in {
type master;
file "run/zone-dyn.you.net";
allow-query { any; };
update-policy { grant gnudip-key subdomain dyn.you.net; };
};
</pre>
</blockquote>
In the examples above, note that the string <b><code>gnudip-key</code>
refers to the name</b> of the key,
whereas the string <b><code>gnudip-keyfile</code> refers to the
file</b> containing the syntax to define that key name.
<p>
Notice above that the zone file is in a subdirectory called <code>run</code>.
This directory should be owned by user "<code>nobody</code>"
(or whatever user ID <code>named</code> runs as) so that
<code>named</code> may create files in it.
<p>
You can set up <code>$TTL</code> and <code>SOA</code> values for the dynamic
zones by setting up an initial
zone file for BIND. BIND will read this the first time, and use the values from
the file. Continuing the previous example, for the file
<code>run/zone-dyn.you.net</code> try something like this sample:
<pre>
$TTL 86400 ; default TTL (1 day)
@ IN SOA ns.you.net. root.you.net. (
0 ; serial
3600 ; refresh (1 hour)
1800 ; retry (30 minutes)
604800 ; expire (1 week)
0 ; TTL for NACK-s (0 seconds)
)
IN NS ns.you.net.
IN A IP_address
</pre>
This zone file should again be owned by user <code>nobody</code>, so that
<code>named</code> may modify it.
<p>
This sample supposes that you want clients to use
<code>dyn.you.net</code> as the name of the GnuDIP server, in addition to the
name of the GnuDIP subdomain.
The <code>A</code> record is required for this. You will not be allowed to
use a <code>CNAME</code> record for this, because the name of the record would
be the same as the name of the <code>SOA</code> record. You can maintain this
<code>A</code> record using <code>nsupdate</code> if the address changes.
<p>
The <code>SOA</code> and <code>NS</code> records may point into an entirely
different domain.
<p>
Note that <b>the base domain <code>you.net</code> can be made the GnuDIP dynamic
domain</b> if you wish. If the <code>NS</code> records point to names within
<code>you.net</code>, you will need glue records in the usual way.
<p>
Note that <u>the default TTL value in this start up file will not apply</u>
to the records added using <code>nsupdate</code>. The
<code>nsupdate</code> command requires a TTL value
with each record added. GnuDIP will use a value of zero for this TTL, unless a
value is specified in
<a href="gnudip/etc/gnudip.conf"><code>/usr/local/gnudip/etc/gnudip.conf</code></a>
(see below).
<p>
You may want to <u>retain a copy of this inital zone file</u>, for use with the
<a href="gnudip/sbin/gdipzone.pl"><code>gnudip/sbin/gdipzone.pl</code></a>
script discussed below.
<p>
Note that if you are the operator of a serious
production shop rather than a home hobbiest, you
will need to set up BIND to do "<b>dynamic update forwarding</b>"
and "<b>incremental zone transfers</b>" to slave DNS servers from the master DNS
server. These details are not explained here.
<p><li>
If the call to the <code>nsupdate</code> command by the GnuDIP CGI script
fails for any reason, the precise command that was invoked as well as the input
that was passed to it and the output from it will be wriiten to the system log.
<p>
<b>The simplest way to debug your BIND configuration is probably by using
<code>nsupdate</code>, the <code>dig</code> command and the <code>ping</code>
command at the UNIX command prompt</b>. For example, <u><b>on the machine where
the GnuDIP CGI script and <code>nsupdate</code> will run</b></u>, try:
<pre>
# dig tester.dyn.you.net. soa
; <<>> DiG 9.1.3 <<>> tester.dyn.you.net. soa
;; global options: printcmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NXDOMAIN, id: 34673
;; flags: qr aa rd ra; QUERY: 1, ANSWER: 0, AUTHORITY: 1, ADDITIONAL: 0
;; QUESTION SECTION:
;tester.dyn.you.net. IN SOA
;; AUTHORITY SECTION:
dyn.you.net. 0 IN SOA you.net. root.you.net. 484 3600 1800 604800 0
;; Query time: 8 msec
;; SERVER: 192.168.0.2#53(192.168.0.2)
;; WHEN: Tue Oct 23 14:47:24 2001
;; MSG SIZE rcvd: 88
# su - nobody
# /usr/bin/nsupdate -v -k /usr/local/gnudip/etc/Kgnudip-key.+157+36000.private
> update add tester.dyn.you.net. 0 A 127.0.0.1
>
> #
# exit
# ping tester.dyn.you.net.
PING tester.dyn.you.net (127.0.0.1): 56 data bytes
64 bytes from 127.0.0.1: icmp_seq=0 ttl=255 time=0.2 ms
64 bytes from 127.0.0.1: icmp_seq=1 ttl=255 time=0.1 ms
--- tester.dyn.you.net ping statistics ---
2 packets transmitted, 2 packets received, 0% packet loss
round-trip min/avg/max = 0.1/0.1/0.2 ms
#
</pre>
In the "<code>su</code>" command, the "<code>nobody</code>" that the
GnuDIP CGI and (X)INETD daemon will run as should be used (see above).
You may want to try the <code>nsupdate</code> as root first.
<p>
If your <code>nobody</code> user is not set up to allow the use of
"<code>su - ...</code>", you may instead try:
<pre>
# sudo -u nobody /usr/bin/nsupdate -v \
-k /usr/local/gnudip/etc/Kgnudip-key.+157+36000.private
</pre>
<p>
The output from the <code>dig</code> command shows that <code>nsupdate</code>
will send its update request to <code>you.net</code>.
<p>
Note that <code>nsupdate</code> accumulates update input lines until it sees an
empty line.
Only then does it do the updates.
To stop <code>nsupdate</code> use "<code>Ctrl-D</code>" to generate
an end of file.
<p>
<b>Remember that BIND comes with documentation</b>.
<p>
You may also want to take advantage of
<a href="http://isc.org/services/public/lists/bind-lists.html">
the BIND mailing lists</a> or
<a href="http://www.isc.org/ml-archives/">their archives</a>.
</ol>
<h3>Editing the Configuration File</h3>
<blockquote>
Edit
<a href="gnudip/etc/gnudip.conf"><code>/usr/local/gnudip/etc/gnudip.conf</code></a>.
There are comments in the sample that is already there.
<p>
In particular, check whether you need a "<code>-p</code>" option for the "<code>logger</code>"
commands in order to ensure that log messages go somewhere acceptable. One user has suggested
"<code>/usr/bin/logger -p local3.err</code>" for Solaris 8 using the default configuration
for syslogd.
<p>Also, check the path to your sendmail program (or sendmail clone). For example
Solaris 8 by default puts sendmail in <code>/usr/lib/sendmail</code>.
<p>
A sendmail alias (or clone equivalent) to direct mail for the "return path" user (the
GnuDIP "nobody" user unless the sendmail "<code>-f</code>" option is used) to
<code>/dev/null</code> is also a good idea, so returned mail for a bad E-mail address
disappears.
<p>
If you already have a <code>gnudip.conf</code> file for an existing installation,
<b>review the sample <code>gnudip.conf</code> file for new parameters</b>.
<p>
Make sure that everything in <code>/usr/local/gnudip/etc/</code> is readable only by
the owner and owned by user "<code>nobody</code>" (the "<code>nobody</code>" that
Apache will run the GnuDIP CGI script as - see step one above), and not writable by
any user.
<p>
You may wish to create a directory <b><code>/etc/gnudip</code></b>,
move (i.e. rename) the directory <code>/usr/local/gnudip/etc</code> to
<code>/usr/local/gnudip/etc_orig</code> (for later reference), and set
<code>/usr/local/gnudip/etc</code> as a <b>symbolic link</b> to
<code>/etc/gnudip</code>. Then create your configuration files
in <code>/etc/gnudip</code>. If you later upgrade, you can then just rename
<code>/usr/local/gnudip/etc</code> to <code>/usr/local/gnudip/etc_orig</code>, and
recreate the link. This practice allows the switch to a new release in production
environments to consist of two "<code>mv</code>" commands and one "<code>ln</code>"
command, which would take only a few seconds.
</blockquote>
<h3>Apache Web Server Set Up</h3>
<blockquote>
The instructions here are for Apache. But it should be possible to use
the web interface with other servers.
<p>
<b>The user maintenance commands or remote maintenance daemon</b> described
below <b>may be used in place of</b> or in addition to <b>the GnuDIP Web
interface</b>. However, the HTTP client update interface is incorporated into
the web interface. The Apache configuration can be made simpler if only
the HTTP client interface is desired. Only the CGI definition
statements are required.
</blockquote>
<ol>
<li>
To run as a standard CGI, add these lines to your Apache configuration file:
<pre>
Alias /gnudip/html/ /usr/local/gnudip/html/
<Location /gnudip/html/>
Options Indexes
ReadmeName .README
HeaderName .HEADER
RemoveHandler .pl
RemoveType .pl
AddType text/plain .pl
</Location>
ScriptAlias /gnudip/cgi-bin/ /usr/local/gnudip/cgi-bin/
</pre>
The URL for the Web Tool will be:
<pre>
http://yourserver/gnudip/cgi-bin/gnudip.cgi
</pre>
The self sign up page will be directly available at:
<pre>
http://yourserver/gnudip/cgi-bin/gnudip.cgi?action=signup
</pre>
Note that this URL is <b>different than the URL</b> for GnuDIP following the installation
instructions <b>for Release 2.1.2</b>. Following those instructions the URL would be
<pre>
http://yourserver/cgi-bin/gnudip2.cgi
</pre>
To provide compatibility copy the perl script
<a href="gnudip/cgi-bin/gnudip2.cgi"><code>/usr/local/gnudip/cgi-bin/gnudip2.cgi</code></a>
to the
<code>cgi-bin</code> directory for your Apache server (or make a
symbolic link). This short script will redirect
to the new URL. Modify
<a href="gnudip/cgi-bin/gnudip2.cgi"><code>gnudip2.cgi</code></a>
to match any change you made to the two Apache configuration lines above.
<p>
Other Apache configurations are possible.
<p><li>
The web tool will run under
<a href="http://perl.apache.org/#modules">mod_perl Apache::Registry</a>.
<p>
To use mod_perl, instead of the lines described above, add these lines
to your Apache configuration file:
<pre>
Alias /gnudip/html/ /usr/local/gnudip/html/
<Location /gnudip/html/>
Options Indexes
ReadmeName .README
HeaderName .HEADER
RemoveHandler .pl
RemoveType .pl
AddType text/plain .pl
</Location>
Alias /gnudip/cgi-bin/ /usr/local/gnudip/cgi-bin/
<Location /gnudip/cgi-bin/>
SetHandler perl-script
PerlHandler Apache::Registry
Options +ExecCGI
PerlSendHeader On
</Location>
</pre>
<p><li>
The web tool will run under
<a href="http://www.fastcgi.com/">FastCGI</a>
using <code>mod_fastcgi</code> and <code>FCGI.pm</code>.
<p>
To use FastCGI, instead of the lines described above, add these lines
to your Apache configuration file:
<pre>
Alias /gnudip/html/ /usr/local/gnudip/html/
<Location /gnudip/html/>
Options Indexes
ReadmeName .README
HeaderName .HEADER
RemoveHandler .pl
RemoveType .pl
AddType text/plain .pl
</Location>
Alias /gnudip/cgi-bin/ /usr/local/gnudip/fcgi-bin/
<Location /gnudip/cgi-bin/>
SetHandler fastcgi-script
Options +ExecCGI
</Location>
</pre>
<p>
When running under mod_perl or FastCGI, adding the line
"<code>persistance = YES</code>"
to <a href="gnudip/etc/gnudip.conf">gnudip.conf</a>
will cause the web tool to use persistant database connections, and to
retain the contents of <a href="gnudip/etc/gnudip.conf">gnudip.conf</a>,
the preferences from the <code>globalprefs</code> table and the
list of domains from the <code>domains</code> table,
and any other configuration files in memory, rather
than re-accessing these files or tables. Make sure that persistance is not on when
configuring your system while running under mod_perl or FastCGI.
</ol>
<h3>Customizing the Web Interface</h3>
<ol>
<li>
The parameters <code>header_file</code> and <code>trailer_file</code> in
<a href="gnudip/etc/gnudip.conf">gnudip.conf</a>
specify a file of HTML to be included at the top and bottom of each
HTML page, respectively. An example of what can be done using these
files is provided.
<p><li>
The parameters <code>URL_sendURL</code>, <code>URL_self_signup</code>
and <code>URL_delthisuser</code> in
<a href="gnudip/etc/gnudip.conf">gnudip.conf</a>
specify URL-s which should take the place of the "Forgotten Password",
"Self Registration" and "Delete Current User" form buttons.
See the comments in <a href="gnudip/etc/gnudip.conf">gnudip.conf</a>
for more information.
<p><li>
The parameters <code>no_robots_prfx</code> and <code>no_robots_imgcmd</code> in
<a href="gnudip/etc/gnudip.conf">gnudip.conf</a>
must be correctly specified in order to user the GnuDIP feature to
suppress automated abuse of "Self Registration", "Forgotten Password"
and "Change E-mail Address".
See the comments in <a href="gnudip/etc/gnudip.conf">gnudip.conf</a>.
If you have <a href="http://www.ImageMagick.org/">ImageMagick</a>
installed then the
<a href="gnudip/sbin/textimage.sh">
sample/default text image generation script</a>
should work for you.
<p>
Once you have ensured the defaults will work, or provided and alternative
image generation script, you can turn this option on in "System Settings"
in the web interface.
<p>
<b>Without this, the GnuDIP Web Interface is vulnerable to being used as the
"man in the middle" for an E-mail bombardment attack.</b>
<p>
A program can "GET" and "POST" the pages that send an E-mail
repeatedly to send an E-mail bombardment to a third party. The
bombardment will seem to come from the GnuDIP site.
</ol>
<h3>(X)INETD Daemon Set Up</h3>
<ol>
<li>
Add an entry to <code>/etc/services</code> like this sample:
<pre>
gnudip 3495/tcp
</pre>
<p><li>
If you use the
<a href="http://www.synack.net/xinetd/"><code>xinetd</code></a>
replacement for <code>inetd</code>, add an entry to
<code>/etc/xinetd.conf</code> like this sample:
<pre>
service gnudip
{
flags = REUSE
socket_type = stream
protocol = tcp
wait = no
user = nobody
server = /usr/local/gnudip/sbin/gdipinet.pl
bind = 0.0.0.0
only_from = 192.168.0.0/24
only_from += 127.0.0.1
only_from += 24.64.0.0/13
only_from += 64.5.210.224/31
only_from += 64.5.221.128/27
}
</pre>
You should of course choose values for "<code>only_from</code>" that are
appropriate to your circumstances. You may want to just leave these lines
out.
<p>
Note that the "<code>nobody</code>" user ID used here should be <b>the same one
Apache will run the GnuDIP CGI script as</b> (see step one above).
<p>
If you have XINETD with TCP wrappers compiled in, make an entry in
<code>/etc/hosts.allow</code> like this sample:
<pre>
gdipinet.pl: 24.64.0.0/255.248.0.0 \
64.5.210.224/255.255.255.232 \
64.5.221.128/255.255.255.160
</pre>
For early releases of XINETD with TCP wrappers, you must use the
service name instead of the process/program name, as follows:
<pre>
gnudip: 24.64.0.0/255.248.0.0 \
64.5.210.224/255.255.255.232 \
64.5.221.128/255.255.255.160
</pre>
If you left out "<code>only_from</code>" above, then you would instead
use a line like:
<pre>
gdipinet.pl: ALL
</pre>
or for early releases of XINETD
<pre>
gnudip: ALL
</pre>