<title>The DXSpider Administration Manual v1.48</title>
<author>Ian Maude, G0VGS, (ianmaude@btinternet.com)</author>
-<date>Version 1.48 August 2001 revision 1.1</date>
+<date>Version 1.48 September 2001 revision 1.2</date>
<abstract>
A reference for SysOps of the DXSpider DXCluster program.
<P>
In fact DXSpider has had a simple system for some time which is called
-<it>isolation</it>. This is similar to what, in other systems such as
+<it>isolation</it>. This is similar to what in other systems such as
<bf>clx</bf>, is called <it>passive mode</it>. A more detailed explanation
of <it>isolation</it> is given further below. This system is still available
and, for simple networks, is probably all that you need.
<P>
-The new functionality introduced in version 1.48 is filtering the node
+The new functionality introduced in version 1.48 allows filtering the node
and user protocol frames on a "per interface" basis. We call this
<it>route filtering</it>. This is used <bf>instead of</bf>
<it>isolation</it>.
<p>
What this really means is that you can control more or less completely
-which PC protocol frames, to do with user and node management, pass to
-each of your partner nodes. You can also limit what comes into your
-node from your partners. You can even control the settings that your
-partner node has for the routing information that it sends to you
+which user and node management PC protocol frames pass to each of your
+partner nodes. You can also limit what comes into your node from your
+partners. It is even possible to control the settings that your partner
+node has for the routing information that it sends to you
(using the <it>rcmd</it> command).
<sect1>Route Filters
explained further on.
<p>
-The first thing that you must do is determine whether you need to do route filtering <bf>at all</bf>. If you are a "normal" node with two or three partners
-and you arranged in an "official" non-looping tree type network, then <bf>you do
-not need to do route filtering</bf> and you will feel a lot better for not
-getting involved. If you are successfully using <it>isolation</it> then you
-also probably don't need to use route filtering.
+The first thing that you must do is determine whether you need to use
+route filtering <bf>at all</bf>. If you are a "normal" node with two or
+three partners and you arranged in an "official" non-looping tree type
+network, then <bf>you do not need to do route filtering</bf> and you will
+feel a lot better for not getting involved. If you are successfully using
+<it>isolation</it> then you also probably don't need to use route filtering.
<p>
-You will only require this functionality if you are
-"well-connected". What that means is that you are connected to several
-different parts of (say) the EU cluster and, at the same time, also
-connected to two or three places in the US which, in turn are
-connected back to the EU. This is called a "loop" and if you are
-seriously looped then you need filtering.
+To put it simply, you should not mix Isolation and Route Filtering. It
+will work, of sorts, but you will not get the expected results. If you
+are using Isolation sucessfully at the moment, do not get involved in
+Route Filtering unless you have a good supply of aspirin! Once you have
+started down the road of Route Filtering, do not use Isolation either.
+Use one or the other, not both.
+
+<p>
+You will only require this functionality if you are "well-connected". What
+that means is that you are connected to several different parts of (say)
+the EU cluster and, at the same time, also connected to two or three places
+in the US which, in turn are connected back to the EU. This is called a
+"loop" and if you are seriously looped then you need filtering.
<P>
I should at this stage give a little bit of background on filters. All
</verb></tscreen>
Please be careful if you alter this setting, it will affect
-<bf><it>ALL</it></bf> your links!
+<bf><it>ALL</it></bf> your links! Remember, this is a <it>default</it>
+filter for node connections, not a <it>per link</it> default.
<p>
For the default routing filter then you have two real choices: either
is accepted.
<p>
-As I imagine it will take a little while to get one's head around all of this you
-can study the effect of any rules that you try by watching the debug output
-after having done:-
+As I imagine it will take a little while to get one's head around all of
+this you can study the effect of any rules that you try by watching the
+debug output after having done:-
<tscreen><verb>
set/debug filter
Here are some examples of route filters ...
<tscreen><verb>
-rej/route gb7djk call_dxcc 61,38 (everything except UK+EIRE nodes)
-rej/route all (equiv to [very] restricted mode)
+rej/route gb7djk call_dxcc 61,38 (send everything except UK+EIRE nodes)
+rej/route all (equiv to [very] restricted mode)
acc/route gb7djk call_dxcc 61,38 (send only UK+EIRE nodes)
acc/route gb7djk call gb7djk (equiv to SET/ISOLATE)
</verb></tscreen>
acc/route gb7baa input all
</verb></tscreen>
-or restricting it quite a lot, in fact making it very nearly like an <it>isolated</it> node, like this:-
+or restricting it quite a lot, in fact making it very nearly like an
+<it>isolated</it> node, like this:-
<tscreen><verb>
acc/route pi4ehv-8 call gb7djk
PC16s for my local users).
<p>
-It is possible to do <bf>much</bf> more complex rules, there are up to 10
-accept/reject pairs per callsign per filter. For more information see the
-next section.
+It is possible to write <bf>much</bf> more complex rules, there are up
+to 10 accept/reject pairs per callsign per filter. For more information
+see the next section.
<sect1>General filter rules
If you alter the file during runtime, the command <em>load/hops</em> will
bring your changes into effect.
+<sect1>Hop Control on Specific Nodes
+
+<p>You can set a callsign specific hop count for any of the standard filter
+options so:-
+
+<tscreen><verb>
+set/hops gb7djk spot 4
+set/hops node_default route 10
+set/hops gb7baa wcy 5
+</verb></tscreen>
+
+all work on their specific area of the protocol.
+
+<p>
+The <em>set/hops</em> command overrides any hops that you have set otherwise.
+
+<p>
+You can set what hops have been set using the <em>show/hops</em> command.
+
<sect1>Isolating networks
<P>
node and it will be routed across.
<P>
-The only limitation currently is that non-private messages cannot be passed down
-isolated links regardless of whether they are generated locally. This will change
-when the bulletin routing facility is added.
-
-<P>
-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 ....
-
-<tscreen><verb>
-$in = [
- [ 1, 0, 'd', 0, 3] # The last figure (3) is the hop count
-];
-</verb></tscreen>
+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 use
+an <em>acc/spot >call< all</em> filter to override the isolate.
<sect>Other filters
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.
-<sect1>Filtering DX callouts (Depricated)
-<P>
-<bf><it>From version 1.47, this method is replaced by the command set/baddx</it></bf>
+<sect1>Filtering words from text fields in Announce, Talk and DX spots
-<P>
-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 ....
+<p>
+From version 1.48 onwards the interface to this has changed. You can now
+use the commands <em>set/badword</em> to add words that you are not prepared
+to see on the cluster, <em>unset/badword</em> to allow that word again and
+<em>show/badword</em> to list the words that you have set.
-<tscreen><verb>
+<p>
+If you have a previous <em>/spider/data/badwords</em>, the first time you start
+the node, it will read and convert this file to the new commands. The old style
+file will then be removed.
-# the list of dx spot addresses that we don't store and don't pass on
+<sect1>Stopping (possibly bad) DX Spots from Nodes or Spotters
+<p>
+There are a number of commands that control whether a spot progresses
+any further by regarding it as "bad" in some way.
-package DXProt;
+<p>
+A DX Spot has a number of fields which can be checked to see whether they
+contain "bad" values, they are: the DX callsign itself, the Spotter and
+the Originating Node.
-@baddx = qw
-
- FROG
- SALE
- FORSALE
- WANTED
- P1RATE
- PIRATE
- TEST
- DXTEST
- NIL
- NOCALL
-);
-</verb></tscreen>
+<p>
+There are a set of commands which allow the sysop to control whether a
+spot continues:-
-<P>
-Again, this is simply a list of names we do not want to see in the spotted
-field of a DX callout.
+<tscreen><verb>
+set/baddx
+set/badspotter
+set/badnode
+</verb></tscreen>
+These work in the same as the <em>set/badword</em> command, you can add
+any words or callsigns or whatever to the appropriate database. For
+example, to stop a spot from a particular node you do:
-<sect1>Filtering words from text fields in Announce, Talk and DX spots
+<tscreen><verb>
+set/badnode gb7djk gb7dxc
+</verb></tscreen>
-<P>
-Create a file in /spider/data called <em>badwords</em>. The format is quite
-simple. Lines beginning with # are ignored so comments can be added. An
-example file is below ...
+a bad spotter:
<tscreen><verb>
-# Below is a list of words we do not wish to see on the cluster
-grunge grunged grunging
-splodge splodger splodging
-grince
-fluffle
+set/badspotter b0mb p1rat nocall
</verb></tscreen>
-Multiple words can be used on the same line as shown. Obviously these
-are just examples :-)
+and some bad dx:
-<P>
-You can reload the file from the cluster prompt as sysop with load/badwords.
+<tscreen><verb>
+set/baddx video wsjt
+</verb></tscreen>
+
+You can remove a word using the appropriate unset command
+(<em>unset/baddx, unset/badspotter, unset/badnode</em>) or list them
+using one of <em>show/baddx, show/badspotter</em> and
+<em>show/badnode</em>.
<sect>Mail
Make sure you only send mail to the clusters that want it by using the
Forward.pl file very carefully.
+<sect>Scripts
+
+<p>
+From 1.48 onwards it will become increasingly possible to control DXSpider's
+operation with scripts of various kinds.
+
+<p>
+In the first instance, in 1.48, the sysop can create, with their favorite
+text editor, files in the directory <em>/spider/scripts</em> which contain
+any legal command for a callsign or class of connection which will be executed
+at logon.
+
+<p>
+The filename is the callsign of the connection that you want the script to
+operate on, eg: <em>/spider/scripts/g1tlh</em>. The filenames are always in
+lower case on those architectures where this makes a difference.
+
+<p>
+In addition to the callsign specific scripts there are three others:-
+
+<tscreen><verb>
+startup
+user_default
+node_default
+</verb></tscreen>
+
+The <em>startup</em> script is executed immediately after all
+initialisation of the node is done, but before any connections are
+possible.
+
+<p>
+The <em>user_default</em> script is executed for every user that does
+<bf>NOT</bf> already have a specific script.
+
+<p>
+The <em>node_default</em> script is executed for every node that doesn't
+have a specific script.
+
+<p>
+There are a couple of examples in the <em>/spider/scripts</em> directory.
+
<sect>Databases
<P>
sources by using a few simple commands.
<P>
-THIS IS NOT FOR THE FAINT HEARTED!!! ONLY DO THIS IF YOU HAVE A TEST
-INSTALLATION OR ARE WILLING TO HAVE YOUR CLUSTER CRASH ON YOU!!!
-THIS MUST BE CONSIDERED AT LEAST BETA TESTING AND MAYBE EVEN ALPHA!!
-YOU HAVE BEEN WARNED!!!
-
-<P>
-DID I MENTION..... ONLY DO THIS IF YOU ARE WILLING TO ACCEPT THE
-CONSEQUENCES!!!
+Please be aware that if you update your system using CVS, it is possible that
+you could be running code that is very beta and not fully tested. There is
+a possibility that it could be unstable.
<P>
I am of course assuming that you have a machine with both DXSpider and
do this if you change this file whilst the cluster is running in order for the
changes to take effect.
-
-<sect1>load/baddx (9)
-
-<P>
-<tt>
-<bf>load/baddx</bf> Reload the bad DX table
-</tt>
-
-<P>
-Reload the /spider/data/baddx.pl file if you have changed it manually whilst
-the cluster is running. This table contains the DX Calls that, if spotted,
-will not be passed on. FR0G and TEST are classic examples.
-
<sect1>load/badmsg (9)
<P>
expressions which are searched for in the fields targetted of each message.
If any of them match then that message is immediately deleted on receipt.
-<sect1>load/badwords (9)
-
-<P>
-<tt>
-<bf>load/badwords</bf> Reload the badwords file
-</tt>
-
-<P>
-Reload the /spider/data/badwords file if you have changed it manually whilst
-the cluster is running. This file contains a list of words which, if found
-on certain text portions of PC protocol, will cause those protocol frames
-to be rejected. It will all put out a message if any of these words are
-used on the announce, dx and talk commands. The words can be one or
-more on a line, lines starting with '#' are ignored.
-
<sect1>load/bands (9)
<P>