]> scm.dxcluster.org Git - spider.git/blob - sgml/adminmanual.sgml
a9287fb187c90c64dd490cc117580b2833542d7d
[spider.git] / sgml / adminmanual.sgml
1 <!doctype linuxdoc system>
2
3 <article>
4
5 <!-- Title information -->
6
7 <title>The DXSpider Installation and Administration Manual 
8 <author>Ian Maude, G0VGS, (ianmaude@btinternet.com)
9 <date>Version 1.24 July 2000
10 <abstract>
11 A reference for SysOps of the DXSpider DXCluster program.
12 </abstract>
13
14 <!-- Table of contents -->
15 <toc>
16
17 <!-- Begin the document -->
18
19 <sect>Installation (Original version by Iain Phillips, G0RDI)
20
21 <P>
22 Last modified: 25 July 2000 by Ian Maude, G0VGS
23
24 <sect1>Introduction
25
26 <P>
27 This section describes the installation of DX Spider v1.35 on a <htmlurl url="http://www.redhat.com" name="RedHat"> Linux Distribution.  I do not intend to try and cover the installation of Linux or the setup of the AX25 utilities.  If you need help on this then read Iains original HOWTO on the <htmlurl url="http://www.dxcluster.org" name="DXSpider"> website.
28
29 <P>
30 I am assuming a general knowledge of Linux and its commands.  You should know how to use <em>tar</em> and how to edit files using your favourite editor.
31
32 <P>
33 The crucial ingredient for all of this is <htmlurl url="http://www.perl.org" name="Perl 5.004">.Now I know Perl 5.005 is out and this will almost certainly work with it, but <htmlurl url="http://www.redhat.com" name="RedHat 5.1"> comes with 5.004. <em>Be Warned</em>, earlier versions of <htmlurl url="http://www.redhat.com" name="RedHat"> <bf>do not</bf> come with 5.004 as standard, you need to <htmlurl url="ftp://upgrade.redhat.com" name="upgrade">
34
35 <P>In addition to the standard Red Hat distribution you will require the following <htmlurl url="http://www.cpan.org/CPAN.html" name="CPAN"> modules: -
36
37 <P>
38 <itemize>
39
40 <item>          MD5-1.7.tar.gz
41 <item>          Data-Dumper-2.10.tar.gz
42 <item>          FreezeThaw-0.3.tar.gz
43 <item>          MLDBM-2.00.tar.gz
44 <item>          TimeDate-1.8.tar.gz
45 <item>          IO-1.20.tar.gz
46 <item>          Net-Telnet-3.02.tar.gz
47 <item>          Curses-1.05.tar.gz
48
49 </itemize>
50
51 <P>
52
53 <em>Do</em> get the latest versions of these packages and install them but use the above list as the earliest versions usable.
54
55 <sect1>Preparation
56
57 <P>
58 I will assume that you have already downloaded the latest tarball of the DXSpider software and are ready to install it. I am assuming version 1.35 for this section but of course you would use the latest version.
59
60 <P>
61 Login as root and create a user to run the cluster under.  <bf><it>UNDER NO CIRCUMSTANCES USE ROOT AS THIS USER!</it></bf>.  I am going to use the name <em>sysop</em>.  You can call it anything you wish.  Depending on your security requirements you may wish to use an existing user, however this is your own choice.
62
63 <P>
64 <tscreen><verb>
65 # adduser -m sysop
66 </verb></tscreen>
67
68 <P>
69 Now set a password for the user ...
70
71 <tscreen><verb>
72 # passwd sysop
73 # New UNIX password:
74 # Retype new UNIX password:
75 passwd: all authentication tokens updated successfully
76 </verb></tscreen>
77
78 <sect1>Installing the software
79
80 <P>
81 Now to unpack the DX Spider distribution, set symbolic links and group permissions.  Copy the tarball to /home/sysop and do the following.
82
83 <tscreen><verb>
84 # cd ~sysop
85 # tar xvfz spider-1.35.tar.gz
86 # ln -s ~sysop/spider /spider
87 # groupadd -g 251 spider       (or another number)
88 </verb></tscreen>
89
90 If you do not have the command <em>groupadd</em> available to you simply add a line in /etc/group by hand.
91
92 <tscreen><verb>
93 # vi /etc/group                (or your favorite editor)
94 </verb></tscreen>
95
96 You also need to add some others to the group, including your own callsign (this will be used as an alias) and root.  The finished line in /etc/group should look something like this
97
98 <tt>
99 spider:x:251:sysop,g0vgs,root
100 </tt>
101
102 <P>
103 The next step is to set the permissions on the Spider directory tree and files ....
104
105 <tscreen><verb>
106 # chown -R sysop.spider spider
107 # find . -type d -exec chmod 2775 {} \;
108 # find . -type f -exec chmod 775 {} \;
109 </verb></tscreen>
110
111 <P>
112 This last step allows various users of the group <em>spider</em> to have write access to all the directories.  This is not really needed just yet but will be useful when web interfaces start to appear.
113
114 <P>
115 Finally, you need to fix the permissions on the ax25_call and netrom_call programs.  Check where they are with the <em>locate</em> command and alter the permissions with the <em>chmod</em> command like this ..
116
117 <tscreen><verb>
118 # chown root ax25_call netrom_call
119 # chmod 4775 ax25_call netrom_call
120 </verb></tscreen>
121
122 <sect1>Setting callsigns etc
123
124 <P>
125 Now login to your machine as the user you created earlier.  In my case that user is called <em>sysop</em>.  Once logged in, issue the following commands ....
126
127 <tscreen><verb>
128 $ cd /spider
129 $ mkdir local
130 $ mkdir local_cmd
131 $ cp perl/DXVars.pm.issue local/DXVars.pm
132 $ cd local
133 $ vi DXVars.pm (or your favourite editor)
134 </verb></tscreen>
135
136 <P>
137 Using the distributed DXVars.pm as a a template, set your cluster callsign, sysop callsign and other user info to suit your own environment. Note that this a perl file which will be parsed and executed as part of the cluster. If you get it wrong then perl will complain when you start the cluster process.  It is important only to alter the text of any section.  Some of the lines look a little odd.  Take this line for example ....
138
139 <tt>
140 $myemail = "ianmaude\@btinternet.com";
141 </tt>
142
143 <P>
144 There appears to be an extra slash in there.  However this has to be there for the file to work so leave it in.
145                 
146 <P><bf>PLEASE USE CAPITAL LETTERS FOR CALLSIGNS</bf>
147                 
148 <P>
149 DON'T alter the DXVars.pm (or any other file) in /spider/perl, they are overwritten with every release. Any files or commands you place in /spider/local or /spider/local_cmd will automagically be used in preference to the ones in /spider/perl EVEN while the cluster is running!
150
151 <P>
152 Save the new file and change directory to ../perl ....
153
154 <tscreen><verb>
155 $ cd ../perl
156 </verb></tscreen>
157
158 <P>
159 Now type the following command which creates the basic user file with you as the sysop.
160
161 <tscreen><verb>
162 $ create_sysop.pl
163 </verb></tscreen>
164
165 <sect1>Starting up for the first time
166
167 <P>
168 We can now bring spider up for the first time and see if all is well or not!  It should look something like this ...
169
170 <tscreen><verb>
171 $ cluster.pl
172 DXSpider DX Cluster Version 1.35
173 Copyright (c) 1998 Dirk Koopman G1TLH
174 loading prefixes ...
175 loading band data ...
176 loading user file system ...
177 starting listener ...
178 reading existing message headers
179 reading cron jobs
180 orft we jolly well go ...
181 </verb></tscreen>
182
183 <P>
184 If all is well then login on another term or console as <em>sysop</em> and cd to /spider/perl.  Now issue the following command ...
185
186 <tscreen><verb>
187 $ client.pl
188 </verb></tscreen>
189
190 <P>
191 This should log you into the cluster as the sysop under the alias callsign we set earlier.  In this case the callsign is G0VGS.  The cluster callsign is set in the DXVars.pm file in /spider/local.  In this case we will assume that this was set as GB7MBC.  You should therefore see this when you login ....
192
193 <tscreen><verb>
194 G0VGS de GB7MBC 19-Nov-1999 2150Z >
195 </verb></tscreen>
196
197 If you do, congratulations!  If not, look over the instructions again, you have probably missed something out.  You can shut spider down again with the command ....
198
199 <tscreen><verb>
200 shutdown
201 </verb></tscreen>
202
203 <P>
204 and both the cluster and the client should return to Linux prompts.
205
206 <sect>The Client program
207
208 <P>
209 In earlier versions of Spider, all the processes were Perl scripts.  This was fine but with a lot of users your computer memory would soon be used up.  To combat this a new client was written in "C".  This client only works for <em>incoming</em> connects at the moment.  Before you can use it though it has to be "made".  CD to /spider/src and type <em>make</em>.  You should see the output on your screen and hopefully now have a small C program called <em>client</em>.  Leave it in this directory.
210
211 <sect>Configuration
212
213 <sect1>Allowing ax25 connects from users
214
215 <P>
216 As stated previously, the aim of this document is not to tell you how to configure Linux or the ax25 utilities.  However, you do need to add a line in your ax25d.conf to allow connections to DXSpider for your users.  For each interface that you wish to allow connections on, use the following format ...
217
218 <tscreen><verb>
219 default  * * * * * *  - sysop /spider/src/client client %u ax25
220 </verb></tscreen>
221
222 <sect1>Allowing telnet connects from users
223
224 <P>
225 Allowing telnet connections is quite simple.  Firstly you need to add a line in /etc/services to allow connections to a port number, like this ....
226
227 <tscreen><verb>
228 spdlogin   8000/tcp     # spider anonymous login port
229 </verb></tscreen>
230
231 Then add a line in /etc/inetd.conf like this ....
232
233 <tscreen><verb>
234 spdlogin stream tcp nowait root /usr/sbin/tcpd /spider/src/client login telnet
235 </verb></tscreen>
236
237 <P>
238 This needs to be added above the standard services such as ftp, telnet etc.  Once this is done, you need to restart inetd like this ....
239
240 <tscreen><verb>
241 killall -HUP inetd
242 </verb></tscreen>
243
244
245 <P>Now login as <em>sysop</em> and cd spider/perl. You can test that spider is accepting telnet logins by issuing the following command ....
246
247 <tscreen><verb>
248 client.pl login telnet
249 </verb></tscreen>
250
251 You should get a login prompt and on issuing a callsign, you will be given access to the cluster.  Note, you will not get a password login.  There seems no good reason for a password prompt to be given so it is not asked for.
252
253 <P>
254 Assuming all is well, then try a telnet from your linux console ....
255
256 <tscreen><verb>
257 telnet localhost 8000
258 </verb></tscreen>
259
260 <P>
261 You should now get the login prompt and be able to login as before.
262
263 <sect1>Setting up node connects
264
265 <P>
266 In order to allow cluster node connections, spider needs to know that the connecting callsign is a cluster node.  This is the case whether the connect is incoming or outgoing.
267 In spider this is a simple task and can be done in runtime.
268
269 <P>
270 Start up the cluster as you did before and login as the sysop with client.pl.
271 The cluster node I am wanting to make a connection to is GB7BAA but you would obviously use whatever callsign you required.
272 At the prompt type ...
273
274 <tscreen><verb>
275 set/node gb7baa
276 </verb></tscreen>
277
278 <P>
279 The case does not matter as long as you have a version of DXSpider later than 1.33.  Earlier versions required the callsign to be in upper case.
280
281 <P>
282 That is now set, it is as simple as that.  To prove it, login on yet another console as sysop and issue the command ...
283
284 <tscreen><verb>
285 client.pl gb7baa (using the callsign you set as a node)
286 </verb></tscreen>
287
288 <P>
289 You should get an initialisation string from DXSpider like this ...
290
291 <tscreen><verb>
292 client.pl gb7baa
293 PC38^GB7MBC^~
294 </verb></tscreen>
295
296 If the callsign you just set up as a cluster node is for an incoming connect, this is all that needs to be done.  If the connection is to be outgoing then a connection script needs to be written.
297
298 <sect2>Connection scripts
299
300 <P>
301 Because DXSpider operates under Linux, connections can be made using just about any protocol;  AX25, NETRom, tcp/ip, ROSE etc are all possible examples.  Connect scripts live in the /spider/connect directory and are simple ascii files.  Writing a script for connections is therefore relatively simple.  
302
303 <P>
304 The connect scripts consist of lines which start with the following keywords or symbols:-
305
306
307 <verb>
308         
309 #               All lines starting with a # are ignored, as are completely blank lines.
310
311 timeout         timeout followed by a number is the number of seconds to wait for a 
312                 command to complete. If there is no timeout specified in the script 
313                 then the default is 60 seconds.
314
315 abort           abort is a regular expression containing one or more strings to look 
316                 for to abort a connection. This is a perl regular expression and is 
317                 executed ignoring case.
318
319 connect         connect followed by ax25 or telnet and some type dependent 
320                 information. In the case of a telnet connection, there can be up to 
321                 two parameters.
322                 The first is the ip address or hostname of the computer you wish to 
323                 connect to and the second is the port number you want to use (this 
324                 can be left out if it is a normal telnet session).
325                 In the case of an ax25 session then this would normally be a call to
326                 ax25_call or netrom_call as in the example above. It is your
327                 responsibility to get your node and other ax25 parameters to work 
328                 before going down this route!
329
330 '               ' is the delimiting character for a word or phrase of an expect/send 
331                 line in a chat type script. The words/phrases normally come in pairs, 
332                 either can be empty. Each line reads input from the connection until 
333                 it sees the string (or perl regular expression) contained in the
334                 left hand string. If the left hand string is empty then it doesn't 
335                 read or wait for anything. The comparison is done ignoring case.
336                 When the left hand string has found what it is looking for (if it is) 
337                 then the right hand string is sent to the connection.
338                 This process is repeated for every line of chat script. 
339
340 client          client starts the connection, put the arguments you would want here 
341                 if you were starting the client program manually. You only need this 
342                 if the script has a different name to the callsign you are trying to 
343                 connect to (i.e. you have a script called other which actually 
344                 connects to GB7DJK-1 [instead of a script called gb7djk-1]).
345 </verb>
346
347
348 There are many possible ways to configure the script but here are two examples, one for a NETRom/AX25 connect and one for tcp/ip.  
349
350 <tscreen><verb>
351         timeout 60
352         abort (Busy|Sorry|Fail)
353         # don't forget to chmod 4775 netrom_call!
354         connect ax25 /usr/sbin/netrom_call bbs gb7djk g1tlh
355         'Connect' ''
356         'Connect' 'c np7'
357         'Connect' 'c gb7dxm'
358         # you can leave this out if you call the script 'gb7dxm'
359         client gb7dxm ax25
360 </verb></tscreen>
361
362 <P>
363
364 <tscreen><verb>
365         timeout 15
366         connect telnet dirkl.tobit.co.uk
367         'login' 'gb7djk'
368         'word' 'gb7djk'
369         # tell GB7DJK-1 that it is connected to GB7DJK
370         # you can leave this out if you call this script 'gb7djk'
371         client gb7djk telnet
372 </verb></tscreen>
373
374 <P>
375 Both these examples assume that everything is set up properly at the other end.  You will find other examples in the /spider/examples directory.
376
377 <sect2>Starting the connection
378
379 <P>
380 You start the connection, from within a sysop enabled cluster login, by typing in the word <em>connect</em> followed by a script name like this ....
381
382 <tscreen><verb>
383 G0VGS de GB7MBC 13-Dec-1998 2041Z >connect gb7djk-1
384 connection to GB7DJK-1 started
385 G0VGS de GB7MBC 13-Dec-1998 2043Z >
386 </verb></tscreen>
387
388 This will start a connection using the script called <em>gb7djk-1</em>.  You can follow the connection by watching the term or console from where you started <em>cluster.pl</em>.  You should see something like this ...
389
390 <tscreen><verb>
391 <- D G1TLH connect gb7djk-1
392 -> D G1TLH connection to GB7DJK-1 started
393 -> D G1TLH G1TLH de GB7DJK 13-Dec-1998 2046Z >
394 timeout set to 15
395 CONNECT sort: telnet command: dirkl.tobit.co.uk
396 CHAT "login" -> "gb7djk"
397 received "
398 Red Hat Linux release 5.1 (Manhattan)
399 Kernel 2.0.35 on an i586
400 "
401 received "login: "
402 sent "gb7djk"
403 CHAT "word" -> "gb7djk"
404 received "gb7djk"
405 received "Password: "
406 sent "gb7djk"
407 Connected to GB7DJK-1, starting normal protocol
408 <- O GB7DJK-1 telnet
409 -> B GB7DJK-1 0
410 GB7DJK-1 channel func  state 0 -> init
411 <- D GB7DJK-1 
412 <- D GB7DJK-1 Last login: Sun Dec 13 17:59:56 from dirk1
413 <- D GB7DJK-1 PC38^GB7DJK-1^~
414 <- D GB7DJK-1 PC18^ 1 nodes, 0 local / 1 total users  Max users 0  Uptime 0 00:00^5447^~
415     etc
416
417 </verb></tscreen>
418
419 <P>
420 With later versions of Spider there is a set/login command for users.  This tells them when a user or node logs in or out.  If you do not add a line to your scripts after the final line (or before the client line which should always be last if needed) then the login/logout information will be sent to users <it>before</it> the login actually completes.  This means if a node is unreachable, it will continue sending logins and logouts to users even though it is not actually connecting.  To avoid this use the following line ...
421
422 <tscreen><verb>
423 'connect' ''
424 </verb></tscreen>
425
426 <P>
427 In a script, this might look like ...
428
429 <tscreen><verb>
430 timeout 35 
431 abort (Busy|Sorry|Fail)
432 connect telnet mary 3000
433 'ogin:' 'gb7mbc'
434 '>' 'telnet 44.131.93.96 7305'
435 'connect' ''
436 </verb></tscreen>
437
438 <sect1>Automating things
439
440 <P>
441 Ok, you should now have DXSpider running nicely and allowing connects by cluster nodes or users.  However, it has to be shutdown and restarted manually and if connection scripts fail they have to be started again manually too, not much use if you are not at the console!
442 So, in this section we will automate both.  Firstly starting the cluster.
443
444 <sect2>Autostarting the cluster
445
446 <P>
447 This is not only a way to start the cluster automatically, it also works as a watchdog, checking the sanity of DXSpider and respawning it should it crash for any reason.
448 Before doing the following, shutdown the cluster as you did earlier.
449
450 <P>
451 Login as root and bring up the /etc/inittab file in your favourite editor.  Add the following lines to the file near the end ...
452
453 <tscreen><verb>
454 ##Start DXSpider on bootup and respawn it should it crash
455 DX:3:respawn:/bin/su -c "/usr/bin/perl -w /spider/perl/cluster.pl" sysop >/dev/tty7
456 </verb></tscreen>
457
458 <P>
459 This will automatically start DXSpider on tty7 (ALT-F7) on bootup and restart it should it crash for any reason.
460
461 <P>
462 As root type the command <em>telinit q</em>.  DXSpider should start up immediately.  You will see the output on tty7 and if you login as <em>sysop</em> you should find everything running nicely.
463
464 <P>
465 So far so good, now to automate script connections...
466
467 <sect2>The crontab file
468
469 <P>
470 Login as <em>sysop</em> and create a file in /spider/local_cmd called crontab.  Edit it with your favourite editor and add a line like this (I have included a comment)
471
472 <tscreen><verb>
473 # check every 10 minutes to see if gb7xxx is connected and if not
474 # start a connect job going
475
476 0,10,20,30,40,50 * * * * start_connect('gb7xxx') if !connected('gb7xxx')
477 </verb></tscreen>
478
479 <P>
480 The callsign involved will be the callsign of the cluster node you are going to connect to.  This will now check every 10 minutes to see if gb7xxx is connected, if it is then nothing will be done.  If it is not, then a connect attempt will be started.
481
482 <P>
483 There are probably lots of other things you could use this crontab file for.  If you want to know more about it, look at the <htmlurl url="http://www.dxcluster.org/cron.html" name="DXSpider"> website at the cron page where it is explained more fully.
484
485 <sect>Hop control
486
487 <P>
488 Starting with version 1.13 there is simple hop control available on a per
489 node basis. Also it is possible to isolate a network completely so that you 
490 get all the benefits of being on that network, but can't pass on information
491 from it to any other networks you may be connected to (or vice versa).
492
493 <sect1>Basic hop control
494
495 <P>
496 In /spider/data you will find a file called hop_table.pl.  This is the file that controls your hop count settings.  It has a set of default hops on the various PC frames and also a set for each node you want to alter the hops for.  You may be happy with the default settings of course, but this powerful tool can help to protect and improve the network.  The file will look something like this ...
497
498 <tscreen><verb>
499
500 # hop table construction
501
502
503 package DXProt;
504
505 # default hopcount to use
506 $def_hopcount = 5;
507
508 # some variable hop counts based on message type
509 %hopcount = 
510
511  11 => 10,
512  16 => 10,
513  17 => 10,
514  19 => 10,
515  21 => 10,
516 );
517
518
519 # the per node hop control thingy
520
521
522 %nodehops = 
523
524  GB7ADX => {            11 => 8,
525                         12 => 8,
526                         16 => 8,
527                         17 => 8,
528                         19 => 8,
529                         21 => 8,
530                    },
531
532  GB7UDX => {            11 => 8,
533                         12 => 8,
534                         16 => 8,
535                         17 => 8,
536                         19 => 8,
537                         21 => 8,
538                    },
539  GB7BAA => {
540                         11 => 5,
541                         12 => 8,
542                         16 => 8,
543                         17 => 8,
544                         19 => 8,
545                         21 => 8,
546                    },
547 };
548 </verb></tscreen>
549
550 <P>
551 Each set of hops is contained within a pair of curly braces and contains a series of PC frame types.  PC11 for example is a DX spot. The figures here are not exhaustive but should give you a good idea of how the file works.
552
553 <P>
554 You can alter this file at any time, including whilst the cluster is running.  If you alter the file during runtime, the command <em>load/hops</em> will bring your changes into effect.
555
556 <sect1>Isolating networks
557
558 <P>
559 It is possible to isolate networks from each other on a "gateway" node using the
560  <em>set/isolate &lt;node_call&gt;</em> command.
561         
562 <P>
563 The effect of this is to partition an isolated network completely from another 
564 nodes connected to your node. Your node will appear on and otherwise behave 
565 normally on every network to which you are connected, but data from an isolated 
566 network will not cross onto any other network or vice versa. However all the 
567 spot, announce and WWV traffic and personal messages will still be handled 
568 locally (because you are a real node on all connected networks), that is locally
569 connected users will appear on all networks and will be able to access and 
570 receive information from all networks transparently.  All routed messages will 
571 be sent as normal, so if a user on one network knows that you are a gateway for 
572 another network, he can still still send a talk/announce etc message via your 
573 node and it will be routed across.
574
575 <P>
576 The only limitation currently is that non-private messages cannot be passed down 
577 isolated links regardless of whether they are generated locally. This will change 
578 when the bulletin routing facility is added.
579
580 <P>
581 If you use isolate on a node connection you will continue to receive all information from the isolated partner, however you will not pass any information back to the isolated node.  There are times when you would like to forward only spots across a link (maybe during a contest for example).  To do this, isolate the node in the normal way and put in a filter in the /spider/filter/spots directory to override the isolate.  This filter can be very simple and consists of just one line ....
582
583 <tscreen><verb>
584 $in = [
585         [ 1, 0, 'd', 0, 3]      # The last figure (3) is the hop count
586 ];
587 </verb></tscreen>
588
589 <P>
590 There is a lot more on filtering in the next section.
591
592 <sect>Filtering
593
594 <P>
595 Filters can be set for spots, announcements and WWV.  You will find the directories for these under /spider/filter.  You will find some examples in the directories with the suffix <em>.issue</em>.  There are two types of filter, one for incoming information and one for outgoing information. Outgoing filters are in the form <em>CALLSIGN.pl</em> and incoming filters are in the form <em>in_CALLSIGN.pl</em>.  Filters can be set for both nodes and users.
596
597 <P>
598 All filters work in basically the same way.  There are several elements delimited by commas.
599 There can be many lines in the filter and they are read from the top by the program.
600 When writing a filter you need to think carefully about just what you want to achieve.  You
601 are either going to write a filter to <em>accept</em> or to <em>reject</em>.
602 Think of a filter as having 2 main elements.  For a reject filter, you would have a line
603 or multiple lines rejecting the things you do not wish to receive and then a default
604 line accepting everything else that is not included in the filter.  Likewise, for an
605 accept filter, you would have a line or multiple lines accepting the things you wish
606 to receive and a default line rejecting everthing else.
607
608 <P>
609 In the example below, a user requires a filter that would only return SSB spots
610 posted in Europe on the HF bands.  This is achieved by first rejecting the CW section 
611 of each HF band and rejecting all of VHF, UHF etc based on frequency.
612 Secondly, a filter rule is set based on CQ zones to only accept spots posted in
613 Europe.  Lastly, a default filter rule is set to reject anything outside the filter.
614
615 <tscreen><verb>
616 $in = [
617         [ 0, 0, 'r', # reject all CW spots
618                 [
619                 1800.0, 1850.0,
620                 3500.0, 3600.0,
621                 7000.0, 7040.0,
622                 14000.0, 14100.0,
623                 18068.0, 18110.0,
624                 21000.0, 21150.0,
625                 24890.0, 24930.0,
626                 28000.0, 28180.0,
627                 30000.0, 49000000000.0,
628                 ] ,1 ],
629         [ 1, 11, 'n', [ 14, 15, 16, 20, 33, ], 15 ], #accept EU
630         [ 0, 0, 'd', 0, 1 ], # 1 = want, 'd' = everything else
631 ];
632 </verb></tscreen>
633
634 <P>
635 The actual elements of each filter are described more fully in the following sections.
636
637 <sect1>Spots
638
639 <P>
640 The elements of the Spot filter are ....
641
642 <tscreen><verb>
643 [action, field_no, sort, possible_values, hops]
644 </verb></tscreen>
645
646 <P>
647 There are 3 elements here to look at.  Firstly, the action element.  This is very simple and only 2 possible states exist, accept (1) or drop (0).
648
649 <P>
650 The second element is the field_no.  There are 13 possiblities to choose from here ....
651
652 <tscreen><verb>
653       0 = frequency
654       1 = call
655       2 = date in unix format
656       3 = comment
657       4 = spotter
658       5 = spotted dxcc country
659       6 = spotter's dxcc country
660       7 = origin
661       8 = spotted itu
662       9 = spotted cq
663       10 = spotter's itu
664       11 = spotter's cq
665       12 = callsign of the channel on which the spot has appeared
666 </verb></tscreen>
667
668 <P>
669 The third element tells us what to expect in the fourth element.  There are 4 possibilities ....
670
671 <tscreen><verb>
672      n - numeric list of numbers e.g. [ 1,2,3 ]
673      r - ranges of pairs of numbers e.g. between 2 and 4 or 10 to 17 - [ 2,4, 10,17 ] 
674      a - an alphanumeric regex
675      d - the default rule
676 </verb></tscreen>
677
678 <P>
679 The fifth element is simply the hops to set in this filter.  This would only be used if the filter was for a node of course and overrides the hop count in hop_table.pl.
680
681 <P>
682 So, let's look at an example spot filter.  It does not matter in the example who the filter is to be used for.
683 So, what do we need in the filter?  We need to filter the spots the user/node requires and also set a default rule for anything else outside the filter.  Below is a simple filter that stops spots arriving from outside Europe.
684
685 <tscreen><verb>$in = [
686   [ 0, 4, 'a', '^(K|N|A|W|VE|VA|J)'],  # 0 = drop, 'a' = alphanumeric
687   [ 1, 0, 'd', 0, 1 ],                 # 1 = want, 'd' = everything else
688                      ];
689 </verb></tscreen>
690
691 <P>
692 So the filter is wrapped in between a pair of square brackets.  This tells Spider to look in between these limits.  Then each line is contained within its own square brackets and ends with a comma.
693 Lets look carefully at the first line.  The first element is 0 (drop).  Therefore anything we put on this line will not be accepted.  The next element is 4.  This means we are filtering by the spotter.  The third element is the letter "a" which tells the program to expect an alphanumeric expression in the fourth element.  The fourth element is a list of letters separated by the pipe symbol.
694
695 <P>
696 What this line does is tell the program to drop any spots posted by anyone in the USA, Canada or Japan.
697
698 <P>
699 The second line is the default rule for anything else.  The "d" tells us this and the line simply reads... accept anything else.
700
701 <P>
702 You can add as many lines as you need to complete the filter but if there are several lines of the same type it is neater to enclose them all as one line.  An example of this is where specific bands are set.  We could write this like this ....
703
704 <tscreen><verb>
705 [ 0,0,'r',[1800.0, 2000.0], 1],
706 [ 0,0,'r',[10100.0, 10150.0], 1],
707 [ 0,0,'r',[14000.0, 14350.0], 1],
708 [ 0,0,'r',[18000.0, 18200.0], 1],
709 </verb></tscreen>
710
711 <P>
712 But the line below achieves the same thing and is more efficient ....
713
714 <tscreen><verb>
715   [ 0, 0, 'r',
716     [  
717       1800.0, 2000.0,         # top band 
718       10100.0, 10150.0,       # WARC  
719       14000.0, 14350.0,       # 20m
720       18000.0, 18200.0,       # WARC
721     [ ,1 ],
722 </verb></tscreen>
723
724
725 <sect1>Announcements
726
727 <P>
728 <tscreen><verb>
729
730 # This is an example announce or filter allowing only West EU announces
731
732 # The element list is:-
733 # 0 - callsign of announcer
734 # 1 - destination * = all, <callsign> = routed to the node
735 # 2 - text
736 # 3 - * - sysop, <some text> - special list eg 6MUK, ' ', normal announce
737 # 4 - origin
738 # 5 - 0 - announce, 1 - wx
739 # 6 - channel callsign (the interface from which this spot came)
740
741 $in = [
742         [ 1, 0, 'a', '^(P[ABCDE]|DK0WCY|G|M|2|EI|F|ON)' ],
743         [ 0, 0, 'd', 0 ]
744 ];
745 </verb></tscreen>
746
747 In this example, only the prefixes listed will be allowed.  It is possible to be quite specific.  The Dutch prefix "P" is followed by several secondary identifiers which are allowed.  So, in the example, "PA" or "PE" would be ok but not "PG".  It is even possible to allow information from a single callsign.  In the example this is DK0WCY, to allow the posting of his Aurora Beacon.
748
749 <sect1>WWV
750
751 <P>
752 <tscreen><verb>
753
754 # This is an example WWV filter
755
756 # The element list is:-
757 # 0 - nominal unix date of spot (ie the day + hour:13)
758 # 1 - the hour
759 # 2 - SFI
760 # 3 - K
761 # 4 - I
762 # 5 - text
763 # 6 - spotter
764 # 7 - origin
765 # 8 - incoming interface callsign
766
767 # this one doesn't filter, it just sets the hop count to 6 and is
768 # used mainly just to override any isolation from WWV coming from
769 # the internet.
770
771 $in = [
772         [ 1, 0, 'd', 0, 6 ]
773 ];
774
775 </verb></tscreen>
776
777 <P>
778 It should be noted that the filter will start to be used only once a user/node has logged out and back in again.
779 <P>
780 I am not going to spend any more time on these filters now as they will become more "comprehensive" in the near future.
781
782 <sect1>Filtering Mail
783
784 <P>
785 In the /spider/msg directory you will find a file called badmsg.pl.issue.  Rename this to badmsg.pl and edit the file.  The original looks something like this ....
786
787 <tscreen><verb>
788
789 # the list of regexes for messages that we won't store having
790 # received them (bear in mind that we must receive them fully before
791 # we can bin them)
792
793
794 # The format of each line is as follows
795
796 #     type      source             pattern 
797 #     P/B/F     T/F/O/S            regex  
798
799 # type: P - private, B - bulletin (msg), F - file (ak1a bull)
800 # source: T - to field, F - from field,  O - origin, S - subject 
801 # pattern: a perl regex on the field requested
802
803 # Currently only type B and P msgs are affected by this code.
804
805 # The list is read from the top down, the first pattern that matches
806 # causes the action to be taken.
807
808 # The pattern can be undef or 0 in which case it will always be selected
809 # for the action specified
810
811
812
813 package DXMsg;
814
815 @badmsg = (
816 'B',    'T',    'SALE', 
817 'B',    'T',    'WANTED',
818 'B',    'S',    'WANTED',
819 'B',    'S',    'SALE', 
820 'B',    'S',    'WTB',
821 'B',    'S',    'WTS',
822 'B',    'T',    'FS',
823 );
824 </verb></tscreen>
825
826 <P>
827 I think this is fairly self explanatory.  It is simply a list of subject headers that we do not want to pass on to either the users of the cluster or the other cluster nodes that we are linked to.  This is usually because of rules and regulations pertaining to items for sale etc in a particular country.
828
829 <sect1>Filtering DX callouts
830
831 <P>
832 In the same way as mail, there are some types of spot we do not wish to pass on to users or linked cluster nodes.  In the /spider/data directory you will find a file called baddx.pl.issue.  Rename this to baddx.pl and edit the file.  The original looks like this ....
833
834 <tscreen><verb>
835
836 # the list of dx spot addresses that we don't store and don't pass on
837
838
839 package DXProt;
840
841 @baddx = qw 
842
843  FROG 
844  SALE
845  FORSALE
846  WANTED
847  P1RATE
848  PIRATE
849  TEST
850  DXTEST
851  NIL
852  NOCALL 
853 );
854 </verb></tscreen>
855
856 <P>
857 Again, this is simply a list of names we do not want to see in the spotted field of a DX callout.
858
859
860 <sect>Information, files and useful programs
861
862 <sect1>MOTD
863
864 <P>
865 One of the more important things a cluster sysop needs to do is to get information to his users.  The simplest way to do this is to have a banner that is sent to the user on login.  This is know as a "message of the day" or "motd".  To set this up, simply create a file in /spider/data called motd and edit it to say whatever you want.  It is purely a text file and will be sent automatically to anyone logging in to the cluster.
866
867 <sect1>Downtime message
868
869 <P>
870 If for any reason the cluster is down, maybe for upgrade or maintenance but the machine is still running, a message can be sent to the user advising them of the fact.  This message lives in the /spider/data directory and is called "offline".  Simply create the file and edit it to say whatever you wish.  This file will be sent to a user attempting to log into the cluster when DXSpider is not actually running.
871
872 <sect1>Other text messages
873
874 <P>
875 You can set other text messages to be read by the user if they input the file name.  This could be for news items or maybe information for new users.  To set this up, make a directory under /spider called <em>packclus</em>.  Under this directory you can create files called <em>news</em> or <em>newuser</em> for example.  In fact you can create files with any names you like.  These can be listed by the user with the command ....
876
877 <tscreen><verb>
878 show/files
879 </verb></tscreen>
880
881 They can be read by the user by typing the command ....
882
883 <tscreen><verb>
884 type news
885 </verb></tscreen>
886
887 If the file they want to read is called <em>news</em>.  You could also set an alias for this in the Alias file to allow them just to type <em>news</em>
888
889 <P>
890 You can also store other information in this directory, either directly or nested under directories.  One use for this would be to store DX bulletins such as the OPDX bulletins.  These can be listed and read by the user.  To keep things tidy, make a directory under /spider/packclus called <em>bulletins</em>.  Now copy any OPDX or similar bulletins into it.  These can be listed by the user in the same way as above using the <em>show/files</em> command with an extension for the bulletins directory you have just created, like this ....
891
892 <tscreen><verb>
893 show/files bulletins
894 </verb></tscreen>
895
896 <P>
897 An example would look like this ....
898
899 <tscreen><verb>
900 sh/files
901 bulletins      DIR 20-Dec-1999 1715Z news          1602 14-Dec-1999 1330Z
902 </verb></tscreen>
903
904 You can see that in the files area (basically the packclus directory) there is a file called <em>news</em> and a directory called <em>bulletins</em>.  You can also see that dates they were created.  In the case of the file <em>news</em>, you can also see the time it was last modified, a good clue as to whether the file has been updated since you last read it.  To read the file called <em>news</em> you would simply issue the command ....
905
906 <tscreen><verb>
907 type news
908 </verb></tscreen>
909
910 To look what is in the bulletins directory you issue the command ....
911
912 <tscreen><verb>
913 show/files bulletins
914 opdx390      21381 29-Nov-1999 1621Z opdx390.1     1670 29-Nov-1999 1621Z
915 opdx390.2     2193 29-Nov-1999 1621Z opdx391      25045 29-Nov-1999 1621Z  
916 opdx392      35969 29-Nov-1999 1621Z opdx393      15023 29-Nov-1999 1621Z  
917 opdx394      33429 29-Nov-1999 1621Z opdx394.1     3116 29-Nov-1999 1621Z  
918 opdx395      24319 29-Nov-1999 1621Z opdx396      32647 29-Nov-1999 1621Z
919 opdx396.1     5537 29-Nov-1999 1621Z opdx396.2     6242 29-Nov-1999 1621Z
920 opdx397      18433 29-Nov-1999 1621Z opdx398      19961 29-Nov-1999 1621Z  
921 opdx399      17719 29-Nov-1999 1621Z opdx400      19600 29-Nov-1999 1621Z
922 opdx401      27738 29-Nov-1999 1621Z opdx402      18698 29-Nov-1999 1621Z
923 opdx403      24994 29-Nov-1999 1621Z opdx404      15685 29-Nov-1999 1621Z
924 opdx405      13984 29-Nov-1999 1621Z opdx405.1     4166 29-Nov-1999 1621Z
925 opdx406      28934 29-Nov-1999 1621Z opdx407      24153 29-Nov-1999 1621Z
926 opdx408      15081 29-Nov-1999 1621Z opdx409      23234 29-Nov-1999 1621Z
927 Press Enter to continue, A to abort (16 lines) >
928 </verb></tscreen>
929
930 You can now read any file in this directory using the type command, like this ....
931
932 <tscreen><verb>
933 type bulletins/opdx391
934 Ohio/Penn DX Bulletin No. 391
935 The Ohio/Penn Dx PacketCluster
936 DX Bulletin No. 391
937 BID: $OPDX.391
938 January 11, 1999
939 Editor Tedd Mirgliotta, KB8NW
940 Provided by BARF-80 BBS Cleveland, Ohio
941 Online at 440-237-8208 28.8k-1200 Baud 8/N/1 (New Area Code!)
942 Thanks to the Northern Ohio Amateur Radio Society, Northern Ohio DX
943 Association, Ohio/Penn PacketCluster Network, K1XN & Golist, WB2RAJ/WB2YQH
944 & The 59(9) DXReport, W3UR & The Daily DX, K3TEJ, KN4UG, W4DC, NC6J, N6HR,
945 Press Enter to continue, A to abort (508 lines) >
946 </verb></tscreen>
947
948 The page length will of course depend on what you have it set to!
949
950 <sect1>The Aliases file
951
952 <P>
953 You will find a file in /spider/cmd/ called Aliases.  First, copy this file to /spider/local_cmd/Aliases and edit this file.  You will see something like this ...
954
955 <tscreen><verb>
956
957 #!/usr/bin/perl
958
959 # provide some standard aliases for commands for terminally
960 # helpless ak1a user (helpless in the sense that they never
961 # read nor understand help files)
962
963 # This file is automagically reloaded if its modification time is 
964 # later than the one stored in CmdAlias.pm
965
966 # PLEASE make this file consistant with reality! (the patterns MUST
967 # match the filenames!)
968
969 # Don't alter this file, copy it into the local_cmd tree and modify it.
970 # This file will be replaced everytime I issue a new release.
971
972 # You only need to put aliases in here for commands that don't work as
973 # you desire naturally, e.g sh/dx on its own just works as you expect
974 # so you need not add it as an alias.
975
976
977
978 package CmdAlias;
979
980 %alias = (
981     '?' => [
982           '^\?', 'apropos', 'apropos',
983         ],
984     'a' => [
985           '^ann.*/full', 'announce full', 'announce', 
986           '^ann.*/sysop', 'announce sysop', 'announce',
987           '^ann.*/(.*)$', 'announce $1', 'announce',
988         ],
989         'b' => [
990         ],
991         'c' => [
992         ],
993         'd' => [
994           '^del', 'kill', 'kill',
995           '^del\w*/fu', 'kill full', 'kill',
996           '^di\w*/a\w*', 'directory all', 'directory',
997           '^di\w*/b\w*', 'directory bulletins', 'directory',
998           '^di\w*/n\w*', 'directory new', 'directory',
999           '^di\w*/o\w*', 'directory own', 'directory',
1000           '^di\w*/s\w*', 'directory subject', 'directory',
1001           '^di\w*/t\w*', 'directory to', 'directory',
1002           '^di\w*/f\w*', 'directory from', 'directory',
1003           '^di\w*/(\d+)', 'directory $1', 'directory',
1004         ],
1005         'e' => [
1006         ],
1007         'f' => [
1008         ],
1009         'g' => [
1010         ],
1011         'h' => [
1012         ],
1013         'i' => [
1014         ],
1015         'j' => [
1016         ],
1017         'k' => [
1018         ],
1019         'l' => [
1020           '^l$', 'directory', 'directory',
1021           '^ll$', 'directory', 'directory',
1022           '^ll/(\d+)', 'directory $1', 'directory',
1023         ],
1024         'm' => [
1025         ],
1026         'n' => [
1027           '^news', 'type news', 'type',
1028         ],
1029         'o' => [
1030         ],
1031         'p' => [
1032         ],
1033         'q' => [
1034           '^q', 'bye', 'bye',
1035         ],
1036         'r' => [        
1037           '^r$', 'read', 'read',
1038           '^rcmd/(\S+)', 'rcmd $1', 'rcmd',
1039         ],
1040         's' => [
1041           '^s/p$', 'send', 'send',
1042           '^sb$', 'send noprivate', 'send',
1043           '^set/home$', 'set/homenode', 'set/homenode',
1044           '^set/nobe', 'unset/beep', 'unset/beep',
1045           '^set/nohe', 'unset/here', 'unset/here',
1046           '^set/noan', 'unset/announce', 'unset/announce',
1047           '^set/nodx', 'unset/dx', 'unset/dx',
1048           '^set/nota', 'unset/talk', 'unset/talk',
1049           '^set/noww', 'unset/wwv', 'unset/wwv',
1050           '^set/nowx', 'unset/wx', 'unset/wx',
1051           '^sh$', 'show', 'show',
1052           '^sh\w*/buck', 'dbshow buck', 'dbshow',
1053           '^sh\w*/bu', 'show/files bulletins', 'show/files',
1054           '^sh\w*/c/n', 'show/configuration nodes', 'show/configuration',
1055           '^sh\w*/c$', 'show/configuration', 'show/configuration',
1056           '^sh\w*/com', 'dbavail', 'dbavail',
1057           '^sh\w*/dx/(\d+)-(\d+)', 'show/dx $1-$2', 'show/dx',
1058           '^sh\w*/dx/(\d+)', 'show/dx $1', 'show/dx',
1059           '^sh\w*/dx/d(\d+)', 'show/dx from $1', 'show/dx',
1060           '^sh\w*/email', 'dbshow email', 'dbshow',
1061           '^sh\w*/hftest', 'dbshow hftest', 'dbshow',
1062           '^sh\w*/vhftest', 'dbshow vhftest', 'dbshow',
1063           '^sh\w*/qsl', 'dbshow qsl', 'dbshow',
1064           '^sh\w*/tnc', 'who', 'who',
1065       '^sh\w*/up', 'show/cluster', 'show/cluster',
1066           '^sh\w*/w\w*/(\d+)-(\d+)', 'show/wwv $1-$2', 'show/wwv',
1067           '^sh\w*/w\w*/(\d+)', 'show/wwv $1', 'show/wwv',
1068           '^sp$', 'send', 'send',
1069         
1070     ],
1071         't' => [
1072           '^ta$', 'talk', 'talk',
1073           '^t$', 'talk', 'talk',
1074         ],
1075         'u' => [
1076         ],
1077         'v' => [
1078         ],
1079         'w' => [
1080           '^wx/full', 'wx full', 'wx',
1081           '^wx/sysop', 'wx sysop', 'wx',
1082         ],
1083         'x' => [
1084         ],
1085         'y' => [
1086         ],
1087         'z' => [
1088         ],
1089 )
1090 </verb></tscreen>
1091
1092 You can create aliases for commands at will.  Beware though, these may not always turn out as you think.  Care is needed and you need to test the results once you have set an alias.
1093
1094 <sect1>Forward.pl
1095
1096 <P>
1097 DXSpider receives all and any mail sent to it without any alterations needed
1098 in files.  Because personal and bulletin mail are treated differently, there
1099 is no need for a list of accepted bulletin addresses.  It is necessary, however,
1100 to tell the program which links accept which bulletins.  For example, it is
1101 pointless sending bulletins addresses to "UK" to any links other than UK
1102 ones.  The file that does this is called forward.pl and lives in /spider/msg.
1103 At default, like other spider files it is named forward.pl.issue.  Rename it
1104 to forward.pl and edit the file to match your requirements.
1105 The format is below ...
1106
1107 <tscreen><verb>
1108 #
1109 # this is an example message forwarding file for the system
1110 #
1111 # The format of each line is as follows
1112 #
1113 #     type    to/from/at pattern action  destinations
1114 #     P/B/F     T/F/A     regex   I/F    [ call [, call ...] ]
1115 #
1116 # type: P - private, B - bulletin (msg), F - file (ak1a bull)
1117 # to/from/at: T - to field, F - from field, A - home bbs, O - origin 
1118 # pattern: a perl regex on the field requested
1119 # action: I - ignore, F - forward
1120 # destinations: a reference to an array containing node callsigns
1121 #
1122 # if it is non-private and isn't in here then it won't get forwarded 
1123 #
1124 # Currently only type B msgs are affected by this code.
1125
1126 # The list is read from the top down, the first pattern that matches
1127 # causes the action to be taken.
1128 #
1129 # The pattern can be undef or 0 in which case it will always be selected
1130 # for the action specified
1131 #
1132 # If the BBS list is undef or 0 and the action is 'F' (and it matches the
1133 # pattern) then it will always be forwarded to every node that doesn't have 
1134 # it (I strongly recommend you don't use this unless you REALLY mean it, if
1135 # you allow a new link with this on EVERY bull will be forwarded immediately
1136 # on first connection)
1137 #
1138
1139 package DXMsg;
1140
1141 @forward = (
1142 'B',    'T',    'LOCAL',        'F',    [ qw(GB7MBC) ],
1143 'B',    'T',    'ALL',          'F',    [ qw(GB7BAA GB7ADX PA4AB-14) ],
1144 'B',    'T',    'UK',           'F',    [ qw(GB7BAA GB7ADX) ],
1145 'B',    'T',    'QSL',          'F',    [ qw(GB7BAA GB7ADX PA4AB-14) ],
1146 'B',    'T',    'QSLINF',       'F',    [ qw(GB7BAA GB7ADX PA4AB-14) ],
1147 'B',    'T',    'DX',           'F',    [ qw(GB7BAA GB7ADX PA4AB-14) ],
1148 'B',    'T',    'DXINFO',       'F',    [ qw(GB7BAA GB7ADX PA4AB-14) ],
1149 'B',    'T',    'DXNEWS',       'F',    [ qw(GB7BAA GB7ADX PA4AB-14) ],
1150 'B',    'T',    'DXQSL',        'F',    [ qw(GB7BAA GB7ADX PA4AB-14) ],
1151 'B',    'T',    'SYSOP',        'F',    [ qw(GB7BAA GB7ADX) ],
1152 'B',    'T',    '50MHZ',        'F',    [ qw(GB7BAA GB7ADX PA4AB-14) ],
1153 );
1154 </verb></tscreen>
1155
1156 Simply insert a bulletin address and state in the brackets where you wish
1157 that mail to go.  For example, you can see here that mail sent to "UK" will
1158 only be sent to the UK links and not to PA4AB-14.
1159
1160 <P>
1161 To force the cluster to reread the file use load/forward
1162
1163 <sect1>Distribution lists
1164
1165 <P>
1166 Distribution lists are simply a list of users to send certain types of
1167 mail to.  An example of this is mail you only wish to send to other
1168 sysops.  In /spider/msg there is a directory called <em>distro</em>.  You
1169 put any distibution lists in here.  For example, here is a file called
1170 SYSOP.pl that caters for the UK sysops.
1171
1172 <tscreen><verb>
1173 qw(GB7TLH GB7DJK GB7DXM GB7CDX GB7BPQ GB7DXN GB7MBC GB7MBC-6 GB7MDX
1174    GB7NDX GB7SDX GB7TDX GB7UDX GB7YDX GB7ADX GB7BAA GB7DXA GB7DXH 
1175    GB7DXK GB7DXI GB7DXS)
1176 </verb></tscreen>
1177
1178 Any mail sent to "sysop" would only be sent to the callsigns in this list.
1179  
1180 <sect1>Console.pl
1181
1182 <P>
1183 In later versions of Spider a simple console program is provided for the sysop.  This has a type ahead buffer with line editing facilities and colour for spots, announces etc.
1184 To use this program, simply use console.pl instead of client.pl.
1185
1186 <P>
1187 To edit the colours, copy /spider/perl/Console.pl to /spider/local and edit the file with your favourite editor.
1188
1189 <sect>Sysop commands
1190
1191 <P>
1192 Most maintenance tasks are automatic but there are some commands that are useful for a sysop.  These are listed below in alphabetical order.  The number in brackets following the command name is the permissions level needed to use the command.
1193
1194 <sect1>announce sysop (5)
1195
1196 <P>
1197 <tt>
1198 <bf>announce sysop &lt;text&gt;</bf>
1199 </tt>
1200
1201 <P>
1202 Send an announcement to Sysops only
1203
1204 <sect1>connect (5) 
1205
1206 <P>
1207 <tt>
1208 <bf>connect &lt;callsign&gt;</bf> Start a connection to another DX Cluster
1209 </tt>
1210
1211 <P>
1212 Start a connection process that will culminate in a new connection to the
1213 DX cluster &lt;callsign&gt;. This process creates a new 'client' process which will
1214 use the script in /spider/connect/&lt;callsign&gt; to effect the 'chat' exchange
1215 necessary to traverse the network(s) to logon to the cluster &lt;callsign&gt;.
1216
1217
1218 <sect1>catch (9) 
1219
1220 <P>
1221 <tt>
1222 <bf>&lt;node_call&gt; All [&lt;msgno&gt; ...]</bf> Mark a message as sent
1223 </tt>
1224
1225 <P>
1226 When you send messages the fact that you have forwarded it to another node 
1227 is remembered so that it isn't sent again. When you have a new partner
1228 node and you add their callsign to your /spider/msg/forward.pl file, all
1229 outstanding non-private messages will be forwarded to them. This may well
1230 be ALL the non-private messages. You can prevent this by using these 
1231 commmands:-
1232
1233   catch GB7DJK all
1234   catch GB7DJK 300 301 302 303
1235         
1236 and to undo what you have just done:-
1237   
1238   uncatch GB7DJK all
1239   uncatch GB7DJK 300 301 302 303
1240
1241 which will arrange for them to be forward candidates again.
1242
1243 <sect1>dbcreate (9)
1244
1245 <P>
1246 <tt>
1247 <bf>dbcreate &lt;name&gt;</bf> Create a database entry<newline>
1248 <bf>dbcreate &lt;name&gt; chain &lt;name&gt; [&lt;name&gt;..]</bf> Create a chained database entry<newline>
1249 <bf>dbcreate &lt;name&gt; remote &lt;node&gt;</bf> Create a remote database entry<newline>
1250 </tt>
1251
1252 <P>
1253 DBCREATE allows you to define a database in the system. It doesn't actually
1254 create anything, just defines it.
1255
1256 The databases that are created are simple DB_File hash databases, they are 
1257 therefore already 'indexed'.
1258
1259 You can define a local database with the first form of the command eg:
1260
1261   DBCREATE oblast
1262
1263 You can also chain databases with the addition of the 'chain' keyword. 
1264 This will search each database one after the other. A typical example 
1265 is:
1266
1267   DBCREATE sdx_qsl chain sql_ad
1268
1269 No checking is done to see if the any of the chained databases exist, in
1270 fact it is usually better to do the above statement first then do each of
1271 the chained databases.
1272
1273 Databases can exist offsite. To define a database that lives on another 
1274 node do:
1275
1276   DBCREATE buckmaster remote gb7dxc
1277
1278 Remote databases cannot be chained; however, the last database in a 
1279 a chain can be a remote database eg:
1280
1281   DBCREATE qsl chain gb7dxc
1282
1283 To see what databases have been defined do:
1284
1285   DBAVAIL (or it will have been aliased to SHOW/COMMAND)
1286
1287 It would be normal for you to add an entry into your local Aliases file
1288 to allow people to use the 'SHOW/&lt;dbname&gt;' style syntax. So you would
1289 need to add a line like:-
1290
1291 <tscreen><verb>
1292   's' => [
1293     ..
1294     ..
1295     '^sh\w*/buc', 'dbshow buckmaster', 'dbshow',
1296     ..
1297     ..
1298    ],
1299 </verb></tscreen>
1300
1301 to allow 
1302
1303   SH/BUCK g1tlh
1304
1305 to work as they may be used to.
1306
1307 See DBIMPORT for the importing of existing AK1A format data to databases.
1308 See DBSHOW for generic database enquiry
1309
1310 <sect1>dbimport (9)
1311
1312 <P>
1313 <tt>
1314 <bf>dbimport &lt;dbname&gt;</bf> Import AK1A data into a database
1315 </tt>
1316
1317 <P>
1318 If you want to import or update data in bulk to a database you can use
1319 this command. It will either create or update entries into an existing
1320 database. For example:-
1321
1322   DBIMPORT oblast /tmp/OBLAST.FUL
1323
1324 will import the standard OBLAST database that comes with AK1A into the
1325 oblast database held locally.
1326
1327 <sect1>dbremove (9)
1328
1329 <P>
1330 <tt>
1331 <bf>dbremove &lt;dbname&gt;</bf> Delete a database
1332 </tt>
1333
1334 <P>
1335 DBREMOVE will completely remove a database entry and also delete any data
1336 file that is associated with it. 
1337
1338 There is no warning, no comeback, no safety net. 
1339
1340 For example:
1341
1342   DBREMOVE oblast 
1343
1344 will remove the oblast database from the system and it will also remove
1345 the associated datafile.
1346
1347 I repeat:
1348
1349 There is no warning, no comeback, no safety net.
1350
1351 You have been warned.
1352
1353 <sect1>debug (9)
1354
1355 <P>
1356 <tt>
1357 <bf>debug</bf> Set the cluster program into debug mode
1358 </tt>
1359
1360 <P>
1361 Executing this command will only have an effect if you are running the cluster
1362 in debug mode i.e.
1363
1364 <tscreen><verb>
1365         perl -d cluster.pl
1366 </verb></tscreen>
1367
1368 It will interrupt the cluster just after the debug command has finished.
1369
1370 <sect1>directory (5)
1371
1372 <P>
1373 Works just like the user command except that sysops can see ALL messages.
1374
1375 <sect1>disconnect (8)
1376
1377 <P>
1378 <tt>
1379 <bf>disconnect &lt;call&gt; [&lt;call&gt; ...]</bf> Disconnect a user or node
1380 </tt>
1381
1382 <P>
1383 Disconnect any &lt;call&gt; connected locally
1384
1385 <sect1>export (9)
1386
1387 <P>
1388 <tt>
1389 <bf>export &lt;msgno&gt; &lt;filename&gt;</bf> Export a message to a file
1390 </tt>
1391
1392 <P>
1393 Export a message to a file. This command can only be executed on a local
1394 console with a fully privileged user. The file produced will be in a form
1395 ready to be imported back into the cluster by placing it in the import 
1396 directory (/spider/msg/import).
1397
1398 This command cannot overwrite an existing file. This is to provide some 
1399 measure of security. Any files written will owned by the same user as the 
1400 main cluster, otherwise you can put the new files anywhere the cluster can
1401 access. For example:-
1402
1403   EXPORT 2345 /tmp/a
1404
1405 <sect1>forward/opername (1)
1406
1407 <P>
1408 <tt>
1409 <bf>forward/opername &lt;call&gt;</bf> Send out information on this &lt;call&gt; to all clusters
1410 </tt>
1411
1412 <P>
1413 This command sends out any information held in the user file which can 
1414 be broadcast in PC41 protocol packets. This information is Name, QTH, Location
1415 and Homenode. PC41s are only sent for the information that is available.
1416
1417 <sect1>init (5)
1418
1419 <P>
1420 <tt>
1421 <bf>init &lt;node call&gt;</bf> Re-initialise a link to an AK1A compatible node
1422 </tt>
1423
1424 <P>
1425 This command attempts to re-initialise a link to a (usually) AK1A node
1426 that has got confused, usually by a protocol loop of some kind. It may
1427 work - but you usually will be better off simply disconnecting it (or
1428 better, if it is a real AK1A node, doing an RCMD &lt;node&gt; DISC/F &lt;your
1429 node&gt;).
1430
1431 Best of luck - you will need it.
1432
1433 <sect1>kill (5)
1434
1435 <P>
1436 <tt>
1437 <bf>kill &lt;msgno&gt [&lt;msgno&gt; ...]</bf> Remove or erase a message from the system<newline>
1438 <bf>kill from &lt;call&gt;</bf> Remove all messages from a callsign<newline>
1439 <bf>kill to &lt;call&gt;</bf> Remove all messages to a callsign<newline>
1440 </tt>
1441
1442 <P>
1443 You can get rid of any message to or originating from your callsign using 
1444 this command. You can remove more than one message at a time.
1445
1446 As a sysop you can kill any message on the system.
1447
1448 <sect1>kill full (5)
1449
1450 <tt>
1451 <bf>kill full &lt;msgno&gt; [&lt;msgno&gt;]</bf> Delete a message from the whole cluster
1452 </tt>
1453
1454 <P>
1455 Delete a message (usually a 'bulletin') from the whole cluster system. 
1456
1457 This uses the subject field, so any messages that have exactly the same subject
1458 will be deleted. Beware!
1459
1460 <sect1>load/aliases (9)
1461
1462 <P>
1463 <tt>
1464 <bf>load/aliases</bf> Reload the command alias table
1465 </tt>
1466
1467 <P>
1468 Reload the /spider/cmd/Aliases file after you have editted it. You will need to
1469 do this if you change this file whilst the cluster is running in order for the
1470 changes to take effect.
1471
1472 <sect1>load/bands (9)
1473
1474 <P>
1475 <tt>
1476 <bf>load/bands</bf> Reload the band limits table
1477 </tt>
1478
1479 <P>
1480 Reload the /spider/data/bands.pl file if you have changed it manually whilst
1481 the cluster is running. 
1482
1483 <sect1>load/cmd_cache (9)
1484
1485 <P>
1486 <tt>
1487 <bf>load/cmd_cache</bf> Reload the automatic command cache
1488 </tt>
1489
1490 <P>
1491 Normally, if you change a command file in the cmd or local_cmd tree it will
1492 automatially be picked up by the cluster program. Sometimes it can get confused
1493 if you are doing a lot of moving commands about or delete a command in the 
1494 local_cmd tree and want to use the normal one again. Execute this command to
1495 reset everything back to the state it was just after a cluster restart.
1496
1497 <sect1>load/messages (9)
1498
1499 <P>
1500 <tt>
1501 <bf>load/messages</bf> Reload the system messages file
1502 </tt>
1503
1504 <P>
1505 If you change the /spider/perl/Messages file (usually whilst fiddling/writing ne
1506 commands) you can have them take effect during a cluster session by executing this
1507 command. You need to do this if get something like :-
1508
1509 unknown message 'xxxx' in lang 'en'
1510
1511 <sect1>load/prefixes (9)
1512
1513 <P>
1514 <tt>
1515 <bf>load/prefixes</bf> Reload the prefix table
1516 </tt>
1517
1518 <P>
1519 Reload the /spider/data/prefix_data.pl file if you have changed it manually whilst
1520 the cluster is running. 
1521
1522 <sect1>merge (5)
1523
1524 <P>
1525 <tt>
1526 <bf>merge &lt;node&gt; [&lt;no spots&gt;/&lt;no wwv&gt;]</bf> Ask for the latest spots and WWV
1527 </tt>
1528
1529 <P>
1530 MERGE allows you to bring your spot and wwv database up to date. By default
1531 it will request the last 10 spots and 5 WWVs from the node you select. The 
1532 node must be connected locally.
1533
1534 You can request any number of spots or wwv and although they will be appended
1535 to your databases they will not duplicate any that have recently been added 
1536 (the last 2 days for spots and last month for WWV data).
1537
1538 <sect1>msg (9)
1539
1540 <P>
1541 <tt>
1542 <bf>msg &lt;cmd&gt; &lt;msgno&gt; [data ...]</bf> Alter various message parameters
1543 </tt>
1544
1545 <P>
1546 Alter message parameters like To, From, Subject, whether private or bulletin
1547 or return receipt (RR) is required or whether to keep this message from timing
1548 out.
1549
1550 <tscreen><verb>
1551   MSG TO <msgno> <call>     - change TO callsign to <call>
1552   MSG FRom <msgno> <call>   - change FROM callsign to <call>
1553   MSG PRrivate <msgno>      - set private flag
1554   MSG NOPRrivate <msgno>    - unset private flag
1555   MSG RR <msgno>            - set RR flag
1556   MSG NORR <msgno>          - unset RR flag
1557   MSG KEep <msgno>          - set the keep flag (message won't be deleted ever)
1558   MSG NOKEep <msgno>        - unset the keep flag
1559   MSG SUbject <msgno> <new> - change the subject to <new>
1560   MSG WAittime <msgno>      - remove any waitting time for this message
1561   MSG NOREad <msgno>        - mark message as unread
1562   MSG REad <msgno>          - mark message as read
1563   MSG QUeue                 - queue any outstanding bulletins
1564   MSG QUeue 1               - queue any outstanding private messages
1565 </verb></tscreen>
1566
1567 You can look at the status of a message by using:-
1568
1569   STAT/MSG &lt;msgno&gt;      
1570
1571 This will display more information on the message than DIR does.
1572
1573 <sect1>pc (8)
1574
1575 <P>
1576 <tt>
1577 <bf>pc &lt;call&gt; &lt;text&gt;</bf> Send text (eg PC Protocol) to &lt;call&gt;
1578 </tt>
1579
1580 <P>
1581 Send some arbitrary text to a locally connected callsign. No processing is done on
1582 the text. This command allows you to send PC Protocol to unstick things if problems
1583 arise (messages get stuck etc). eg:-
1584
1585    pc gb7djk PC33^GB7TLH^GB7DJK^400^
1586
1587 You can also use in the same way as a talk command to a connected user but
1588 without any processing, added of "from &lt;blah&gt; to &lt;blah&gt;" or whatever.
1589
1590    pc G1TLH Try doing that properly!!!
1591
1592 <sect1>ping (1)
1593
1594 <P>
1595 <tt>
1596 <bf>ping &lt;node&gt;</bf> Send a ping command to another cluster node
1597 </tt>
1598
1599 <P>
1600 This command is used to estimate the quality of the link to another cluster. 
1601 The time returned is the length of time taken for a PC51 to go to another 
1602 cluster and be returned.
1603
1604 Any visible cluster node can be PINGed.
1605
1606 <sect1>rcmd (1)
1607
1608 <P>
1609 <tt>
1610 <bf>rcmd &lt;node call&gt; &lt;cmd&gt;</bf> Send a command to another DX cluster
1611 </tt>
1612
1613 <P>
1614 This command allows you to send nearly any command to another DX Cluster
1615 node that is connected to the system. 
1616
1617 Whether you get any output is dependant on a) whether the other system knows
1618 that the node callsign of this cluster is in fact a node b) whether the
1619 other system is allowing RCMDs from this node and c) whether you have
1620 permission to send this command at all.
1621
1622 <sect1>read (5)
1623
1624 <P>
1625 <tt>
1626 <bf>read &lt;msgno&gt;</bf> Read a message on the system
1627 </tt>
1628
1629 <P>
1630 As a sysop you may read any message on the system
1631
1632 <sect1>set/debug (9)
1633
1634 <P>
1635 <tt>
1636 <bf>set/debug &lt;name&gt;</bf> Add a debug level to the debug set
1637 </tt>
1638
1639 <P>
1640 You can remove this level with unset/debug &lt;name&gt;
1641
1642 <sect1>set/isolate (9)
1643
1644 <P>
1645 <tt>
1646 <bf>set/isolate &lt;node call&gt;</bf> Isolate a node from the rest of the network
1647 </tt>
1648
1649 <P>
1650 Connect a node to your system in such a way that you are a full protocol
1651 member of its network and can see all spots on it, but nothing either leaks
1652 out from it nor goes back into from the rest of the nodes connected to you.
1653
1654 You can potentially connect several nodes in this way.
1655
1656 You can see which nodes are isolated with the show/isolate (1) command.
1657
1658 You can remove the isolation with the command unset/isolate.
1659
1660 <sect1>set/sys_location (9)
1661
1662 <P>
1663 <tt>
1664 <bf>set/sys_location &lt;lat & long&gt;</bf> Set your cluster latitude and longitude
1665 </tt>
1666
1667 <P>
1668 In order to get accurate headings and such like you must tell the system
1669 what your latitude and longitude is. If you have not yet done a SET/QRA
1670 then this command will set your QRA locator for you. For example:-
1671
1672   SET/LOCATION 52 22 N 0 57 E
1673
1674 <sect1>set/lockout (9)
1675
1676 <P>
1677 <tt>
1678 <bf>set/lockout &lt;call&gt;</bf> Stop a callsign connecting to the cluster
1679 </tt>
1680
1681 <P>
1682 You can show who is locked out with the show/lockout (9) command.
1683
1684 To allow the user to connect again, use the command unset/lockout
1685
1686 <sect1>set/node (9)
1687
1688 <P>
1689 <tt>
1690 <bf>set/node &lt;call&gt; [&lt;call&gt; ...]</bf> Make the callsign an AK1A cluster
1691 </tt>
1692
1693 <P>
1694 Tell the system that the call(s) are to be treated as AK1A cluster and
1695 fed PC Protocol rather normal user commands.
1696
1697 From version 1.41 you can also set the following types of cluster
1698
1699 <verb>
1700 set/spider
1701 set/dxnet
1702 set/clx
1703 set/arcluster
1704 </verb>
1705
1706 To see what your nodes are set to, use the show/nodes command.
1707
1708 <sect1>set/obscount (9)
1709
1710 <P>
1711 <tt>
1712 <bf>set/obscount &lt;count&gt; &lt;node call&gt;</bf> Set the 'pump-up' obscelence counter
1713 </tt>
1714
1715 <P>
1716 From version 1.35 onwards neighbouring nodes are pinged at regular intervals (see
1717 SET/PINGINTERVAL), usually 300 seconds or 5 minutes. There is a 'pump-up'
1718 counter which is decremented on every outgoing ping and then reset to
1719 the 'obscount' value on every incoming ping. The default value of this
1720 parameter is 2. 
1721
1722 What this means is that a neighbouring node will be pinged twice at 
1723 (default) 300 second intervals and if no reply has been heard just before
1724 what would be the third attempt, that node is disconnected.
1725
1726 If a ping is heard then the obscount is reset to the full value. Using
1727 default values, if a node has not responded to a ping within 15 minutes,
1728 it is disconnected.
1729
1730 <sect1>set/pinginterval (9)
1731
1732 <P>
1733 <tt>
1734 <bf>set/pinginterval &lt;time&gt; &lt;node call&gt;</bf> Set the ping time to neighbouring nodes
1735 </tt>
1736
1737 <P>
1738 As from version 1.35 all neighbouring nodes are pinged at regular intervals
1739 in order to determine the rolling quality of the link and, in future, to
1740 affect routing decisions. The default interval is 300 secs or 5 minutes.
1741
1742 You can use this command to set a different interval. Please don't. 
1743
1744 But if you do the value you enter is treated as minutes up 60 and seconds
1745 for numbers greater than that.
1746
1747 This is used also to help determine when a link is down at the far end
1748 (as certain cluster software doesn't always notice), see SET/OBSCOUNT
1749 for more information.
1750
1751 <sect1>set/privilege (9)
1752
1753 <P>
1754 <tt>
1755 <bf>set/privilege &lt;n&gt; &lt;call&gt; [&lt;call&gt; ...]</bf> Set the privilege level on a call
1756 </tt>
1757
1758 <P>
1759 Set the privilege level on a callsign. The privilege levels that pertain
1760 to commands are as default:-
1761
1762 <tscreen><verb>
1763   0 - normal user
1764   1 - allow remote nodes normal user RCMDs
1765   5 - various privileged commands (including shutdown, but not disc-
1766       connect), the normal level for another node.
1767   8 - more privileged commands (including disconnect)
1768   9 - local sysop privilege. DO NOT SET ANY REMOTE USER OR NODE TO THIS
1769       LEVEL.
1770 </verb></tscreen>
1771
1772 If you are a sysop and you come in as a normal user on a remote connection
1773 your privilege will automatically be set to 0.
1774
1775 <sect1>set/password (9)
1776
1777 <P>
1778 <tt>
1779 <bf>set/password &lt;callsign&gt; &lt;string&gt;</bf> Set a users password
1780 </tt>
1781
1782 <P>
1783 The password for a user can only be set by a full sysop. The string
1784 can contain any characters but any spaces are removed (you can type in
1785 spaces - but they won't appear in the password). You can see the
1786 result with STAT/USER.  The password is the usual 30 character baycom
1787 type password.
1788
1789 <sect1>set/sys_qra (9)
1790
1791 <P>
1792 <tt>
1793 <bf>set/sys_qra &lt;locator&gt;</bf> Set your cluster QRA locator
1794 </tt>
1795
1796 <sect1>show program (5)
1797
1798 <P>
1799 <tt>
1800 <bf>show/program</bf> Show the locations of all the included program modules
1801 </tt>
1802
1803 <P>
1804 Show the name and location where every program module was load from. This
1805 is useful for checking where you think you have loaded a .pm file from.
1806
1807 <sect1>shutdown (5)
1808
1809 <P>
1810 <tt>
1811 <bf>shutdown</bf> Shutdown the cluster
1812 </tt>
1813
1814 <P>
1815 Shutdown the cluster and disconnect all the users.  If you have Spider
1816 set to respawn in /etc/inittab it will of course restart.
1817
1818 <sect1>spoof (9)
1819
1820 <P>
1821 <tt>
1822 <bf>spoof &lt;callsign&gt; &lt;command&gt;</bf> Run commands as another user
1823 </tt>
1824
1825 <P>
1826 This is a very simple yet powerful command for the sysop.  It allows you to
1827 issue commands as if you were a different user.  This is very useful for the
1828 kind of things that users seem to always get wrong.. like home_node for
1829 example.
1830
1831 <sect1>stat/db (5)
1832
1833 <P>
1834 <tt>
1835 <bf>stat/db &lt;dbname&gt;</bf> Show the status of a database
1836 </tt>
1837
1838 <P>
1839 Show the internal status of a database descriptor.
1840
1841 Depending on your privilege level you will see more or less information. 
1842 This command is unlikely to be of much use to anyone other than a sysop.
1843
1844 <sect1>stat/channel (5)
1845
1846 <P>
1847 <tt>
1848 <bf>stat/channel &lt;callsign&gt;</bf> Show the status of a channel on the cluster
1849 </tt>
1850
1851 <P>
1852 Show the internal status of the channel object either for the channel that 
1853 you are on or else for the callsign that you asked for.
1854
1855 Only the fields that are defined (in perl term) will be displayed.
1856
1857 <sect1>stat/msg (5)
1858
1859 <P>
1860 <tt>
1861 <bf>stat/msg &lt;msgno&gt;</bf> Show the status of a message
1862 </tt>
1863
1864 <P>
1865 This command shows the internal status of a message and includes information
1866 such as to whom it has been forwarded, its size, origin etc etc.
1867
1868 <sect1>stat/user (5)
1869
1870 <P>
1871 <tt>
1872 <bf>stat/user &lt;callsign&gt;</bf> Show the full status of a user
1873 </tt>
1874
1875 <P>
1876 Shows the full contents of a user record including all the secret flags
1877 and stuff.
1878
1879 Only the fields that are defined (in perl term) will be displayed.
1880
1881
1882
1883 </article>