Commit 16d5e89b authored by nobody's avatar nobody

This commit was manufactured by cvs2svn to create tag '1.2.0'.

parent b3f987d7
Administrating a LysKOM site
============================
This document is a short description of how to administrate a LysKOM
database on your site.
The first thing you will have to do is to follow the instructions in
the file INSTALL. This will set up the LysKOM system with a database
containing a few necessary conferences and one person - the
administrator.
Once the LysKOM system is running, there is not much you will have
to do to keep it that way. One thing to remember is that the current
release of the server (0.32) has an incomplete handling of garbage
collection of the database. The database is split into two files, the
information file and the text file. Newly written texts are
concatenated to the text file and old texts are never removed. The
information file contains information about conferences, users and
where in the text file the texts are. This file is properly garbage
collected, but not the text file.
There is a program called dbck (Data Base Check) which is used to
check the consistency of the LysKOM database. This program can also
be used to shrink the text file. To do this, just type `dbck -g' in
the database directory, or give additional switches to dbck to use the
correct directory. See further the manual page for dbck. When dbck
is to be run on the database, the LysKOM server *must* be stopped, or
unrepairable damage may result. See below for a description on how to
stop the server.
There is a shell script called updateLysKOM which is used to insure
continuous operation. This script is run with certain intervals and
if the LysKOM server has died for some reason, updateLysKOM restarts
it. If the server is still running properly, updateLysKOM sends a
signal (SIGUSR1) to it, which causes the server to write call
statistics to a file named etc/lyskomd-log in the lyskom directory.
Taking the server down cleanly can be done in two ways: through the
use of the LysKOM protocol on a socket, preferably through the use of
a suitable client, or to send the signal SIGHUP to it. This will
cause the server to save the database and close all client
connections. It will also create a file named etc/memory-usage in
which the memory usage of the server is reported. There is currently
a small memory leak in the server. We know about it, so there is no
need to send bug reports to us about that (unless you have found where
the leak is).
Edit src/server/config.c. Be careful to check
MAX_NO_OF_CONNECTIONS.
\ No newline at end of file
#
# $Id: Makefile.template,v 0.2 1991/09/15 09:54:15 linus Exp $
# Copyright (C) 1991 Lysator Academic Computer Association.
#
# This file is part of the LysKOM server.
#
# LysKOM is free software; you can redistribute it and/or modify it
# under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 1, or (at your option)
# any later version.
#
# LysKOM is distributed in the hope that it will be useful, but WITHOUT
# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
# for more details.
#
# You should have received a copy of the GNU General Public License
# along with LysKOM; see the file COPYING. If not, write to
# Lysator, c/o ISY, Linkoping University, S-581 83 Linkoping, SWEDEN,
# or the Free Software Foundation, Inc., 675 Mass Ave, Cambridge,
# MA 02139, USA.
#
# Please mail bug reports to bug-lyskom@lysator.liu.se.
#
# Makefile for LysKOM
#
###############################################################################
#
# SPECIAL CONSIDERATIONS:
#
# - Requires GNU make.
# - CC, OPTIMIZE-FLAGS and other make variables are passed down
# in the environment.
# - C compiler must be ANSI conformant.
#
###############################################################################
#
# SPECIAL TARGETS:
###############################################################################
# Directories that you might want to override via the environment.
ifndef TOPDIR
TOPDIR := /usr/lyskom/src
endif
ifndef SCRIPTDIR
SCRIPTDIR := $(TOPDIR)/scripts
endif
include $(SCRIPTDIR)/import.make
# All directories that make should traverse to when doing clean etc.
SUBDIRS = doc include junk lib scripts src
all:
for i in $(SUBDIRS) ; \
do \
echo making all in directory $$i; \
(cd $$i; $(MAKE) all) \
done
.\" $Id: ramkom.5,v 1.4 1991/09/15 09:54:59 linus Exp $
.\" Copyright (C) 1991 Lysator Academic Computer Association.
.\"
.\" This file is part of the LysKOM server.
.\"
.\" LysKOM is free software; you can redistribute it and/or modify it
.\" under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 1, or (at your option)
.\" any later version.
.\"
.\" LysKOM is distributed in the hope that it will be useful, but WITHOUT
.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
.\" FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
.\" for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with LysKOM; see the file COPYING. If not, write to
.\" Lysator, c/o ISY, Linkoping University, S-581 83 Linkoping, SWEDEN,
.\" or the Free Software Foundation, Inc., 675 Mass Ave, Cambridge,
.\" MA 02139, USA.
.\"
.\" Please mail bug reports to bug-lyskom@lysator.liu.se.
.\"
.\" $Id: ramkom.5,v 1.4 1991/09/15 09:54:59 linus Exp $
.\" $Date: 1991/09/15 09:54:59 $
.TH ramkom 5 "August 24, 1991"
.SH NAME
ramkom - LysKOM
.I database
format
.SH SYNOPSIS
.B /usr/lyskom/db/ramkomd-*
.br
and
.br
.B /usr/lyskom/etc/pid
.PP
.B #include <lyskom/kom-types.h>
.SH DISCLAIMER
The
.I database
is not really a database but a sequential file where all data is saved
from the memory.
.SH DESCRIPTION
There are 2 files: One file with all the data
.RB ( ramkomd-data ).
And one with all texts
.RB ( ramkomd-texts ).
The texts file does not contain any information about where any text
starts of ends, all this is in the data file together with other infos
on the text.
.PP
If the first five chars of the data file is CLEAN then the
.I database
is considered clean. If its anything else the
.BR ramkomd (8)
program will try to find the backupfile instead.
.PP
Then there is a number telling the number of the next free conference
.RI ( next_free_num ).
.PP
Now follows a list of all conferences. One conference on each line. If
the conference is deleted the line consists of a
.B @
otherwise it starts with a
.BR + .
.PP
Now follows a list of all person statuses. Here is also every person
on its own line and the deleted persons or the numbers that are not
persons but conferences are lines containing just a
.BR @ .
.PP
Both the conference status part and the person status part are exactly
.IR next_free_num -1
lines long.
.PP
Now follows the number of the next text that is not used and a list of
text statuses.
Every text status has its own line just like the other statuses and
non-existent texts are represented by the
.BI @ .
.PP
The different statuses types are
.B conference
.BR statuses ,
.B person statuses
and
.B text
.BR statuses .
These are in a struct in the include file but in this file they are
not saved as structs but every element is saved as a ascii string.
Strings are saved as holerith strings. The field of the struct is not
even saved in the same order as in the struct.
Their order in the database is followed below.
.PP
An array of things is represented in the database by a number telling
how many elements there are in the array and the either a
.B *
in the case no elements or a
.B {
followed by all the elements and a finishing
.BR } .
.SS Conference status
.LP
This contains all information for a conference. A conference is a
object that recieves texts.
.TP 15
.I Name
Name of the conference saved as a holerith string.
.TP
.I Member list
An array of the members in that conference.
.TP
.I First local number
This is the local number of the first text in the conference. Its
saved here in order to save space in this file by not mentioning all
deleted texts in the beginning of the conference.
.TP
.I Texts
This is an array of recieved texts. The local number of the text is
determined by the position in this list and the value of the
.I first local
.IR number .
.TP
.I Type
This is the type of the conf, it contains the infomation that says if
the conference is read protected, original flagged conference, secret,
or if its a letter box.
.TP
.I Creation time
The time the conference was created.
.TP
.I Last written
The time the last text was sent to the conference.
.TP
.I Creator
The number of the person that has created the conference. This is 0
for conferences that are created initially.
.TP
.I Presentation
This is the number of the text containing a presentation of the
conference. If there is no presentation this number is 0.
.TP
.I Supervisor
This is the number of the conference whose members are supervisors of
the conference. Initially this is set to be the number of the letter
box of the creator.
.TP
.I Permitted submitters
This is the number of the conference whose members are allowed to
submit texts to this conference. If this is 0 (the default) all
persons i
.B LysKOM
are allowed to submit.
.TP
.I Super conference
This is a number of a conference that comments to articles should be
sent to if this conference is original flagged.
.TP
.I Message of the day
This is the textnumber of the text containing a notice message about
the conference. Mostly used for letter boxes. If 0 then there is no
such message.
.TP
.I Garb nice
This is the number of days a text stays in the conference before it is
removed by the expiration routines. Its really the expiration rate.
.SS Person statuses
.LP
Person statuses contains all info about persons.
.TP 15
.I Password
The password is stored as a string. The length of the string is 64 but
the length of the password itself is stored as the first char in the
string. Passwords longer that 63 chars are truncated.
.TP
.I Username
This is the username and machine from the last time the person logged in.
.TP
.I Privileges
The persons privileges are stored here. This is a bit array, length is
16 bits. It is not really welldetemined what bit does what.
.TP
.I Personal flags
The persons flags are stored here.
.TP
.I First local number
This is the local number of the first created text that still exists
in the database. Its local to this list.
.TP
.I Created text list
This is an array of all created texts beginning at the first local
number.
.TP
.I Marked texts
This is an array of all marked texts and their mark type. Every
element in the array is a text number and a mark number.
.TP
.I Membership
Here is the information about which conferences the person is member
in. Its an array where every element is of the type
.B Membership
(See below).
.TP
.I Last login
Time of the last login.
.TP
.I User area
Number of the text being the persons user area. If there is no user
area this is 0.
.TP
.I Total time present
Time in
.B LysKOM
in seconds.
.TP
.I Sessions
Number of logins made for that person.
.TP
.I Created lines
.TP
.I Created bytes
.TP
.I Read texts
Count of read marked texts.
.TP
.I No of fetches
This is the information about how many texts this person has fetched.
Using caching clients this number could increase well beyond
.I Read
.IR texts .
.TP
.I Created persons
Count of created persons.
.TP
.I Created conferences
Count of created conferences.
.SS Text statuses
This contains info about the texts.
.TP 15
.I Created time
Time this text was created.
.TP
.I Author
Person that wrote this text.
.TP
.I Start
Start pointer for the text in the
.I ramkomd-texts
file.
.TP
.I Number of lines
Length of the text in lines.
.TP
.I Number of chars
Length of the text in chars.
.TP
.I Number of marks
Count of existing marks on this text.
.TP
.I Header list
An array containing info about
.IR recipients ,
.I comments
.IR to -pointers
etc. Every element is a
.IR Misc_info .
.SS Membership
The membership type tells us about conferences we are member of and
how much we have already read of it. It is saved in this way:
.TP
.I Last time read
Updated when we mark a text as read in this conference.
.TP
.I Conference number
The number telling what conf.
.TP
.I Priority
Used by the client to determine reading order.
.TP
.I Last text read
Local number of the last text we have read. This is used to keep track
of which texts we have not yet read and calculate how many unread we
have in this conference.
.TP
.I Read texts
An array containing the texts that we have read after the
.I Last text
.IR read .
This is necessary because its possible to read in any order.
.SH FILES
.TP 20
.IB database-directory /db/ramkomd-data
File with all the elements and pointers.
.TP
.IB database-directory /db/ramkomd-texts
File with the texts.
.TP
.IB database-directory /etc/pid
File with the pid of the lyskom-process.
.TP
.IB database-directory /db/ramkomd-backup
Backup file with all data.
.SH "SEE ALSO"
.BR ramkomd (8),
.BR dbck (8)
.SH BUGS
This is really a joke. Its not a database, not optimal in any way. But
it works.
.PP
The
.I message of the day
text number is not saved anywhere. This makes the
server forget what text that is when restarting.
.SH NOTES
This will soon disapear and be replaced by something more bazaarly
inexplicable.
.\" $Id: ramkomd.8,v 1.4 1991/09/15 09:54:39 linus Exp $
.\" Copyright (C) 1991 Lysator Academic Computer Association.
.\"
.\" This file is part of the LysKOM server.
.\"
.\" LysKOM is free software; you can redistribute it and/or modify it
.\" under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 1, or (at your option)
.\" any later version.
.\"
.\" LysKOM is distributed in the hope that it will be useful, but WITHOUT
.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
.\" FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
.\" for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with LysKOM; see the file COPYING. If not, write to
.\" Lysator, c/o ISY, Linkoping University, S-581 83 Linkoping, SWEDEN,
.\" or the Free Software Foundation, Inc., 675 Mass Ave, Cambridge,
.\" MA 02139, USA.
.\"
.\" Please mail bug reports to bug-lyskom@lysator.liu.se.
.\"
.\" $Id: ramkomd.8,v 1.4 1991/09/15 09:54:39 linus Exp $
.\" $Date: 1991/09/15 09:54:39 $
.TH ramkomd 8 "August 22, 1991"
.SH NAME
ramkomd - LysKOM server
.SH SYNOPSIS
.B /usr/lyskom/bin/ramkomd
[
.B -d
] [
.B -q
] [
.BI -D database-directory
] [
.BI -p clientportnumber
] [
.BI -P muxportnumber
] [
.B -a
]
.SH DESCRIPTION
This program runs a LysKOM server.
.PP
It listens for connections on the given portnumbers (defaults are 4894
for the
.I clientportnumber
and 4787 for the
.IR muxportnumber ).
.SH OPTIONS
.TP
.B \-d
Adds one to the debug-level i.e. increases the amount of output on the
stderr from the process.
Using one
.B \-d
make the process print a
.I >
for every timeout, a message for every person that is connecting or
disconnecting and a message for every succesful or unsuccessful
communication to the process.
.TP
.B \-q
Never save the database.
.TP
.BI \-D database-directory
Use the database in the
.I database-directory.
.br
Example: If your database is in
.B $HOME/lyskom/db
you should use the option
.B \-D$HOME/lyskom
.TP
.BI \-p clientportnumber
listens for clients on the port number
.I clientportnumber.
.TP
.BI \-P muxportnumber
listens for mux connections on the port number
.I muxportnumber.
A mux connection is a connection using a special protocoll to allow
several sessions within one connection.
.TP
.B \-a
Do not send any non-requested messages. This disables the sending of
messages about events in the server to all connections.
.SH FILES
.TP 20
.B /usr/lyskom
Default database directory.
.TP
.IB database-directory /db/ramkomd-data
File with all the elements and pointers.
.TP
.IB database-directory /db/ramkomd-texts
File with the texts.
.TP
.IB database-directory /etc/pid
File with the pid of the lyskom-process.
.TP
.IB database-directory /db/ramkomd-backup
Backup file with all data.
.SH BUGS
Small memory leak.
.PP
There is no practical handling of security.
.PP
The choice of asynchronously issued messages is not very good.
.PP
The so called "data base" is a joke.
.SH AUTHOR
Per Cederqvist <ceder@lysator.liu.se>
.SH NOTE
Version 2.0 on its way.
This diff is collapsed.
LysKOM-Projektet
--------------------------------
Beskrivning av server-klient-protokollet,
version A, i LysKOM
--------------------------------
av Lars Aronsson
<aronsson@lysator.liu.se>
datum ok{nt
Kommunikationen till servern sker i klartext. P} s} vis {r det m|jligt
att provk|ra utan att ha en klient ig}ng. Avlusningen blev ocks}
enklare.
UPPKOPPLING
Vid uppkoppling s{nder klienten ett 'A' f|ljt av login-identiteten f|r
anv{ndaren (en str{ng, se nedan). Servern svarar med att skicka
"LysKOM\n". Sedan {r uppkopplingen gjord.
FUNKTIONSANROP
Vid ett funktionsanrop skickas f|ljande data fr}n klienten till
servern:
ref-nr funktions-nr parametrar
ref-nr {r ett heltal (unsigned, max 32 bitar) som klienten kan v{lja
fritt, t ex som ett l|pnummer.
funktions-nr {r ett heltal som anger vilken funktion man vill anropa.
De definieras i isc/com.h.
Om anropet lyckades ser svaret ut s} h{r:
=ref-nr svar
Om det misslyckas:
%ref-nr kom_errno err_stat
DATAFORMAT
Allt som skickas (utom m|jligtvis innuti str{ngar) {r ASCII. Bortsett
fr}n innuti str{ngar skickas inga kontrolltecken. Whitespace anv{nds
f|r att skilja olika f{lt }t. Som whitespace r{knas ' ', \r, \n, \t
och \000. (Ett funktionsanrop beh|ver inte avslutas med \n, det g}r
lika bra med vilken whitespace som helst, men det m}ste finnas en
whitespace - det r{cker inte med att paketet tar slut).
Alla tal, (t ex int, Pers_no, Conf_no) skickas i decimal form.
Enumar skickas i decimal form.
Str{ngar skickas som Hollerith-str{ngar, dvs f|rst ett heltal som
anger l{ngden, sen ett H, sen str{ngen. Innuti en str{ng kan vilka
tecken som helst komma. (0-255).
Arrayer skickas inom m}svingar. T ex kan en Text_list som ser ut s}
h{r:
typedef struct {
Local_text_no first_local_no,
no_of_texts;
Text_no * texts;
} Text_list;
skickas s} h{r:
5 3 { 8 9 11 }
eller, om texts==NULL:
5 3 *
Asterisk anv{nds allts} f|r att markera en tom array. (Till exempel om
man inte fr}gar efter Membership). Asterisk-notationen kan bara
anv{ndas i rikting fr}n servern till klienten.
EXEMPEL
S} h{r kan en k|rning se ut.
Klienten skickar Servern svarar F|rklaring
================ ============== ==========
A5Hceder LysKOM\n Uppkoppling.
1 37 =1 100 1 2 3 4 5712 Get_info
69 27 5712 =69 {textstat} Get_text_stat
18 26 5712 =18 {textmassa} Get_text
2 1 334 5HaBcdE %2 3 0 0 0 Login, misslyckas. (KOM_PWD)
3 1 334 5HaBcDe =3 Login, lyckas.
...
9 2 =9 Logout (beh|vs eg. ej)
FELHANTERING
Om servern tar emot text som inte st{mmer med det protokoll som f|r
tillf{llet {r implementerat (f|rhoppningsvis, men ej n|dv{ndigtvis,
det som {r beskrivet h{r) skriver den ut "%% LysKOM protocol error.\n"
ASYNKRONA MEDDELANDEN
Servern skickar ibland ut meddelanden som clienterna kanske tycker {r
intressanta. Formatet f|r dessa {r:
:no_of_tokens function < tokens >
De b|rjar allts} med ":" i st{llet f|r "=" eller "%". Genom att
antalet token alltid s{nds s} kan {ven gamla klienter "|verleva" en ny
klient med nya asynkrona meddelanden. Det {r bara att hoppa |ver r{tt
antal token.
Termen "asynkrona meddelanden" {r lite oegentlig. Meddelanden {r
synkroniserade med allt annat som skickas ut fr}n servern. Ett
meddelanden kommer bara n{r ett svar skulle ha kommit.
DATAFORMAT F\R SAMMANSATTA TYPER