html/connect.html

   1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
   2 <html>
   3   <head>
   4     <title>Connecting to other Clusters</title>
   5         <meta name="Keywords" content="DX Cluster, DXSpider, Spider, Packet Cluster, DXCluster, Pavillion Software, AK1A, AX25, AX.25, WWV, Packet Radio, Amateur Radio, Propagation, DX, DXing, G1TLH, GB7TLH, Dirk Koopman, Mailing list, Linux, RedHat, PERL">
   6         <meta name="Description" content="Software and systems for realtime digital communications between amateur radio stations for the provision of information on propagation conditions and stations operating">
   7         <meta name="Author" content="Dirk Koopman G1TLH">
   8     <link rel=stylesheet href="style.css" type="text/css" title="default stylesheet">
   9   </head>
  10
  11   <body TEXT="#000000" LINK="#0000ff" VLINK="#800080" BGCOLOR="#FFFFFF">
  12         <FONT COLOR="#606060">
  13           <hr>
  14           <h2>Connecting to other Clusters</h2>
  15           <hr>
  16         </font>
  17
  18
  19         <address><a href="mailto:djk@tobit.co.uk">Dirk Koopman G1TLH</a></address>
  20         <p>
  21           <!-- Created: Sun Dec 13 20:25:14 GMT 1998 -->
  22           <!-- hhmts start -->
  23 Last modified: Sun Sep  2 20:31:56 BST 2001
  24 <!-- hhmts end -->
  25         <p>At the moment, anybody can connect inwards at any time from outside, either by ax25 or by
  26           telnet (assuming you have followed the instructions in <a href="install.html">installation</a>
  27           instructions. However, in order to connect outwards, you will need to create <em>connect</em> scripts.
  28
  29         <p><em>Connect</em> scripts live in the <tt>/spider/connect</tt> directory and are simple ascii scripts
  30           that are written using a normal editor. There are a couple of examples in the issue directory.
  31
  32         <p>Here are a few of basic types, first a telnet connection where the
  33            client is set up in the passwd file thus:-
  34         <pre>
  35     gb7djk:x:1372:1291::/home/gb7djk:/usr/bin/perl /spider/perl/client.pl gb7djk telnet
  36         </pre>
  37         and the connect script would be:-
  38         <pre>
  39     timeout 15
  40     # this is a comment
  41     connect telnet dirkl.tobit.co.uk
  42     'login' 'gb7djk'
  43     'word' 'gb7djk'
  44     client gb7djk telnet
  45         </pre>
  46         <p>For a connect that requires a login and execution of the programs
  47           from a normal shell, do:-
  48
  49         <pre>
  50     timeout 15
  51     connect telnet dirkl.tobit.co.uk
  52     'login' 'gb7djk'
  53     'word' 'gb7djk'
  54     '\$' 'cd /spider/perl'
  55     # set the line to prevent echoing, leaving this out will
  56     # confuse whole networks for hours!
  57     '\$' 'stty -echo raw'
  58     # tell GB7DJK that you are GB7DJK-1
  59     '\$' '/spider/src/client gb7djk-1 telnet'
  60     # tell GB7DJK-1 that it is connected to GB7DJK
  61     # you can leave this out if you call this script 'gb7djk'
  62     client gb7djk telnet
  63         </pre>
  64
  65         <p>a ax25 example:-
  66         <pre>
  67     timeout 60
  68     abort (Busy|Sorry|Fail)
  69     # don't forget to chmod 4775 netrom_call!
  70     connect ax25 /usr/sbin/netrom_call bbs gb7djk-0 g1tlh-0
  71     'Connected' ''
  72     'Connected' 'c np7'
  73     'linked to' 'c gb7dxm'
  74     'Connect' ''
  75         </pre>
  76
  77     The <tt>-0</tt> ssid is important if you want it to work reliably. Obviously if you are
  78     using a different ssid then you would use that.
  79
  80     <p>A AGW Engine example would be very similar and look like this:-
  81         <pre>
  82     timeout 60
  83     abort (Busy|Sorry|Fail)
  84     connect agw 2 g1tlh
  85     '*** Connected' ''
  86     '*** Connect' 'c np7'
  87     'linked to' 'c gb7dxm'
  88     'Connect' ''
  89         </pre>
  90
  91         <p>A connection is started manually by typing in <tt>connect &lt;scriptname&gt;</tt> on a sysop enabled
  92           <tt>client.pl</tt> session. For example:-
  93         <pre>
  94     G1TLH de GB7DJK 13-Dec-1998 2041Z > connect gb7djk-1
  95     connection to GB7DJK-1 started
  96     G1TLH de GB7DJK 13-Dec-1998 2043Z >
  97         </pre>
  98
  99         <p>Consider the following specific example, it is located in the file <tt>/spider/connect/gb7djk-1</tt> :-</p>
 100
 101     <pre>
 102     <span class=cmd>timeout 15</span>
 103     <span class=cmd>connect telnet dirkl.tobit.co.uk</span>
 104     <span class=expect>'login'</span> <span class=send>'gb7djk'</span>
 105     <span class=expect>'ssword'</span> <span class=send>'gb7djk'</span>
 106     </pre>
 107
 108     <p>You can watch the progress of the connection (if you have <tt>connect</tt>
 109      debugging enabled [<tt>set/debug connect</tt>]) on the
 110           <tt>cluster.pl</tt> screen and you should see something like this:-
 111         <pre>
 112     &lt;- D G1TLH connect gb7djk-1
 113     -> D G1TLH connection to GB7DJK-1 started
 114     -> D G1TLH G1TLH de GB7DJK 13-Dec-1998 2046Z >
 115     <span class=cmd>timeout set to 15</span>
 116     <span class=cmd>CONNECT sort: telnet command: dirkl.tobit.co.uk</span>
 117     CHAT "login" -> "gb7djk"
 118     received "
 119     Red Hat Linux release 5.1 (Manhattan)
 120     Kernel 2.0.35 on an i586
 121     "
 122     <span class=expect>received "login: "</span>
 123     <span class=send>sent "gb7djk"</span>
 124     CHAT "word" -> "gb7djk"
 125     received "gb7djk
 126
 127     "
 128     <span class=expect>received "Password: "</span>
 129     <span class=send>sent "gb7djk"</span>
 130     Connected to GB7DJK-1, starting normal protocol
 131     &lt;- O GB7DJK-1 telnet
 132     -> B GB7DJK-1 0
 133     GB7DJK-1 channel func  state 0 -> init
 134     &lt;- D GB7DJK-1
 135     &lt;- D GB7DJK-1 Last login: Sun Dec 13 17:59:56 from dirk1
 136     &lt;- D GB7DJK-1 PC38^GB7DJK-1^~
 137     &lt;- D GB7DJK-1 PC18^ 1 nodes, 0 local / 1 total users  Max users 0  Uptime 0 00:00^5447^~
 138     etc
 139         </pre>
 140
 141         <p>I have coloured the commands in an attempt to make it clear as to what goes on, where and why.
 142           <span class=cmd>These coloured lines are miscellaneous commands</span>, the <span class=expect>things
 143           that are this colour are the strings I am looking for (what I am "expecting")</span>
 144           and the <span class=send>things that are this colour
 145           are the commands I am going to make when I see the "expect" strings in the input</span>.</p>
 146
 147         <p>The script starts by setting the timeout to 15 seconds, then starts
 148           the connection. It is <b>important</b> to note that, in the case of
 149           an ax25 connection (usually) this will be the callsign of the <i>first hop</i> along the
 150           route that you are going to take to the destination, so this will be typically the callsign
 151           of your local node.</p>
 152
 153     <p>You will notice that the script waits until it sees the left hand string
 154           of the pair and <b>only then</b> does it send the,
 155           string on the right
 156           hand side. This is called a <i>State Machine</i>.</p>
 157
 158         <p>A <i>state machine</i> "walks" through a conversation (in this case) looking
 159           for "states" (in this case particular strings) and then performs some
 160           "action" (usually some kind of connect command for the type of system
 161           you are trying to navigate). When one "state" "fires" (detects the string
 162           are looking for), it sends the command associated with that state and then
 163           moves onto the next "state", in our case: the next line.</p>
 164
 165         <p><b>PLEASE NOTE</b>: the colouration in the above example is for illustrative purposes
 166           only, the debug output is all one colour.</p>
 167
 168         <p>The connect scripts consist of lines which start with the
 169         following keywords or symbols:-
 170
 171         <ul>
 172
 173                 <li><b>#</b> All lines starting with a <b>#</b> are
 174                 ignored, as are wholly blank lines.
 175         <br><br>
 176
 177                 <li><b>timeout</b> followed by a number is the number of
 178                 seconds to wait for a command to complete. If there is no
 179                 <b>timeout</b> specified in the script then the default is 60
 180                 seconds.
 181         <br><br>
 182
 183                 <li><b>abort</b> is a regular expression containing one or
 184                 more strings to look for to abort a connection. This is a perl
 185                 regular expression and is executed ignoring case.
 186         <br><br>
 187
 188                 <li><b>connect</b> followed by <b>ax25</b>, <b>telnet</b> or <b>agw</b>
 189                 and some type dependent information.
 190
 191         <p>In the case of a
 192                 <b>telnet</b> connection, there can be up to two parameters,
 193                 the first is the ip address or hostname of the computer you
 194                 wish to connect to and the second is the port number you want
 195                 to use (this can be left out if it is a normal telnet
 196                 session).
 197
 198                 <p>In the case of an <b>ax25</b> session then this would
 199                 normally be a call to <tt>/usr/sbin/ax25_call</tt> or
 200                 <tt>/usr/sbin/netrom_call</tt> as in the example above. It is your
 201                 responsibility to get your node and other ax25 parameters to
 202                 work before going down this route!
 203
 204         <p>For <b>agw</b> connections you will need a port number (starting
 205         from 1) and the callsign of the first &quot;hop&quot; along the way.
 206         <br><br>
 207
 208                 <li><b>'</b> is the delimiting character for a word or
 209                 phrase of an expect/send line in a <tt>chat</tt> type
 210                 script. The words/phrases normally come in pairs, either can
 211                 be empty. Each line reads input from the connection until it
 212                 sees the string (or perl regular expression) contained in the
 213                 left hand string. If the left hand string is empty then it
 214                 doesn't read or wait for anything. The comparison is done
 215                 ignoring case.
 216
 217                 <p>When the left hand string has found what it is looking (if
 218                 it is) then the right hand string is sent to the connection.
 219
 220                 <p>This process is repeated for every line of <tt>chat</tt> script.
 221         <br><br>
 222
 223                 <li><b>client</b> starts the connection, put the arguments
 224                 you would want here if you were starting the client program
 225                 manually. You only need this if the script has a different
 226                 name to the callsign you are trying to connect to (i.e. you
 227                 have a script called <tt>other</tt> which actually connects to
 228                 <tt>GB7DJK-1</tt> [instead of a script called
 229                 <tt>gb7djk-1</tt>]).
 230
 231         </ul>
 232
 233 <!-- Standard Footer!! -->
 234         <p>&nbsp;</p>
 235         <p>
 236           <FONT COLOR="#606060"><hr></font>
 237         <font color="#FF0000" size=-2>
 238           Copyright &copy; 1998 by Dirk Koopman G1TLH. All Rights Reserved<br>
 239         </font>
 240         <font color="#000000" size=-2>$Id$</font>
 241   </body>
 242 </html>