------------------------------------------------------------------------
           Socketeer release 0.13                          (29 Aug 1998)

                                                        by Matthew Bloch
                                                        <mattbee@eh.org>
------------------------------------------------------------------------

     ********************
     *** What it does ***
     ********************

Socketeer is (intended to be) a stress-free way of connecting an Acorn
machine to the internet through a telephone (or ISDN) line.  I wrote it
because there aren't any good, free, uncomplicated and reliable internet
diallers around for RISC OS; certainly nothing to touch the ease of use of
Windows 95's Dial-Up Networking.

     ************************
     *** What you'll need ***
     ************************

These need to be installed on your computer for Socketeer to work:

- Acorn's latest Toolbox modules (from around December '97)
- !FreeNet or !Internet
- The ANT / Acorn Resolver module
- !SerialDev, the block serial drivers
- Either Sergio Monesi's or Acorn's PPP module
    (Sergio's PPP driver will only be used if it is registered, and thus not
     subject to the 15-minute connection time)

Note that the PPP, PPPdriver and Resolver modules (except for FreeNet's)
*must* go inside the !System.Modules.310.Network folder, otherwise Socketeer
won't find them (though you can alter this easily enough, I want to keep
standards!).

Also, make sure you have a suitable Choices folder set up-- this should be
fine with all RISC PCs, and older machines as long as they use Acorn's !Boot
structure.

If you are lacking any of these, you ought to go to

   http://www.soup-kitchen.demon.co.uk/software/socketeer.html

before continuing, or ask your nearest friendly PD library for the
relevant modules (such as APDL) if you don't have internet access.

     ******************
     *** Setting up ***
     ******************

Copy Socketeer to wherever you can find it most easily, or (like me) in your
!Boot.Choices.Boot.Tasks folder so it loads on startup.  After loading it for
the first time, go straight to the Setup... window off the main icon, rename
the Default setup, and enter the details of your internet connection into the
relevant boxes.  If you have accounts with more than one service provider,
click 'Add...' and repeat the process for as many accounts as you have. 
Before clicking on 'Save changes...', make sure you've chosen the account you
wish to use primarily.

 Modem
 ~~~~~
The Modem setup is all pretty standard: the only thing you might need
to change is the speed if your modem doesn't support 115200 baud, or if
you've got an old computer which won't go above 19200.  The 'Drop connection
cleanly' option will mean that Socketeer trusts your PPP module to drop the
connection rather than dropping the DTR line; I'd suggest you only use this
if you know what it means ;-)

 Internet provider
 ~~~~~~~~~~~~~~~~~
If you don't know what the internet provider settings mean, give your ISP's
helpdesk a call, explain your situation, and they'll be able to fill in the
fields for you.  Same for your account details, though they should have sent
you these by post.  PEOPLE USING ACORN'S PPP MODULE TAKE NOTE!  You'll need
to put a PAPSecrets file inside your !Internet.files.PPP folder, of the
format:

j.smith * password

(e.g. your login name, a space, then an asterisk, then a space, then your
password, then a new line) for as many accounts as you use PAP with.  Also,
since 0.12 you *must* explicitly enter your ISP's gateway address so that the
connection monitoring code knows your nearest 'external' internal address.

PLEASE NOTE that despite appearances, the only connection types supported are
PPP and PPP (PAP) which seems to cover 99% of commercial ISPs.  I'm working
on SLIP and the rest, honestly!

 Your account
 ~~~~~~~~~~~~
This is where you put your login details: your ISP should have sent you
these.  If you don't want Socketeer keeping track of your password (which is
stored unencrypted on your hard drive), you can ask for it to prompt you,
either before it even dials, or it can prompt you at the moment 'when
needed', i.e. at the moment it needs to send your password to the ISP for
confirmation.

The reason I put this second option in is for people who need to use 'key
fobs' to generate passwords which are sometimes time-critical to within a few
seconds.  For the uninitiated, some companies are worried enough about
security that they issue little credit-card sized 'key fobs' which generate a
password given the current time, so that people not possessing these cannot
possibly use the company system.

 Connection management
 ~~~~~~~~~~~~~~~~~~~~~
Socketeer can be made to dial your internet provider unattended at various
times of the day.  If you specify, for instance:

  0900 1200 1600-1700

...Socketeer will connect at 9am, 12pm and 4pm daily (and in this case, the
4pm connection will disconnect an hour later); if you do not specify a time
for the connection to be terminated, Socketeer will use the idle time, so
that once your mail has finished downloading, disconnection will occur within
the time you specify.

To explain: after an 'idle' period where no internet traffic has gone
backwards or forwards, Socketeer will disconnect the modem to save on your
phone bill.  This 'idle' time also applies to connections you initiate
yourself, in case you leave a download going then go off to make the tea like
I do sometimes ;-)  The only problem is that due to the way that Socketeer
monitors the status of your connection, there is always some residual 'ping'
traffic going backwards and forwards, so it also asks you to set an idle
threshold, i.e. the maximum amount of traffic that Socketeer can count as
'idle'.  See the statistics section later for more on this.

Specifying a disconnection time like that is useful if you want to be able to
telnet into your Demon (or other fixed IP) account while away for the day.

'Retry dead connections' specifies the number of times Socketeer will retry a
connection if the packet driver dies prematurely, that is to say if the modem
has successfully made a connection and BT has debited 5p from your phone
bill.  If a connection was started automatically, the redial will happen
immediately; if you initiated the connection, you'll be asked.

The online and offline scripts are files or applications which will be run
when Socketeer connects or disconnects-- note that the offline script will
not be run if Socketeer doesn't successfully get online.

