Added information on registration, login scripts and passwords to the

[spider.git] / sgml / adminmanual.sgml

diff --git a/sgml/adminmanual.sgml b/sgml/adminmanual.sgml
index d6fb29940ca80701b12555b89ae1fed1aa24cd66..967a4cb36fc83595a6efce35fd6d3fb283a4a793 100644 (file)
--- a/sgml/adminmanual.sgml
+++ b/sgml/adminmanual.sgml
@@ -6,7 +6,7 @@
 
 <title>The DXSpider Administration Manual v1.48</title> 
 <author>Ian Maude, G0VGS, (ianmaude@btinternet.com)</author>
 
 <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.49 November 2001 revision 1.0</date>

 
 <abstract>
 A reference for SysOps of the DXSpider DXCluster program.
 
 <abstract>
 A reference for SysOps of the DXSpider DXCluster program.


@@ -37,23 +37,23 @@ of protection for these nodes.
 
 <P>
 In fact DXSpider has had a simple system for some time which is called
 
 <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>
 <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
 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
 (using the <it>rcmd</it> command).
 
 <sect1>Route Filters


@@ -66,19 +66,27 @@ However using a default filter is an appropriate thing to do. How, is
 explained further on.
 
 <p>
 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>
 
 <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
 
 <P>
 I should at this stage give a little bit of background on filters.  All


@@ -125,7 +133,8 @@ channel_zone &lt;numbers&gt;
 </verb></tscreen>
 
 Please be careful if you alter this setting, it will affect 
 </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
 
 <p>
 For the default routing filter then you have two real choices: either


@@ -164,9 +173,9 @@ by implication, any other node information (not from the UK and Eire)
 is accepted.
 
 <p>
 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
 
 <tscreen><verb>
 set/debug filter


@@ -196,8 +205,8 @@ accept/route &lt;node_call&gt; &lt;filter_option&gt;
 Here are some examples of route filters ...
 
 <tscreen><verb>
 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 gb7djk call_dxcc 61,38 (send only UK+EIRE nodes)
 acc/route gb7djk call gb7djk     (equiv to SET/ISOLATE)
 </verb></tscreen>


@@ -210,7 +219,8 @@ acc/route gb7baa all
 acc/route gb7baa input all
 </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
 
 <tscreen><verb>
 acc/route pi4ehv-8 call gb7djk


@@ -222,9 +232,9 @@ but only sends him my local configuration (just a PC19 for GB7DJK and
 PC16s for my local users).
 
 <p>
 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
 
 
 <sect1>General filter rules


@@ -553,8 +563,7 @@ 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
 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 &gt;call&lt; all</em filter in the
-to override the isolate. 
+an <em>acc/spot &gt;call&lt; all</em> filter to override the isolate. 

 
 <sect>Other filters
 
 
 <sect>Other filters
 


@@ -630,7 +639,7 @@ There are a number of commands that control whether a spot progresses
 any further by regarding it as "bad" in some way.
 
 <p>
 any further by regarding it as "bad" in some way.
 
 <p>

-A DX Spot has a number of fields which can checked to see whether they
+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.
 
 contain "bad" values, they are: the DX callsign itself, the Spotter and
 the Originating Node.
 


@@ -875,7 +884,7 @@ any legal command for a callsign or class of connection which will be executed
 at logon.
 
 <p> 
 at logon.
 
 <p> 

-The filename are the callsign of the connection that you want the script to 
+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.
 
 operate on, eg: <em>/spider/scripts/g1tlh</em>. The filenames are always in 
 lower case on those architectures where this makes a difference.
 


@@ -1032,6 +1041,13 @@ 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.
 
 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.
 

+<sect1>MOTD_NOR
+
+<P>
+This message of the day file lives in the same directory as the standard
+motd file but is only sent to non-registered users.  Once registered they
+will receive the same message as any other user.
+

 <sect1>Downtime message
 
 <P>
 <sect1>Downtime message
 
 <P>


@@ -1340,6 +1356,130 @@ ID and password.  You also at this point need to set $allow=1 to complete
 the setup.  Many thanks to Fred Lloyd, the proprieter of
 <htmlurl url="http://www.qrz.com" name="qrz.com"> for allowing this access.
 
 the setup.  Many thanks to Fred Lloyd, the proprieter of
 <htmlurl url="http://www.qrz.com" name="qrz.com"> for allowing this access.
 

