OS/2 Shareware BBS: 35 Internet/35-Internet.zip/tserve11.zip/TSERVE.DOC

Text File | 1996-02-02 | 15KB | 295 lines

TSERVE V1.1b Technical Documentation.

        This document covers some of the more detailed technical issues and
specifications. Most of the configuration information you need can be found
in the sample .CFG and .USR files. Other technical information is available
in the .ISP file which is a text document about setting youself up as an
internet service provider using warp connect.

        TSERVE is a rudamentary terminal server program for OS/2 Warp
Connect. If you have a dedicated connection to the internet, and a machine
running OS/2 warp connect, you can be an internet provider. The .ISP
document explains how to set up a system just like the one we use here at
Micro-Neil. (more or less)

        TSERVE is a small command line utility that should typically be run
in a .CMD file. We could have made it into a large, impressive, PM
application with lots of buttons and bells and whistles, but that would
have been a lot more than was needed. Also, if you're serious about
providing internet access, the smaller, faster program is much better. We
are looking into a PM configuration utility for a later version of TSERVE
which will allow you to use the familiar notebook strategy for modifying
and updating all of the configuration files you need for TSERVE. Stay tuned
on that one :-)

        I reccomend that you install TSERVE in it's own directory so that
you can keep all of your configuration information in one place. This isn't
necessary, though, since TSERVE will run from anywhere as long as the
configuration file is accessible, and the paths listed in that file are
explicit enough. TSERVE always looks for files from the perspective of the
current working directory. Therefore, if you run TSERVE from your BBS
directory, and your configuration and user list files are somewhere else,
you need to have complete paths in your configuration file. The sample
configuration doesn't do that, so pay attention.

        To start tserve, you simply run the program and pass it the path to
your configuration file. From then on, it's up to the configuration file to
tell it what to do. Please read all of the text files in this package
before you attempt to run tserve. You will save yourself a lot of headaches
in the long run. An example command line might be:

tserve node1.cfg

WHAT'S NEW WITH 1.1b...

    It came to my attention (how silly) that most people need to run a
front end mailer program on their BBS's. They couldn't use TSERVE1.0b because
it would reset the modem. TSERVE1.1b includes an optional command line switch
that tells TSERVE a caller is already connected. When this command line switch
is turned on, TSERVE will skip all of the modem initialization stuff and pick
up right where it sends the greeting. From there on, TSERVE runs the same. To
Start TSERVE after a front end mailer, use the command line:

tserve config.cfg -o[SPEED]

    This option let's you run TSERVE where you would normally run your
BBS program. TSERVE will then proceed to identify the user and either start
your BBS program or PPP as appropriate.

    If your mailer can provide the connection speed of the caller, then
you can include it after the -o with no space in between.. ie. -o19200.
TSERVE will use this value as if it picked it up from the modem's connect
message. If you do not provide a speed (ie. -o ) then TSERVE will act as if
the modem connect message did not include the caller's speed, and will assume
the locked baud rate included in the .CFG file.

    TSERVE cannot accept a hot com handle from Maximus, any other BBS, or
your front end mailer program. This is because the PPP program cannot be started
with a hot file handle. The PPP program must be given a com port name. Also,
your front end mailer must open the com port in a shared mode or else you will
not be able to start PPP or run TSERVE.

HOW TSERVE WORKS...

        When TSERVE starts, the first thing it does is read the
configuration file. This file tells it what com port to use, what speed to
expect, the path to the user list file, and all of the other parameters
that are important. You can change this file with a regular text editor,
and the sample is well documented. I reccomend that once you get up to
speed on how to configure TSERVE you should delete all the comments and
make your configuration files a lot shorter. This will make TSERVE load
just a bit faster, and there's less chance of something in one of your
comments being accidentally interpereted as a set-up parameter.

    If you start TSERVE without the -o option, read on. If you are
starting TSERVE after a front end mailer program, skip to SENDING THE
WELCOM GREETING...

        The next thing TSERVE does is reset and initialize the modem. It
