Commit ba8212fe authored by nobody's avatar nobody

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

parent fe4b1a60
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).
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
Person
username str{ng
privileges bitstr{ng
personal_flags bitstr{ng
created_texts:
first_local_no
no_of_texts
texts array
marks:
no_of_marks
marks array
conferences:
no_of_confs
confs: array
conf_no
priority
last_time_read
last_text_read
no_of_read
read_texts array
user_area
last_login
total_time_present
sessions
created_lines
created_bytes
read_texts
no_of_text_fetches
created_persons
created_confs
Conference
name str{ng
members:
no_of_members
members: array
member (Pers_no)
texts:
first_local_no
no_of_texts
texts array (Text_no)
conf_type bitstr{ng
creator
creation_time
presentation
supervisor
permitted_submitters
super_conf
last_written
msg_of_day
nice
Text_stat
author
creation_time
no_of_lines
no_of_marks
no_of_misc
misc_info: array
type 0 recpt
1 cc_recpt
2 comm_to
3 comm_in
4 footn_to
5 footn_in
6 loc_no
7 rec_time
8 sent_by
9 sent_at
datum
Info
version
conf_pres_conf
pers_pres_conf
motd_conf
kom_news_conf
motd_of_lyskom
Membership
no_of_confs
confs: array
conf_no
priority
last_time_read
last_text_read
no_of_read
read_texts array
Text_list
first_local_no
no_of_texts
texts array
str{ng
12HTolv tecken.
This swedish text describes how the client knows which texts the user
has not yet read. It is extracted from the LysKOM-server that runs
at lysator.liu.se.
-------------------------------------------------------------------
102868 1991-09-07 20:40 /132 rader/ ceder (Per Cederqvist Lysator)
Kommentar till text 102846 av Jonas S Karlsson (@Link ping enl CSN)
Mottagare: LysKOM internals <1804>
Markerad av dig och 2 andra.
[rende: Hur man vet vad som {r ol{st.
------------------------------------------------------------
Varje person har en lista |ver vilka m|ten han {r med i. F|r varje
m|te han {r med i lagras i en struct som vi kallar Membership:
* m|tesnumret
* prioriteten p} m|tet
* n{r man senast l{ste en text i m|tet (markerade en text i
m|tet som l{st)
* vilka texter man har l{st (lokala m|tesnummer)
Just nu lagras det som
Local_text_no last_text_read;
u_short no_of_read_texts;
Local_text_no *read_texts;
vilket inneb{r att man har l{st alla texter fram till och
med last_text_read, och dessutom alla texter som finns i den
dynamiskt allokerade arrayen read_texts (som inneh}ller
no_of_read_texts texter).
query_read_texts tar som argument en person och ett m|te (som
eventuellt kan vara en brevl}da) och returnerar den personens
Membership f|r just det m|tet. Till protokoll B kommer vi att d|pa om
funktionen till get_membership.
> 102846 1991-09-07 17:05 /16 rader/ Jonas S Karlsson (@Link ping enl CSN)
> Mottagare: LysKOM internals <1801>
> [rende: Protokollet fr{ga...
102846 {r ett globalt textnummer. Vi anv{nder typen Text_no f|r att
lagra och hantera s}dana nummer. 1801 {r ett lokalt nummer f|r m|tet
LysKOM internals. S}dana nummer lagras i en Local_text_no. (B}de
Text_no och Local_text_no {r 32 bittar just nu).
F|r varje m|te finns en relation MAP : Local_text_no -> Text_no. Med
anropet get_map kan man h{mta en tabell med vars hj{lp man kan g|ra den
|vers{ttningen f|r ett visst m|te.
get_created_texts ger en lista som inneh}ller de texter som en viss
person har skrivit.
F|r att ta reda p} vilka m|ten man har ol{sta inl{gg i g|r man s} h{r:
1) get_unread_confs (ditt personnummer)
Du f}r en lista med m|tesnummer. LysKOM garanterar att du inte har
n}got ol{st i n}got annat m|te, men det kan h{nda att den ger tillbaks
n}gra m|ten som du i verkligheten inte har n}got ol{st i.
De m|ten man f}r tillbaks {r de d{r de existerar (eller har existerat)
en text med ett h|gre lokalt textnummer {n last_text_read i ditt
Membership i m|tet i fr}ga.
2a) G|r query_read_texts f|r alla m|ten i listan du fick i steg 1.
2b) Samtidigt h{mtar du m|tesstatusen f|r de m|tena (med
get_conf_stat).
3) Samla ihop alla svaren och sortera dom s} att man f}r l{sa
inl{ggen i r{tt ordning.
4) Ta det f|rsta m|tet. J{mf|r det h|gsta lokala numret som existerar
(det kan du f} fram ur m|tesstatusen) med last_text_read i ditt
Membership. Om det visar sig att det finns texter du inte har l{st
m}ste du g|ra ett get_map f|r att ta reda p} vilket globalt textnummer
de ol{sta texterna har.
5) Sl} upp varje lokalt textnummer som du inte har l{st i mappen. Du
f}r ett Text_no. Om du f}r en nolla inneb{r det att den text som hade
det numret har raderats eller subtraherats fr}n m|tet. Ignorera det
lokala numret och tag n{sta.
6) N{r du f}r ett textnummer som inte {r noll h{mtar du textstatusen
och textmassan (sj{lva texten) med get_text_stat och get_text, och
visar den p} sk{rmen. N{r anv{ndaren har l{st klart texten talar du om
det f|r servern med mark_as_read (som tar ett m|tesnummer och ett
Local_text_no som argument och uppdaterar ditt Membership f|r det
m|tet). Om texten har flera mottagare som du {r medlem i ska du anropa
mark_as_read en g}ng f|r varje mottagare.
Repetera steg 5 och 6 tills du har l{st ut m|tet. Se till att du
f|ljer kommentartr{det, om anv{ndaren vill det.
Repetera steg 4 tills allt {r utl{st.
Visa alla markerade.
Se tiden.
=================================================================
S} g}r det till, grovt sett. Saker och ting kompliceras av att det
hela tiden skrivs nya texter. Servern skickar ut ett asynkront
meddelande n{r en ny text skapas (i ett m|te som man {r medlem i). I
meddelandet finns hela textstatusen (s} att man slipper h{mta den).
En annan grej som g|r det hela komplicerat {r att man g{rna vill att
klienten ska h{mta saker i f|rv{g n{r man inte har n}got annat att
g|ra. Man vill att klienten inte ska h{mta samma information mer {n en
g}ng. Man vill f} upp den f|rsta texten s} snabbt som m|jligt. Man
vill kunna g|ra Lista Nyheter s} snabbt som m|jligt. Det finns m}nga
saker man kan optimera p} olika s{tt.
Elispklienten g|r inte riktigt som jag har beskrivit det p} alla
st{llen, men resultatet blir i princip det samma. En del av anropen
(t ex get_unread_confs) har vi inf|rt i efterhand f|r att vi m{rkte
att det var n|dv{ndigt f|r att f} saker och ting att g} n}gorlunda
snabbt.
Vi har medvetet valt att g|ra s} mycket jobb som m|jligt i klienten,
och s} lite jobb som m|jligt i servern. Nu, n{r det blev s} att
klienten {r skriven i elisp, s} skulle vi nog ha f}tt ett snabbare
system (s{rskilt uppstarten) om servern varit mer intelligent och valt
i vilken ordning texter ska visas. Systemet {r designat med m}let att
det inte ska bli l}ngsammare {ven om m}nga klienter kopplar upp sig
samtidigt, och det m}let har vi nog n}tt. (Att det kan g} l}ngsamt n{r
5-6 personer k|r sin elispklient p} lysator.liu.se beror inte p}
svarstiderna fr}n LysKOM-servern, utan p} att emacsarna blir
l}ngsamma. De som k|r fr}n en obelastad maskin samtidigt m{rker inte
att det g}r l}ngsamt (skryt, skryt:-)). (Nej, det finns inga m{tningar
som bekr{ftar det h{r - men jag t{nker m{ta lite responstider senare i
h|st).
Med en smart klient skriven i c kommer LysKOM att bli snabbt. Om
c-klienterna k|rs p} varsin maskin (var och en har sin egen
arbetsstation) tror jag att systemet kommer att klara "tillr{ckligt"
m}nga anv{ndare. (LysKOM {r ju ett lokalt media. Om hela v{rlden k|rde
p} samma LysKOM-server i st{llet f|r att skriva news skulle det bli
olidligt att l{sa LysKOM {ven om man bortser fr}n responstider...)
P}peka g{rna eventuella oklarheter i den h{r texten. Jag t{nker skicka
med den bland dokumentationen vi har i serverreleasen som vi snart
g|r, s} jag vill att texten ska vara begriplig...
(102868) -----------------------------------
# This file is included by all Makefiles in the LysKOM hierarchy.
# It gives default values for all variables that is normally used.
# TOPDIR and SCRIPTDIR must be set before this file is included.
# If any of the variables are defined in the environment, that value
# will override the value that is set here.
#
# ceder is guilty.
#
SHELL=/bin/sh
AWK = gawk
SED = /usr/bin/sed
CC = gcc -ansi
RM = /usr/gnu/bin/rm -vf
INCLUDEDIR = $(TOPDIR)/include
LIBDIR = $(TOPDIR)/lib
ANSIDIR = $(INCLUDEDIR)/ansi
INCLUDES = -I$(ANSIDIR) -I$(INCLUDEDIR)
OPTIMIZE-FLAGS = -O
MISC-CFLAGS = -g -Wall
PIPE = -pipe
# -h flag makes NULL pointer references generate runtime errors
LDFLAGS = -h -L$(LIBDIR)
CFLAGS = $(INCLUDES) $(OPTIMIZE-FLAGS) $(MISC-CFLAGS) $(PIPE) $(TARGET)
# LysKOM executables that the typical user don't use go here.
# (The server, dbck, et c)
LYSKOMSYSBIN = /usr/lyskom/bin
# User executables (such as lyskom, kompost et c)
LYSKOMUSRBIN = /usr/local/bin
GENERIC-CLEAN = *~ *.o lib*.a dependencies core TAGS temp-Makefile \
temp-?-Makefile
# Too ugly... and it swells...
#
# EXPORTS = CC="${CC}" SHELL="${SHELL}" AWK="${AWK}" SED="${SED}" \
# RM="${RM}" INCLUDEDIR="${INCLUDEDIR}" LIBDIR="${LIBDIR}" \
# ANSIDIR="${ANSIDIR}" INCLUDES="${INCLUDES}" \
# OPTIMIZE-FLAGS="${OPTIMIZE-FLAGS}" \
# MISC-CFLAGS="${MISC-CFLAGS}" PIPE="${PIPE}" \
# LDFLAGS="${LDFLAGS}" CFLAGS="${CFLAGS}" \
# LYSKOMSYSBIN="${LYSKOMSYSBIN}" LYSKOMUSRBIN="${LYSKOMUSRBIN}" \
# TOPDIR="${TOPDIR}" SCRIPTDIR="${SCRIPTDIR}" AR="${AR}" \
# ARFLAGS="${ARFLAGS}" GENERIC-CLEAN="${GENERIC-CLEAN}"
EXPORTS =
# The Makefiles also dependes on the variables
# AR, ARFLAGS
# that are automatically set by GNU Make.
/*
** config.h
**
** System: SunOS 4.1.1
*/
/* #define HAVE_STRERROR */
strerror.o : strerror.c config.h
kom-errno.o : kom-errno.c /users/ceder/lyskom/include/ansi/stdio.h \
/users/ceder/lyskom/include/config.h \
/users/ceder/lyskom/include/kom-errno.h \
/users/ceder/lyskom/include/ansi/sys/types.h /usr/include/sys/types.h \
/usr/gnu/lib/gcc-include/sys/stdtypes.h /usr/include/sys/stdtypes.h \
/usr/include/sys/sysmacros.h
misc-parser.o : misc-parser.c misc-parser.h \
/users/ceder/lyskom/include/kom-types.h \
/users/ceder/lyskom/include/ansi/sys/types.h /usr/include/sys/types.h \
/usr/gnu/lib/gcc-include/sys/stdtypes.h /usr/include/sys/stdtypes.h \
/usr/include/sys/sysmacros.h /usr/gnu/lib/gcc-include/limits.h \
/users/ceder/lyskom/include/ansi/time.h /usr/include/time.h \
/users/ceder/lyskom/include/s-string.h \
/users/ceder/lyskom/include/ansi/stdio.h \
/users/ceder/lyskom/include/ansi/stddef.h \
/users/ceder/lyskom/include/misc-types.h \
/users/ceder/lyskom/include/s-collat-tabs.h
parser.o : parser.c /users/ceder/lyskom/include/ansi/stddef.h \
/users/ceder/lyskom/include/ansi/sys/types.h /usr/include/sys/types.h \
/usr/gnu/lib/gcc-include/sys/stdtypes.h /usr/include/sys/stdtypes.h \
/usr/include/sys/sysmacros.h /users/ceder/lyskom/include/s-string.h \
/usr/gnu/lib/gcc-include/limits.h /users/ceder/lyskom/include/ansi/stdio.h \
/users/ceder/lyskom/include/misc-types.h \
/users/ceder/lyskom/include/s-collat-tabs.h parser.h \
/users/ceder/lyskom/include/zmalloc.h \
/users/ceder/lyskom/include/compiler.h
numlist.o : numlist.c /users/ceder/lyskom/include/ansi/stdio.h \
/users/ceder/lyskom/include/ansi/stdlib.h \
/users/ceder/lyskom/include/ansi/stddef.h \
/users/ceder/lyskom/include/ansi/sys/types.h /usr/include/sys/types.h \
/usr/gnu/lib/gcc-include/sys/stdtypes.h /usr/include/sys/stdtypes.h \
/usr/include/sys/sysmacros.h /users/ceder/lyskom/include/misc-types.h \
numlist.h
testnumlist.o : testnumlist.c /users/ceder/lyskom/include/ansi/stdio.h \
/users/ceder/lyskom/include/ansi/stdlib.h \
/users/ceder/lyskom/include/ansi/stddef.h \
/users/ceder/lyskom/include/ansi/sys/types.h /usr/include/sys/types.h \
/usr/gnu/lib/gcc-include/sys/stdtypes.h /usr/include/sys/stdtypes.h \
/usr/include/sys/sysmacros.h /users/ceder/lyskom/include/misc-types.h \
numlist.h
numlist2.o : numlist2.c /users/ceder/lyskom/include/ansi/stdio.h \
/users/ceder/lyskom/include/ansi/stdlib.h \
/users/ceder/lyskom/include/ansi/stddef.h \
/users/ceder/lyskom/include/ansi/sys/types.h /usr/include/sys/types.h \
/usr/gnu/lib/gcc-include/sys/stdtypes.h /usr/include/sys/stdtypes.h \
/usr/include/sys/sysmacros.h /users/ceder/lyskom/include/misc-types.h \
numlist2.h
zmalloc.o : zmalloc.c /users/ceder/lyskom/include/ansi/stddef.h \
/users/ceder/lyskom/include/ansi/sys/types.h /usr/include/sys/types.h \
/usr/gnu/lib/gcc-include/sys/stdtypes.h /usr/include/sys/stdtypes.h \
/usr/include/sys/sysmacros.h /users/ceder/lyskom/include/ansi/malloc.h \
/users/ceder/lyskom/include/ansi/string.h \
/users/ceder/lyskom/include/compiler.h zmalloc.h
pom.o : pom.c /users/ceder/lyskom/include/ansi/sys/types.h \
/usr/include/sys/types.h /usr/gnu/lib/gcc-include/sys/stdtypes.h \
/usr/include/sys/stdtypes.h /usr/include/sys/sysmacros.h \
/users/ceder/lyskom/include/ansi/time.h /usr/include/time.h \
/users/ceder/lyskom/include/ansi/math.h /usr/include/math.h \
/usr/include/floatingpoint.h /usr/include/sys/ieeefp.h \
/users/ceder/lyskom/include/ansi/stdio.h pom.h
s-collat-tabs.o : s-collat-tabs.c s-collat-tabs.h \
/usr/gnu/lib/gcc-include/limits.h
s-string.o : s-string.c /users/ceder/lyskom/include/ansi/sys/types.h \
/usr/include/sys/types.h /usr/gnu/lib/gcc-include/sys/stdtypes.h \
/usr/include/sys/stdtypes.h /usr/include/sys/sysmacros.h \
/users/ceder/lyskom/include/ansi/stdio.h \
/users/ceder/lyskom/include/ansi/string.h \
/users/ceder/lyskom/include/ansi/ctype.h /usr/include/ctype.h \
/users/ceder/lyskom/include/ansi/stdlib.h \
/users/ceder/lyskom/include/ansi/stddef.h /usr/gnu/lib/gcc-include/assert.h \
/users/ceder/lyskom/include/misc-types.h s-collat-tabs.h \
/usr/gnu/lib/gcc-include/limits.h s-string.h
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment