[spider.git] / sgml / wininstallation.sgml

<!doctype linuxdoc system>

<article>

<!-- Title information -->

<title>The Installation Guide for DXSpider under Microsoft Windows</title>
<author>Iain Philipps, G0RDI (g0rdi@77hz.com)</author>
<date>$Date$ $Revision$</date>
<abstract>
DX Spider under Microsoft Windows &trade;
</abstract>

<!-- Table of contents -->
<toc>

<!-- Begin the document -->

<sect>Introduction

<P>
<bf>IMPORTANT:</bf> 

What you'll be left with once you've followed these instructions
is (hopefully) a working DX Spider v1.47 system that is capable
of accepting or originating "internet" connections, plus inbound
AX.25 and TCP/IP radio connections. If the absence of outbound
radio connections is a serious limitation for you, it would be
better for you to wait a couple more weeks until this support has
been added.

On the other hand, you may have an enquiring mind, or better yet,
may be looking for a useful way of connecting your current
(perhaps) AK1A cluster "to the internet" via some networking
mechanism (BPQEther, etc) or other. I won't be producing
instructions for the latter case, because I don't have an AK1A to
play with. But someone might ...

Whatever, this document is intended to get you started with DX
Spider in a Microsoft Windows &trade; environment. It's not
intended to teach you anything other than how to perform a
minimum configuration of a DX Spider installation and have it
able to connect across "the internet" to other DX Clusters, while
accepting inbound TELNET and radio connections.

<sect1>The requirements

<P>
The very first things you're going to need are (in order of
importance):-

<itemize>
<item>A cup of good, strong tea
<item>A supported Windows platform with an internet connection so you can
download the necessary software bits and bobs directly to it. There are other ways, but this is preferable.
<item>Another cup of good, strong tea
<item>If all goes according to plan, about an hour to spare
<item>Plenty of good, strong tea
</itemize>

<sect1>The system

<P>
The platform I used to generate these instructions was a
"vanilla" Microsoft Windows Me 4.90.3000 system, with a 700MHz
AMD Athlon processor and 96 Mb memory. I've also personally
verified that it runs on my laptop (Pentium 266MHz, 32 Mb memory,
Windows 98 SE v4.10.2222 A) and a computer that I assembled from
a random pile of junk (AMD K6-2 333MHz, 64 Mb memory, Windows 98
v4.10.1998). As a result, I have reason to believe that what I'm
about to describe will perform equally on any 32-bit MS Windows
environment with 32 Mb of memory.

Because of the changes that have recently been made to the core
"cluster.pl" module and the introduction of a very lightweight
"winclient.pl", I have a sneaking suspicion that this will now
run on any platform that has reasonably complete support for
Perl. Is there someone out there with both an enquiring mind and
(say) a Macintosh, for instance?

Please bear in mind, though, that my instructions relate solely
to how to get this going under a Microsoft Windows environment,
and I have zero intention of trying to make them say otherwise.

<sect1>Perl

<P>
Install your chosen Perl environment. Unless you have a very good
reason for not doing so, I strongly suggest that you use
ActivePerl v5.6. For my testing & development, I used build 623.
You can get this from:- <htmlurl
url="http://www.activestate.com/Products/ActivePerl/Download.html"
name="http://www.activestate.com/Products/ActivePerl/Download.html">

You will need to choose either the MSI or the AS package. My
recommendation is that you choose the MSI package and deal with
the consequences if your system isn't equipped with support for
the latest MS Installer; you'll be better off in the long run.
The build 623 download is 7,460 KB, so now is a really good time
to have some tea if you're on a slow dial-up connection.

During installation, please ensure that you do choose the options
to "Add Perl to the PATH environment variable" and "Create Perl
file extension association"; it will make your life so much
easier. Once the installation is finished, be sure to reboot your
PC. You probably won't be told anywhere else that this needs to
be done now, but it does. Really.

