Acorn User 1/AU_CD1.iso/internet/starterpak/Docs/FAQs/Guide1_21

Text File | 1994-12-13 | 62KB | 1,428 lines

This is a guide to the installation and use of the various versions of ka9q
for the Archimedes.  Because the different versions have been produced by
two people who collaborate and merge changes only occasionally, there are
some differences in the implementation of some of the commands.  This guide
attempts to cover general principles, and will point out most of the major
differences, but when in doubt, read the documentation accompanying your
version of ka9q.

This file is copyright  1993 Paul L. Allen & The ARM Club.



REVISION HISTORY
================

    Version 1.0: 22/9/1993.  Initial release.  Note that this was written to
    a deadline with no opportunity to verify details with Jonathan Naylor or
    Anthony Frost (who are responsible for the various versions of Arc ka9q)
    so you are advised to look for updates (corrections) to this file on
    ftp.demon.co.uk and Arcade BBS.

    Version 1.1: 3/10/1993.  Many corrections, both major and minor.  Thanks
    go to the DIS support team, Anthony Frost, Jonathan Naylor, John Stonier
    and Julian Bewick.



GENERAL INFO
============

Some of the earliest versions floating around do not handle usenet news -
the latest version can be obtained by ftp from ftp.demon.co.uk or downloaded
from Arcade BBS (this version uses the serial block drivers, so is RISC OS 3
only).

Ka9q commands may be abbreviated to the minimum length which remains
unambiguous, so `smtp kick' and `sm k' have the same effect.  In this
document I will use the unabbreviated form for clarity.


ESTABLISHING AN ACCOUNT
=======================

Pick a site name (between 4 and 8 characters), and phone Demon Internet
Services during office hours on 081 349 0063 to subscribe.  Give them your
site name (it's best to have a couple of alternates ready in case somebody
else has already chosen that name), personal details and credit card number
(you can order by letter and pay by cheque, but credit card gets you
connected immediately).

Choose a password (you don't tell the DIS people, but use your first login to
let the system know which p/w you've chosen).  Requirements may change, but
you will probably need to choose something which doesn't contain a valid word
and you will probably need to incorporate one or more numbers.  You may even
find that passwords composed of key clusters (such as `qwas' or `qwerty')
will also be rejected.

Use your comms program to dial a suitable DIS site (London 081 343 4848,
Edinburgh 031 552 8883, Warrington 0925 411383).  When it asks you to login
enter your site name.  You will then be asked for your password - it is not
echoed to your screen, so you will be asked to enter it a second time to make
sure you didn't mistype.

The screen will then display your site's IP address - take care to note it
down.  The connection will close after 30s.

Note that this procedure applies *only* to your first call - subsequent
connections will require the use of ka9q.



INSTALLATION
============

Although the program announces itself as ka9q, the application is called
!TCPIP.  Unpack it from the Sparkive to a convenient place on disc.  You
should also get an application called !MailDir - this is not an application
as such but a repository for mail and news.

n the examples that follow, I will use my site name (sktb) and my IP
address ([158.152.9.18]) - you should replace them with your own site name
and IP address (see previous section on establishing an account).

Be careful to retain the original versions of all files that you modify - if
you have problems you can return to a known starting point.

You should check the following files in the !TCPIP folder:


!TCPIP.Autoexec
---------------

This is a file of ka9q commands which are executed when ka9q starts.  Like
any other commands they can be abbreviated, but it is probably best to use
the long form.  A #-sign is used to indicate a comment to ka9q.

Remember that wherever you see `sktb' you should use your own site name, and
wherever you see [158.152.9.18] you should use your own IP address.

There will be a sample file !TCPIP.Autoexec, but in some versions this is
for packet radio use - if you see the letters TNC throughout then delete it,
look for a file called Autoslip and rename it as Autoexec.

Some of the commands mentioned below are not supported by all versions of
ka9q.  Usually if a command is supported it will appear in the sample
autoexec provided, although it may be commented out (the exceptions to this
are the commands dealing with Usenet news which may not be present even
if they are supported).  If you try and use a command that your version
doesn't understand it will complain...

                                  ---

Versions of ka9q which support the serial block drivers (RISC OS 3 only)
allow you to pipe the display to your favourite comms program (this will
let you use various terminal emulations such as VT100 which can be very
useful with some services).  The command will look something like:

    window terminal external pipeb

or

    window terminal internal

to use ka9q's in-built display routines.  The default is internal.

                                  ---

With older versions of ka9q, any time it displayed some text in its window
it would grab the input focus (so if you were editing something at the same
time you'd suddenly find your keystrokes going to ka9q).  Newer versions
allow you to use:

    window cursor off

which means that no caret will be displayed by ka9q, but that way it won't
give you nasty surprises.  You can turn it back on with:

    window cursor on

                                  ---

Change the hostname line to reflect your site name, e.g.:

    hostname sktb.demon.co.uk

                                  ---

Change the ip address to reflect the number allocated by DIS, e.g.:

    ip address [158.152.9.18]

                                  ---

Modify the attach command to reflect your baud rate.  Depending upon the
version of ka9q this may take one of the following forms:

    1)  attach asy internal slip ax0 2048 1500 19200

    2)  attach asy internal slip 0 ax0 2048 1500 19200

    3)  attach asy internal slip ax0 1500 19200

Here `asy' indicates that the interface is an asynchronous serial port.

The word `internal' specifies that the internal port be used.  For some
versions of ka9q (form 1 and 3) this is the *only* port which may be
specified, but those versions which understand the serial block drivers
(RISC OS 3 only) use form 2 where the port can be one of:

    internal 0
    II_dual 0
    II_dual 1
    sp_dual 0
    sp_dual 1

to indicate use of the internal port or the dual serial port cards from
Intelligent Interfaces or The Serial Port.  Note that the version which
supports the serial block drivers will not work correctly *if* you have an
II card and something else is using another port (including the internal
serial port).  This is of particular concern for BBSs as the BBS software
will poll ports at regular intervals (even if nobody is using the BBS) - the
fix is to shutdown the Board software and Binkley (this problem may be fixed
in a future version of ka9q).

The word `slip' indicates that the SLIP protocol should be used (Arc ka9q
does not support any other protocol).

The word `ax0' is a label used by other commands to refer to this port (use
anything you like, but remember to be consistent - we'll stick with ax0 in
these examples.

The figure of 2048 is a buffer size, but the Arc version of ka9q ignores it.
Some versions of Arc ka9q require it be present (forms 1 and 2) even though
it is ignored, whilst some versions (form 3) require it to be absent - be
guided by the example autoexec provided.

The figure of 1500 is the maximum IP packet size - this is probably the
optimal value for internet usage (lower values values in some versions derive
from ham-radio usage).

The figure of 19200 is the speed of the serial port - set this accordingly
Some versions of ka9q may ignore this figure entirely and not change the
serial port speed - they rely on your comms/dialer program setting things
up.  Put it in anyway...  Note that older machines (A300 and A400 series)
running RISC OS 3 may have problems with speeds above 9600 (there is a
patch which fixes the problem in most cases).  It is a good idea to ensure
that the speed given here matches the speed your dialler/comms program uses
to establish the connection to demon - some modems can handle a speed-change
mid-call but some can't.


                                  ---

Check that the default route is given as follows:

    route add default ax0 [158.152.1.65] 1

The address is that of gate.demon.co.uk, and need not be changed even if
you dial in to a different node.  The value of 1 at the end represents a
routing `cost' - versions of ka9q from Jonathan Naylor do not use this (and
may complain if it is present).

                                  ---

