ceder-1616-generations-topgit

1. What is 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.

LysKOM is much faster than netnews - almost as fast as irc or ICQ! -
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 available.
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 hostname of the server is kom.lysator.liu.se.  Of
course, you need a client to test it.  On that particular server most
of the discussions are done in Swedish.

See the file NEWS for information about changes, or the various
ChangeLogs for more detailed information.

The lyskom-server distribution, of which this README file is a part,
only contains the server.  You must obtain the clients separately.


2. Documentation
================

doc/lyskomd.texi	Instructions for maintaining a LysKOM server.
			Also contains a chapter for hackers that want
			to extend or modify the server.

doc/Protocol-A.texi	Documentation of the protocol used between the
			clients and the LysKOM server.

NEWS			What is new in this release?
README			This file.
INSTALL			Generic install instructions (see below for
			lyskomd-specific instructions).
HACKING			Information that may be useful if you want to
			change lyskomd.
COPYING			The license for lyskomd (GNU GPL).
AUTHORS			List of authors.


3. Installation
===============

   1. Select a location where you want the LysKOM database and server
      binaries to reside.  We recommend something like /usr/lyskom
      (the default), /usr/local/lyskom or /opt/lyskom.

      WARNING: Do not use /usr/local as the prefix!  lyskomd was
      written with the assumption that it should have a prefix of its
      own, and it creates files such as etc/pid under the prefix you
      use.  (Fixing this is on the TODO list.)

      WARNING: Do not place the database on an NFS-mounted directory
      that is mounted with "intr"!  If you do, the system calls that
      writes the database may return a failure and set errno to
      EINTR.  lyskomd does not yet handle that appropriately.  See bug
      847 for more details and the current status of this problem.
      <URL:http://bugzilla.lysator.liu.se/show_bug.cgi?id=847>.

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

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

      The prefix defaults to /usr/lyskom.  There are many other
      options that you can give to the configure script.  Most of them
      are documented in the generic INSTALL file.  There are a few
      LysKOM-specific options, but except for --with-language they are
      only useful if you want to debug lyskomd.  See the HACKING file
      for more information about them.

      You can use --with-language=sv to select that a Swedish database
      should be installed (if no previous database exists).  By
      default, an English database will be installed.

      The "-C" option tells configure to cache configuration values in
      config.cache.  Since the lyskomd distribution uses more than one
      configure scripts, this will speed up the configure process.

   3. Compile it:

	$ make

   4. If you like, you can run the test suite:

	$ make check

      There should be no unexpected errors.  It is normal that some
      unsupported tests and expected errors are reported.  You need
      DejaGnu 1.4.2 and Python to run the test suite.  DejaGnu in turn
      needs TCL and expect.  They can be downloaded the software from:

	ftp://prep.ai.mit.edu/pub/gnu/dejagnu/dejagnu-1.4.2.tar.gz
	ftp://ftp.scriptics.com/pub/tcl/tcl8_3/tcl8.3.4.tar.gz
	http://expect.nist.gov/src/expect-5.38.0.tar.gz
	http://www.python.org/download/

   5. Create a user that should own the database files.  This file
      assumes that the user is named "lyskom".

   6. As "lyskom", install it:

	$ su lyskom
	$ make install

      This will install the server and documentation.  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, "Administrator (for) LysKOM", with password
      "gazonk".  See "Database versions" below if you have an old
      database -- you may have to convert it.

      A sample config file will be installed in etc/config, unless
      it already exists.  If you are upgrading to a new version of
      lyskomd you may have to edit the config file.  The current
      sample config file is in run-support/config.

      The configuration for aux-items will be installed in
      etc/aux-items.conf.  It will be overwritten even if it has been
      edited locally.

   7. 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".

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

   9. Read the documentation in doc/lyskomd.info, especially the
      Administration chapter.  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 twice a year.

  10. 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 that you are running a server.  (You are very welcome to
      tell more about you, but that's not necessary).


4. Database Versions -- you may have to convert the database
============================================================

The database format has not changed in the 2.0.1 through 2.0.6
releases.  However, there was a bug in the 2.0.0 release that may have
caused the database to contain errors.  Most of them can be fixed by
dbck, but some cannot yet be fixed; a release with an improved dbck
might be created in the future.  Please run this command if you are
upgrading from the 2.0.0 release:

	dbck -i

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)


5. Contact information
======================

If you find a bug, please take a moment to check the bug database at
http://bugzilla.lysator.liu.se/ to make sure that it isn't an old
bug.  If you find your bug there, and feel that you have more
information about it, please make an "additional comment".  If you
cannot find the bug, please enter a bug report there.

If you are unable to use Bugzilla, you can send your bug reports to
the email address bug-lyskom@lysator.liu.se.

The latest release of the server can always be found from

	ftp://ftp.lysator.liu.se/pub/lyskom/server/

This file and almost the entire lyskomd server is 
Copyright (C) 1991-2002 Lysator Academic Computer Association
See also the AUTHORS file.