
      *** THE MORE COMPLETE 'README' 07/09/1994 version 1.4 (ALPHA) ***

   This document is the installation instructions and admin guide for the
   (x)convers server support for Linux, this README file has been written
   by Darryl Miles, G7LED (C) Copyright 1994.  Do not reproduce any part of
   this file without reference to your source, and if you do reproduce any
   part of it make the original in complete form available.

   First of all the files you should have enclosed in this archive are:

   Binary Distribution: conversd.bin.tar.gz (-O -m486) (libc 4.5.26)

   Makefile      - The Makefile
   README        - Text info (This file)
   convers       - Linux executable
   conversd      - Linux executable
   conversd.conf - Example /etc/convers/conversd.conf file
   conversd.motd - Example /etc/convers/conversd.motd file
   conversd.mesg1
   conversd.mesg - Example /etc/convers/conversd.mesg file
   conversd.help - Conversd on-line help file
   userinfo.sh   - User info conversion utility old to new
   contrib (dir) - Extra stuff you may be interested in, see README there.

   Source Distribution: conversd.src.tar.gz

   Makefile      - The Makefile
   README        - Text info (This file)
   conversd.conf - Example /etc/convers/conversd.conf file
   conversd.motd - Example /etc/convers/conversd.motd file
   conversd.mesg1
   conversd.mesg - Example /etc/convers/conversd.mesg file
   conversd.help - Conversd on-line help file
   userinfo.sh   - User info conversion utility old to new
   contrib (dir) - Extra stuff you may be interested in, see README there.
   convers.c     - Source code files...
   conversd.c
   libutil.a     - Libraries...
   liblzw.a
   lzw.h         - Header files for source code...
   mbuf.h
   buildsaddr.h
   md5.h