Check that the IP time-to-live is given as:

    ip ttl 64

This determines the maximum number of hops a packet can take (the maximum
number of routing sites it passes through).  Older versions of ka9q may have
a lower figure here - you should change it to 64 as the Internet has grown
quite a bit since that version was released.

                                  ---

Check that the TCP maximum segment size is 40 bytes smaller than the IP
packet size given in the attach command - if you attached with an IP packet
size of 1500 you would have

    tcp mss 1460

                                  ---

The value used for the initial round-trip time is a guess which is used until
ka9q can measure the actual round-trip time.  Ka9q assumes packets which
take longer than the average round-trip time to arive have gone missing, so
setting a high value initially will prevent a flurry of retransmissions.
Typically this is given as

    tcp irtt 30000

                                  ---

The value for tcp window defines the maximum number of words of data can
handle - in essence it defines a buffer size.  Each time ka9q requests a
packet from a remote site it tells it how much room is left in the buffer.
This should be larger than the figure given in the `tcp mss' command or
transfers will be inefficient, especially over slow links.  Some versions of
ka9q have the same value here as for tcp mss, and should be changed to:

    tcp window 15000

Note that different versions of ka9q have some very strange and conflicting
ideas for the values of tcp window, tcp mss and the IP packet size specified
in the attach command.  I've chosen a value which is 10 times the IP packet
size specified in the attach command.  It is possible you may have to
increase the value of WimpSlot set in !TCPIP.!Run to accomodate this,
although I have had no problems with the existing value of WimpSlot.

                                  ---

Some versions of ka9q have a hangup command, if so you will see

    tcp hangup 15 3

which hangs up the modem if there have been 3 consecutive idle periods of 15
seconds.  The hangup is achieved by toggling the DTR line for one second, so
you must configure the modem to respond to this.  If you want to turn the
timer off, use `tcp hangup 0 0'.  Note that finger and ping commands do not
count as activity, but that various wait states do - so if you are very
unlucky ka9q may not hangup automatically.  DIS also have an inactivity
timer (which, for reasons of legal liability, they do NOT guarantee to
operate), so you have to be extremely unlucky for the connection not to
close.  However, if you are planning unattended operation you may want to
invest in a time-switch as well...  Note to BBS sysops, a `tcp exit' command
may appear in the next release to allow BBSs to automatically communicate
with demon in the small hours and then return to BBS operation.

                                  ---

Check that the domain suffix is correct:

    domain suffix demon.co.uk

                                  ---

Decide if you want a logfile recording connections and activities.  This
file can grow very large if you forget to clear it out regularly, and a large
logfile will slow things down quite a bit.  If you want logging, use the
command:

    log <TCPIP$Dir>.logfile

Or remove the command/comment it out if you don't want logging.

                                  ---

Start the echo server with:

    start echo

This will allow your machine to echo characters to incoming telnet sessions
if requested.

                                  ---

Start the discard server with:

    start discard

I'm not sure what this does, but every autoexec file I've seen has it in...

                                  ---

If you wish to allow people to ftp to your machine to send you files or to
take copies of your files, then start the ftp server:

    start ftp

Note, you should edit the FTPusers file to reflect the degree of security
you require - see later.

                                  ---

You should start the smtp server so you can receive e-mail:

    start smtp

                                  ---

If you would like other sites to be able to finger your machine to see which
usernames exist and possibly get some info on you or your setup, start the
finger server:

    start finger

You will need to create information files for each user in the finger
directory - see later.

                                  ---

If you would like other sites to be able to telnet in for a chat, start the
telnet server:

    start telnet

                                  ---

During the initial stages of setting up you may wish to have the trace window
appear for debugging purposes:

    trace ax0 112

Note that ax0 is the label given in the attach command.  The trace window
will slow things down tremendously - it is fairly undecipherable, but you
should watch for error messages.  You may see a `bad packet' message on
startup, but there should be no errors after that.  Closing the window kills
the trace activity.

                                  ---

When you telnet or ftp to a remote machine it is preferable to have the
remote machine echo what you type rather than perform the echo locally.
However, remote echoing of commands can slow command entry quite a bit.
You turn remote echoing on with:

    echo accept

or turn it off with

    echo refuse

                                  ---

Define post.demon.co.uk to act as a mail-router with:

    smtp gateway [158.152.1.72]

                                  ---

It's useful to get some feedback as the sending of outgoing mail progresses,
as well as to get a message when all mail has been sent:

    smtp trace 1

                                  ---

To make outgoing mail be sent automatically when ka9q starts up, use:

    smtp kick

                                  ---

If you are going to receive Usenet news, it's useful to see when news starts,
what groups are being downloaded and when the session finishes:

    nntp trace 2

                                  ---

To tell ka9q where to get Usenet news from, put in:

    nntp addserver news.demon.co.uk 1800 Dem

The figure of 1800 means that the ka9q will check for news every 1800s
(30min).  The `Dem' is an abbreviation prefixed to certain filenames used
by to get Usenet news, it should consist of a maximum of 4 characters which
are valid in a filename - in the remainder of this document we will stick
with `Dem' in the examples.

