================================================================
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 1.9.0 uses a new improved 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 1 -F
You must, of course, use version 1.9.0 or later of dbck to do the
conversion. You can convert back the database to the old format with
dbck -o 0 -F
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.