Features:
=========

  Client - The client, has a number of options, these will override any other
           settings.  If the environment var USERNAME exists it will use this
           as the user <tag>: otherwise LOGNAME.

           It now does not accept ANSI codes as an input, I decided to use
           this method rather than have the server remove all ANSI codes from
           the text.

           As of version 1.2 the client no longer looks up or uses the gecos
           field in a users /etc/passwd entry.  There is no further need for
           this as conversd looks after its own user information file.

           With version 1.3 there has been no change here.

           With version 1.4 added a informative message when the server link
           closes: "*** The convers server connection has closed."


  Server - I have added support for the UDAT command as has been used with
           JNOS, also the users can now use the params with the '/USERS' and
           '/WHO' commands on the system to request only selected users.  The
           sound option has been added and if currently off by default, it
           only send a bell when a user logs onto their channel.

           The 0x00 (NULL) character to users that have been idle for 10
           mins, and a <CR><LF> to TCP hosts that have been idle for an hour.
           This is hardwired in at the moment, but should help out for a
           while, as I concentrate on other things.

           By popular request, the servers will on getting a SIGHUP (kill -1)
           attempt to connect to all hosts in its peers table that it is not
           connected to already.  As the minimum wait time for retry is 1
           minute and maximum 3 hours, then having to restart convers in order
           to get the other links to kick in was a bind, as all users would get
           thrown off in the process.

           The 'xconversd' binary has LZW compression, and will listen on
           kernel port 3601, and unix file-sys socket /tcp/sockets/xconvers.
           /PEERS and /LINKS commands have changed to include the status of
           the compression, and also the far right Xmitted and Receivd in the
           /LINKS display are the actually physical number of bytes sent down
           the connection.

           /PERSONAL text size limit is now in there, of 43 characters by
           default, which is the length until just before it scrolls off the
           screen with a /USERS.


           Okay from the TODO section, I did for version 1.2:

           Fixes, the link will not be disconnected immediately upon any LZW
           decompression error(s) - not that you should have any.

           If the /..LOOP command is sent, all further /..USER info coming
           in will just be ignored.

           Support for /INVITE user@host is now an added feature, IMHO this
           should be compatible with the existing setup as not many systems
           have an AT in the user-name for obvious reasons.  Using the command
           without the @ will assume all hosts are the be check for that user.

           I have just looked above and seen that I have not explained
           /INV user[@host] some_text, has not been documented.  The text
           after the user-name is accepted, and sent to the user in the bell'ed
           invite message.  It can only be up to one line long, so you can
           send a 'Hi there' in the invite now.

           A command to display the last known time a particular user was
           logged onto convers for anywhere on the system also giving hostname
           info from that time useful to see if a friend has been on for a
           sked etc.  Hold a config file, so that once a user sets their
           personal text up at their local convers host it will retain it,
           along with all user preferences like default sound option, and
           link idle params.

           The command is /QUERY and it has been created at the expense of
           the silent command /QUIT, which has now been taken out to stop the
           conflict when using the abbreviated forms.  Data file name
           is /etc/convers/conversd.inf, and although it is text based it
           should not need editing at all.  If you do wish to hand edit it,
           then please work out what you are doing from the source and make
           sure that conversd is NOT running at the time.

           I was in two minds what this should hold, and if it should only
           be information about users connected to the local system.  It was
           decided that it should hold all convers user traffic information,
           as convers was not designed to have two g7led's signing on at the
           same time.  The users name, channel, login time, logout time,
           record update time, local system flags and personal text should be
           stored.

           If a user now sets their personal text up, when they reconnect to
           convers it will be restored upon the next connection to whatever it
           was left as.  One other interesting point is that if that same user
           logs onto another conversd system, and sets up personal text there,
           your local system will also change its personal text record to
           reflect.  Local system options, which is just currently the sound
           on/off are only affected in the file is that user so changes the
           option when on your machine.  The login times should be useful to
           see when a user was last on convers, and the data file should make
           interesting reading to the sysop. :-)

           I did for version 1.3:

           The configuration files have all now been moved to a /etc/convers
           directory, even the /tcp/convers.conf file, that has also been
           renamed to /etc/convers/conversd.conf.

           From the TODO section, a conversd Motd has been added this is
           always displayed to all users when they login the information
           is read in from the file /etc/convers/conversd.motd.

           There is a secondary type of MOTD file, called
           /etc/convers/conversd.mesg, this is only displayed to the user
           under the Motd when a user first logs in to your system and all
           logins by that user for the next 24 hours, then it will not get
           seen again, unless you modify the file in which case the user
           will see it again for the news 24hrs after the first login since
           the file was modified.

           There is support for a channel number -1, its being used as a
           conversd admin channel so when your system reboots conversd it
           sends out a short message here.  Also users are now notified why
           they are about to be chucked out of convers, when you SIGTERM it
           or the convers decides it need to auto reboot.

           Auto reboot will automatically restart the server if either the
           binary file is changed or the conversd.conf file is changed since
           conversd was initially started.

           Extra bomb proofing has been added into the source in a number of
           areas, and the debugging command line option has changed to a
           '-d<val>' the debugging now uses bit setting.

           In version 1.2 the hostname of your system still needed to be the
           FIRST line in the conversd.conf file.  This has now been fixed so
           thats its the first UNCOMMENTED entry in the file, this was
           brought to my attention by Paul G4APL.

           If the /INVITE command was issued with a connect to the user,
           then it would not display the text if the user was logged on a
           remote machine, this has now been fixed.

           I don't know if I introduced this bug or not, a quick glance says
           I didn't but if a user sends too much text before pressing the <CR>
           (and so telling conversd to process it) then the convers server
           just crashed with a Seg Fault.  The original implementation did
           look out for this problem, but didn't take into account any extra
           room for it to be sent down a host link with all the
           /..CMSG <user> <chan> info as well.  Now it just trims off the
           first 2043 bytes or so, and just processes that, extra room is
           taken into account now for host linking information.

           The time format in /QUERY was a little limiting in version 1.2,
           so its now changed to the ctime() format minus the year.  I hope
           this is better now.  The /QUERY command on its own will return
           the local convers servers status, including the softwares uptime.
           This information is also now issued under the MOTD/NEWS info on
           login.

           A bug which has now been fixed occurred when a JNOS machine has a
           remote user who has setup their personal text.  Two Linux
           machines with /..USER personal text support connect up and when
           the JNOS user's info gets sent it's rejected by the host linking
           up.

           User existence checking with UDAT, it now does not allocate
           resources for a user, it it does not exist.

           JNOS auto-detection on host links, or rather /..USER personal text
           support detection on hosts links.  Your personal text should
           appear in all the neighbor JNOS machines and beyond, it'll even
           be right from boot-up.  This is not fully tested yet, the 'P' flag
           indicates that /..USER personal text is supported, its on by
           default upon connection, then first bit of user info coming back
           without personal text will reset it.

           /HOSTS [all], without the 'all' it will display only hosts what
           currently have users signed on at.  With the 'all' option it'll
           display ALL known hosts.

           /LINKS now indicates the max number of bits being used on the
             link.

           A sequencing bug has been removed, when a host link drops out, it
           sends a sign off message about each user, it backs off the
           sequence number two before that sent in the message.  So it will
           re-accept the sign on message, note that the difference between a
           proper sign off and a sign off because of a link drop out, is
           that a proper one has an old-channel number set to 0 or more, and
           a link drop has an old-channel and new-channel number of -1.

           On-line help is now setup and available, the users users
           the '/HELP <topic>' for more detailing information.  They can
           even start a tutorial about using convers if '/HELP menu' is
           used.

           Finally syslog support has been added to trap some of the errors,
           and retain connection open and close information.

           WARNING: The conversd.inf file format has changed just a little,
                    you must run the utility script userinfo.sh, it will
                    reformat it such that all local users options and personal
                    text can be retained.


           I did for version 1.4:

           /INVITE changes so that it just displays a one line invitation
           message if no addition text was given, and a two line (second line
           with the addition text) if given.

           Reformat of the conversd.conf file, to account for some later
           additions with the host validation and channel distribution.  The
           HDAT text space has also been added to this file at the same time.
           This is the second uncommented line in the file, you are also
           recommended to have to 'default' line in your file just as in the
           sample 'conversd.conf' file.

           /..LOOP fix in h_user, it will now catch hosts using sequence
           numbers in USER info.  The /..LOOP bug which caused it to core
           dump occasionally was traces to a buffering problem, I hope this
           has now been resolved.

           A JNOS like maxq for ALL connections has been implemented, this
           is compiled in to a reasonable value of 15Kb (that which conversd
           itself has to buffer, because the transport mech's buffers have
           also over flown.

           I am now making forced logout's (that which the host connection
           died) while users were still logged in down it return a
           oldchan/newchan of -1/-1.  This will also trigger the fact that
           the sequence number given is NOT a *real* one, but one created
           by the host which experienced the disconnection an so will back
           it off by two, so that the hidden user problem goes away totally.

           When a turn around occurs the host 'via' are also switched over
           to the new host link in the process.  Also those users which are
           linked via the old host connection are now NOT repeated back to
           the other host.

           Idler timeout fix, if the conversd buffer remained non zero, and
           the host/user experienced a timeout, the stime was not updated
           to the current time because no data got written out of convers, so
           the idler timeout would occur next time the select call exited.

           The user option ground work is in, so that a user can switch off
           the idler timeout if the <NULL> causes any problems.
           
           '/QUERY <user>' will now display (if available) the localtime which
           that user last logged into convers.  This may look ugly if the
           user last user this local convers, as some of the log time will
           be identical.  Might be possible to cut this out if people think
           its needed.

           '/USERS last' will now display any users which logged out in the
           last 60 minutes, and their logout times, channels they were on
           last also their personal text from then.  '/QUERY last all' will
           display ALL using info which has still be held about users which
           are NOT actually logged in.  Including those users which were
           forced a logout.

           Syslog has been improved somewhat now.  Still using utility
           local6.  Wants a little standardization on the information, so
           that a script can examine the log for any real or potential
           problems.

           A SIGUSR1 will now dump the whole contents of the list of users
           to syslog.  All those held in memory, for debugging purposes.

           The user lockout flag has been added ready for naught word
           checker.  Also improvements to the host link lockout have now
           fixed it so no more host command what so ever are accepted on
           the link, as used with LOOP detection.

           A big change in the handling of the user info file, NDBM support
           has now been added to the system, improving lookup speeds.  The
           option parsing and setting has been improved, and an extra field
           which should indicate the number of sign off updates to the file.
           The default options will enable both DBM and the old TEXT file
           support just as well, it will slowly delete the entries (if found
           in the text file) from it, and insert info the DBM file.

           The groundwork for some more flags has been included, on which
           locks the personal text, so stop it from being zapped if the
           user signs onto a host that reset the personal text to nothing
           (by default, because it does not retain it, nor has it setup).
           Any setting of personal text from the localhost will override it
           in the userinfo database.  If the user logs on to another system
           which says the text is reset then it'll not zap the contents out
           of the database on the local system.  If the personal text is
           setup with something else on another system then the local database
           will be updated with it.

           /HOSTS <hostname> will now ask that remote host for information
           about that system.  It will return the version of software
           running, the local time of the system and information setup by the
           sysop about its location (usually).

           There have been a few myterious occurences of me being signed on
           as g7led@conscience.g7led and also g7led@conscience.  Some system
           out there truncated the hostname and it somehow got offered back
           to me.  The user/host name checking not have a compile time
           option of HOST8 and HOST10 for 8 and 10 chars significant hostname,
           also USER8 and USER10 for 8 and 10 chats significant usernames.
           These options have been added for experimentation/checking at the
           moment so its default stauts may change.

           /HOSTS to <host> and /HOSTS hops <num> has been added to the HDAT
           command, the facility of these allow a possible traceroute of
           servers to a convers host, also reporting of all servers X numbers
           of hops away.
           
           A user link is now appended to the link list rather than stuck at
           the head.  This has the effect of sending data out to host links
           first then to local users.

           Userinfo at a turnaround is not repeated back to the other host
           if the link to that user is via 'the other host'.  For fear of a
           /..LOOP coming back.

           WARNING: The conversd.inf file format has changed just a little,
                    you must run the utility script userinfo.sh, it will
                    reformat it such that all local users options and personal
                    text can be retained.