Note that you should be able to set up several different news servers, or
drop a server and switch to another.  In practice, none of this works on any
existing version of ka9q - you're limited to a single news server.

                                  ---

To start a news download initially, use:

    nntp kick Dem


The very first version of ka9q which supported news downloads required the
the full name of the news server be used instead of the abbreviation - so
if you have that version you would use `nntp kick news.demon.co.uk'.

News downloads can take a long time, so if you want to login between 13:00
and 18:00 to check for mail (something you might want to do if you work
from home or the site belongs to a company) then you don't want news starting
up and running up the phone bills, so leave this line out and enter it
manually when you're on the cheap rate.

                                  ---

Now to check for errors...  Just run !TCPIP (no need to dial out first, it
will work quite happily).  If you've mistyped the name of a command ka9q will
complain about an unknown command and tell you which line of Autoexec
contains the error.  Note that you should ignore the message `NNTP - No mail
ID archive' if it appears - this is nothing to do with autoexec.


!TCPIP.Domain
-------------

This is a list of sitenames and their IP addresses.  The purpose of it is
to allow you to refer to sites by their sitename rather than by the IP
address - it's much easier to remember micros.hensa.ac.uk (the microcomputer
section of the Higher Education National Software Archive) than
[148.88.8.84], so it's worthwhile building up this file.  You must maintain
this file manually - this is a bit of a pain whenever you want to ftp to a
site you've never used before, and can cause problems when the name/address
relationship changes.  As with autoexec, a #-sign means the rest of the line
is a comment.

If you know a sitename but not the IP address you can use finger to look
it up (see the section on the finger command) and enter it into this file.
However, you should note that this file is read in by ka9q only on startup,
so modifications to it will *not* be recognised until the next time you start
up ka9q (the way around this problem is also discussed in the section on
the finger command).

Whichever ka9q you have, you should ensure it contains the following entries
(note that the format is *not* the same as that described in the user
manual).  A future version of ka9q may support automatic address queries, at
which point the only entries you need add by hand will be your own and the
DIS machines.

First ensure your sitename/address appears in both of the following formats
(as usual, I will use my sitename/address as an example):

    sktb.demon.co.uk.        IN A 158.152.9.18

Note that the `.' on the end of the sitename is a necessary part of the
syntax, and that the square brackets normally associated with IP addresses
are not used in this file.  The `IN A' stands for `Internet Address' - PC
versions of ka9q allow other types of record such as `MX' (mail alias).

    .                        IN A 158.152.9.18

The single `.' here ensures that the local site is used if no sitename is
given in a command.

                                  ---

It is useful to have the Points of Presence (dial-in sites), so you can
finger them and see who's on.  The name/address is unlikely to change.

    gate.demon.co.uk.        IN A 158.152.1.65   # London PoP
    clootie.demon.co.uk.     IN A 158.152.6.65   # Edinburgh PoP
    hel.demon.co.uk.         IN A 158.152.5.194  # Warrington PoP

                                  ---

The news server is necessary for the nntp addserver command, and the mail
server is handy so you can finger yoursite@post and see how many messages
are waiting.  The password server allows you to change your password if you
think it may have been compromised. The addresses for these functions have
changed in the past (when mail and news handling was offloaded from gate
onto separate machines) and it is possible that news may change again during
the next twelve months.

    news.demon.co.uk.        IN A 158.152.1.69  # news server
    post.demon.co.uk.        IN A 158.152.1.72  # mail server
    password.demon.co.uk.    IN A 158.152.1.68  # password server

                                  ---

There are many useful files held by demon, so it is useful to have the
address of the ftp server.  The Internet Relay Chat host is fun, but may
give you a heart attack when you see your phone bill.  The addresses of these
two sites are a little more volatile.  Ftp access may be shunted to the
machine with the biggest free disc space, whilst irc may move to follow
spare CPU capacity.  This is no great problem - if things break then
finger [e-mail] (or irc...) to see what the new
address is and change the entry in the file (this will not take effect until
the next time you start up ka9q).

    ftp.demon.co.uk.         IN A 158.152.1.68  # ftp server
    irc.demon.co.uk.         IN A 158.152.1.74  # irc host


!TCPIP.Finger
-------------

This directory is used to hold textfiles relating to users on your system.
When somebody fingers your site the names of the files in this directory
are displayed on their screen as usernames.  So, if you finger
sktb.demon.co.uk (and sktb happens to be logged in to demon at the time) you
will see a user called `pla' because I have a file called !TCPIP.Finger.pla.
If you then finger [e-mail] the contents of the `pla' file is
displayed on your screen.

You can put any info you want in here - full name, whether your site is
your home connection or a company, the equipment you use, interests, etc.
It is not a good idea to put in your full address - I don't know if any
burglars use the internet, but why risk telling them where to go for
computer equipment?

You can finger your own site to see what the display will look like to
others.  Of course, for this directory to be of use, you must have started
the finger server.

Note that the usernames in this directory are for informational purposes
only - you do not need an entry in this directory for people to be able to
e-mail a username.  However, by having a list of usernames in this directory
you allow people to find out what your *preferred* usernames are.


!TCPIP.FTPusers
---------------

This file controls who can ftp to your site (provided you have started the
ftp server).  Be *very* careful with this as you can leave your private
files wide open.  The file contains lines describing who can ftp to your
site and what they can do, as follows:

    username password path permissions

the user manual says there must be exactly one space between fields.  A
#-sign in column 1 denotes a comment.  You can give access to many different
users, such as guest, or anonymous.  The password can be * (a single
asterisk) which means that any password is acceptable.  The path determines
the effective CSD for that user - there are some important points to note:

  1) You cannot specify a filing system in the path.
  2) Unless the path exists on the currently-selected drive/filing system
     it won't be found, so you must ensure that the current drive/FS is
     correct if you want people to ftp to your machine.
  3) Ka9q should prevent users changing directory to anywhere which does
     not start with the specified path, although it is rumoured that some
     early versions of Arc ka9q did not enforce this.

The permissions field is a decimal number which determines access for
read, create and write operations.  The number is interpreted as a bit-mapped
mask with the following interpretation:

            Decimal value   Access

    Bit 0         1         File read
    Bit 1         2         File create/write (cannot overwrite an existing
                            file)
    Bit 2         4         File create/write/overwrite existing file/delete
                            existing file

