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 22:02:36 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>The first example is a simple telnet (TCP/IP) connect to port 7000 of WR3D (this will actually
  33           work if you have or make an arrangement to connect to WR3D)[oh, and substitute x1xxx for your real
  34           node callsign].</p>
  35
  36         <p>The colouration will be explained later on in this page, you don't have to try to emulate the colours!</p>
  37
  38         <pre>
  39     <span class=cmd>timeout 15</span>
  40     # this is a comment
  41     <span class=connect>connect telnet wr3d.dxcluster.net 7000</span>
  42     <span class=expect>'login'</span> <span class=send>'x1xxx'</span>
  43     <span class=cmd>client wr3d telnet</span>
  44         </pre>
  45
  46         <p>If you put the above script in a file called: <tt>/spider/connect/wr3d</tt> then you can leave out
  47           line: <span class=cmd>client wr3d telnet</span>.
  48         <p>For a connect that requires a login and execution of the programs
  49           from a normal shell, do:-</p>
  50
  51         <pre>
  52     <span class=cmd>timeout 15</span>
  53     <span class=connect>connect telnet dirkl.tobit.co.uk</span>
  54     <span class=expect>'login'</span> <span class=send>'gb7djk'</span>
  55     <span class=expect>'word'</span> <span class=send>'gb7djk'</span>
  56     <span class=expect>'\$'</span> <span class=send>'cd /spider/perl'</span>
  57     # set the line to prevent echoing, leaving this out will
  58     # confuse whole networks for hours!
  59     <span class=expect>'\$'</span> <span class=send>'stty -echo raw'</span>
  60     # tell GB7DJK that you are GB7DJK-1
  61     <span class=expect>'\$'</span> <span class=send>'/spider/src/client gb7djk-1 telnet'</span>
  62     # tell GB7DJK-1 that it is connected to GB7DJK
  63     # you can leave this out if you call this script 'gb7djk'
  64     <span class=cmd>client gb7djk telnet</span>
  65         </pre>
  66
  67         <p>a ax25 example (connecting from GB7DJK, to GB7DXM via my local BPQ node and one X1J intermediate node):-
  68
  69         <pre>
  70     <span class=cmd>timeout 60</span>
  71     <span class=cmd>abort (Busy|Sorry|Fail)</span>
  72     # don't forget to chmod 4775 netrom_call!
  73     <span class=connect>connect ax25 /usr/sbin/netrom_call bbs gb7djk-0 g1tlh-0</span>
  74     <span class=expect>'Connected'</span> <span class=send>'c np7'</span>
  75     <span class=expect>'*** Connect'</span> <span class=send>'c gb7dxm'</span>
  76     <span class=expect>'Connect'</span> <span class=send>''</span>
  77         </pre>
  78
  79     <p>The <tt>-0</tt> ssid is important if you want it to work reliably. Obviously if you are
  80     using a different ssid then you would use that. You can use the Netrom alias instead if it
  81         it is in the machines node table.</p>
  82
  83         <p>The line: "<tt><span class=expect>'Connected'</span> <span class=send>''</span></tt>" means: wait for
  84           the string <span class=expect>Connected</span> and when that is seen, then move onto the next line
  85           <b>without <span class=send>sending</span> anything</b>. The reason you do this (in this case) is to wait
  86         for the final "connect" string from the BPQ node that directly connects you to the
  87         cluster node itself.</p>
  88
  89     <p>An AGW Engine example would be very similar and look like this:-</p>
  90
  91         <pre>
  92     <span class=cmd>timeout 60</span>
  93     <span class=cmd>abort (Busy|Sorry|Fail)</span>
  94     <span class=connect>connect agw 2 g1tlh</span>
  95     <span class=expect>'*** Connect'</span> <span class=send>'c np7'</span>
  96     <span class=expect>'Connected'</span> <span class=send>'c gb7dxm'</span>
  97     <span class=expect>'Connect'</span> <span class=send>''</span>
  98         </pre>
  99
 100         <p>A connection is started manually by typing in <tt>connect &lt;scriptname&gt;</tt> on a sysop enabled
 101           <tt>client.pl</tt> session. For example:-</p>
 102
 103         <pre>
 104     G1TLH de GB7DJK 13-Dec-1998 2041Z > connect gb7djk-1
 105     connection to GB7DJK-1 started
 106     G1TLH de GB7DJK 13-Dec-1998 2043Z >
 107         </pre>
 108
 109         <p>Consider the following specific example, it is located in the file <tt>/spider/connect/gb7djk-1</tt> :-</p>
 110
 111     <pre>
 112     <span class=cmd>timeout 15</span>
 113     <span class=connect>connect telnet dirkl.tobit.co.uk</span>
 114     <span class=expect>'login'</span> <span class=send>'gb7djk'</span>
 115     <span class=expect>'ssword'</span> <span class=send>'gb7djk'</span>
 116     </pre>
 117
 118     <p>You can watch the progress of the connection (if you have <tt>connect</tt>
 119      debugging enabled [<tt>set/debug connect</tt>]) on the
 120           <tt>cluster.pl</tt> screen and you should see something like this:-</p>
 121
 122         <pre>
 123     &lt;- D G1TLH connect gb7djk-1
 124     -> D G1TLH connection to GB7DJK-1 started
 125     -> D G1TLH G1TLH de GB7DJK 13-Dec-1998 2046Z >
 126     <span class=cmd>timeout set to 15</span>
 127     <span class=connect>CONNECT sort: telnet command: dirkl.tobit.co.uk</span>
 128     CHAT "login" -> "gb7djk"
 129     received "
 130     Red Hat Linux release 5.1 (Manhattan)
 131     Kernel 2.0.35 on an i586
 132     "
 133     <span class=expect>received "login: "</span>
 134     <span class=send>sent "gb7djk"</span>
 135     CHAT "word" -> "gb7djk"
 136     received "gb7djk
 137
 138     "
 139     <span class=expect>received "Password: "</span>
 140     <span class=send>sent "gb7djk"</span>
 141     Connected to GB7DJK-1, starting normal protocol
 142     &lt;- O GB7DJK-1 telnet
 143     -> B GB7DJK-1 0
 144     GB7DJK-1 channel func  state 0 -> init
 145     &lt;- D GB7DJK-1
 146     &lt;- D GB7DJK-1 Last login: Sun Dec 13 17:59:56 from dirk1
 147     &lt;- D GB7DJK-1 PC38^GB7DJK-1^~
 148     &lt;- D GB7DJK-1 PC18^ 1 nodes, 0 local / 1 total users  Max users 0  Uptime 0 00:00^5447^~
 149     etc
 150         </pre>
 151
 152         <p>I have coloured the commands in an attempt to make it clear as
 153         to what goes on, where and why.  Lines that are <span
 154         class=cmd>coloured thus</span> are miscellaneous setup
 155         commands. Lines that are <span class=connect>this colour</span>
 156         are lines that make the initial <span
 157         class=connect>connection</span> to the first hop. The things that
 158         are <span class=expect>this colour</span> are the strings I am
 159         looking for (what I am <span class=expect>"expecting"</span>) and
 160         the things that are <span class=send>this colour</span> are the
 161         commands I am going to <span class=send>send</span> when I see the
 162         "expect" strings in the input.</p>
 163
 164         <p>The script starts by setting the timeout to 15 seconds, then starts
 165           the connection. It is <b>important</b> to note that, in the case of
 166           an ax25 connection (usually) this will be the callsign of the <i>first hop</i> along the
 167           route that you are going to take to the destination, so this will be typically the callsign
 168           of your local node.</p>
 169
 170     <p>You will notice that the script <span class=expect>waits</span>
 171     until it sees the left hand string of the pair and <b>only
 172     then</b> does it <span class=send>send</span> the string on the
 173     right hand side. This is called a <i>State Machine</i>.</p>
 174
 175         <p>A <i>state machine</i> "walks" through a conversation (in this
 176         case) looking for "<span class=expect>states</span>" (in this case
 177         particular strings) and then performs some "<span
 178         class=send>action</span>" (usually some kind of connect command
 179         for the type of system you are trying to navigate). When one
 180         "<span class=expect>state</span>" "fires"
 181         (detects the string are looking for), it <span class=send>sends the command</span>
 182         associated with that state and then moves onto the next "<span
 183         class=expect>state</span>", in our case: the next line.</p>
 184
 185         <p><b>PLEASE NOTE</b>: the colouration in the above example is for illustrative purposes
 186           only, the debug output is all one colour.</p>
 187
 188         <p>The connect scripts consist of lines which start with the
 189         following keywords or symbols:-</p>
 190
 191         <ul>
 192
 193                 <li><b>#</b> All lines starting with a <b>#</b> are
 194                 ignored, as are wholly blank lines.
 195         <br><br>
 196
 197                 <li><b><span class=cmd>timeout</span></b> followed by a number is the number of
 198                 seconds to wait for a command to complete. If there is no
 199                 <b><span class=cmd>timeout</span></b> specified in the script then the default is 60
 200                 seconds.
 201         <br><br>
 202
 203                 <li><b><span class=cmd>abort</span></b> is a regular expression containing one or
 204                 more strings to look for to abort a connection. This is a perl
 205                 regular expression and is executed ignoring case.
 206         <br><br>
 207
 208                 <li><b><span class=connect>connect</span></b> followed by <b>ax25</b>, <b>telnet</b> or <b>agw</b>
 209                 and some type dependent information.
 210
 211         <p>In the case of a
 212                 <b>telnet</b> connection, there can be up to two parameters,
 213                 the first is the ip address or hostname of the computer you
 214                 wish to connect to and the second is the port number you want
 215                 to use (this can be left out if it is a normal telnet
 216                 session).
 217
 218                 <p>In the case of an <b>ax25</b> session then this would
 219                 normally be a call to <tt>/usr/sbin/ax25_call</tt> or
 220                 <tt>/usr/sbin/netrom_call</tt> as in the example above. It is your
 221                 responsibility to get your node and other ax25 parameters to
 222                 work before going down this route!
 223
 224         <p>For <b>agw</b> connections you will need a port number (starting
 225         from 1) and the callsign of the first &quot;hop&quot; along the way.
 226         <br><br>
 227
 228                 <li><b>'</b> is the delimiting character for a word or phrase
 229                 of an <span class=expect>expect</span>/<span
 230                 class=send>send</span> line.  The words/phrases normally come
 231                 in pairs, but either can be empty. Each line reads input from
 232                 the connection until it sees the string (or perl regular
 233                 expression) that
 234                 is contained in the left hand string. If the left hand
 235                 string is empty then it doesn't read or wait for anything. The
 236                 comparison is done ignoring case.
 237
 238                 <p>When the left hand string has found what it is <span class=expect>expecting</span> (if
 239                 it is) then the right hand string is <span class=send>sent</span> to the connection.
 240
 241                 <p>If the right hand string is empty ('') then nothing is <span class=send>sent</span>, the
 242                   script simply moves onto the next line.</P>
 243
 244                 <p>This process is repeated for every line of <tt>chat</tt> script.
 245         <br><br>
 246
 247                 <li><b><span class=cmd>client</span></b> starts the connection, put the arguments
 248                 you would want here if you were starting the client program
 249                 manually. You only need this if the script has a different
 250                 name to the callsign you are trying to connect to (i.e. you
 251                 have a script called <tt>other</tt> which actually connects to
 252                 <tt>GB7DJK-1</tt> [instead of a script called
 253                 <tt>gb7djk-1</tt>]).
 254
 255         </ul>
 256
 257 <!-- Standard Footer!! -->
 258         <p>&nbsp;</p>
 259         <hr>
 260         <span class=copy>Copyright &copy; 1998 by Dirk Koopman G1TLH. All Rights Reserved</span><br>
 261         <span class=id>$Id$</span>
 262   </body>
 263 </html>