Once you've rebooted, open a "DOS box" (Start > Run > command
might do it, if you can't find it elsewhere) and from wherever it
lands, type PERL -v &lt;ENTER&gt; (it's better if that's a lower-case
'v', because an upper-case 'V' means something else. You should
be rewarded with some interesting information about your Perl
installation. If you're not, you must go back to the beginning
and discover what went wrong and fix it. It's pointless to
proceed unless this simple check is passed. Assuming it did work,
you may now move on.

<sect1>Additional packages

<P>
Some extensions ("packages") need to be added to the base Perl
distribution, and we'll do this next. If you're using the Perl I
recommended, and don't know any better for yourself, then just
blindly following these instructions will work just fine. If that
didn't describe you, then you're on your own.

Visit the following URL:

<htmlurl url="http://www.activestate.com/PPMPackages/zips/6xx-builds-only/"
name="http://www.activestate.com/PPMPackages/zips/6xx-builds-only/">

and download the following files:-

<tscreen><verb>
Data-Dumper.zip
Net-Telnet.zip
TimeDate.zip
Time-HiRes.zip
DB_File.zip
</verb></tscreen>

Make yourself a convenient directory to unpack all of these zip
files into (I put mine in "D:\ppm>") and do the following (the
bits you type in are blue ). Note that where these files land
will be directly related to where you chose to install your
ActivePerl (mine, as you can probably guess from what follows,
went into "D:\Perl"):-

<tscreen><verb>
D:\ppm>ppm install Data-Dumper.ppd
Installing package 'Data-Dumper.ppd'
Installing D:\Perl\site\lib\auto\Data\Dumper\Dumper.bs
Installing D:\Perl\site\lib\auto\Data\Dumper\Dumper.dll
Installing D:\Perl\site\lib\auto\Data\Dumper\Dumper.exp
Installing D:\Perl\site\lib\auto\Data\Dumper\Dumper.lib
Installing D:\Perl\html\site\lib\auto\Data\Dumper\Dumper.html
Installing D:\Perl\site\lib\Data\Dumper\Dumper.pm
Writing D:\Perl\site\lib\auto\Data\Dumper\Dumper.packlist
D:\ppm>
</verb></tscreen>

I'm not going to bother you with exhaustive details of the rest
of them, but suffice it to say you need to:

<tscreen><verb>
ppm install DB_File.ppd
ppm install Net-Telnet.ppd
ppm install TimeDate.ppd
ppm install Time-HiRes.ppd
</verb></tscreen>

If all that seemed to work OK, time to move along. Before anyone
who is familiar with PPM tells me that we didn't need to download
and keep those files locally, I knew that. I also knew that PPM
is sometimes awkward to configure via firewalls, and that
sometimes the repositories don't always work the way we'd hope. I
do it that way because it suits me.

<sect1>Getting Spider

<P>
Get the current version of the DX Spider distribution. This needs
to be v1.47 or later. You've got two ways (currently) of getting
this; either get a CVS update from sourceforge (if you don't know
what this is, then it isn't for you) or get my package from:-

<htmlurl url="http://www.dcc.rsgb.org/WinSpider.zip" name="http://www.dcc.rsgb.org/WinSpider.zip">

If you went down the CVS route, then everything will be nicely
set out on your local disk. If you got the ZIP file, unpack it to
somewhere convenient. The following examples assume that you put
it on drive "C:\", for convenience.

<bf>NOTE:</bf> This distribution method will go away as soon as the first
v1.47 tarball is released. You can use WinZip to unpack that, and
my life will be made easier by not needing to keep this .ZIP file
updated.

<sect>Installing the software

<P>
Ensure that your CVS session or your unZIPped file have left you
with a directory "C:\spider\local"; if not, go to "C:\spider\"
and create one. If "C:\spider" is missing, go back and figure out
why, because it shouldn't be.

Now create your own local copy of the DXVars.pm file by:-

<tscreen><verb>
copy c:\spider\perl\DXVars.pm.issue
c:\spider\local\DXVars.pm
</verb></tscreen>

Now you'll need to edit this file using a text editor. If nothing
else, you can simply

<tscreen><verb>
cd \spider\local
</verb></tscreen>

and then

<tscreen><verb>
notepad DXVars.pm
</verb></tscreen>

to bring up an editor window containing the file. As an absolute
minimum you must adjust the following items in DXVars.pm:-

<itemize>
<item> $mycall  - Should hold the callsign of your DX Cluster
<item> $myname  - The SysOp's first name
<item> $myalias - the SysOp's callsign. Cannot be the same as $mycall!
</itemize>

You really also ought to update the $mylatitude, $mylongitude,
$myqth and $myemail variables. And unless you are absolutely
certain you know what you're doing, you should change nothing
else in this file.

<sect1>The AGW packet engine

<P>
On the assumption that you'll be using the SV2AGW Packet Engine
to interface your radios to the cluster, you should now create
your own local copy of AGWConnect.pm by:-

<tscreen><verb>
copy c:\spider\perl\AGWConnect.pm
c:\spider\local\AGWConnect.pm
</verb></tscreen>

and then

<tscreen><verb>
notepad AGWConnect.pm
</verb></tscreen>

to bring up an editor window containing the file. You must
consider adjusting the following items in AGWConnect.pm:-

<itemize>
<item>$enable - set to '1' to enable AGWPE interface 
<item>$login  - the login ID you chose when you set up the SV2AGW security :-)
<item>$passwd - password that matches $login
</itemize>

<sect1>Setting up the initial user files

<P>
Next you need to create the initial user files, etc. A tool is
supplied which will do this for you. To run the tool:-

<tscreen><verb>
cd \spider\perl
perl create_sysop.pl
</verb></tscreen>

If all goes according to plan, you will see no output from this
program, and after a brief wait, your DOS prompt will be
returned.

Depending on how brave you are, you might now care to try the
following:-

<tscreen><verb>
perl cluster.pl
</verb></tscreen>

If you did everything you were told, your DOS window will now
hold a display which looks something like:-

<tscreen><verb>
DXSpider DX Cluster Version 1.47
Copyright (c) 1998-2001 Dirk Koopman G1TLH
loading prefixes ...
loading band data ...
loading user file system ...
starting listeners ...
Internal port: localhost 27754
load badwords: Ok
reading in duplicate spot and WWV info ...
reading existing message headers ...
load badmsg: Ok
load forward: Ok
load swop: Ok
@msg = 0 before delete
@msg = 0 after delete
reading cron jobs ...v cron: reading /spider/cmd/crontab
cron: adding 1 0 * * 0
DXUser::export("$main::data/user_asc")
reading database descriptors ...
doing local initialisation ...
orft we jolly well go ...
queue msg (0)
</verb></tscreen>

Now, if that's what you've got, you are very nearly home and dry
(in as far as these particular experiments are concerned, anyhow)

To access your new cluster (from the local machine) find yourself another
"DOS box" and do the following:-

<tscreen><verb>
cd \spider\perl
perl winclient.pl
</verb></tscreen>

If you are rewarded with a display which looks something like:-

<tscreen><verb>
Hello Iain, this is GB7SJP in Amersham, Bucks running DXSpider V1.47
Cluster: 1 nodes, 1 local / 1 total users Max users 2 Uptime 0 00:00
M0ADI de GB7SJP 4-Mar-2001 1511Z >
</verb></tscreen>

You've arrived. Try some commands, and see how they feel. (In
case you were wondering, "Iain", "M0ADI" and "GB7SJP" all came
from the version of DXVars.pm that was on the machine when I
started the winclient.pl)

<sect1>Incoming telnets

<P>
If you want to enable inbound "TELNET" connections, you've got a
little more work to do. From a handy "DOS box" that's not doing
anything else, do the following:-

<tscreen><verb>
copy \spider\perl\listeners.pm \spider\local
cd \spider\local
notepad listeners.pm
</verb></tscreen>

The following lines need attention:-

<tscreen><verb>
["0.0.0.0", 7300],
</verb></tscreen>

On my machine, I've simply uncommented the "0.0.0.0" entry by
removing the '#' from the front of the line. 

If you don't have a static hostname for your machine, and you
intend to allow folk to connect to your machine across the
internet, then I'd suggest you pay a visit to www.dyndns.org and
create one for yourself. While it's free, it will take a modest
an amount of effort on your part to read, understand and
implement what needs to be done to set this up.

<sect1>Connecting to other clusters

<P>
If you want to connect this to another cluster, then you'll want
to negotiate a link with someone. For experimental purposes, I'm
happy to allow folk to connect to GB7DXA (spud.ath.cx), on the
understanding that the system may or may not be there and may or
may not be connected to anything particularly useful at any given
moment. Contact me by Email if you want me to set up a connection
for you.

<it>Last updated: 15-Apr-01</it>

</article>