A value of 1 allows read-only access, 3 allows read/write/create access (but
existing files may not be overwritten) and 7 allows read/write/create/delete
access.

For instance, to allow anonymous ftp to a directory $.ftp giving permission
to download and upload files but not overwrite/delete existing files you
would have

    anonymous * $.ftp 3

You might like to also have the commonly-used alternative of

    ftp * $.ftp 3

so people don't have to type `anonymous'...

You can run ka9q without calling demon and ftp to yourself to check your
setup and gain some familiarity with ftp.


!TCPIP.DemGroup
---------------

This is a file you create containing a list of Usenet newsgroups you wish
to receive.  Note that the `Dem' part of `DemGroup' was the abbreviation
specified in the `nntp addserver' command in autoexec - if you chose a
different abbreviation (4 chars max), you will need to change the name of
this file accordingly.

The simplest way of specifying groups is to put each group on a new line.
Note that you should not leave any blank lines in the file or ka9q will
get upset.

    comp.binaries.acorn
    comp.sys.acorn
    comp.sys.acorn.advocacy
    comp.sys.acorn.tech
    demon.announce
    demon.ip.support
    demon.ip.support.archimedes
    demon.local

However, this format is not conducive to news.demon.co.uk finding articles
very quickly as it will perform a linear search of the news database for
articles in the first group, send them, search for articles in the second
group...  Things can be speeded up quite a bit by using wildcards:

   comp.binaries.acorn
   comp.sys.acorn*
   demon*

Note that if you had put comp.sys.acorn.* (a `.' before the `*') then you
would not receive comp.sys.acorn itself.

There is another speed-up which can be performed, and that is to put the
group names on one line, separated by commas.  E.g., the previous example
could be given as:

   comp.binaries.acorn,comp.sys.acorn*,demon*

There should be no spaces anywhere on the line - although spaces would make
it easier to read, it just won't work if you have:

    comp.binaries.acorn, comp.sys.acorn*, demon*

Note that there is a limit on the maximum length of a groups line.  Although
the recommended limit is supposed to be 512 characters, Arc ka9q seems to
be stuck with 256.  You can't even use the full 256 because ka9q adds control
information to the list, so a safe figure to use is 200 characters (2.5 rows
in a full-width !Edit window).  If your line is longer than ka9q can accept
it will crash with a bad memory access - you have been warned.

Although I have not tried it, you should also be able to use the `!'
wildcard to negate matches.  If you wanted all the comp.sys.acorn* groups
except comp.sys.acorn.advocacy you should be able to use:

    comp.sys.acorn*,!comp.sys.acorn.adv*

Note that this will *only* work if the two group specifications are on the
same line and are therefore processed as part of the same request.

If you want to know what groups are available, there are listings of all the
groups in the seven main hierarchies and the mainstream alternative
hierarchies (but not the national ones like uk or scot) posted monthly to
news.announce.newusers - these listings have a brief (one or two line)
description of what each group is about.  If you want to know all the groups
that DIS carry (but without descriptions), then you should ftp to
ftp.demon.co.uk and get the file active.zip from the /pub/news directory.


!TCPIP.DemLast
---------------

This file holds the date and time of the start of your last *successful*
news download (again, the `Dem' in `DemLast' is the abbreviation you gave
in the `nntp addserver' command).  When you ask for news, ka9q will use the
information in this file to request all news which has appeared since that
time.  When your download finishes successfully this file is updated - that
way, if news crashes in mid-download you can start again without missing
anything.

If this file is not present, ka9q will request all news since the first day
of the current month - you don't *have* to create it, but if you don't your
first news download could be *very* big...

The file consists of two lines, the first for the date and the second for the
time, as folllows:

    yymmdd
    hhmmss

So, if your last news download was on the 21st of September 1993 at half-past
seven (and a few seconds) in the evening the file would contain:

    930921
    193004



USING KA9Q
==========

Logging in
----------

Ka9q is not capable of dialling DIS or logging in for you, so you must use
your favourite comms program (or a dialler program) to do this *before*
starting ka9q.

Use your comms program to dial whichever DIS Port of Presence results in the
cheapest phone charges.  When you see the `Login:' prompt enter your site
name (e.g., I would enter sktb).  When you see the `Password:' prompt
enter your password (it will not be echoed).  Next you will see a `Protocol:'
prompt - enter slip.  Wait until you see the word `HELLO', then quit your
comms program (with some comms programs like HearSay you can select the
`off-line' option instead) and start up ka9q by double-clicking on !TCPIP.
If you forget to quit your comms program or take it off-line it will `eat
up' incoming data and nothing will work.  You may experience problems if
your comms program establishes the connection at a different speed to the
one given in !TCP.Autoexec - some modems can cope with a speed change in
mid-call, but many cannot.

Note that if you have a smart comms program which allows login sequences to
be handled automatically, the *only* words it should look for/act upon are
Login, Password, Protocol and HELLO.  Demon actually advise that you look
for `ogin:', `word:', `ocol:' and HELLO as the checks are usually
case-sensitive and you might get `Login' or `login', depending upon who last
fiddled with the login software at the DIS end...

Also note that ka9q assumes that you are using ReaderS to read news messages
(mainly because Anthony Frost who wrote ReaderS added the support for news
to Arc ka9q), and relies upon ReaderS's message history file to avoid
downloading the same messages twice (this happens because you request new
articles which arrived since the *start* of your last news download, so there
can be overlaps).  If you don't have ReaderS you will get the warning
message `NNTP - No mail ID archive', which you can ignore.


Entering commands
-----------------

To enter commands, ensure the ka9q window has the input focus and type away.
There is a problem with Acorn's `txt' routines in the C library which
surfaces in programs which handle character-echoing themselves instead of
allowing the `txt' routines to perform the echoing - sometimes you type a
character and it doesn't appear until you type the next one.  This can be
confusing (did I press the key hard enough?) and there can be occasions
(see section on finger) where you don't want another character to be
entered - the answer is to press one of the cursor keys, this causes the
missing character to show up without any side-effects.

You will not see any modem activity as you type - you are entering a command
to ka9q which then interprets it.  If it is a command which results in ka9q
sending data to the DIS Point of Presence (possibly to be passed on to a
distant machine), then there will be a brief burst of modem activity when
you press return.  If you want to check your connection then the ping command
is a quick and easy way of finding out if everything is working.

If you use a command which requires a sitename to be specified (telnet,
finger ping or ftp), and the site is in the demon.co.uk subdomain (i.e., DIS
machines or subscribers) you can omit the `demon.co.uk' part.  E.g., to
change your password you could use `telnet password' instead of
`telnet password.demon.co.uk'.  Sitenames which do not end in `demon.co.uk'
must be specified in full.  If you see the error message `host <sitename>
unknown' this means that there is no entry for <sitename> in !TCPIP.domain -
if you know the numeric address you can use that instead - e.g.,
`finger @[158.152.9.18]' instead of `finger @sktb.demon.co.uk'.