will drop DTR, wait a few seconds for that to sink in, then raise DTR and
send the INIT: string to the modem. You should have your modem set up to
reset, hang up, and return to the command state when DTR is "cycled." You
should also make sure that another program hasn't set the mode of the com
port so that DTR cannot be used this way. OS/2 is very robust in it's
treatment of com ports and allows programs to establish elaborate and
strange handshaking arangements with other devices. You should make sure
that the DTR mode is ON (look up your OS/2 documentation on the MODE
command) to insure that the DTR signal can be controlled directly by
TSERVE. There is more information about initializing the modem in the
sample configuration file.

        Once the modem has been initialized, TSERVE will wait for a caller.
When the modem sends back a "RING" signal, TSERVE will instruct the modem
to answer the phone "ATA". Once the connection is made, TSERVE will attempt
to read the caller's connect speed from the connect message and store it
for later use. For example: "CONNECT 24000 LAPM". If your modem doesn't send
the connect speed as part of the message, TSERVE will default to the fixed
baud rate you set in the config file.

        IT IS IMPORTANT TO NOTE: TSERVE DOES NOT SET THE COM PORT's SPEED
OR OTHER PARAMETERS, IT TAKES THINGS AS IT FINDS THEM. YOU SHOULD SET THE
COM PORT's OPERATING PARAMETERS USING THE MODE COMMAND.

SENDING THE WELCOME GREETING...

    If you started TSERVE with the -o option, for use with a front
end mailer program, then this is where all the action starts.

        When the modems are connected, TSERVE will send the welcome file
