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