Ka9q will run perfectly happily even if you haven't dialled into DIS - the
only difference is that no site other than your own will answer.  This way
you can learn how the various commands work and what sort of responses to
expect without running up your phone bill.  You can ftp to your own site
and learn to how to find and transfer files, finger your own site to see how
the !TCPIP.finger.<user> files you have set up will appear to other people,
etc. You'll also catch any errors in your !TCPIP.Autoexec.


Special Keys
------------

Ka9q recognises the following special keys:

  F10 and Ctrl-] return you to the net prompt when a session is active (see
  later for a discussion of sessions).  F10 works only with ka9q's own
  window (window terminal internal) whilst Ctrl-] works when you pipe ka9q's
  I/O through your comms program.

  <-| The backspace key deletes characters from the line you've typed.

  <Escape> empties the line buffer - if you're typing a line and realise you
  made a mistake at the beginning, this is a lot quicker than using the
  backspace key.

  Ctrl-W deletes the last word in the line buffer - this is quicker than the
  backspace key but not as brutal as <Escape>.

  Ctrl-R repeats the line you're entering.  This is useful when ka9q gives
  an informational message just as you fumble and are not sure what you
  typed.

  F3 recalls the last line you entered.  This is handy if you want to repeat
  commands.  Unfortunately it `loses' @-signs, so is not very useful with
  the finger command.  It only works with ka9q's internal window.


Help
----

The help command (or just ?) will list the available commands.  You can get
further help on most, but not all, commands which take arguments by
following the command name with a space then a question mark, e.g.:

    smtp ?

will list the possible arguments for the smtp command.


Ping
----

A useful way of checking your connection is to ping the PoP you've dialled
into - if you phoned the London PoP then `ping gate' should give you some
modem activity and return the round-trip time (typically 250ms under light
loading, up to a couple of seconds under heavy loading).


Mail
----

Incoming mail is delivered automatically as soon as you login (it can take
up to a minute under heavy loading to start up).  Outgoing mail created
before you started ka9q will be sent as soon as you login, provided you have
the command `smtp kick' in your autoexec.  If you create mail whilst
connected, or the mail appears to be stuck, you can enter the `smtp kick'
command manually.  You can check how much incoming mail is waiting for you
with the finger command (see section on finger).

You can also use the smtp timer command to cause the mail queue to be
scanned automatically at fixed intervals.  I wouldn't advise using this -
too long an interval and you'll have logged out before it kicks in, too
short and ka9q will waste a lot of time repeatedly checking for outgoing
mail.