+<sect1>Scripts
+
+<P>
+The directory /spider/scripts is used for several things.  Firstly it
+contains a file called startup that can be used to call in any changes
+to the cluster from the default settings on startup.  Examples of this
+include how many spots it is possible to get with the sh/dx command, 
+whether you want registration/passwords to be permanently on etc.  An
+example file is shown below and is included in the distribution as
+startup.issue.
+
+<tscreen><verb>
+#
+# startup script example
+#
+# set maximum no of spots allowed to 100
+# set/var $Spot::maxspots = 1
+#
+# Set registration on
+# set/var $main::reqreg = 1
+#
+# Set passwords on
+# set/var $main::passwdreq = 1
+#
+</verb></tscreen>
+
+Secondly, it is used to store the login scripts for users.  Currently
+this can only be done by the sysop but it is envisaged that eventually
+users will be able to set their own.  An example is included in the
+distibution but here is a further example.
+
+<tscreen><verb>
+#
+# G0FYD
+#
+blank +
+sh/wwv 3
+blank +
+sh/dx 
+blank +
+t g0jhc You abt?
+blank +
+</verb></tscreen>
+
+The lines in between commands can simply insert a blank line or a character
+such as a + sign to make the output easier to read.
+
+<sect>Security
+
+<P>
+From version 1.49 DXSpider has some additional security features.  These
+are not by any means meant to be exhaustive, however they do afford some
+security against piracy.  These two new features can be used independently 
+of each other or in concert to tighten the security.
+
+<sect1>Registration
+
+<P>
+The basic principle of registration is simple.  If a user is not registered
+by the sysop, then they have read-only access to the cluster.  The only
+thing they can actually send is a talk or a message to the sysop.  In
+order for them to be able to spot, send announces or talks etc the sysop
+must register them with the <em>set/register</em> command, like this ...
+
+<tscreen><verb>
+set/register g0vgs
+</verb></tscreen>
+
+The user g0vgs can now fully use the cluster.  In order to enable 
+registration, you can issue the command ...
+
+<tscreen><verb>
+set/var $main::reqreg = 1
+</verb></tscreen>
+
+Any users that are not registered will now see the motd_nor file rather
+than the motd file as discussed in the Information, files and useful 
+programs section.
+
+<P>
+Entering this line at the prompt will only last for the time the cluster
+is running of course and would not be present on a restart.  To make the
+change permanent, add the above line to /spider/scripts/startup.  To
+read more on the startup file, see the section on Information, files 
+and useful programs.
+
+<P>
+To unregister a user use <em>unset/register</em> and to show the list
+of registered users, use the command <em>show/register</em>.
+
+<sect1>Passwords
+
+<P>
+At the moment, passwords only affect users who login to a DXSpider
+cluster node via telnet.  If a user requires a password, they can
+either set it themselves or have the sysop enter it for them by using
+the <em>set/password</em> command.  Any users who already have passwords, 
+such as remote sysops, will be asked for their passwords automatically 
+by the cluster.  Using passwords in this way means that the user has a
+choice on whether to have a password or not.  To force the use of
+passwords at login, issue the command ...
+
+<tscreen><verb>
+set/var $main::passwdreq = 1
+</verb></tscreen>
+
+at the cluster prompt.  This can also be added to the /spider/scripts/startup
+file as above to make the change permanent.
+
+<P>
+Of course, if you do this you will have to assign a password for each of 
+your users.  If you were asking them to register, it is anticipated that
+you would ask them to send you a message both to ask to be registered and
+to give you the password they wish to use.
+
+<P>
+Should a user forget their password, it can be reset by the sysop by
+first removing the existing password and then setting a new one like so ...
+
+<tscreen><verb>
+unset/password g0vgs
+set/password g0vgs new_password
+</verb></tscreen>
+

 <sect>CVS
 
 <P>
 <sect>CVS
 
 <P>


@@ -1349,14 +1489,9 @@ that it is possible to update your DXSpider installation to the latest
 sources by using a few simple commands.
 
 <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
 
 <P>
 I am of course assuming that you have a machine with both DXSpider and