DISCLAIMER: Please note that although I have tested these features to the
best of my ability, you use them at your own risk and I will not be held
responsible for connections which have stayed open all day, either by
misconfiguration or bugs in the software.  Having said this, I entrust
Socketeer to check my mail while I'm out or asleep, so if it happens to you,
divine justice will mean it'll probably happen to me at some point.

 Front-end
 ~~~~~~~~~
Here are three miscellaneous options which are largely a matter of taste:

'No sound effects' turns off the audible warnings Socketeer gives when the
connection is faltering, or when it is about to idle out.

'Confirm disconnections' will ask you to confirm your actions every time you
ask Socketeer to disconnect.

'Right hand button open stats' changes the default action of the right-hand
button on the icon-bar.  Normally it acts as a short-cut to connect and
disconnect you from the internet, but you may want it to open the Statistics
window instead.

 Launcher
 ~~~~~~~~
Click the 'Launcher...' button to edit the application launcher
configuration: this is still a bit raw, since you'll have to edit a text file
which simply contains lines of the following format:

<application path><TAB><sprite to use><TAB><text to display underneath>

e.g. mine reads (verbatim):

ADFS::Buttercup.$.Internet.Clients.!Fresco	!fresco	Fresco
ADFS::Buttercup.$.Internet.Clients.!Talker	!talker	Talker
ADFS::Buttercup.$.Internet.Newsbase.!Messenger	!messenger	Messenger
ADFS::Buttercup.$.Internet.Clients.!ANTterm	!antterm	Terminal
ADFS::Buttercup.$.Internet.Clients.!FTPclient	!ftpclient	FTP
ADFS::Buttercup.$.Internet.Clients.Tools.!Ping	!ping	Ping
ADFS::Buttercup.$.Internet.!Attacher	!attacher	Attacher
ADFS::Buttercup.$.Internet	directory	Open Internet folder

and the file format is pretty strict: you should only put one tab inbetween
each field, and make sure the last entry has a newline after it, otherwise
Bad Things will happen.

Technical note: Each item will be Filer_Booted when Socketeer starts up, and
Filer_Run when double-clicked on to minimise Socketeer's involvement with the
relevant applications.  Hence ou can hold down shift while double-clicking to
open application folders too.

     **************
     *** In use ***
     **************

Once you have chosen a setup, Socketeer will connect and disconnect when you
tell it to: clicking the right-hand button on the main icon mirrors the
functionality of the menu option and the big button in the main window. 
Also, Socketeer will notice if the PPP module disconnects for some reason,
though it won't always be able to help you diagnose why.

If your connection is within the 'idle' threshold you specified in the setup
window, you'll see Zs appear on the icon.  If you're seeing these Zs when
your connection *isn't* idle, or you're not seeing them when it *is*, you
need to adjust your setup slightly; see under 'statistics'.

If Socketeer detects that the connection is faltering, a white exclamation
mark will appear on the icon-bar.  After a little more time (usually
about 10secs), when Socketeer is convinced something is amiss, a visual and
audible warning will appear.  After a little longer, Socketeer will assume
the connection is stuffed, and disconnect.  See below for more detail on
this.

Every time you connect or disconnect from the internet, Socketeer will write
the time and date to its log file, which you can analyse later by clicking on
'Call log...' from the main menu.

     *****************************
     *** Statistics and idling ***
     *****************************
     
You can open the statistics window by choosing it from the icon-bar menu, or,
if you've ticked the appropriate box in the Front-end section of the Setup,
you can click adjust on the icon-bar icon.  The first and most obvious thing
it shows is the CONNECT speed reported by the modem; this ought to reflect
the baud rate at which you have connected to your ISP, though it can change
midway and you wouldn't know anything about it.

Also, while online, Socketeer will regularly 'ping' your ISP's gateway
address (i.e. the nearest machine to you on the internet) to check that the
modem and your internet provider are still responding properly.  A ping is so
called because it expects a response from the address that it pings, a little
like sonar.  If Socketeer doesn't get a response within 2 seconds, it counts
this towards your connection's 'Latency'-- this indicator will slowly
increase if your connection is unreliable, and will disconnect after 20 pings
have not been responded to.  The Latency indication is only worth paying
attention to if you suspect something is wrong with your connection: to gauge
the actual speed, have a look at the 'Traffic' bar which will tell you how
much data is being passed through your modem.  Note that the exclaimation
mark apeears on the icon bar after 2 lost pings, and the audible warning
after 10.

Socketeer decides whether your connection is 'idle' by looking at the traffic
bar every half-second and comparing it against the idle threshold in the
current setup.  When idle, you'll see Zs appear on the icon bar.  To
calibrate your idle threshold (and I apologise for this unsatisfactory way of
doing things), connect Socketeer to your ISP and watch the traffic indicator:
it will most likely flicker between zero and a lowish reading.  Your idle
threshold should be set a bit above this; don't worry if the reading jumps up
occasionally as Socketeer will ignore uncharacteristics 'blips' in the
traffic.  No, I don't know why it does it either ;-)

     ********************
     *** Other issues ***
     ********************

Some may find it worrying that Socketeer doesn't use any scripting: I decided
not to go for event a simple script language because 99% of ISPs I've
encountered ask users to login in exactly the same ways.  What it does is to
read a list of prompts and responses to expect from the server; this file is
called Prompts, and is stored in '!Socketeer.Bits'.  If you find Socketeer
can't log you in, it's probably because your ISP's prompts are not stored in
this file: please mail me any useful additions to this (Technical
note: ESPECIALLY if you find Socketeer can't cope in a particular situation,
or you've had to bodge something which ought to be included in the
front-end).

ta ra,

-- 
Matthew
