README

   ================================================================
				README

			 -- LysKOM server --

    Copyright (C) 1991-1998 Lysator Academic Computer Association
   ================================================================


			   What is LysKOM?

  This is the README file for the server of the electronic conference
system LysKOM.

  LysKOM has a lot in common with netnews, but LysKOM is intended for
local discussions (instead of worldwide).  LysKOM consists of a server
process and several client programs.  The server process maintains a
data base of persons, conferences and articles.  The clients connect
to the server and let the users browse the database for unread
articles.  Currently the only protocol available for connections is
TCP/IP, but rewriting the server and clients for using e.g. DECNET
should be trivial.

  LysKOM is much faster than netnews - almost as fast as irc! - but
like in netnews the articles are saved so that you don't have to be
logged in to receive the news.

  As mentioned above, you need a client to be able to do something
useful with LysKOM.  At this time there are several clients avaliable.
The most popular client is written in elisp and requires Gnu Emacs or
XEmacs to run. There are also web clients and a MS Windows client. See 
<URL:http://www.lysator.liu.se/lyskom/> for availability of clients.

  A LysKOM server has been running at Lysator since July 25th 1990.
You can connect to it and test it out if you like to get a feel for
what LysKOM is.  The IP address of the server is kom.lysator.liu.se.
Of course, you need a client to test it.



		  How do you set up a LysKOM server?

  Installation instructions are in the file INSTALL.   Instructions
for maintaining a LysKOM server are in the file doc/ADMINISTRATION.
Some other documentation, such as the specification for the
server-client protocol is also available in the doc directory.

  If you find a bug, please send your bug reports to the email address
bug-lyskom@lysator.liu.se, but before you do, please check the file
doc/known-server-bugs.



			  About this release

  This release tries to adhere to the GNU Coding Standars, except that
we indent the code in another way (use "M-x set-c-style RET BSD RET"
if you are using Emacs 19).  See the file NEWS for information about
changes, or the various ChangeLogs for more detailed information.


The testsuite
=============

You should be able to compile, install and run lyskomd in almost any
reasonably modern Unix environment.  The test suite, however, requires
that some special software is installed on your system.  In the list
below we give the location for the version that was used to run the
test suite prior to release of the LysKOM server.  Later versions may
be available when you read this.  Later versions may of course cause
the test suite to fail.

DejaGnu
-------

DejaGnu is a test suite framework.  It is based on expect, which is in
turn unfortunately based on TCL.  I really wish there was something
like DejaGnu based on something better than TCL, but for now we are
stuck with this.  It is better than no framework.  DejaGnu can be
found at this location:

	ftp://prep.ai.mit.edu/pub/gnu/dejagnu-1.3.tar.gz

Tcputils
--------

Tcputils is a small package of tiny shell utilities that are very
handy when you use the network.  It can be found at this localtion:

	ftp://ftp.lysator.liu.se/pub/unix/tcputils-0.6.2.tar.gz

Installation
============

This file describes how to build and install a LysKOM server.