Mail to a particular username appears as a file in !MailDir.spool.mail.text
and the filename is the same as the username (so mail to pla@sktb... appears
as a textfile called `pla').  The upshot of this is that you *must* choose
usernames which are valid RISC OS leaf-names (so paul.allen@sktb... would not
work).  In fact a DOS limitation has been retained and usernames must have
no more than 8 characters (the required user called postmaster is handled as
a special case and converted to `postmast').  I don't advise you to try
reading mail with Edit - bad as the BM mailer is at creating mail, it's
better than Edit for reading mail.

There is no way of defining which usernames are acceptable and which aren't
for incoming mail - as long as it's a valid leafname of 8 characters or less,
people can send mail to it.  However, you can indicate your preferred
username(s) by creating entries for them in the !TCPIP.finger directory.

Outgoing mail is placed in !MailDir.spool.mqueue.text - each message gets a
unique number, and each message requires a correspondingly-numbered work file
in !MailDir.spool.mqueue.work.  I won't go into the formats of these files
as I *definitely* wouldn't advise trying to create outgoing mail with Edit.
However if you create e-mail you have the opportunity to tweak or delete it
before firing up ka9q - just remember to remove the work file as well as the
text file if you want to delete a message.

Mail can only handle 7-bit characters, and some IBM machines have a habit
of getting the ASCII/EBCDIC conversion wrong and mangling the odd character
even then, so you can't mail Sparkives or other binary files to people.
However, you can uuencode the file (an option Spark offers) which encodes
the file so it will survive.  The file will increase in size, but at least
it can be sent.

Arc ka9q differs from the PC versions in that all outgoing mail is routed
via the smtp gateway defined in !TCPIP.Autoexec.  Prior to this modification
mail was sent directly to the site concerned (which meant that mail to other
demon subscribers could not be sent unless they were logged on to DIS at the
same time).  Although this change means that mail takes slightly longer to
reach its destination, it also means that you (generally) spend less on-line
time sending it.


News
----

News downloads are started using `nntp kick Dem' (assuming `Dem' was the
abbreviation you used in the `nntp addserver' command in your autoexec).
You will either have this command in your autoexec if you want news every
time you login, or enter it manually to only collect news during cheap rates.
No further interaction should be required on your part.

Downloaded news appears in !MailDir or !MailDir.spool, depending on which
version of ka9q you have.  The file will be called DemNews (again assuming
you used `Dem' as the abbreviation in the nntp addserver command), and there
will also be a file called DemNG which lists all the new groups which have
been created since you last downloaded news.  You should look at DemNG to
see if there's anything of interest, add the groups to !TCPIP.DemGroup as
required then delete it (information is appended to DemNG, so if you don't
delete it it will slowly grow and grow).  You can read news with an editor,
but if you want to see it presented more logically, and have the opportunity
to reply you should get hold of a newsreader.

You may notice that after ka9q requests a list of groups that activity is
rather slow at first.  This is because the news-server is searching an index
to find articles in the appropriate groups which have arrived since your
last news download - it passes the unique message-ID of each matching
article to ka9q which puts the IDs in a temporary workfile !TCPIP.DemNew
(see previous comments about `Dem').  Once the list is complete ka9q then
requests each article in turn and there will be a lot of activity as the
articles come down.  If news terminates unsuccessfully (say you get cut
off) then !TCPIP.DemNew may be left hanging around - don't worry about it.

Note that if you've been on holiday you can reset the time in !TCPIP.DemLast
so you don't get deluged with news - that's if you can live without it.

Outgoing news articles are actually sent as e-mail.  Depending on which
newsreader you use they will be addressed either to
[e-mail] (which allows cross-posting) or
<newsgroup>@post.demon.co.uk (where the article is posted only to the
group given in the address, e.g., [e-mail] to post
to comp.sys.acorn).  Either way, you have the opportunity to tweak or remove
them before firing up ka9q (see the section on Mail).  By the way, there's
a little more to creating a valid news posting than just addressing mail to
mail2news, so don't be tempted to do it by hand...

If news.demon.co.uk is heavily loaded it will refuse further connections -
if there appears to be no activity use the tcp status command (explained
later) to see if socket 119 is in use.  If not, try the nntp kick command
again, or logout and try later.

Telnet
------

Telnet allows you to login to remote sites - just `telnet <site>' e.g.,
`telnet archie.doc.ic.ac.uk' to connect to the `archie' Internet archive
listing service at Imperial College.  For some sites a telnet session will
behave as if you were logging in at a local terminal on that machine - you
will be asked for a username and password (if you don't know a valid
combination you won't get very far).  If you telnet to information services
you will usually be told a username and password to enter, or logged on
automatically.  Some sites may react to telnet connections in a special way:
for instance you change your site's password by `telnet password.demon.co.uk'
and following the instructions.

You can even use telnet to explore the hidden depths of some protocols which
build upon telnet by adding a `socket number' to the command, but that is
outside the scope of this document.

Most single-user machines (as used by many demon subscribers) will enter
a chat mode if you telnet to them - you can talk to your friends whilst
news downloads.  If the person you're chatting to is using a PC you should
telnet to socket 87 by `telnet <site> 87' or they will have a hard time of
things.

Telnet is one of the ka9q commands which runs in its own `session' - you
should read the next section to see what this means.  Depending on what
you telnet to, you might need to use logout, logoff, quit or exit to
finish (if you telnet to someone for a chat you have to return to the
net prompt and close the session - see next section).

If ka9q complains of an unknown host you will have to find the IP address
(see section on finger) and telnet to that instead until you update your
domain file.


Sessions
--------

Some ka9q commands (such as telnet and ftp) create a `session' - you
can have several sessions running simultaneously and switch between them
(*only* if you're using the `internal' window and not piping i/o through
your comms program).

If you've entered a telnet command the title of the ka9q window will change
from `NET <version>' to `Telent - <site>'.  Also the command prompt `net>'
will no longer be present.  Anything you type now will be sent to the remote
site (after you press return).  You can return to the ka9q command line by
pressing F10 (this *only* works with the `internal' window, if you pipe
i/o through your comms program use Ctrl-] instead) - the `net>' prompt
returns and the window title reverts to `Net <version>'.  Back at the `net>'
prompt you can enter ka9q commands again, but the telnet session isn't dead -
it's just hiding.  If you type the command `session' at the net prompt it
will list all active sessions - they each have a number and you can return to
them by entering `session <number>'.  One of the sessions will have an
asterisk by it - that is the session you were most recently using, and
pressing return at the `net>' prompt will (usually) return to it.

If you close the session (say by logging out of a telnet session or
quitting an ftp session) once the remote site has acknowledged you will
be returned to the `net>' prompt.  If you can't work out how to finish a
particular session (you can't logout if you're using telnet to chat to
someone), you can kill a session with the `close' command - e.g., F10
followed by `close <session number>'.

Note that whilst you are in a session you will still see informational
messages from ka9q (for instance mail and news progress) - this is useful
because you don't have to return to the `net>' prompt to see how things
are going, but it's also a bit of a pain because they appear in the middle
of what you're typing.  Sometimes the `net>' prompt doesn't appear after
you press F10 - check the window title to see where you are.

Sessions buffer information sent from the remote machine whilst you're in
another session or at the `net>' prompt - to a degree.  I don't know what
the limit is - certainly 1 line, maybe 2.  It might even be more, but I have
a vague feeling that it isn't very much.

If someone telnets to you for a chat, you will see a message like `Incoming
Telnet session 2 from 158.152.9.18:1003'.  The `2' in the example is the
session number (so use `session 2' to connect to it), the `158.152.9.18' is
the IP address of the site telnetting to you, and the `:1003' is a
sequentially-assigned socket number (which you can ignore).  If you don't
feel like chatting to that person, just ignore the message...


Ftp
---

Ftp connections run as ka9q sessions and start out a little like telnet
sessions in that you usually have to login.  After that you send commands to
the remote ftp server to change directories, examine directory listings, get
files, etc.  Usually you will be using anonymous ftp - that means you give a
username `anonymous' (some sites accept ftp as an alternative) and give your
full e-mail address as a password (some sites ask for an `ident' - then you
need only give your username).  One site which is handy to try for test
purposes is ftp.demon.co.uk, which you can connect to with the command

    ftp ftp.demon.co.uk

or even just ftp ftp.  Another thing you can try is to ftp to yourself with
the modem offline (keeps the phone bills down whilst you familiarize yourself
with the commands).

If ka9q complains of an unknown host you will have to find the IP address
(see section on finger) and ftp to that instead.

Most ftp sites use a restricted Unix style syntax (though there are
variations).  You will also find that with most ftp sites you can give the
minumum unique abbreviation for a command, e.g., `c' can be used instead of
`cd'.  Useful commands (which are usually accepted):

    quit    this quits the ftp session, and will (after the remote machine
        acknowledges it) return you to the `net>' prompt.  Be careful that
        you only enter this command when you are connected to an ftp session,
        if you type it at the `net>' prompt ka9q will exit.  This command
        cannot be abbreviated.

    ls    brief directory listing giving names of files and directories, but
        you probably won't be told which is which.

    dir    full directory listing, giving file sizes, ownerships and
        some method of distinguishing ownership (on Unix you will see a
        string of letters denoting access permissions - `r' for read-only,
        etc. - directories have a `d' in there somwhere).

    cd    change directory.  Usually you change to a subdirectory with
        `cd <subdirectory>'.  You can move back up the directory tree with
        `cd ..' (sometimes you can also use `cdup').  The usual directory
        separator on unix systems is `/' and you can traverse more than one
        level if you wish, e.g.:

            cd foo
            cd bar
            cd fubb

        could be replaced by

           cd foo/bar/fubb

        The root directory is specified as `/', so `cd /' will take you to
        the root directory, whilst `cd /pub' will take you to the `pub'
        (public) directory (on the Arc this would be called $.pub).

        Many ftp sites make /pub your CSD when you connect, and those which
        do often prevent you straying - frequently if you type `cd /' you
        will end up in /pub.  Note that when you ftp to ftp.demon.co.uk
        you will be placed in the `real' root directory.

    get    get a file.  The file will be placed in your CSD, wherever that
        happens to be when you issue the file.  The format is `get <file>'.
        Ka9q will try to create a file with the same name - which will fail
        if you try and get something which isn't a valid RISC OS leafname
        (like name.ext, verylongfilename or $^@).  To fix this problem you
        can specify a local filename in the command, e.g.:

            get verylongfilename$.zip localfile

        which will copy the remote file to `localfile'.

        Arc ka9q does not support the `mget' (multiple get) command which
        allows you to transfer several files at once by using wildcards, so
        you'll have to do it the hard way.

    type    this shows or sets the type of file to be transferred.  Different
        OSs have different conventions about end-of-line markers for text
        files (as you will realise if you've ever seen a DOS textfile in
        a Spark archive).  You can tell ftp to convert end-of-line markers
        from the conventions on the remote system to Archimedes conventions
        with:

            type a

        where the `a' stands for ASCII (do this *before* you use the get
        command).  Obviously you don't want this conversion to take place if
        you are transferring an archive, executable or similar binary
        (non-text) file, so for this you use:

            type i

       where the `i' stands for image.  On most systems you can also use
       `type b' instead of `type i' (the `b' stands for `binary') and
       sometimes you can enter just `image' or `binary' (sometimes even
       `i' or `b').  Similarly you can often enter `ascii' to select ASCII
       transfer.  The default type is usually ASCII, but you can check by
       just entering `type' without an argument.  You may forget to set the
       type at first, but once you've transferred a big Sparkive in ASCII
       mode you'll not forget again...  Unix compressed file (readable with
       Spark) normally end in `.Z' - so if you grab one of these you need
       type i.

    put    this transfers a file *to* the remote site.  Obviously sites are
       a little more sensitive about this sort of thing.  DIS allow uploads
       (of *useful* software, usually having some relevance to their
       subscribers - e.g., an improved mailer) to /incoming - you should
       then e-mail a description of the file, what machine it's for, etc. to
       [e-mail].

    abort   when you realise you've started to get the wrong file, or you've
       set the wrong type, or conditions mean the transfer has slowed to a
       crawl, abort will kill the transfer.  Some ftp servers are rather
       antisocial and perform a quit when you abort (so if you aborted
       because you had the wrong file you then have to start a new ftp
       session to get the right one.

    hash    this is a very useful command which puts a #-sign on the screen
       every time a block of data has been transferred so you can estimate
       progress.  This just doesn't work on the Arc, so when people tell you
       about it, ignore them.

Whenever you type an ftp command you will (eventually) receive an
acknowledgement message (usually prefixed by something like `220-', which
you can ignore).  This can be confusing during a get operation as the
acknowledgement that the get command is being processed can come well into
the file transfer, and the wording is such that it is easy to mis-interpret
it as meaning the file transfer is complete.  One way to check is to enter
`xxx' - if the transfer is in progress you will be told that the only
acceptable command is abort (though quit will often also be accepted), whilst
if the transfer has actually completed you will be told that the command
`xxx' is not understood.  Actually, and somewhat perversely, the message
telling you that the file transfer is complete can appear while there are
still blocks of data in the pipeline - so check the modem lights before
quitting...

Most ftp sites have a textfile in the root directory which lists all the
files available for transfer.  On Unix systems this is called `ls-lR'
(Unix filenames are case-sensitive) because the command to recursively list
all files is ls-lR.  Other systems may have something called
000directory.list - you'll just have to look in the root directory until
you spot something that looks like it might be the file listing.

The DIS ls-lR listing is just under a megabyte, so if you want Archimedes-
related files (what few there are) just cd to /pub/archimedes and do an ls.

If you are looking for DOS files (why?) DIS mirror (keep an automatically-
updated copy) of the famous SIMTEL-20 archive of PD DOS files (this is
maintained by the US military, although it is in the process of being
moved from the White Sands Missile Range).

Note that you receive no warning message if someone is ftp-ing to you, so
be careful about security (see the section on the FTPusers file).


Finger
------

Finger also runs as a session, but it is transitory in nature and once
the (limited quantity of) information has been provided the session will
close automatically.  Note that if it's taking finger a long time to return
the information and you leave the session then the information will be lost
if it comes in whilst you're away.

Do not type anything into a finger session - for some reason this prevents
the information ever being sent (remember the display bug where characters
appear to get lost - this can affect the carriage return at the end of the
command - the solution is to press one of the cursor keys).  Finger sessions
can also get confused if you set more than one in motion at once...

If someone fingers you, you will see a message like `You're being fingered
by 158.152.9.18:1005!'.  The `158.152.9.18' is the IP address of the site
telnetting to you, and the `:1005' is a sequentially-assigned socket number
(which you can ignore).

Demon have a modified finger server running on gate and post: if you finger
<site>@gate it will tell you the IP address and other (possibly) useful info.
Note that when <site> is a DIS address you give the *full* sitename - e.g.,
finger sktb.demon.co.uk@gate will give you the IP address [158.152.9.18].
Remember that even if you modify your domain file this will not take effect
until the next time you start ka9q, so if you wanted to telnet in for a chat
during that connection you would need to use the numeric form of the address
(telnet [158.152.9.18] instead of telnet sktb).

The modified finger server on post also serves another function when used
with *abbreviated* sitenames of DIS subscribers - it tells you how many
mail messages are waiting for that site.  E.g., finger sktb@post will tell
you how many messages are waiting for sktb.  If you finger your own sitename
you will also be told who each message is from and to.


Hanging up
----------

Enter the `quit' command or select the quit option from ka9q's icon-bar
menu, then use your comms program to hangup the modem.  Most versions of
ka9q scramble the serial port when they exit (which persists even though
both Jonathan and Anthony changed the code to try and fix it) - you can send
data out (which is why you can use your comms program to hangup), but
incoming data vanishes into thin air.  The only cure is to quit your comms
program and reinstall it (occasionally you may have to do this a couple of
times). It is possible that the version of ka9q which supports serial block
drivers does not suffer from this problem, but I've never used it so can't be
sure.


Other Commands
--------------

Other useful commands include:

    Record    this allows you to record a telnet session to a file.  Use:

            record <file>

        to record the current session (the one marked with the asterisk when
        you use the `session' command into <file>.  When you're finished,
        use `record off' to finish.  Note that you cannot record ftp
        sessions.  Theoretically you can record finger sessions, but in
        practice the incoming information usually vanishes before you can
        start recording.

    asystat    shows how many characters have been transmitted/received and
        how many overruns occured.

    ip status    shows how many ip packets have been transmitted/received
        and how many errors of various sorts have occured.  It is a good idea
        to check this (and asystat) during your first-ever connection to DIS.
        If there are lots of overruns or errors then you may have a problem
        with your serial port not coping with the speed (a problem which
        occurs frequently with RISC OS 3 - get hold of the serial port
        patch).

    tcp status    this lists all the tcpip connections.  Even if you
        aren't doing anything, connections will be shown for the various
        servers you started in autoexec (like start smtp, echo, discard,
        etc.) but if the number against the `remote socket' for a
        connection is 0.0.0.0:0 then that connection is not in active use.

        You can use this as a way of checking that it's safe to logoff, or
        if you see unexplained disc activity you can check if someone is
        ftp-ing to you (remember you get no warning message) - look for
        a local socket number ending in :21 with a remote socket number
        other than 0.0.0.0:0.


Bugs
----

Apart from problems already mentioned, there is a bug which until recently
affected all versions of ka9q on all platforms - this concerns the transfer
of mail and news in both directions (the latest PC ka9q has fixed the bug
for mail but not for news).

Any outgoing news/mail message which has a line starting with a full stop (.)
should have another full stop appended to it by ka9q before that line is sent
to the remote site.  Any incoming news/mail message which has one or more
full stops at the start of the line should have the first full stop removed.
The net effect is that as long as both sites perform these actions, the
messages will end up the same as they started (why this has to be done at all
is to do with the mechanics of the message transfer).

Unfortunately ka9q does not do either action, so outgoing news/mail which
has a full stop at the start of the line will end up without one, whilst
incoming news/mail which ought to have a a single full stop at the start of
a line will have two.  This is not usually a serious problem, with one
exception.  Uuencoded files (see the section on Mail) sometimes have the
penultimate line start with a dot (only the penultimate line can ever start
with a dot, and even this is rare) - the dot gets doubled and the archive is
corrupted.

I found this problem when I obtained a uuencoded archive from the Newcastle
info-server and it was corrupted - it took a long time for all concerned to
figure out what had gone wrong.



BM
==

BM is the horrible mailer which comes with ka9q (on the occasions Anthony
Frost actually remembers to include it).  It is a real pain to use, and is
something you only perservere with until you get something better (like
ReaderS).


Installation
------------

You need to modify !BM.BMconfig to reflect your details.  As an example,
mine looks like:

    host sktb.demon.co.uk
    user pla
    fullname Paul L. Allen
    reply [e-mail]

You should replace the sktb.demon.co.uk with your own fully-specified site
name.  The user is the username you will use to send/receive mail (remember
the username must be a valid RISC OS leafname, and have a maximum of 8
chars).  Fullname is your own name (or a pseudonym if that's what you want).
Reply is the address which is inserted into the `Reply-to:' field of your
messages - try and get this one right or you won't get any replies.

BM can only handle a single user (so remember to check the postmast mailbox
by hand occasionally), but you can get round this by having several config
files named after users, and using obey files to delete BMconfig and copy
the appropriate config file to BMconfig.

Some versions of BM allow you to create a file !BM.Sig, the contents of
which are appended to the end of any mail message you create.  This usually
holds some informative or witty comment - it is considered bad taste and a
waste of bandwidth to have more than 3 lines of signature.


Using
-----

BM has many problems.

    1)  Lines do not automatically wrap, so you must insert carriage returns
        manually at the end of each line.  If your lines are longer than
        80 characters (because you forgot to press return) you will annoy
        people, if they're longer than 1024 characters they will be
        truncated en-route and people will miss your words of wisdom.

    2)  It isn't a cursor-driven text editor.  You can type, and you can
        use the delete key - that's all.  And once you've pressed the
        return key that line is cast in stone.

    3)  You can't quote bits of other people's messages when you reply.

    4)  There is a command (~r) that allows you to include a pre-prepared
        text file, but it doesn't seem to work.

It is possible to work around some of these problems (but if you do this
make *sure* you haven't used ka9q's `smpt timer' command to have ka9q scan
for mail every so often or a half-formed message may go out).

For new mail use BM to set up the address and subject, and send a blank
message (no text).  Then go to !MailDir.spool.mqueue.text and use Edit to
write the body of the message into the blank.


For replies, use BM's save option to save the incoming message.  Then use
the reply option to reply to the message, but again send a blank message.
Use edit on the saved message to `quote' it and compose your reply.  So if
the incoming message said:

    Hello Paul.

    How are you?

The first stage would be to `quote' it (indicate which bits came from the
original message - this is conventionally done by prefixing the lines with
a `>' character:


Then indicate that you are in fact replying by adding something along the
lines of:

    In message <[e-mail]> you wrote:

    > Hello Paul.

    > How are you?

Next, insert your own comments, and trim out any excess quoting

    In message <[e-mail]> you wrote:

    > How are you?

    I'm fine thanks.  How are you?

Note that the `> Hello Paul' was deleted - the sender doesn't want to see
that again, but the `> How are you?' was retained to jog his memory as to
what your answer refers to.

Finally use Edit to take your composed message and insert it into the blank
message in !MailDir.spool.mqueue.text.


Alternatives
------------

After you get fed up with BM (which will be very shortly after you start
playing with it), you might want to consider using ReaderS which handles
both mail and news.  Send 10 (the bulk of which is divided between the RNLI
and the Cornwall Air Ambulance Trust) to

    Anthony Frost
    VCS Kernow
    10 Whiterocks Park
    St Anns Chapel
    Gunnislake
    Cornwall
    PL 18 9EF