html/install.html

   1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
   2 <HTML>
   3   <HEAD>
   4         <TITLE>DX Spider Installation</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
  10   </HEAD>
  11
  12   <body TEXT="#000000" LINK="#0000ff" VLINK="#800080" BGCOLOR="#FFFFFF">
  13         <FONT COLOR="#606060" face="Verdana,Helvetica,Swiss,Arial">
  14           <hr>
  15           <h2>Installing DX Spider (on Redhat 5.1)</h2>
  16           <hr>
  17         </font>
  18
  19         <address><A HREF="mailto:ip@g8sjp.demon.co.uk">Iain Phillips G0RDI</A></address>
  20 <!-- Created: Wed Dec  2 16:40:25 GMT 1998 -->
  21 <!-- hhmts start -->
  22 Last modified: Sun Aug  6 10:00:05 BST 2000
  23 <!-- hhmts end -->
  24         <P>This HOWTO describes the installation for DX Spider v1.30 on a "vanilla"
  25           <A href="http://www.redhat.com">RedHat</A> 5.1 platform,
  26           and assumes that you have started with a clean disk, with nothing other than the standard
  27           Red Hat 5.1 distribution. I always select 'everything', and that seems to ensure that
  28           nothing is missed out :-) [ more normal people may like to try with less <em>Ed</em> ].
  29
  30         <p><b><i>WARNING</i></b> The perl on the vanilla RedHat 5.2
  31         (perl-5.004m4-1.i386.rpm) is <em>BROKEN</em>, please use the one
  32         in the <a href="../download/index.html#perl">Download</a> section.
  33
  34         <p>The crucial ingredient for all of this is <a href="http://www.perl.org">Perl 5.004</a>. Now I know
  35           Perl 5.005 is out and this will almost certainly work with it, but
  36           <A Href="http://www.redhat.com">RedHat</A> 5.1 comes with 5.004.
  37           <em>Be Warned</em> earlier versions of <A Href="http://www.redhat.com">RedHat</A>
  38           <b>do not</b> come with 5.004 as standard, you need to
  39           <a href="ftp://upgrade.redhat.com">upgrade</a>
  40
  41         <P>In addition to the standard Red Hat distribution you will require the following <A HREF="http://www.cpan.org/CPAN.html">CPAN</A> modules:
  42         <p>
  43         <dir>
  44                 <a href="http://www.cpan.org/modules/by-module/MD5/MD5-1.7.tar.gz">MD5-1.7.tar.gz</a><BR>
  45                 <a href="http://www.cpan.org/modules/by-module/Data/Data-Dumper-2.10.tar.gz">Data-Dumper-2.10.tar.gz</a><BR>
  46                 <a href="http://www.cpan.org/modules/by-module/Date/TimeDate-1.08.tar.gz">TimeDate-1.08.tar.gz</a><BR>
  47                 <a href="http://www.cpan.org/modules/by-module/IO/IO-1.20.tar.gz">IO-1.20.tar.tgz</a><BR>
  48                 <a href="http://www.cpan.org/modules/by-module/Net/Net-Telnet-3.02.tar.gz">Net-Telnet-3.02.tar.gz</a><BR>
  49                 <a href="http://www.cpan.org/modules/by-module/Curses/Curses-1.05.tar.gz">Curses-1.05.tar.gz</a><BR>
  50         <a href="http://www.cpan.org/modules/by-module/Time/Time-HiRes-01.20.tar.gz">Time::Hires</a>
  51         </DIR>
  52
  53         <p>The modules above are the current versions found at <a href="http://www.cpan.org">www.cpan.org</a> in the appropriate directories -
  54         you can click on the links (above) to download them - particularly useful if you use the Lynx text HTML browser from your Linux box.
  55         You may wish to check for more recent versions of these modules and use the newer ones if they are available.</p>
  56
  57         <br>
  58
  59         <P>You'll also need the AX25 utility package. There is much debate about what is "best", what is "better". What works for 5.1 is this: -
  60         <p>
  61         <DIR>
  62                 ax25-utils-2.1.42a-1.i386.rpm
  63         </DIR>
  64
  65         <P>This can be found at (among other places) <A HREF="ftp://contrib.redhat.com/libc6">ftp://contrib.redhat.com</A>. Note that no attempt is made within this document to describe the steps necessary to install and commission the AX25 kernel package. It remains the responsibility of the reader to have sufficient knowledge and expertise to make this part of the system operation (and to be satisfied that it <B><I>is </B></I>operational) before attempting to install DX Spider. Read the AX25-HOWTO and ask around if you
  66  still have trouble after that.
  67
  68         <P>The last "must have" is the DX Spider distribution itself, and this is available via: -
  69
  70         <p>
  71         <DIR>
  72                 <A HREF="../download/index.html">The DX Spider Software</A>
  73         </DIR>
  74
  75         <p>We can now begin:-
  76         <P>
  77         <OL>
  78
  79           <p><LI>Copy the CPAN modules listed above to a convenient place on your computer. For no good reason, I put mine in /usr/local/packages, and the instructions which follow will assume that that's where yours are, too.
  80                 <P>Log in as 'root', and make sure you're at '/root' before you continue. Here are exactly the commands you must issue next: -
  81                 <PRE>
  82 # tar xvfz /usr/local/packages/MD5-1.7.tar.gz
  83 # cd MD5-1.7
  84 # perl Makefile.PL
  85 # make test
  86 # make install
  87 # cd ..
  88 #
  89 # tar xvfz /usr/local/packages/Data-Dumper-2.10.tar.gz
  90 # cd Data-Dumper-2.10
  91 # perl Makefile.PL
  92 # make test
  93 # make install
  94 # cd ..
  95 #
  96 # tar xvfz /usr/local/packages/TimeDate-1.08.tar.gz
  97 # cd TimeDate-1.08
  98 # perl Makefile.PL
  99 # make test
 100 # make install
 101 # cd ..
 102 #
 103 # tar xvfz /usr/local/packages/IO-1.20.tar.gz
 104 # cd IO-1.20
 105 # perl Makefile.PL
 106 # make test
 107 # make install UNINST=1
 108 # cd ..
 109 #
 110 # tar xvfz /usr/local/packages/Net-Telnet-3.02.tar.gz
 111 # cd Net-Telnet-3.02
 112 # perl Makefile.PL
 113 # make test
 114 # make install
 115 # cd ..
 116 #
 117 # tar xvfz /usr/local/packages/Curses-1.05.tar.gz
 118 # cd Curses-1.05
 119 # perl Makefile.PL
 120 # make test
 121 # make install
 122 # cd ..
 123 #
 124 # tar xvfz /usr/local/packages/Time-HiRes-01.20.tar.gz
 125 # cd Time-HiRes-01.20
 126 # perl Makefile.PL
 127 # make test
 128 # make install
 129 # cd ..
 130 #
 131                 </pre>
 132                 <P>Do not fall into the trap of thinking they're all the same, just because they nearly are! Pay particular attention to the instructions of IO, above.
 133
 134                 <p><LI>Create a user to run the cluster under. <B><I><U>UNDER NO CIRCUMSTANCES USE ROOT
 135                 </B></I></U><P>Again: <B><I><U>DO NOT USE</B></I></U> root.
 136                 <P>In the instructions which follow, it is assumed that this user is called 'sysop'. You may call it anything you wish. Depending upon your security requirements, you may choose to use an existing user. This will be your choice, not ours!
 137                 <P># adduser -m sysop
 138                 <P>Now set a password for the user:-
 139                 <PRE>
 140 #
 141 # passwd sysop
 142 # New UNIX password:
 143 # Retype new UNIX password:
 144 passwd: all authentication tokens updated successfully
 145                 </PRE>
 146                 <P># Do not fall into the trap of thinking they're all the same, just because they nearly are! Pay particular attention to the instructions of IO, above.
 147
 148                 <p><LI>Now unpack the DX Spider distribution, set symbolic links and group permissions like this (assumes that the version we're interested in is 1.9. The distribution tar file may be named slightly differently in your case: -
 149                 <PRE>
 150 # cd ~sysop
 151 # tar xvfz spider-1.9.tar.gz
 152 # ln -s ~sysop/spider /spider
 153 # groupadd -g 251 spider       (or another number)
 154 # vi /etc/group                (or your favorite editor)
 155                 </PRE>
 156                 <P>add 'sysop', your own callsign (in my case 'g0rdi' - which will be used as an alias) and 'root' to the group spider. The result should look something like:-
 157                 <PRE>
 158 spider:x:251:sysop,g0rdi,root
 159                 </PRE>
 160
 161                 <p><LI>Next step is to set permissions on the 'spider' directory tree and files:-
 162                 <PRE>
 163 # chown -R sysop.spider spider
 164 # find . -type d -exec chmod 2775 {} \;
 165 # find . -type f -exec chmod 775 {} \;
 166                 </PRE>
 167                 <P>This last step allows various users of group spider to have write access to all the directories. Not really needed for now but will be useful when web interfaces start to appear.
 168
 169                 <p><LI>In later releases there is a client program written in C. You
 170                 must <tt>make</tt> this program before you can use it (and you must
 171                 remember to to remake with every new release).
 172
 173                 <p>To do this you should:-
 174                 <PRE>
 175 # cd /spider/src
 176 # make
 177         </PRE>
 178
 179                 <p>You can continue to use the perl client (<tt>/spider/perl/client.pl</tt>, but
 180                 support of this will gradually whither away.
 181
 182                 <p><LI><a name="connect"></a>If you want to be able to allow people or clusters
 183                 to login via IP then you will need to set up logins for them.
 184
 185                 <p><pre>
 186 # useradd -m gb7djk
 187 # passwd gb7djk
 188 New UNIX password:
 189 Retype new UNIX password:
 190 passwd: all authentication tokens updated successfully
 191                 </pre>
 192
 193                 <p>You can then either alter the default .bashrc so that it
 194                 contains just one line (assuming you use the default bash
 195                 shell).
 196
 197                 <p><PRE>
 198 exec /spider/perl/client.pl &lt;callsign&gt; telnet
 199                 </PRE>
 200
 201                 <p>Alternatively you can alter the <tt>/etc/passwd</tt> thus:-
 202
 203                 <pre>
 204 fbb:x:505:505::/home/fbb:/bin/bash
 205 gb7djk:x:506:506::/home/gb7djk:/usr/bin/perl /spider/perl/client.pl gb7djk telnet
 206                 </pre>
 207
 208                 Don't forget to give them a real password. The <tt>telnet</tt> argument
 209                 does two things, it sets the EOL convention to \n rather than
 210                 AX25's \r and it automatically reduces the privilege of the
 211                 &lt;callsign&gt; to a 'safe[r]' level.). If the user or other cluster
 212                 program requires AX25 conventions to operate then you can use
 213                 <tt>ax25</tt> instead.
 214
 215                 <p>Another thing you can do is to get <tt>inetd</tt> to listen
 216                 on a specific port and then start the client up directly. To
 217                   do this, create an entry in <tt>/etc/services</tt> with a
 218                   port number > 1000 that isn't used elsewhere eg:-
 219
 220                 <p><pre>
 221 gb7djk     8001/tcp
 222 gb7tlh     8002/tcp
 223         </pre>
 224
 225                 Then create some lines in <tt>/etc/inetd.conf</tt> that look
 226                 like this:-
 227
 228                 <p><pre>
 229 gb7djk  stream tcp   nowait   sysop /usr/sbin/tcpd /spider/src/client gb7djk telnet
 230 gb7tlh  stream tcp   nowait   sysop /usr/sbin/tcpd /spider/src/client gb7tlh telnet
 231                 </pre>
 232
 233                 Please <b>DON'T</b> run the client as <tt>root</tt> you will only
 234                 come to regret it later when the next person finds a security hole
 235                 in DX Spider (there are bound to be some although I have tried to
 236                 avoid the obvious ones I could think of).
 237
 238                 <p>The only reason I would use this mechanism is for Internet connections
 239                   to other or from other clusters. Don't use this for normal users.
 240
 241                 <p>In the example I have used <tt>tcpd</tt> as the access control
 242                   mechanism to the port. Don't (I can't be bothered to emphasize
 243                   it any more) run a system like this without one, you are asking
 244                   for trouble. In fact I use the <a href="http://www.tis.com">TIS
 245                   Firewall Toolkit</a> myself, you may find this more intuitive
 246                   to use. The point is that <tt>gb7djk</tt> would only be coming
 247                   from one IP address, if it coming from another, it is an imposter!
 248
 249                 <p><b>You are responsible for arranging and looking after your
 250                         security - not me.</b>
 251
 252                 <p><LI>As mentioned earlier, for AX25 connections <B><I>you</B></I> are expected to have the AX25 utilities installed, setup, tested and working. See the AX25-HOWTO for more info on this - it really is beyond the scope of this document DX Spider uses ax25d for incoming connections. You need to have entries like this:-
 253                 <PRE>
 254 [ether]
 255 NOCALL   * * * * * *  L
 256 default  * * * * * *  - sysop /spider/src/client client %u ax25
 257 &lt;cluster&gt;
 258 NOCALL   * * * * * *  L
 259 default  * * * * * *  - sysop /spider/src/client client %u ax25
 260                 </PRE>
 261                 <P>where 'ether' and 'bbs' are appropriate <B><I>KNOWN WORKING</B></I> axport and nrport names respectively. Obviously you can use different names, callsigns or whatever for your purposes, but it is up to you to get it to work. Note I use BPQ over ethernet which why I have the port names I have.
 262
 263                 <p><LI>Find your <TT>netrom_call</TT> and <TT>ax25_call</TT> programs (which on my system live in <TT>/usr/sbin)</TT> and chmod them so that they are SUID <TT>root</TT>
 264                 <PRE>
 265 # chown root ax25_call netrom_call
 266 # chmod 4775 ax25_call netrom_call
 267                 </PRE>
 268                 <P>This has to be done to allow you to specify the correct callsigns on outgoing connects
 269
 270                 <p><LI><a name="dxvar"></a>Login to your computer as sysop, and create the initial DX Spider parameters necessary to start the cluster for the first time.
 271                 <PRE>
 272 $ startx&#9;&#9;&#9;(much easier to use X)
 273 $ cd /spider
 274 $ mkdir local
 275 $ mkdir local_cmd
 276 $ cp perl/DXVars.pm local
 277 $ cd local
 278 $ vi DXVars.pm&#9;&#9;&#9;(or 'joe DXVars.pm' if you're a WordStar fan ;-)
 279                 </PRE>
 280                 <P>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.
 281                 <P><b>PLEASE USE CAPITAL LETTERS FOR CALLSIGNS</B>
 282                 <P>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 whilst the cluster is running!
 283                 <PRE>
 284 :x
 285
 286 $ cd ../perl
 287                 </PRE>
 288                 <P>Next, run the following script, which will create the basic user file with you as the sysop.
 289                 <PRE>
 290 $ create_sysop.pl
 291                 </PRE>
 292                 <P>Now attempt to startup the cluster program and see whether all the various rivets are flying in approximate formation...
 293                 <PRE>
 294 $ cluster.pl
 295 DXSpider DX Cluster Version 1.9
 296 Copyright (c) 1998 Dirk Koopman G1TLH
 297 loading prefixes ...
 298 loading band data ...
 299 loading user file system ...
 300 starting listener ...
 301 reading existing message headers
 302 reading cron jobs
 303 orft we jolly well go ...
 304                 </PRE>
 305
 306                 <p><LI>now log in again (as 'sysop') or start another rxvt or xterm
 307
 308                 <PRE>
 309 $ client.pl
 310                 </PRE>
 311                 <P>at the cluster prompt (which will look something like):-
 312                 <PRE>
 313 G1JIM de GB7JIM 12-Dec-98 1718Z &gt;
 314                 </pre>
 315                 Type:
 316                 <pre>
 317 set/node GB7XXX
 318                 </PRE>
 319                 <p>(where 'GB7XXX' is a DX cluster which you expect to connect to or from).
 320                 <P>Now shut the cluster down by simply typing 'shutdown' at the prompt.
 321                 <P>The cluster and the client should both go back to prompts
 322                 <p>The callsigns should be the sysop callsign and the cluster callsign
 323                   as per your modified DXVars.pm. You can check that the cluster
 324                   connections will work by:-
 325                 <pre>
 326 $ client.pl gb7xxx      (doesn't have to be uppercase).
 327 PC38^GB7JIM^~           &lt;- the cluster thinks this is a cluster
 328 ^C                      &lt;- to get out
 329                 </pre>
 330                 <p>
 331           <li> Finally try:-
 332             <pre>
 333 $ console.pl
 334         </pre>
 335                 <p>This is the normal way (as of version 1.30) of running the cluster system
 336                 as a sysop. It is a simple program client program that allows you to
 337         press &lt;up-arrow> &lt;down-arrow> and use all the usual line editting
 338                 keystrokes that you can use on the unix shell under linux or bash.
 339                 <p>In addition, it will highlight certain type of lines in particular
 340                 colours and allow you to scroll the top window up and down with the
 341                 &lt;page-up> and &lt;page-down> keys.
 342         </ol>
 343
 344         <p>You should now have a basic working system. Best of luck! Can I now draw your attention to
 345           the <a href="http://www.dxcluster.org/spider">Bug Reporting</a> System.
 346
 347         <p>Can I commend to you the Announcements mailing list to which you may
 348           <a href="mailto:majordomo@dxcluster.org?subject=Subscribe&body=subscribe%20dxspider-announce%0D%0A--%0D%0A">subscribe</a>.
 349           This is a low volume mailing list which will send you announcements of new patches and
 350           such like things as they arise.
 351
 352         <p>If you like what you see and want to be a part of the ongoing development then
 353           <a href="mailto:majordomo@dxcluster.org?subject=Subscribe&body=subscribe%20dxspider-support%0D%0A--%0D%0A">subscribe</a>
 354           to the support mailing list which will be the focus of any discussion/bug fixing etc.
 355
 356 <!-- Standard Footer!! -->
 357         <p>&nbsp;</p>
 358         <p>
 359           <FONT COLOR="#606060"><hr></font>
 360         <font color="#FF0000" size=-2>
 361           Copyright &copy; 1998 by Dirk Koopman G1TLH and Iain Phillips G0RDI. All Rights Reserved<br>
 362         </font>
 363         <font color="#000000" size=-2>$Id$</font>
 364
 365   </BODY>
 366 </HTML>