]> scm.dxcluster.org Git - spider.git/blob - txt/installation.txt
df4e0cdf3a988777ae6f17445d3c0e770d4dcd81
[spider.git] / txt / installation.txt
1   The DXSpider Installation Manual v1.49
2   Iain Philipps, G0RDI (g0rdi@77hz.com) and Ian Maude, G0VGS,
3   (ianmaude@btinternet.com)
4   November 2001 revision 1.0
5
6   A reference for SysOps of the DXSpider DXCluster program.
7   ______________________________________________________________________
8
9   Table of Contents
10
11
12   1. Linux Installation
13
14      1.1 Introduction
15      1.2 Preparation
16      1.3 Installing the software
17      1.4 Setting callsigns etc
18      1.5 The client program
19      1.6 Starting up for the first time
20
21   2. Linux quick installation guide
22
23   3. Configuration
24
25      3.1 Allowing ax25 connects from users
26      3.2 Allowing telnet connects from users
27      3.3 Setting up telnet connects (from 1.47 onwards)
28      3.4 Setting up for AGW Engine (1.47 onwards)
29      3.5 Setting up node connects
30      3.6 Connection scripts
31      3.7 Starting the connection
32      3.8 Telnet echo
33      3.9 Autostarting the cluster
34
35   4. Microsoft Windows Installation
36
37      4.1 Introduction
38      4.2 The requirements
39      4.3 The system
40      4.4 Perl
41      4.5 Additional packages
42      4.6 Getting Spider
43
44   5. Installing the software
45
46      5.1 The AGW packet engine
47      5.2 Setting up the initial user files
48      5.3 Incoming telnets
49      5.4 Connecting to other clusters
50
51   6. General Information
52
53      6.1 The crontab file
54
55
56   ______________________________________________________________________
57
58   1.  Linux Installation
59
60   1.1.  Introduction
61
62   This section describes the installation of DX Spider v1.47 on a RedHat
63   Linux Distribution.  Wherever possible I will try to include
64   differences for other distributions.  I do not intend to try and cover
65   the installation of Linux or the setup of the AX25 utilities.  If you
66   need help on this then read Iains original installation guide that
67   comes with the Spider distribution.
68
69
70   I am assuming a general knowledge of Linux and its commands.  You
71   should know how to use tar and how to edit files using your favourite
72   editor.
73
74
75   The crucial ingredient for all of this is Perl.  Earlier versions of
76   Spider required perl 5.004, however it is now STRONGLY recommended
77   that you use at least version 5.005_03 as this is the version being
78   used in the development of Spider.
79
80
81   In addition to the standard Red Hat distribution you will require the
82   following modules from http://www.cpan.org/CPAN.html ...
83
84
85
86   o  Data-Dumper-2.10.tar.gz
87
88   o  TimeDate-1.10.tar.gz
89
90   o  IO-1.20.tar.gz (for perl 5.00403 and lower)
91
92   o  Net-Telnet-3.02.tar.gz
93
94   o  Curses-1.06.tar.gz
95
96   o  Time-HiRes-01.20.tar.gz
97
98
99   Copy the CPAN modules listed above to a convenient place on your
100   computer. One good place would be /usr/local/packages, and the
101   instructions which follow will assume that that's where you have put
102   them.
103
104
105   Log in as 'root', and make sure you're at '/root' before you continue.
106   Here are exactly the commands you must issue next: -
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   # tar xvfz /usr/local/packages/Data-Dumper-2.10.tar.gz
134   # cd Data-Dumper-2.10
135   # perl Makefile.PL
136   # make test
137   # make install
138   # cd ..
139   #
140   # tar xvfz /usr/local/packages/TimeDate-1.10.tar.gz
141   # cd TimeDate-1.10
142   # perl Makefile.PL
143   # make test
144   # make install
145   # cd ..
146   #
147   # tar xvfz /usr/local/packages/IO-1.20.tar.gz
148   # cd IO-1.20
149   # perl Makefile.PL
150   # make test
151   # make install UNINST=1
152   # cd ..
153   #
154   # tar xvfz /usr/local/packages/Net-Telnet-3.02.tar.gz
155   # cd Net-Telnet-3.02
156   # perl Makefile.PL
157   # make test
158   # make install
159   # cd ..
160   #
161   # tar xvfz /usr/local/packages/Curses-1.06.tar.gz
162   # cd Curses-1.06
163   # perl Makefile.PL
164   # make test
165   # make install
166   # cd ..
167   #
168   # tar xvfz /usr/local/packages/Time-HiRes-01.20.tar.gz
169   # cd Time-HiRes-01.20
170   # perl Makefile.PL
171   # make test
172   # make install
173   # cd ..
174
175
176
177
178   Do not fall into the trap of thinking they're all the same, just
179   because they nearly are! Pay particular attention to the instructions
180   of IO, above.
181
182
183
184   1.2.  Preparation
185
186   I will assume that you have already downloaded the latest tarball of
187   the DXSpider software and are ready to install it. I am assuming
188   version 1.47 for this section but of course you would use the latest
189   version.
190
191
192   Login as root and create a user to run the cluster under.  UNDER NO
193   CIRCUMSTANCES USE ROOT AS THIS USER!.  I am going to use the name
194   sysop.  You can call it anything you wish.  Depending on your security
195   requirements you may wish to use an existing user, however this is
196   your own choice.
197
198
199        # adduser -m sysop
200
201
202
203
204
205   For SUSE distributions, the command would be ..
206
207
208
209        # useradd -m sysop
210
211
212
213
214
215   Now set a password for the user ...
216
217
218
219        # passwd sysop
220        # New UNIX password:
221        # Retype new UNIX password:
222        passwd: all authentication tokens updated successfully
223
224
225
226
227
228   1.3.  Installing the software
229
230   Now to unpack the DX Spider distribution, set symbolic links and group
231   permissions.  Copy the tarball to /home/sysop and do the following.
232
233
234
235        # cd ~sysop
236        # tar xvfz spider-1.47.tar.gz
237        # ln -s ~sysop/spider /spider
238        # groupadd -g 251 spider       (or another number)
239
240
241
242
243   If you do not have the command groupadd available to you simply add a
244   line in /etc/group by hand.
245
246
247
248        # vi /etc/group                (or your favorite editor)
249
250
251
252
253   You also need to add some others to the group, including your own
254   callsign (this will be used as an alias) and root.  The finished line
255   in /etc/group should look something like this
256
257   spider:x:251:sysop,g0vgs,root
258
259
260   The next step is to set the permissions on the Spider directory tree
261   and files ....
262
263
264
265   # chown -R sysop.spider spider
266   # find . -type d -exec chmod 2775 {} \;
267   # find . -type f -exec chmod 775 {} \;
268
269
270
271
272
273   This last step allows various users of the group spider to have write
274   access to all the directories.  This is not really needed just yet but
275   will be useful when web interfaces start to appear.
276
277
278   Finally, you need to fix the permissions on the ax25_call and
279   netrom_call programs.  Check where they are with the locate command
280   and alter the permissions with the chmod command like this ..
281
282
283
284        # chown root ax25_call netrom_call
285        # chmod 4775 ax25_call netrom_call
286
287
288
289
290
291   1.4.  Setting callsigns etc
292
293   Now login to your machine as the user you created earlier.  In my case
294   that user is called sysop.  Once logged in, issue the following
295   commands ....
296
297
298
299        $ cd /spider
300        $ mkdir local
301        $ mkdir local_cmd
302        $ cp perl/DXVars.pm.issue local/DXVars.pm
303        $ cd local
304        $ vi DXVars.pm (or your favourite editor)
305
306
307
308
309
310   Using the distributed DXVars.pm as a a template, set your cluster
311   callsign, sysop callsign and other user info to suit your own
312   environment. Note that this a perl file which will be parsed and
313   executed as part of the cluster. If you get it wrong then perl will
314   complain when you start the cluster process.  It is important only to
315   alter the text of any section.  Some of the lines look a little odd.
316   Take this line for example ....
317
318   $myemail = "ianmaude\@btinternet.com";
319
320
321   There appears to be an extra slash in there.  However this has to be
322   there for the file to work so leave it in.
323
324
325   PLEASE USE CAPITAL LETTERS FOR CALLSIGNS
326
327
328   DON'T alter any file in /spider/perl, they are overwritten with every
329   release. Any files or commands you place in /spider/local or
330   /spider/local_cmd will automagically be used in preference to the ones
331   in /spider/perl EVEN while the cluster is running!
332
333
334   Save the new file and change directory to ../perl ....
335
336
337
338        $ cd ../perl
339
340
341
342
343
344   Now type the following command which creates the basic user file with
345   you as the sysop.
346
347
348
349        $ ./create_sysop.pl
350
351
352
353
354
355   1.5.  The client program
356
357   In earlier versions of Spider, all the processes were Perl scripts.
358   This was fine but with a lot of users your computer memory would soon
359   be used up.  To combat this a new client was written in "C".  This
360   client only works for incoming connects at the moment.  Before you can
361   use it though it has to be "made".  CD to /spider/src and type make.
362   You should see the output on your screen and hopefully now have a
363   small C program called client.  Leave it in this directory.
364
365
366
367   1.6.  Starting up for the first time
368
369   We can now bring spider up for the first time and see if all is well
370   or not!  It should look something like this ...
371
372
373
374        $ ./cluster.pl
375        DXSpider DX Cluster Version 1.47
376        Copyright (c) 1998 Dirk Koopman G1TLH
377        loading prefixes ...
378        loading band data ...
379        loading user file system ...
380        starting listener ...
381        reading existing message headers
382        reading cron jobs
383        orft we jolly well go ...
384
385
386
387
388
389   If all is well then login on another term or console as sysop and cd
390   to /spider/src.  Now issue the following command ...
391
392
393
394        $ ./client
395
396
397   This should log you into the cluster as the sysop under the alias
398   callsign we set earlier.  In this case the callsign is G0VGS.  The
399   cluster callsign is set in the DXVars.pm file in /spider/local.  In
400   this case we will assume that this was set as GB7MBC.  You should
401   therefore see this when you login ....
402
403
404
405        G0VGS de GB7MBC 19-Nov-1999 2150Z >
406
407
408
409
410   If you do, congratulations!  If not, look over the instructions again,
411   you have probably missed something out.  You can shut spider down
412   again with the command ....
413
414
415
416        shutdown
417
418
419
420
421
422   and both the cluster and the client should return to Linux prompts.
423
424
425
426   2.  Linux quick installation guide
427
428   This section is designed for experienced Spider sysops who want to
429   install Spider from scratch.  It is simply a check list of things that
430   need to be done without any explanations.  The name in brackets at the
431   end of each line is the user that should be doing that process.
432
433
434   o  Login as root
435
436   o  Get the additional CPAN modules and install them (root)
437
438   o  Create the "sysop" user and set a password (root)
439
440   o  Put the Spider tarball in  sysop and untar it (root)
441
442   o  ln -s  sysop/spider /spider (root)
443
444   o  groupadd -g 251 spider (root)
445
446   o  Add any more users you need to the group entry in /etc/group (root)
447
448   o  Set the permissions on the spider tree (root)
449
450   o  Fix permissions on ax25_call and netrom_call (root)
451
452   o  Login as the sysop user
453
454   o  cd to /spider (sysop)
455
456   o  mkdir local (sysop)
457
458   o  mkdir local_cmd (sysop)
459
460   o  cp perl/DXVars.pm.issue local/DXVars.pm (sysop)
461
462
463   o  cd to /spider/local and edit DXVars to set your details (sysop)
464
465   o  cd ../perl (sysop)
466
467   o  ./create_sysop.pl (sysop)
468
469   o  ./cluster.pl (sysop)
470
471   Spider should now be running and you should be able to login using the
472   client program.
473
474
475   o  Login as root
476
477   o  Enter the correct line in ax25d.conf (root)
478
479   o  Enter the correct line in /etc/services (root)
480
481   o  Enter the correct line in /etc/inetd.conf (root)
482
483   o  killall -HUP inetd (root)
484
485   Spider should now be able to accept logins via telnet, netrom and
486   ax25.
487
488
489   o  Login as sysop
490
491   o  Start the cluster (sysop)
492
493   o  set/node and type for links (sysop)
494
495   o  Write any connect scripts (sysop)
496
497   o  Edit /spider/crontab as required (sysop)
498
499   o  Edit any other files as necessary (sysop)
500
501   o  Set filters, hops and forwarding files (sysop)
502
503   o  Login as root
504
505   o  Enter the correct line in /etc/inittab (root)
506
507
508   3.  Configuration
509
510   3.1.  Allowing ax25 connects from users
511
512   As stated previously, the aim of this document is not to tell you how
513   to configure Linux or the ax25 utilities.  However, you do need to add
514   a line in your ax25d.conf to allow connections to DXSpider for your
515   users.  For each interface that you wish to allow connections on, use
516   the following format ...
517
518
519
520        default  * * * * * *  - sysop /spider/src/client client %u ax25
521
522
523
524
525   or, if you wish your users to be able to use SSID's on their callsigns
526   ..
527
528
529        default  * * * * * *  - sysop /spider/src/client client %s ax25
530
531
532
533
534   For most purposes this is not desirable. The only time you probably
535   will need this is when you need to allow other cluster nodes that are
536   using SSID's in. In this case it would probably be better to use the
537   first example and then add a specific line for that node like this:
538
539
540
541        GB7DJK-2  * * * * * *  - sysop /spider/src/client client gb7djk-2 ax25
542        default  * * * * * *  - sysop /spider/src/client client %u ax25
543
544
545
546
547
548   3.2.  Allowing telnet connects from users
549
550
551   From version 1.47 there is a new (more efficient) way of doing this
552   (see next section) but, if you prefer, the method of doing it
553   described here will continue to work just fine.
554
555
556   Allowing telnet connections is quite simple.  Firstly you need to add
557   a line in /etc/services to allow connections to a port number, like
558   this ....
559
560
561
562        spdlogin   8000/tcp     # spider anonymous login port
563
564
565
566
567   Then add a line in /etc/inetd.conf like this ....
568
569
570
571        spdlogin stream tcp nowait root /usr/sbin/tcpd /spider/src/client login telnet
572
573
574
575
576
577   Once this is done, you need to restart inetd like this ....
578
579
580
581        killall -HUP inetd
582
583
584
585
586
587
588   Now login as sysop and cd spider/src. You can test that spider is
589   accepting telnet logins by issuing the following command ....
590
591
592
593        ./client login telnet
594
595   You should get a login prompt and on issuing a callsign, you will be
596   given access to the cluster.  Note, you will not get a password login.
597   There seems no good reason for a password prompt to be given so it is
598   not asked for.
599
600
601   Assuming all is well, then try a telnet from your linux console ....
602
603
604
605        telnet localhost 8000
606
607
608
609
610
611   You should now get the login prompt and be able to login as before.
612
613
614   3.3.  Setting up telnet connects (from 1.47 onwards)
615
616   From version 1.47 you can choose to allow the perl cluster.pl program
617   to allow connections directly (i.e. not via the /spider/src/client
618   interface program). If you are using Windows then this is the only
619   method available of allowing incoming telnet connections.
620
621
622   To do this you need first to remove any line that you may previously
623   have set up in /etc/inetd.conf. Remember to:-
624
625
626
627        killall -HUP inetd
628
629
630
631
632
633   to make the change happen...
634
635
636   Having done that, you need to copy the file /spider/perl/Listeners.pm
637   to /spider/local and then edit it. You will need to uncomment the line
638   containing "0.0.0.0" and select the correct port to listen on. So that
639   it looks like this:-
640
641
642
643        @listen = (
644            ["0.0.0.0", 8000],
645        );
646
647
648
649
650
651   As standard, the listener will listen on all interfaces
652   simultaneously.  If you require more control than this, you can
653   specify each interface individually:-
654
655
656
657
658
659
660
661   @listen = (
662       ["gb7baa.dxcluster.net", 8000],
663       ["44.131.16.2", 6300],
664   );
665
666
667
668
669
670   This will only be successful if the IP addresses on each interface are
671   static.  If you are using some kind of dynamic IP addressing then the
672   'default' method is the only one that will work.
673
674
675   Restart the cluster.pl program to enable the listener.
676
677
678   One important difference with the internal listener is that no echoing
679   is done by the cluster program. Users will need to set 'local-echo' on
680   in their telnet clients if it isn't set automatically (as per the
681   standards).  Needless to say this will probably only apply to Windows
682   users.
683
684
685   3.4.  Setting up for AGW Engine (1.47 onwards)
686
687   AGW Engine is a Windows based ax25 stack. You can connect to an AGW
688   engine from Linux as well as Windows based machines.
689
690
691   In order to enable access to an AGW Engine you need to copy
692   /spider/perl/AGWConnect.pm to /spider/local and edit it.  Specifically
693   you must:-
694
695
696   o  set $enable to 1.
697
698   o  set $login and $passwd to the values set up in your AGW
699      installation.  If you haven't set any there, then you should not
700      touch these values.
701
702   o  You can connect to a remote AGW engine (ie on some other machine)
703      by changing $addr and $port appropriately.
704
705   o  Restart the cluster.pl program
706
707
708
709
710   3.5.  Setting up node connects
711
712   In order to allow cluster node connections, spider needs to know that
713   the connecting callsign is a cluster node.  This is the case whether
714   the connect is incoming or outgoing.  In spider this is a simple task
715   and can be done in runtime.
716
717
718   Later versions of Spider can distinguish different software and treat
719   them differently.  For example, the WCY beacon cannot be handles by
720   AK1A type nodes as AK1A does not know what to do with PC73.  There are
721   4 different types of node at present and although they may not have
722   any major differences at the moment, it allows for compatibility.  The
723   4 types are ...
724
725
726
727   set/node        (AK1A type)
728   set/spider
729   set/dxnet
730   set/clx
731
732
733
734
735
736   For now, we will assume that the cluster we are going to connect to is
737   an AK1A type node.
738
739
740   Start up the cluster as you did before and login as the sysop with
741   client.  The cluster node I am wanting to make a connection to is
742   GB7BAA but you would obviously use whatever callsign you required.  At
743   the prompt type ...
744
745
746
747        set/node gb7baa
748
749
750
751
752
753   The case does not matter as long as you have a version of DXSpider
754   later than 1.33.  Earlier versions required the callsign to be in
755   upper case.
756
757
758   That is now set, it is as simple as that.  To prove it, login on yet
759   another console as sysop, cd to spider/src and issue the command ...
760
761
762
763        ./client gb7baa (using the callsign you set as a node)
764
765
766
767
768
769   You should get an initialisation string from DXSpider like this ...
770
771
772
773        ./client gb7baa
774        PC38^GB7MBC^~
775
776
777
778
779   If the callsign you just set up as a cluster node is for an incoming
780   connect, this is all that needs to be done.  If the connection is to
781   be outgoing then a connection script needs to be written.
782
783
784   Sometimes you make a mistake... Honest, it does happen.  If you want
785   to make a node back to being a normal user, regardless of what type it
786   is, do:
787
788
789
790        unset/node gb7baa
791
792
793   3.6.  Connection scripts
794
795   Because DXSpider operates under Linux, connections can be made using
796   just about any protocol;  AX25, NETRom, tcp/ip, ROSE etc are all
797   possible examples.  Connect scripts live in the /spider/connect
798   directory and are simple ascii files.  Writing a script for
799   connections is therefore relatively simple.
800
801
802   The connect scripts consist of lines which start with the following
803   keywords or symbols:-
804
805
806
807      #  All lines starting with a # are ignored, as are completely blank
808         lines.
809
810
811      timeout
812         timeout followed by a number is the number of seconds to wait
813         for a command to complete. If there is no timeout specified in
814         the script then the default is 60 seconds.
815
816
817      abort
818         abort is a regular expression containing one or more strings to
819         look for to abort a connection. This is a perl regular
820         expression and is executed ignoring case.
821
822
823      connect
824         connect followed by ax25, agw (for Windows users) or telnet and
825         some type dependent information. In the case of a telnet
826         connection, there can be up to two parameters.  The first is the
827         ip address or hostname of the computer you wish to connect to
828         and the second is the port number you want to use (this can be
829         left out if it is a normal telnet session).  In the case of an
830         ax25 session then this would normally be a call to ax25_call or
831         netrom_call as in the example above. It is your responsibility
832         to get your node and other ax25 parameters to work before going
833         down this route!
834
835
836      '  line in a chat type script. The words/phrases normally come in
837         pairs, either can be empty. Each line reads input from the
838         connection until it sees the string (or perl regular expression)
839         contained in the left hand string. If the left hand string is
840         empty then it doesn't read or wait for anything. The comparison
841         is done ignoring case.  When the left hand string has found what
842         it is looking for (if it is) then the right hand string is sent
843         to the connection.  This process is repeated for every line of
844         chat script.
845
846
847      client
848         client starts the connection, put the arguments you would want
849         here if you were starting the client program manually. You only
850         need this if the script has a different name to the callsign you
851         are trying to connect to (i.e. you have a script called other
852         which actually connects to GB7DJK-1 [instead of a script called
853         gb7djk-1]).
854
855
856   There are many possible ways to configure the script but here are
857   three examples, one for a NETRom/AX25 connect, one for AGW engines and
858   one for tcp/ip.
859        timeout 60
860        abort (Busy|Sorry|Fail)
861        # don't forget to chmod 4775 netrom_call!
862        connect ax25 /usr/sbin/netrom_call bbs gb7djk g1tlh
863        # you can leave this out if you call the script 'gb7dxm'
864        client gb7dxm ax25
865
866
867
868
869
870
871
872
873        timeout 60
874        abort (Busy|Sorry|Fail)
875        # this does exactly the same as the previous example
876        # the '1' is the AGW port number to connect thru for g1tlh
877        connect agw 1 g1tlh
878        # you can leave this out if you call the script 'gb7dxm'
879        client gb7dxm ax25
880
881
882
883
884
885
886
887
888        timeout 15
889        connect telnet dirkl.tobit.co.uk
890        # tell GB7DJK-1 that it is connected to GB7DJK
891        # you can leave this out if you call this script 'gb7djk'
892        client gb7djk telnet
893
894
895
896
897
898   Both these examples assume that everything is set up properly at the
899   other end.  You will find other examples in the /spider/examples
900   directory.
901
902
903   3.7.  Starting the connection
904
905   You start the connection, from within a sysop enabled cluster login,
906   by typing in the word connect followed by a script name like this ....
907
908
909
910        G0VGS de GB7MBC 13-Dec-1998 2041Z >connect gb7djk-1
911        connection to GB7DJK-1 started
912        G0VGS de GB7MBC 13-Dec-1998 2043Z >
913
914
915
916
917   This will start a connection using the script called gb7djk-1.  You
918   can follow the connection by watching the term or console from where
919   you started cluster.pl.  From version 1.47 onwards, you will need to
920   set/debug connect first.  You should see something like this ...
921
922
923
924
925   <- D G1TLH connect gb7djk-1
926   -> D G1TLH connection to GB7DJK-1 started
927   -> D G1TLH G1TLH de GB7DJK 13-Dec-1998 2046Z >
928   timeout set to 15
929   CONNECT sort: telnet command: dirkl.tobit.co.uk
930   CHAT "login" -> "gb7djk"
931   received "
932   Red Hat Linux release 5.1 (Manhattan)
933   Kernel 2.0.35 on an i586
934   "
935   received "login: "
936   sent "gb7djk"
937   CHAT "word" -> "gb7djk"
938   received "gb7djk"
939   received "Password: "
940   sent "gb7djk"
941   Connected to GB7DJK-1, starting normal protocol
942   <- O GB7DJK-1 telnet
943   -> B GB7DJK-1 0
944   GB7DJK-1 channel func  state 0 -> init
945   <- D GB7DJK-1
946   <- D GB7DJK-1 Last login: Sun Dec 13 17:59:56 from dirk1
947   <- D GB7DJK-1 PC38^GB7DJK-1^~
948   <- D GB7DJK-1 PC18^ 1 nodes, 0 local / 1 total users  Max users 0  Uptime
949   0 00:00^5447^~
950       etc
951
952
953
954
955
956   With later versions of Spider there is a set/login command for users.
957   This tells them when a user or node logs in or out.  If you do not add
958   a line to your scripts after the final line (or before the client line
959   which should always be last if needed) then the login/logout
960   information will be sent to users before the login actually completes.
961   This means if a node is unreachable, it will continue sending logins
962   and logouts to users even though it is not actually connecting.  To
963   avoid this use the following line ...
964
965
966
967
968
969
970
971
972   In a script, this might look like ...
973
974
975
976        timeout 35
977        abort (Busy|Sorry|Fail)
978        connect telnet mary 3000
979
980
981
982
983
984   3.8.  Telnet echo
985
986   Cluster links in particular suffer greatly from the presence of telnet
987   echo.  This is caused by the telnet negotiation itself and can create
988   at worst severe loops.  At best it creates unnecessary bandwidth and
989   large logfiles!  There are things that can be done to limit this
990   problem but will not always work dependent on the route taken to
991   connect.
992
993
994   Telnet echo itself should only be a problem if the connection is being
995   made to the telnet port (23).  This port uses special rules that
996   include echo negotiation.  If the connection is to a different port,
997   such as 7300, this negotiation does not happen and therefore no echo
998   should be present.
999
1000
1001   Sometimes it is not possible to make a direct connection to another
1002   node and this can cause problems.  There is a way of trying to
1003   suppress the telnet echo but this will not always work, unfortunately
1004   it is difficult to be more specific.  Here is an example of what I
1005   mean ...
1006
1007
1008
1009        timeout 35
1010        abort (Busy|Sorry|Fail)
1011        connect telnet mary.lancs.ac.uk
1012
1013
1014
1015
1016   So, the first connection is made by Spider.  This is fine as Spider
1017   uses the Net_Telnet script from within perl.  This actually uses TCP
1018   rather than TELNET so no negotiation will be done on the first
1019   connection.  Once connected to mary.lancs.ac.uk, the command is sent
1020   to suppress echo.  Now a telnet is made to a cluster node that is
1021   accepting connections on port 23.  The problem with this link is that
1022   the negotiation is made by the remote machine, therefore you have no
1023   control over it.  The chances are that this link will create echo and
1024   there will be no way you can stop it.
1025
1026
1027
1028   3.9.  Autostarting the cluster
1029
1030   Ok, you should now have DXSpider running nicely and allowing connects
1031   by cluster nodes or users.  However, it has to be shutdown and
1032   restarted manually.  It would be much easier to have it start
1033   automatically.
1034
1035
1036   This is not only a way to start the cluster automatically, it also
1037   works as a watchdog, checking the sanity of DXSpider and respawning it
1038   should it crash for any reason.  Before doing the following, shutdown
1039   the cluster as you did earlier.
1040
1041
1042   Login as root and bring up the /etc/inittab file in your favourite
1043   editor.  Add the following lines to the file near the end ...
1044
1045
1046
1047        ##Start DXSpider on bootup and respawn it should it crash
1048        DX:3:respawn:/bin/su -c "/usr/bin/perl -w /spider/perl/cluster.pl" sysop >/dev/tty7
1049
1050
1051
1052
1053
1054   This line works fine for RedHat distributions. It is also fine for
1055   SuSE up to 7.0.  From Suse 7.1 you need to add runlevels 2 and 5 like
1056   this ...
1057        DX:235:respawn:/bin/su -c "/usr/bin/perl -w /spider/perl/cluster.pl" sysop >/dev/tty7
1058
1059
1060
1061
1062
1063   The line required for Slackware distributions is slightly different.
1064   My thanks to Aurelio, PA3EZL for this information.
1065
1066
1067
1068        DX:23:respawn:/bin/su - sysop -c "/usr/bin/perl -w /spider/perl/cluster.pl" >/dev/tty7
1069
1070
1071
1072
1073
1074   This will automatically start DXSpider on tty7 (ALT-F7) on bootup and
1075   restart it should it crash for any reason.
1076
1077
1078   As root type the command telinit q.  DXSpider should start up
1079   immediately.  You will see the output on tty7 and if you login as
1080   sysop you should find everything running nicely.
1081
1082
1083   4.  Microsoft Windows Installation
1084
1085   4.1.  Introduction
1086
1087   IMPORTANT:
1088
1089   What you'll be left with once you've followed these instructions is
1090   (hopefully) a working DX Spider v1.47 system that is capable of
1091   accepting or originating "internet" connections, plus inbound AX.25
1092   and TCP/IP radio connections. If the absence of outbound radio
1093   connections is a serious limitation for you, it would be better for
1094   you to wait a couple more weeks until this support has been added.
1095
1096   On the other hand, you may have an enquiring mind, or better yet, may
1097   be looking for a useful way of connecting your current (perhaps) AK1A
1098   cluster "to the internet" via some networking mechanism (BPQEther,
1099   etc) or other. I won't be producing instructions for the latter case,
1100   because I don't have an AK1A to play with. But someone might ...
1101
1102   Whatever, this document is intended to get you started with DX Spider
1103   in a Microsoft Windows (TM) environment. It's not intended to teach
1104   you anything other than how to perform a minimum configuration of a DX
1105   Spider installation and have it able to connect across "the internet"
1106   to other DX Clusters, while accepting inbound TELNET and radio
1107   connections.
1108
1109
1110   4.2.  The requirements
1111
1112   The very first things you're going to need are (in order of
1113   importance):-
1114
1115
1116   o  A cup of good, strong tea
1117
1118   o  A supported Windows platform with an internet connection so you can
1119      download the necessary software bits and bobs directly to it. There
1120      are other ways, but this is preferable.
1121
1122
1123   o  Another cup of good, strong tea
1124
1125   o  If all goes according to plan, about an hour to spare
1126
1127   o  Plenty of good, strong tea
1128
1129
1130   4.3.  The system
1131
1132   The platform I used to generate these instructions was a "vanilla"
1133   Microsoft Windows Me 4.90.3000 system, with a 700MHz AMD Athlon
1134   processor and 96 Mb memory. I've also personally verified that it runs
1135   on my laptop (Pentium 266MHz, 32 Mb memory, Windows 98 SE v4.10.2222
1136   A) and a computer that I assembled from a random pile of junk (AMD
1137   K6-2 333MHz, 64 Mb memory, Windows 98 v4.10.1998). As a result, I have
1138   reason to believe that what I'm about to describe will perform equally
1139   on any 32-bit MS Windows environment with 32 Mb of memory.
1140
1141   Because of the changes that have recently been made to the core
1142   "cluster.pl" module and the introduction of a very lightweight
1143   "winclient.pl", I have a sneaking suspicion that this will now run on
1144   any platform that has reasonably complete support for Perl. Is there
1145   someone out there with both an enquiring mind and (say) a Macintosh,
1146   for instance?
1147
1148   Please bear in mind, though, that my instructions relate solely to how
1149   to get this going under a Microsoft Windows environment, and I have
1150   zero intention of trying to make them say otherwise.
1151
1152
1153   4.4.  Perl
1154
1155   Install your chosen Perl environment. Unless you have a very good
1156   reason for not doing so, I strongly suggest that you use ActivePerl
1157   v5.6. For my testing & development, I used build 623.  You can get
1158   this from:-
1159   http://www.activestate.com/Products/ActivePerl/Download.html
1160
1161   You will need to choose either the MSI or the AS package. My
1162   recommendation is that you choose the MSI package and deal with the
1163   consequences if your system isn't equipped with support for the latest
1164   MS Installer; you'll be better off in the long run.  The build 623
1165   download is 7,460 KB, so now is a really good time to have some tea if
1166   you're on a slow dial-up connection.
1167
1168   During installation, please ensure that you do choose the options to
1169   "Add Perl to the PATH environment variable" and "Create Perl file
1170   extension association"; it will make your life so much easier. Once
1171   the installation is finished, be sure to reboot your PC. You probably
1172   won't be told anywhere else that this needs to be done now, but it
1173   does. Really.
1174
1175   Once you've rebooted, open a "DOS box" (Start > Run > command might do
1176   it, if you can't find it elsewhere) and from wherever it lands, type
1177   PERL -v <ENTER> (it's better if that's a lower-case be rewarded with
1178   some interesting information about your Perl installation. If you're
1179   not, you must go back to the beginning and discover what went wrong
1180   and fix it. It's pointless to proceed unless this simple check is
1181   passed. Assuming it did work, you may now move on.
1182
1183
1184   4.5.  Additional packages
1185
1186   Some extensions ("packages") need to be added to the base Perl
1187   distribution, and we'll do this next. If you're using the Perl I
1188   recommended, and don't know any better for yourself, then just blindly
1189   following these instructions will work just fine. If that didn't
1190   describe you, then you're on your own.
1191
1192   Visit the following URL:
1193
1194   http://www.activestate.com/PPMPackages/zips/6xx-builds-only/
1195
1196   and download the following files:-
1197
1198
1199
1200        Data-Dumper.zip
1201        Net-Telnet.zip
1202        TimeDate.zip
1203        Time-HiRes.zip
1204        DB_File.zip
1205
1206
1207
1208
1209   Make yourself a convenient directory to unpack all of these zip files
1210   into (I put mine in "D:\ppm>") and do the following (the bits you type
1211   in are blue ). Note that where these files land will be directly
1212   related to where you chose to install your ActivePerl (mine, as you
1213   can probably guess from what follows, went into "D:\Perl"):-
1214
1215
1216
1217        D:\ppm>ppm install Data-Dumper.ppd
1218        Installing package 'Data-Dumper.ppd'
1219        Installing D:\Perl\site\lib\auto\Data\Dumper\Dumper.bs
1220        Installing D:\Perl\site\lib\auto\Data\Dumper\Dumper.dll
1221        Installing D:\Perl\site\lib\auto\Data\Dumper\Dumper.exp
1222        Installing D:\Perl\site\lib\auto\Data\Dumper\Dumper.lib
1223        Installing D:\Perl\html\site\lib\auto\Data\Dumper\Dumper.html
1224        Installing D:\Perl\site\lib\Data\Dumper\Dumper.pm
1225        Writing D:\Perl\site\lib\auto\Data\Dumper\Dumper.packlist
1226        D:\ppm>
1227
1228
1229
1230
1231   I'm not going to bother you with exhaustive details of the rest of
1232   them, but suffice it to say you need to:
1233
1234
1235
1236        ppm install DB_File.ppd
1237        ppm install Net-Telnet.ppd
1238        ppm install TimeDate.ppd
1239        ppm install Time-HiRes.ppd
1240
1241
1242
1243
1244   If all that seemed to work OK, time to move along. Before anyone who
1245   is familiar with PPM tells me that we didn't need to download and keep
1246   those files locally, I knew that. I also knew that PPM is sometimes
1247   awkward to configure via firewalls, and that sometimes the
1248   repositories don't always work the way we'd hope. I do it that way
1249   because it suits me.
1250
1251
1252
1253
1254
1255   4.6.  Getting Spider
1256
1257   Get the current version of the DX Spider distribution. This needs to
1258   be v1.47 or later. You've got two ways (currently) of getting this;
1259   either get a CVS update from sourceforge (if you don't know what this
1260   is, then it isn't for you) or get my package from:-
1261
1262   http://www.dcc.rsgb.org/WinSpider.zip
1263
1264   or if you want the lastest CVS version (which is produced every night)
1265
1266   http://www.dxcluster.org/download/CVSlatest.tgz
1267
1268   If you went down the CVS route, then everything will be nicely set out
1269   on your local disk. If you got the ZIP file, unpack it to somewhere
1270   convenient. The following examples assume that you put it on drive
1271   "C:\", for convenience.
1272
1273   NOTE: This distribution method will go away as soon as the first v1.47
1274   tarball is released. You can use WinZip to unpack that, and my life
1275   will be made easier by not needing to keep this .ZIP file updated.
1276
1277
1278   5.  Installing the software
1279
1280   Ensure that your CVS session or your unZIPped file have left you with
1281   a directory "C:\spider\local"; if not, go to "C:\spider\" and create
1282   one. If "C:\spider" is missing, go back and figure out why, because it
1283   shouldn't be.
1284
1285   Now create your own local copy of the DXVars.pm file by:-
1286
1287
1288
1289        copy c:\spider\perl\DXVars.pm.issue
1290        c:\spider\local\DXVars.pm
1291
1292
1293
1294
1295   Now you'll need to edit this file using a text editor. If nothing
1296   else, you can simply
1297
1298
1299
1300        cd \spider\local
1301
1302
1303
1304
1305   and then
1306
1307
1308
1309        notepad DXVars.pm
1310
1311
1312
1313
1314   to bring up an editor window containing the file. As an absolute
1315   minimum you must adjust the following items in DXVars.pm:-
1316
1317
1318   o  $mycall  - Should hold the callsign of your DX Cluster
1319
1320
1321   o  $myname  - The SysOp's first name
1322
1323   o  $myalias - the SysOp's callsign. Cannot be the same as $mycall!
1324
1325   You really also ought to update the $mylatitude, $mylongitude, $myqth
1326   and $myemail variables. And unless you are absolutely certain you know
1327   what you're doing, you should change nothing else in this file.
1328
1329
1330   5.1.  The AGW packet engine
1331
1332   On the assumption that you'll be using the SV2AGW Packet Engine to
1333   interface your radios to the cluster, you should now create your own
1334   local copy of AGWConnect.pm by:-
1335
1336
1337
1338        copy c:\spider\perl\AGWConnect.pm
1339        c:\spider\local\AGWConnect.pm
1340
1341
1342
1343
1344   and then
1345
1346
1347
1348        notepad AGWConnect.pm
1349
1350
1351
1352
1353   to bring up an editor window containing the file. You must consider
1354   adjusting the following items in AGWConnect.pm:-
1355
1356
1357   o  $enable - set to '1' to enable AGWPE interface
1358
1359   o  $login  - the login ID you chose when you set up the SV2AGW
1360      security :-)
1361
1362   o  $passwd - password that matches $login
1363
1364
1365   5.2.  Setting up the initial user files
1366
1367   Next you need to create the initial user files, etc. A tool is
1368   supplied which will do this for you. To run the tool:-
1369
1370
1371
1372        cd \spider\perl
1373        perl create_sysop.pl
1374
1375
1376
1377
1378   If all goes according to plan, you will see no output from this
1379   program, and after a brief wait, your DOS prompt will be returned.
1380
1381   Depending on how brave you are, you might now care to try the
1382   following:-
1383
1384
1385
1386
1387   perl cluster.pl
1388
1389
1390
1391
1392   If you did everything you were told, your DOS window will now hold a
1393   display which looks something like:-
1394
1395
1396
1397        DXSpider DX Cluster Version 1.47
1398        Copyright (c) 1998-2001 Dirk Koopman G1TLH
1399        loading prefixes ...
1400        loading band data ...
1401        loading user file system ...
1402        starting listeners ...
1403        Internal port: localhost 27754
1404        load badwords: Ok
1405        reading in duplicate spot and WWV info ...
1406        reading existing message headers ...
1407        load badmsg: Ok
1408        load forward: Ok
1409        load swop: Ok
1410        @msg = 0 before delete
1411        @msg = 0 after delete
1412        reading cron jobs ...v cron: reading /spider/cmd/crontab
1413        cron: adding 1 0 * * 0
1414        DXUser::export("$main::data/user_asc")
1415        reading database descriptors ...
1416        doing local initialisation ...
1417        orft we jolly well go ...
1418        queue msg (0)
1419
1420
1421
1422
1423   Now, if that's what you've got, you are very nearly home and dry (in
1424   as far as these particular experiments are concerned, anyhow)
1425
1426   To access your new cluster (from the local machine) find yourself
1427   another "DOS box" and do the following:-
1428
1429
1430
1431        cd \spider\perl
1432        perl winclient.pl
1433
1434
1435
1436
1437   If you are rewarded with a display which looks something like:-
1438
1439
1440
1441        Hello Iain, this is GB7SJP in Amersham, Bucks running DXSpider V1.47
1442        Cluster: 1 nodes, 1 local / 1 total users Max users 2 Uptime 0 00:00
1443        M0ADI de GB7SJP 4-Mar-2001 1511Z >
1444
1445
1446
1447
1448   You've arrived. Try some commands, and see how they feel. (In case you
1449   were wondering, "Iain", "M0ADI" and "GB7SJP" all came from the version
1450   of DXVars.pm that was on the machine when I started the winclient.pl)
1451
1452
1453   5.3.  Incoming telnets
1454
1455   If you want to enable inbound "TELNET" connections, you've got a
1456   little more work to do. From a handy "DOS box" that's not doing
1457   anything else, do the following:-
1458
1459
1460
1461        copy \spider\perl\listeners.pm \spider\local
1462        cd \spider\local
1463        notepad listeners.pm
1464
1465
1466
1467
1468   The following lines need attention:-
1469
1470
1471
1472        ["0.0.0.0", 7300],
1473
1474
1475
1476
1477   On my machine, I've simply uncommented the "0.0.0.0" entry by removing
1478   the '#' from the front of the line.
1479
1480   If you don't have a static hostname for your machine, and you intend
1481   to allow folk to connect to your machine across the internet, then I'd
1482   suggest you pay a visit to www.dyndns.org and create one for yourself.
1483   While it's free, it will take a modest an amount of effort on your
1484   part to read, understand and implement what needs to be done to set
1485   this up.
1486
1487
1488   5.4.  Connecting to other clusters
1489
1490   If you want to connect this to another cluster, then you'll want to
1491   negotiate a link with someone. For experimental purposes, I'm happy to
1492   allow folk to connect to GB7DXA (spud.ath.cx), on the understanding
1493   that the system may or may not be there and may or may not be
1494   connected to anything particularly useful at any given moment. Contact
1495   me by Email if you want me to set up a connection for you.
1496
1497
1498   6.  General Information
1499
1500   The following relates to all versions of DXSpider and is not platform
1501   related.
1502
1503
1504   6.1.  The crontab file
1505
1506   Login as sysop and create a file in /spider/local_cmd called crontab.
1507   Edit it with your favourite editor and add a line like this (I have
1508   included a comment)
1509
1510
1511
1512        # check every 10 minutes to see if gb7xxx is connected and if not
1513        # start a connect job going
1514
1515        0,10,20,30,40,50 * * * * start_connect('gb7xxx') unless connected('gb7xxx')
1516
1517
1518
1519   The callsign involved will be the callsign of the cluster node you are
1520   going to connect to.  This will now check every 10 minutes to see if
1521   gb7xxx is connected, if it is then nothing will be done.  If it is
1522   not, then a connect attempt will be started.
1523
1524
1525   There are probably lots of other things you could use this crontab
1526   file for.  If you want to know more about it, look at the DXSpider
1527   website at the cron page where it is explained more fully.
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584