Table of Contents:
------------------

	1. Requirements
	2. Building and installing (simplified version)
	3. Database versions (upgrade instructions)
	4. Building (details you normally don't need to know)
	5. Installing (details you normally don't need to know)

1. Requirements:
----------------

1.1  ANSI C compiler, such as GNU CC.

LysKOM is written in ANSI C, with full prototypes.  If your compiler
doesn't support prototypes you'd better get gcc (the GNU C compiler).
It is available freely via anonymous from many sites, e.g. isy.liu.se
or prep.ai.mit.edu.

The server was written with the assumption that full prototypes was
available for all functions in the standard libraries, so we don't
cast our pointers. This could lead to errors if no function prototypes
are given by the include files.

A recent release (not necessarily the current release) of lyskomd have
been tested on all of the following environments:

    Release Compiler        OS              CPU     Computer name

    1.9.0   gcc 2.7.2       SunOS 5.4       Sparc
    1.9.0   gcc 2.7.0       SunOS 4.1.1_U1  m68k    (Sun-3)
    1.9.0   apcc 3.0        SunOS 5.4       Sparc
    1.9.0   sparcworks      SunOS 5.4       Sparc
    1.9.0   gcc 2.7.0       Linux 2.0.0     i486    (PC)
    1.9.0   gcc 2.7.2       NetBSD 1.1      sparc   (SPARCstation IPC)
    1.9.0   gcc 2.4.5       NetBSD 1.1      sparc   (SPARCstation IPC)
    1.9.0   gcc 2.6.3       AIX 3.2         rs6000  (IBM RS/6000 320)
    1.9.0   gcc 2.7.2       Ultrix 4.5      VAX
    1.9.0   gcc 2.7.2       Ultrix 4.5      MIPS    (DECstation 5000/20)
    1.9.0   cc              OSF1 V3.2       alpha
    1.9.0   gcc 2.7.0       OSF1 V3.2       alpha
    1.9.0   gcc 2.4.5       Dynix 3.0.14    ns32k   (Sequence Balance 8000)
    1.9.0   gcc 2.6.3       IRIX 4.0.5      MIPS    (SGI Personal Iris)

	(*) The "komrunning" script will not work on Solaris 2.x.

It should compile on most other Unix machines as well. Please tell me
if you succeed in compiling it with another machine/OS/compiler.

1.2  Decent make

We use the "include" statement in our Makefiles.  Get GNU make if your
make does not support it.

1.3  Bison and flex

You may need the Gnu tools bison and flex. The standard lex and yacc
are not flexible enough. You should have bison version 1.25 or later
and flex version 2.5.4 or later.


2. INSTALLING (quick version)
   --------------------------
   1. Select a location where you want the LysKOM database and server
      binaries to reside.

   2. From the top directory of the server sources, run configure:

	$ ./configure --prefix=/usr/local/lyskom

      The prefix defaults to /usr/lyskom.

   2b. Edit src/server/tmp-limits.h

      There is a hardcoded limit to the number of persons and texts
      that LysKOM supports.  The limit won't be hardcoded in future
      releases.  LysKOM currently has a table that holds as many
      entries as is said here, so it is wasteful to have a too big
      number here.  On the other hand, you must recompile and restart
      the server when the limit is reached, so it is unwise to set it
      too low.

      All other parameters (which used to be hardcoded) can now be set
      in a configuration file which is read in everytime lyskomd is
      started.  See lyskomd.8 (in doc/man/lyskomd.8).

   3. Compile it:

	$ make all

   4. Create a user "lyskom".

   5. As "lyskom", install it:

	$ make install

      This will install the server and man pages.  It will also
      install an empty database, unless it finds an old database.  The
      empty database will contain four standard conferences and one
      privileged user, "Administratör (för) LysKOM", with password
      "gazonk".  See "database version" below if you have an old
      database -- you may have to convert it.

   6. Make sure updateLysKOM is run regularly by user lyskom.  The
      recommended way is to add a line such as this to the cron file
      of the lyskom user:

	0,10,20,30,40,50 * * * * /usr/lyskom/bin/updateLysKOM

      If your cron does not support per-user cron files you will have
      to arrange this in some other way.

      The updateLysKOM will occasionally output a message to stderr
      and exit with a non-zero exit status.  It expects the cron to
      send a mail to a LysKOM administrator with the output from the
      program.  Most sane cron systems does so.  You may want to
      create a .forward file for user "lyskom".

   7. Wait for upateLysKOM to start the server, or run updateLysKOM
      manually (as user "lyskom").  You are ready.

   8. Read the doc/ADMINISTRATION file.  It tells you how to shut down
      and restart lyskomd.  LysKOM needs your attention once in a
      while.  Here at Lysator we expunge old texts (with "dbck -g")
      approximately once every 2 months, and restarts the server after
      about 1000 connection attempts (a little more than one week).

   9. We would like to know about where LysKOM servers are running.
      If you start a server, please mail "kom@lysator.liu.se", and
      tell us your email address.  (You are very welcome to tell more
      about you, but that's not necessary).  We will tell you when we
      make new releases, and warn you if we should find any serious
      problems.


3. DATABASE VERSIONS -- you may have to convert the database
------------------------------------------------------------

lyskomd version 2.0.0 uses a new file format for the database. If you
have been running earlier versions of lyskomd you must convert the
database by issuing the following command:

	dbck -o 2 -F

You must, of course, use version 2.0.0 or later of dbck to do the
conversion.  You can convert back the database to the old format with

	dbck -o 1 -F        (for lyskomd version 1.9.0)
	dbck -o 0 -F        (for ancient lyskomd versions)

4. BUILDING -- the details
--------------------------

This section describes how to build a lyskom server, after you have
run "make pure" (which removes everything which can be built from some
other file).  This section also describes everything you can change to
get different behavior.

   1. Generate the configure script from configure.in.  This requires
      GNU autoconf version 2 or later (we have been using version 2.4).

	$ autoconf

   2. Generate Makefile.in from Makefile.src.  There is
      (almost) one Makefile.src per directory.  As of this writing,
      there are 19 of them.

	$ ./mkmi

      The mkmi script uses m4 to process all Makefile.in templates.
      The file scripts/mkmi.m4 contains m4 macro definitions which are
      used. If you want to change how the Makefiles work, it is
      probably there you have to do the change.  The Makefile.in files
      which are distributed with lyskomd 1.8.0 were generated using GNU
      m4 version 1.3.

   3. Run configure, to generate Makefile from Makefile.in.  You do
      not have to compile in the source directory.  This can be useful
      if you build the server for several architectures at once (but,
      unless you are preparing a new release and want to test it on
      several architectures, there is probably no need to do it.)  To
      compile in a separate directory, do like this:

	$ mkdir compilation-dir
	$ cd compilation-dir
	$ ../lyskom-1.8.0/configure

      The configure script understands (at least) these options:

	--prefix=path	Tell lyskomd where it should be installed.
		      	Note that this path will be compiled into the
      			programs, so try to get it right.

	--help		List everything it understands.

      The configure script also adheres to some environment variables,
      among them are:

	CC	C compiler to use
	CFLAGS	Flags to pass when compiling.  The configure script
      		will add additional flags.
	CPPFLAGS
	LDFLAGS	Flags to pass when linking.  The configure script will
      		add additional flags.

      You should not normally need to set these environment variables,
      but you might have to clear them, to avoid confusing the
      configure script.  You can add these values to CFLAGS to enable
      or disable features in the server:

	-DNDEBUG	Disable the ``-d'' option of lyskomd.  The
			result should be slightly faster, but a lot
			harder to debug.  Not recommended, but
			harmless.
	-DNDEFENSIVE_CHECKS   Omit some code which is used to detect
			internal errors.  Not recommended.
	-DLOGACCESSES	Enable the configuration option ``Log
			accesses'' parameter.  Not recommended, since
			it slows down the server quite a bit, and
			unless you plan to write a new cache you have
			no use of the resulting (large) trace anyhow.

   4. Install include files.  During the build, various source files
      are installed in the directory include.  This step also
      generates some include files and various other automatically
      generated files.

	$ make includes

   5. Create dependency files.

	$ make depend

      You might want to "make stamp-depend" instead.  That target
      starts a "make depend" and touches the file "stamp-depend".  The
      target "all" depends on "stamp-depend" to make sure that "make
      depend" is run once (and only once).

   6. Create libraries.

	$ make libraries

      The libraris are installed in the lib directory.

   7. Make the binaries.

	$ make binaries

      "make all" will automatically do step 4-7 for you.

   8. Install everything.

	$ make install

      This will create the installation directories and install
      everything which is necessary to run a LysKOM server.  If there
      is no database, a new will be copied from dbcrypt/db.

5. INSTALLATION - the details
-----------------------------

This chapter is not yet written.  But let it be known that although
the server can be configured to find files in various location via the
configuration file, the updateLysKOM program and komrunning script
contain the paths hard-coded.  This might be fixed in future releases.
It *is* safe to change the prefix, though.