Installation:
=============

  For those with source code distribution, then they can do:

     make bin_clean
     make all
     make install
     userinfo.sh

  For those with binary code distribution:

     make install
     userinfo.sh

  If you wish to manually install then I would suggest putting:

   'conversd' (the server itself) in '/etc/conversd'
   'xconversd' (the compressed server itself) in '/etc/xconversd'
   'convers' (the users client) in '/usr/local/bin/convers'
     if you do not have this directory, then put it in /usr/bin/convers'.
   A directory /etc/convers needs to exist, in there goes:
     conversd.conf, conversd.help, conversd.motd, conversd.mesg,
     and the user database conversd.inf.


  You'll need to setup '/etc/convers/conversd.conf' according to the host you
  wish to link out of, and also your own host name.

    ***** NOTE: Please look at the information given in this file  *****
    *****       for its format, also PLEASE check it every time you *****
    *****       upgrade the server for a format change!            *****


  Now you have two servers, one called 'conversd' and the other 'xconversd',
  you should ONLY run the ONE server.  If you require LZW compressed links you
  run 'xconversd' if you don't at all you run 'conversd'


  The server must be run permanently to accept connections, this is done in
  the background with:

  /etc/conversd &

  The ampersand on the end is important to make the shell execute this
  program in the background, otherwise you won't get your prompt back.
  I personally start my convers in /etc/rc.net before I start LNET.
  Also if the '/etc/convers/conversd.conf' file does not exist or can not
  be accessed, then 'conversd' will just exit, with code 2.  Just as it will
  if it cannot create the dbm format file nor open it sucessfully.

  If the time stamps on '/etc/(x)conversd' or '/etc/convers/conversd.conf'
  change, conversd will automatically reboot within 10 minutes of the change.
  This is to allow for automatic updating of binaries and configs, and so
  could be setup to have it reload again with new setup.  If it can not access
  /etc/convers/convers.inf at startup it will exit with code 3.

  As of 1.4 the /etc/convers/conversd.conf is flock'ed  on bootup, if this
  flock cannot be obtained then it will exit with a code 4.  This is
  probably because another copy of conversd is running.

  The convers client program just connects to the convers port and sends a
  '/NAME <username> <channel> <personal_text>' into it.  This can be run as
  any user, and so you *could* have 'root' signing on.  If the personal text
  is not given then the server will look down the database for the the text
  you last used.


  To setup WAMPES or LNET, you need to have these lines in net.rc:

  start tcpgate 3000 unix:/tcp/sockets/convers
  start tcpgate 3601 unix:/tcp/sockets/xconvers

  Even if you are not running 'xconversd' but are running 'conversd' it is
  safe to have the 3601 line in the above.
  With this setup you can now accept incoming connections.


 Findings:

|   I have somewhat met the JNOS version of convers at a halfway house, as
|   this now supports its UDAT for the personal text transfer, I saw it was a
|   more efficient method of exchanging the information when a user added after
|   login, or changed existing data there to something else.  But the
|   original method of appending it to the end of the host mode 'USER' command
|   was more efficient if a user has a pre setup personal text.  So I have
|   kept both.
|
|   This may cause problems to systems that don't support the 'USER' method of
|   personal text, so I'll leave its inclusion into the JNOS source for the
|   JNOS team if someone tells them.  It would only be visible at startup on
|   the local machine and right down the longest chain of systems with support
|   the 'USER' method.  The personal text won't propagate any further.

   The above should now be resolved with the JNOS auto-detection.

   One thing about convers routing, you must not create a loop of connected
   servers; only a chain.  With this convers server it is also fine to have
   two hosts in each others connection list as in '/tcp/convers.conf' and
   there is no problem of these systems fighting over connection rights, only
   the possibility of an initial turnaround in connection.  This is fine
   with two of these servers back to back, but I am unsure of Linux<->other
   type connections.  I think again hyper-thetically (SP) that depending on
   who connects to who, there is the possibility of having two turnaround
   before it all stops, because the Linux one will be intelligent enough to
   see this.


   Also you'll notice that the case is not preserved for user or host names,
   this should not cause any problems as the convers system is linked in a
   chain, and references to hostnames are not used for any of the hostmode
   commands at the moment.

   IMHO I think that the hostname should be 'THE' hostname of the server
   minus its .ampr.org. as this is designed for Amateur purposes and not for
   any other, all the hosts should be in the ampr.org domain and so
   it would be done if not for practicality, but because everyone can
   immediately append the .ampr.org. and perform a nslookup and get a
   host address back.  This returns exactly which server it is and under
   who's callsign.  The case of domain names does not matter and the
   majority of them are expressed in lowercase so this is my reasoning
   behind this.  Should any convers system come from a single TNC job, then
   the callsign minus the SSID would be useful rather than any ALIAS, as a
   location could be obtained from the callsign.


 Bugs:

   Please mail me on what they are, and any *features* you may find along
   the way.  Also I'm open for suggestions to put onto the TODO list.


 TODO:


   Users:
     Split screen for the sysop user!
     Allow shortened form of help information, e.g. make '/HELP PER' the
       same as '/HELP PERSONAL'
     Add facility to change user options.
     Add /WHO ? and /USERS ? to list only those users on the same channel as
       yourself.


   Sysops:
     Possible hop-check type command/protocol to see what path is taken to
       get to particular hosts, and also if that host is on air with
       conversd functioning.  Another use for the same command to users
       could be an enquiry to a host for some additional info about its
       location and also IP address.

     PID file.

     Logging on all convers activity going thru your station, all traffic
       can be logged as per channel so that a running conversation can be
       seen, and also control info traffic can be logged.
     Validation of hostname to adjoining systems going host mode.
     Validation of callsigns on non-privileged channels for national and
       international convers channels.
     Also configuration of organized and a channelised convers setup, so
       that regional, national and international convers channels can be setup
       to further reduce unwanted/unneeded traffic.
     The rude word filter!  There will come the day when it WILL be needed
       (unfortunatly) to disconnect those sad people, and temporarily lock
       them out.
     Suggestion from G1NZZ for a '/msg user1,user2,user3 message' to allow
       multiple copies of the same message to be sent to a variety of users.
     Change the '*** <user> signed off' message for a '*** <user> link out'
       if the user did not *really* sign off the convers system, but was
       forced off because of a link which dropped out.  It can be treated
       just like a 'sign off' message, but will give a better indication of
       why the user was signed off.

     #ifdef out all the extra garbage and remove all the paranoid checking
       which is in there, to optimize the code.

   Extras:
     Do something about the accept call on network connections if possible,
       maybe fork off handle the accept, and use an IPC to get the data back to
       the parent.  Sounds messy though :-(
     Put in uncompressed data write buffering on compressed connections, but
       then again this will all change when LNET5-0 comes out :-).


  DONE:

   Users:

     Link idle setup to keep an idle link open much the same way a DXcluster
       does, so that the idle time through any NODE on the way times out. 
       Sending an 0x00 would be okay as many TNC have by default the Filter
       option set so that a NULL is not sent to the terminal.