and prompt the user for a login code. The user has 5 chances to enter a
login code. If they skip it by pressing <cr> without entering anything, the
login: prompt will be displayed again. This is to allow for some automatic
login scripts (such as OS/2's Dial Other Proviers) which send a few extra
carriage returns just because. TSERVE will ignore them.

        After reading the dailer's login code, TSERVE will open and read
the user list. If it locates a user entry with the same login code, it will
read the line from the user list and prepare to verify the user. If the
line contains a password, the user will be prompted to enter the password.
TSERVER will echo periods for each letter, and backspace does work,
however, the password function is written with the assumption that it will
be talking to a dial-in script engine that's not likely to make a mistake.
There is only one chance to get the password right. If the password is
wrong, the caller is immediatly disconnected and TSERVE will end.

        If the login code is not found in the user list, TSERVE will spawn
the BBS program using the command line listed in the configuration file.
Please read the sample file documentation. You can create just about any
command line you'd like using the macro's provided by TSERVE.

        If the login code is found in the user list and the password is
entered correctly, then TSEVER will spawn the PPP program using the command
line listed in the configuration file. Again, you can create just about any
command line you need to with the macro's provided by TSERVE. This includes
HOST and USER IP addresses as defined by the configuration file and the
user's entry. It is possible to assign specific addresses for each user.

        The BBS and PPP command lines executed by TSERVE need not be the
programs themselves, although this is the best approach. It is possible to
execute .CMD or .RXX programs in their places so that you can handle extra
processing or error handling. This might be the case if you need to look
for net-mail processing from your BBS package (like Maximus) or if you want
to make special routing entries before and after running PPP.

        TSERVE opens the com port you define in the config file in a shared
mode so that PPP can have control of it. TSERVE also provides the hot file
handle so that you can run a package (like Maximus) which needs that. Such
a program is considered a "child process" so it inherits access to the open
file handle.

        Whatever program you run from TSERVE must end! If it doesn't end
and give control back to TSERVE, then TSERVE can't help you. This is
especailly important for Maximus user's who typically run their program in
a loop in a .cmd file. For these users, I reccomend that you either run
Maximus directly from the TSERVE program as I do in the examples, or that
you remove the loop and the mode command from your Maximus .cmd file. If
you've been able to get Maximus running happily for you, you should have no
trouble understanding how to set this up.

        Once a caller has been handled, TSERVE will end and close the com
port. Before it does, it attempts to hang up the modem. TSERVE will wait a
few seconds, send "+++", wait a few more seconds (guard time) and then send
"ATH0". If your modem is already hung up (on hook) then this will have no
ill effects. If your modem isn't already hung up, it should regain control
of the modem gracefully.

        TSERVE should be run in an endless loop in a .CMD file. Please take
a look at the sample .cmd file that I've included. This is the same file I
use on my system.

        Each incoming line needs to have it's own configuration file. Most
of the time, the only differences in the command files are the task number,
the com port, and the default IP addresses. The rest can be copied
verbatim.

        TSERVE will share the userlist file (or any other except it's log)
with other nodes. However, it is possible to set up different userlist
files for each node, or group of nodes, by specifying different files in
the configuration.


LOGGING AND ERRORS:

        TSERVE provides a simple, but effective error and logging system.
You can have TSERVE produce a log file containing all of it's activity, or
just bits and pieces. Then you can use this file for billing purposes if
you want to charge by the hour or minute. You've probably noticed, however,
that most ISP's these days are offering unmetered access, so it's up to
you. The configuration file contains information on formatting your log
file and deciding which events you want included. Listed below are all of
the evnets, there errorlevel (if TSERVE will exit), and the event flag(s)
that will include the event(s) in the log file.


ERRLVL  FLAGS   EVENT STRING

10 -- Command line error, not posted to log file.
11 -- Initialization error, not posted to log file.
12 -- Invalid or unreadably configuration file, not posted to log file.

        B       TSERVE STARTED.
13      X       ERROR OPENING COM PORT!
        S       SECURITY EVENT, WRONG PASSWORD!
14      X       ERROR INITIALIZING MODEM!
0       XE      TSERVE ENDING, NO CALLER.
        R       RING
15      XN      NO CONNECTION AFTER RING!
16      X       ERROR SENDING HELO!
17      XO      FAILURE TO GET LOGIN!
        L       LOGIN.
18      X       ERROR READING USER LIST!
19      XQ      BAD/NO PASSWORD!
        P       PASSWORD.
20      X       SPAWNING PPP DID NOT RETURN 0!
21      X       ERROR SENDING POST!
22      X       SPAWNING BBS DID NOT RETURN 0!
0       X       UNCERTAIN HANGUP!
23      X       ERROR CLOSEING COM PORT!
0       E       TSERVE ENDED.
        I       STARTING PPP LINK.
        J       ENDED PPP LINK.
        M       STARTING BBS LINK.
        Z       ENDED BBS LINK.

TSERVE LICENSE:

        TSERVE is a shareware program. It is NOT FREE software. You are
free to use this package for 30 days on a single computer while you
evaluate the program. If you continue to use it after 30 days, you MUST
register your copy of TSERVE. If you intend to use TSERVE on more than one
computer, you must register it for each computer you install it on. The
price for the registered version is $60 (US dollars). You can register
your TSERVE package by filling out the order form in ORDER.TXT and faxing,
mailing, or e-mailing that form to Micro-Neil. You will receive a disk with
a registered version of the program, and you will be entitled to all minor
upgrades within the current major version.

        You may freely distribute the TSERVE10.ZIP package provided that
you do not charge for this distribution and that you make NO ALTERATIONS
whatsoever to the contents of the file(s).

        You may not include all or part of the TSERVE package in other
software, documentation, or any other media without the express written
consent of Micro-Neil.

        You may not disassemble or modify the executable(s) contianed in
this package, and you may not copy or reproduce portions of the files
without express written permission from Micro-Neil.

        If you use this package for any period of time, you are agreeing to
abide by the terms of this license.

*********

        This software is not guaranteed to work on your system, nor is it
guaranteed not to cause harm to your system or data. You use this program
at your own risk.

        If this program causes any damage or data loss by it's use or
misuse by you or anyone associated with you in any way, Micro-Neil may not
be held responsible for any loss or damages, wether directly or indirectly
caused by the use or misuse of this program or it's documentation.

*********

        At Micro-Neil we feel it is very important for our products to
perform as we advertise. If you have trouble with any of our products,
please notify us of your problem with as much detail as possible so that we
may have the oportunity to correct the problem and improve the product. We
also welcome any suggestions for improvemtents or new products or services.
We sincerely hope that our products can help you achieve your goals.

***************** CREDITS ************************************************

Special thanks to:

Chris Haddox    Who helped solve the arp / routing problem.
David Klett     Who enlisted and supported outside users in testing.
Linda McNeil    Who helped edit and review the technical documentation.
Puffins         Who reminded me when it was time to sleep, and time to fill
                her food bowl.

-Peter G. McNeil