WARRANTY

   None what so ever at all, no fitness for purpose or warranty is given.
   


CREDITS

   I have tried to credit all those known about from the sources I used,
   please get in touch if you are not included below for you inclusion.

   mbuf.c - From JNOS port to Linux.

/* mbuf (message buffer) primitives
 * Copyright 1991 Phil Karn, KA9Q
 *
 * Mods by G1EMM
 */

   lzw.c - From JNOS port to Linux, with clarifications from WNOS 4A9.

/*              SM0RGV data compression routines.
 * This file implements the Lempel-Ziv Welch (LZW) data compression
 * algorithm but with a variable code size, as in GIF format files.
 *
 * Copyright 1990 by Anders Klemets, SM0RGV. Permission granted for
 * non-commercial distribution only.
 */

   convers.c  - Code originally came from the WAMPES 931001 distribution.
   conversd.c - Code originally came from the WAMPES 931001 distribution.

   Full credit must go to the WAMPES team for getting the code to the rock
   solid stability is has before I even get my paws on it.  I hope the
   additional features I have added make the system better for the users as
   well as the sysops.

Ideas:

   DL9SAU for the /..LOOP detection.  Hope this works just the same.


Keeper of the the new package.

  Darryl Miles G7LED

  2 Barrington Road,     g7led @ g7led.ampr.org
  Olton,                darryl @ frink.demon.co.uk
  Solihull,              G7LED @ G7LED.GB7MIP.#29.GBR.EU
  West Midlands,
  B92 8DP.

  (021) 706 6681.

