lyskomd.texi 92.2 KB
 David Byers committed Dec 30, 1998 1 \input texinfo  Per Cederqvist committed Apr 18, 2001 2 @c $Id: lyskomd.texi,v 1.35 2001/04/18 07:03:46 ceder Exp$  David Byers committed Dec 30, 1998 3 4 @c %**start of header @setfilename lyskomd.info  Per Cederqvist committed Apr 03, 1999 5 6 @include version.texi @settitle lyskomd @value{VERSION} Reference Manual  David Byers committed Dec 30, 1998 7 8 9 @setchapternewpage odd @c %**end of header  David Byers committed May 21, 1999 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 @iftex @parindent 0pt @begin tex \global\def\BB#1{\b{#1}} \global\def\II#1{\i{#1}} @end tex @end iftex @ifinfo @macro BB {text} '\text\' @end macro @macro II {text} /\text\/ @end macro @end ifinfo  David Byers committed Dec 30, 1998 27 @ifinfo  Per Cederqvist committed Apr 03, 1999 28 29 This is the reference manual for the lyskomd LysKOM server version @value{VERSION}.  David Byers committed Dec 30, 1998 30   Per Cederqvist committed Sep 05, 2000 31 Copyright @copyright{} 1995-2000 Lysator ACS.  David Byers committed Dec 30, 1998 32 33 34 35 36 37 38 39 40 41 42 43 44  Permission is granted to make and distribute verbatim copies of this specification provided the copyright notice and this permission notice are preserved on all copies. @end ifinfo @dircategory LysKOM @direntry * lyskomd: (lyskomd). lyskomd reference manual. @end direntry @titlepage @sp 10  David Byers committed Jan 14, 1999 45 @title lyskomd Reference Manual  David Byers committed Dec 30, 1998 46 @sp 2  Per Cederqvist committed Apr 03, 1999 47 @subtitle Server version @value{VERSION}  David Byers committed Dec 30, 1998 48 49 50 51 52 @sp 2 @author by the lyskomd developers @page @vskip 0pt plus 1filll  Per Cederqvist committed Sep 05, 2000 53 Copyright @copyright{} 1995-2000 Lysator ACS  David Byers committed Dec 30, 1998 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69  Permission is granted to make and distribute verbatim copies of this document provided the copyright notice and this permission notice are preserved on all copies. Modified versions of this document may be redistributed with the added condition that all modifications not cleared with the LysKOM development group are clearly marked and that the entire modified work be redistributed under the same conditions as the original. Permission is granted to copy and distribute translations of this manual into another language under the same conditions as for modified versions. @end titlepage @ifinfo  Per Cederqvist committed May 23, 1999 70 @node Top  David Byers committed Dec 30, 1998 71 72 73 @top lyskomd lyskomd is a server for the LysKOM conferencing system. This info file  Per Cederqvist committed Apr 03, 1999 74 documents version @value{VERSION} of lyskomd.  David Byers committed Dec 30, 1998 75 76 77 78 79 80 81  @menu * Copying:: lyskomd is free software. * Overview:: Overview of LysKOM. * Installation:: How to install lyskomd. * Configuration:: How to configure lyskomd. * Running lyskomd:: How to run lyskomd.  Per Cederqvist committed May 16, 1999 82 83 * Invoking updateLysKOM:: How to run updateLysKOM. * Invoking komrunning:: How to run komrunning.  David Byers committed Dec 30, 1998 84 * Administration:: Administering a LysKOM server.  David Byers committed May 18, 1999 85 86 87 * Bugs:: Known bugs in lyskomd. * DBCK Reference:: Checking and repairing the database. * Hacking:: Notes for server developers.  David Byers committed May 21, 1999 88 * lyskomd Database Specification::  David Byers committed Dec 30, 1998 89 90 91 92 @end menu @end ifinfo  Per Cederqvist committed May 23, 1999 93 @node Copying  David Byers committed Dec 30, 1998 94 95 @chapter Copying  Per Cederqvist committed May 23, 1999 96 97 lyskomd is free software. It is distributed under the Gnu General Public License version 2. The file COPYING in the top level of the distribution  David Byers committed Dec 30, 1998 98 99 100 contains the text of the license.  Per Cederqvist committed May 23, 1999 101 @node Overview  David Byers committed Dec 30, 1998 102 103 104 105 106 107 @chapter Overview LysKOM is a conferencing system@footnote{Or in modern terms, enabling technology for Computer-Supported Cooperative Work (CSCW).}. Similar systems were QZ-KOM and PortaCOM@footnote{Also known as PottaKOM'' and BortaKOM''.}. The LysKOM system is copyrighted by Lysator Academic  Per Cederqvist committed May 23, 1999 108 109 Computing Society and distributed under conditions of the GNU General Public License version 2. LysKOM and its documentation is provided as is'' without  David Byers committed Dec 30, 1998 110 111 warranty of any kind.  Per Cederqvist committed Apr 03, 1999 112 113 This reference manual documents version @value{VERSION} of the lyskomd LysKOM server. The lyskomd server is the work of several people. The main  David Byers committed Dec 30, 1998 114 contributors have been  Per Cederqvist committed May 23, 1999 115 116 117 Per Cederqvist @email{ceder@@lysator.liu.se}, Inge Wallin @email{inge@@lysator.liu.se}, Thomas Bellman @email{bellman@@lysator.liu.se},  Per Cederqvist committed Apr 03, 1999 118 119 David Byers @email{byers@@lysator.liu.se} and Peter Eriksson @email{pen@@lysator.liu.se}.  David Byers committed Dec 30, 1998 120 121 122 123 124 125 126 127 128  @section History In 1990, Per Cederqvist @email{ceder@@lysator.liu.se} and Peter Eriksson @email{pen@@lysator.liu.se} and a few other persons started to write the server. It was operational in the summer of 1990, even though the members of Lysator discovered a thing called MUD. We started using RCS on 20 May 1991. The first release was made on 16 Sept 1991. Around that  Per Cederqvist committed May 23, 1999 129 time we switched from RCS to CVS to handle our source code.  David Byers committed Dec 30, 1998 130 131 132   Per Cederqvist committed May 23, 1999 133 @node Installation  David Byers committed Dec 30, 1998 134 135 @chapter Installation  Per Cederqvist committed May 23, 1999 136 137 138 139 Instructions for compiling and installing lyskomd are in the files @file{README} and @file{INSTALL}, located in the top level of the lyskomd distribution. Installation should be straightforward on most platforms.  David Byers committed Dec 30, 1998 140 141   Per Cederqvist committed May 23, 1999 142 @node Configuration  David Byers committed Dec 30, 1998 143 144 145 146 @chapter Configuration There are two configuration files for lyskomd. One defines the server options and the other defines aux-item types @ref{(protocol-a)The  Per Cederqvist committed May 23, 1999 147 Aux-Item List,The Aux-Item List}.  David Byers committed Dec 30, 1998 148 149 150 151 152 153 154  @menu * Server Configuration File:: The server configuration file. * Aux-Item Definition File:: The aux-item definition file. @end menu  Per Cederqvist committed May 23, 1999 155 @node Server Configuration File  David Byers committed Dec 30, 1998 156 157 158 @section Server Configuration File The server reads its configuration from a configuration file. The  Per Cederqvist committed Apr 03, 1999 159 default configuration file is @file{/usr/lyskom/etc/config}. The  David Byers committed Dec 30, 1998 160 161 162 163 164 location of the configuration file can be changed at run-time by supplying an argument to lyskomd. The configuration file is line oriented. Each line consists of a parameter name followed by a colon, and the value of the parameter.  David Byers committed May 23, 1999 165 Empty lines and lines whose first non-blank character is a @samp{#} are  David Byers committed Dec 30, 1998 166 167 168 169 170 171 172 ignored. @menu * Parameter Types:: Types of configuration parameters. * Parameters:: Valid configuration parameters. @end menu  Per Cederqvist committed May 23, 1999 173 @node Parameter Types  David Byers committed Dec 30, 1998 174 175 176 177 178 179 180 181 182 183 184 @subsection Parameter Types Every parameter has a type. The legal types are: @table @code @item bool The parameter can be true or false. Legal values are @code{on}, @code{true}, @code{yes} and @code{1} for true and @code{off}, @code{false}, @code{no} and @code{0} for false. @item locale-name  Per Cederqvist committed May 23, 1999 185 The parameter is a locale name. The value must be a legal locale name of  David Byers committed Dec 30, 1998 186 187 188 189 the system where lyskomd is running. @item path The parameter is a path name. The value must be a legal path on the  Per Cederqvist committed Apr 03, 1999 190 system where lyskomd is running. Most paths you can specify can be  Per Cederqvist committed May 23, 1999 191 either absolute paths (if they begin with a @samp{/}) or paths relative  David Byers committed Dec 30, 1998 192 to the installation prefix which is specified at compile time or with  Per Cederqvist committed Apr 03, 1999 193 the @samp{Prefix} parameter in the configuration file.  David Byers committed Dec 30, 1998 194 195 196  @item portname The parameter is a TCP/IP port. It can be a symbolic port name  Per Cederqvist committed Apr 03, 1999 197 (traditionally looked up in @file{/etc/services}) or a port number.  David Byers committed Dec 30, 1998 198 199 200  @item int The parameter is a number of some sort. It can be a conference number,  Per Cederqvist committed May 23, 1999 201 text number or perhaps a timeout.  David Byers committed Dec 30, 1998 202 203 204 205  @end table  Per Cederqvist committed May 23, 1999 206 @node Parameters  David Byers committed Dec 30, 1998 207 208 209 210 @subsection Parameters @table @code  David Byers committed May 12, 1999 211 212 213 214 215 216 217 218 219 220 @item Max conferences: @var{int} The maximum number of conferences possible in the server. This number must be larger than the number of conferences in the database. This parameter is required. There is no default. @item Max texts: @var{int} The maximum number of texts possible in the server. This number must be larger than the number of texts in the database. This parameter is required. There is no default.  Per Cederqvist committed Apr 03, 1999 221 222 @item Locale: @var{string} Use @var{string} as the locale to run in. This parameter is only  David Byers committed Dec 30, 1998 223 224 225 226 available om systems which support the @code{setlocale} call. If this parameter is not set, no call to @code{setlocale} will be made. The default is unset.  Per Cederqvist committed Apr 03, 1999 227 @item Force ISO 8859-1: @var{bool}  David Byers committed Dec 30, 1998 228 229 This option is provided for those with dysfunctional computers that cannot handle @code{setlocale} properly. If this is set, lyskomd will  Per Cederqvist committed Apr 03, 1999 230 handle texts according to the ISO 8859-1 (latin1) alphabet. Default  David Byers committed Dec 30, 1998 231 232 is off.  Per Cederqvist committed Apr 03, 1999 233 @item Prefix: @var{path}  David Byers committed Dec 30, 1998 234 All files that the server uses are found in sub-directories of this  Per Cederqvist committed May 23, 1999 235 directory. The default value of this parameter is set at compile time.  Per Cederqvist committed Apr 03, 1999 236 The default at compile time is @file{/usr/lyskom}.  David Byers committed Dec 30, 1998 237   Per Cederqvist committed Apr 03, 1999 238 @item Send async: @var{bool}  David Byers committed Dec 30, 1998 239 240 241 242 Do not send any non-requested messages. This disables the sending of messages about events in the server to all connections. Use of this parameter is not recommended. Default is on.  Per Cederqvist committed Apr 19, 1999 243 244 245 246 247 248 249 @item Client host: @var{hostname} Specify which IP number the server should use when listening for new clients. @var{hostname} may be a FQDN (such as @samp{kom.lysator.liu.se}) or an IP number (such as @samp{10.0.0.1}). Default is to bind @code{INADDR_ANY}, which means that the server will listen to all IP numbers of the computer it is running on.  Per Cederqvist committed Apr 03, 1999 250 251 @item Client port: @var{portname} Listen for new clients on port @var{portname}. The default is 4894, which  David Byers committed Dec 30, 1998 252 253 254 is what all clients expect. Do not change this parameter without really good reason.  Per Cederqvist committed Apr 03, 1999 255 @item Presentation of conferences: @var{int}  Per Cederqvist committed May 23, 1999 256 The number of the conference where presentations should be sent.  David Byers committed Dec 30, 1998 257 258 259 260 Defaults to 1. This option is ignored in lyskomd 1.9 and later. Set this using dbck or the @ref{(protocol-a)set-info,set-info}.  Per Cederqvist committed Apr 03, 1999 261 @item Presentation of persons: @var{int}  Per Cederqvist committed May 23, 1999 262 The number of the conference where presentations should be sent.  David Byers committed Dec 30, 1998 263 264 265 Defaults to 2. This option is ignored in lyskomd 1.9 and later. Set this using dbck or the @ref{(protocol-a)set-info,set-info}.  Per Cederqvist committed Apr 03, 1999 266 @item Motd-conference: @var{int}  David Byers committed Dec 30, 1998 267 The number of the conference where "message-of-the-day" messages should  Per Cederqvist committed May 23, 1999 268 be sent. Defaults to 3. This option is ignored in lyskomd 1.9 and later.  David Byers committed Dec 30, 1998 269 270 Set this using dbck or the @ref{(protocol-a)set-info,set-info}.  Per Cederqvist committed Apr 03, 1999 271 @item News-conference: @var{int}  David Byers committed Dec 30, 1998 272 273 274 275 276 277 278 279 The number of the conference where news of interest to the readers of this LysKOM server should be written. This is typically a conference with very low traffic which everyone shoule be a member of. Clients should offer new users to join it. Defaults to 4. This option is ignored in lyskomd 1.9 and later. Set this using dbck or the @ref{(protocol-a)set-info,set-info}.  Per Cederqvist committed Apr 03, 1999 280 @item Message of the day: @var{int}  David Byers committed Dec 30, 1998 281 282 283 284 285 286 Default message-of-the-day of this server. The text will be shown automatically by conforming LysKOM clients when a user logs on. This option is ignored in lyskomd 1.9 and later. Set this using dbck or the @ref{(protocol-a)set-info,set-info}.  Per Cederqvist committed Apr 03, 1999 287 @item Garb: @var{bool}  David Byers committed Dec 30, 1998 288 289 290 Should the database be automatically purged of old texts? The default is on.  Per Cederqvist committed Apr 03, 1999 291 @item Never save: @var{bool}  Per Cederqvist committed Aug 04, 2000 292 293 Completely disables saving the database. Do not set this to @code{true} unless you really know what you're doing. The default is @code{false}.  David Byers committed Dec 30, 1998 294   Per Cederqvist committed Apr 03, 1999 295 @item Log accesses: @var{path}  David Byers committed Dec 30, 1998 296 297 298 299 This parameter can only be set if the server has been compiled with @code{LOGACCESSES} defined. It will save a trace of all activity in the database to a file, for later use in simulations et c. Compiling with @code{LOGACCESSES} slows the server down quite a lot, so it is normally  Per Cederqvist committed May 23, 1999 300 not defined.  David Byers committed Dec 30, 1998 301   Per Cederqvist committed Apr 03, 1999 302 @item Data file: @var{path}  David Byers committed Dec 30, 1998 303 The path relative to the installation prefix where part of the database  Per Cederqvist committed Apr 03, 1999 304 is kept. The default is @file{db/lyskomd-data}.  David Byers committed Dec 30, 1998 305   Per Cederqvist committed Apr 03, 1999 306 @item Backup file: @var{path}  David Byers committed Dec 30, 1998 307 The path relative to the installation prefix where a backup of the  Per Cederqvist committed May 23, 1999 308 database is kept. This file will always contain a complete database, but  Per Cederqvist committed Apr 03, 1999 309 it may be a little out-of-date. Default is @file{db/lyskomd-backup}.  David Byers committed Dec 30, 1998 310   Per Cederqvist committed Apr 03, 1999 311 @item Backup file 2: @var{path}  David Byers committed Dec 30, 1998 312 313 314 The path relative to the installation prefix where a previous generation of the backup of the database is kept. This file may be needed if an error in the backup file is detected during the creation of the data  Per Cederqvist committed Apr 03, 1999 315 file. Default is @file{db/lyskomd-backup-prev}.  David Byers committed Dec 30, 1998 316   Per Cederqvist committed May 21, 1999 317 318 319 320 321 322 @item Lock file: @var{path} Name of the lock file that ensures that @code{dbck} and @code{lyskomd} never attempt to modify the database at the same time. It should always reside in the same directory as the @samp{Data file}. Default is @file{db/lyskomd-lock}.  Per Cederqvist committed Apr 03, 1999 323 @item Text file: @var{path}  David Byers committed Dec 30, 1998 324 The path relative to the installation prefix where the actual texts in  Per Cederqvist committed Apr 03, 1999 325 the database are kept. Default is @file{db/lyskomd-texts}.  David Byers committed Dec 30, 1998 326   Per Cederqvist committed Apr 03, 1999 327 @item Text backup file: @var{path}  David Byers committed May 23, 1999 328 When dbck is run with the @samp{-g} option (@ref{(dbck)Invoking  David Byers committed Dec 30, 1998 329 330 331 dbck,Invoking dbck}, it will store the previous contents of the text file in the file specified by this option. The path is relative to the installation prefix. This file is never used by lyskomd itself. Default  Per Cederqvist committed Apr 03, 1999 332 is @file{db/lyskomd-texts-backup}.  David Byers committed Dec 30, 1998 333   Per Cederqvist committed Apr 03, 1999 334 @item Log file: @var{path}  David Byers committed Dec 30, 1998 335 The path relative to the installation prefix where log messages from  Per Cederqvist committed Apr 03, 1999 336 lyskomd are written. Default is @file{etc/server-log}.  David Byers committed Dec 30, 1998 337   Per Cederqvist committed Apr 03, 1999 338 339 @item Log statistics: @var{path} Whenever lyskomd receives a SIGUSR1 it will append a timestamp and  David Byers committed Dec 30, 1998 340 341 a count of how many different atomic calls have been made in this file. The path is relative to the installation prefix. Default is  Per Cederqvist committed Apr 03, 1999 342 @file{etc/lyskomd-log}.  David Byers committed Dec 30, 1998 343   Per Cederqvist committed Apr 03, 1999 344 @item Pid file: @var{path}  David Byers committed Dec 30, 1998 345 346 347 When lyskomd is up and running it will write its pid in this file. The path is relative to the installation prefix. This file is used so the @code{updateLysKOM} script can easily find out what pid the LysKOM  Per Cederqvist committed Apr 03, 1999 348 server has. Default is @file{etc/pid}.  David Byers committed Dec 30, 1998 349   Per Cederqvist committed May 16, 1999 350 351 352 This file should be removed when the computer reboots, before @code{komrunning} or @code{updateLysKOM} is run.  Per Cederqvist committed Apr 03, 1999 353 @item Memory usage file: @var{path}  David Byers committed Dec 30, 1998 354 355 When lyskomd exits normally it appends some info on its usage of memory to this file. The path is relative to the installation prefix. Almost  Per Cederqvist committed Apr 03, 1999 356 357 any memory leak bugs should be detectable by looking in this file. Default is @file{etc/memory-usage}.  David Byers committed Dec 30, 1998 358   Per Cederqvist committed Apr 03, 1999 359 @item Aux-item definition file: @var{path}  David Byers committed Dec 30, 1998 360 This file defines which aux-items the server should support and how it  Kent Engström committed Oct 12, 1999 361 362 should handle them. You will find the details in @xref{Aux-Item Definition File}.  David Byers committed Dec 30, 1998 363 The path is relative to the installation prefix. Default is  Per Cederqvist committed Apr 03, 1999 364 @file{etc/aux-items.conf}.  Per Cederqvist committed Sep 06, 2000 365 This file is re-read if a @samp{SIGWINCH} singal is sent to the server.  David Byers committed Dec 30, 1998 366   David Byers committed May 12, 1999 367 @item Core directory: @var{path}  Per Cederqvist committed May 23, 1999 368 The Directory where core dumps are written. This path is relative to the  David Byers committed May 12, 1999 369 370 installation prefix. Default is @file{cores}.  Per Cederqvist committed Apr 17, 1999 371 372 373 @item Status file: @var{path} This file is created by @code{komrunning} to indicate that lyskomd should currently not be running. When this file exists  David Byers committed May 23, 1999 374 @code{updateLysKOM} will send it a @samp{SIGHUP} signal, so that it  Per Cederqvist committed Apr 17, 1999 375 376 saves the database and dies. Default is @file{etc/status}.  David Byers committed May 12, 1999 377 378 @item Nologin file: @var{path} If this file exists, the server will not allow any connections at all.  David Byers committed May 23, 1999 379 Default is @file{/etc/nologin}.  David Byers committed Dec 30, 1998 380   Per Cederqvist committed Apr 03, 1999 381 @item Idle timeout: @var{int}  David Byers committed Dec 30, 1998 382 383 384 Number of milliseconds to sleep when there is nothing for lyskomd to do. Default is @code{120000} (two minutes.)  Per Cederqvist committed Apr 03, 1999 385 @item Garb timeout: @var{garb}  David Byers committed Dec 30, 1998 386 387 388 389 Number of milliseconds to sleep when the server is garbage-collecting texts, but has nothing else important to do. Default is @code{100} (0.1 seconds.)  Per Cederqvist committed Apr 03, 1999 390 @item Sync timeout: @var{sync}  David Byers committed Dec 30, 1998 391 392 393 Number of milliseconds to sleep when lyskomd is saving its database. Defaults to 0.  Per Cederqvist committed Apr 03, 1999 394 @item Permissive sync: @var{bool}  David Byers committed Dec 30, 1998 395 Turning this option on lets any session sync the LysKOM database.  Per Cederqvist committed May 23, 1999 396 Turning it off restricts the operation to LysKOM administrators. Default  David Byers committed Dec 30, 1998 397 398 is off.  Per Cederqvist committed Apr 03, 1999 399 @item Garb interval: @var{int}  David Byers committed Dec 30, 1998 400 401 402 Number of minutes between each garb sweep. Defaults to @code{1440}, that is, a garb sweep will be run once per day.  Per Cederqvist committed Apr 03, 1999 403 @item Sync interval: @var{int}  David Byers committed Dec 30, 1998 404 405 406 407 408 Number of minutes between syncs. The current version of lyskomd keeps changes to the database in memory until they are synced to disk. This parameter specifies the number of minutes the server waits before attempting to dump the database. The default is @code{5}.  Per Cederqvist committed Apr 03, 1999 409 @item Sync retry interval: @var{int}  David Byers committed Dec 30, 1998 410 411 412 413 If anything goes wrong while trying to dump the data base (such as if the disk is full), lyskomd will wait for this many minutes before trying again. Default is @code{1}.  Per Cederqvist committed Jun 19, 1999 414 415 416 417 418 419 420 @item Saved items per call: @var{int} When the server is saving the database, it does so in the background. It serves one call from a client, saves a few items to the new database file, serves another call, et c. This parameter sets the number of items (texts, conferences, persons) that are saved after each call. Default is @code{5}.  David Byers committed May 12, 1999 421 422 423 424 @item Max client data length: @var{int} The maxiumum allowed length for client name and version data. The default is @code{60}.  Per Cederqvist committed Apr 03, 1999 425 @item Max conference name length: @var{int}  David Byers committed Dec 30, 1998 426 427 The maximum length of conference names. The default is @code{60}.  Per Cederqvist committed Apr 03, 1999 428 @item Max password length: @var{int}  David Byers committed Dec 30, 1998 429 430 431 432 Only the first eight characters of the password are currently significant, even if this number is much larger. The default is @code{128}.  Per Cederqvist committed Apr 03, 1999 433 @item Max what am I doing length: @var{int}  David Byers committed Dec 30, 1998 434 435 436 437 The maximum length of the string permitted in the protocol A call @ref{(protocol-a)change-what-i-am-doing, change-what-i-am-doing}. The default is 60.  Per Cederqvist committed Apr 03, 1999 438 @item Max username length: @var{int}  David Byers committed Dec 30, 1998 439 440 The maximum length permitted for user names. Default is 128.  Per Cederqvist committed Apr 03, 1999 441 @item Max text length: @var{int}  David Byers committed Dec 30, 1998 442 443 The maximum length allowed for a text. The default is 131072 characters.  Per Cederqvist committed Jun 13, 1999 444 445 446 447 @item Max aux_item length: @var{int} The maximum length allowed for a single aux-item. The default is 16384 characters.  Per Cederqvist committed Apr 03, 1999 448 @item Max broadcast length: @var{int}  David Byers committed Dec 30, 1998 449 450 451 The maximum length allowed for broadcast messges. The default is 1024 characters.  Per Cederqvist committed Apr 03, 1999 452 @item Max regexp length: @var{int}  David Byers committed Dec 30, 1998 453 454 455 The maximum length allowed for regexps in various calls. The default is 1024 characters.  Per Cederqvist committed Apr 03, 1999 456 @item Max marks per person: @var{int}  David Byers committed Dec 30, 1998 457 458 459 The maximum number of marks a person is allowed to have. The default is 2048.  Per Cederqvist committed Apr 03, 1999 460 @item Max marks per text: @var{int}  David Byers committed Dec 30, 1998 461 462 The maximum number of marks a text can have. The default is 1024.  Per Cederqvist committed Apr 03, 1999 463 @item Max recipients per text: @var{int}  David Byers committed Dec 30, 1998 464 465 The maximum number of recipients of a text. The default is 512.  Per Cederqvist committed Apr 03, 1999 466 @item Max comments per text: @var{int}  David Byers committed Dec 30, 1998 467 468 The maximum number of comments a text can have. The default is 128.  Per Cederqvist committed Apr 03, 1999 469 @item Max footnotes per text: @var{int}  David Byers committed Dec 30, 1998 470 471 The maximum number of footnotes a text can have. The default is 32.  Per Cederqvist committed Apr 03, 1999 472 @item Max links per text: @var{int}  David Byers committed May 23, 1999 473 The maximum number of misc info items that can be added to a text.  David Byers committed Dec 30, 1998 474   Per Cederqvist committed Apr 03, 1999 475 @item Max mark_as_read chunks: @var{int}  David Byers committed May 23, 1999 476 @c FIXME: What is this?  David Byers committed Dec 30, 1998 477   Per Cederqvist committed Apr 03, 1999 478 @item Max super_conf loop: @var{int}  David Byers committed May 23, 1999 479 @c FIXME: What is this?  David Byers committed Dec 30, 1998 480   Per Cederqvist committed Apr 03, 1999 481 @item Max accept_async len: @var{int}  David Byers committed Dec 30, 1998 482 483 484 Maximum length of list accepted in the accept_async call. Default is 128.  Per Cederqvist committed Apr 03, 1999 485 @item Max aux_items deleted per call: @var{int}  David Byers committed Dec 30, 1998 486 487 488 Maximum number of aux_items that can be deleted in one call. Default is 128.  Per Cederqvist committed Apr 03, 1999 489 @item Max aux_items added per call: @var{int}  Per Cederqvist committed Jun 13, 1999 490 Maximum number of aux_items that can be added at once. Default is 128.  David Byers committed Dec 30, 1998 491   Per Cederqvist committed Apr 03, 1999 492 @item Default garb nice: @var{int}  David Byers committed Dec 30, 1998 493 494 495 496 497 Each conference has a lifetime for texts written in it. The lifetime is counted in days, and can be set for each conference by the administrator of the conference. This is the default value assigned to new conferences. Default is 77 days.  Per Cederqvist committed Apr 03, 1999 498 @item Default keep commented nice: @var{int}  David Byers committed Jan 07, 1999 499 500 501 502 503 A text will not be removed if it has comments newer than a certain number of days. This number can be set for each conference. This parameter specifies the default value for that number of days. The default is 77.  Per Cederqvist committed Apr 03, 1999 504 @item Max client transmit queue: @var{int}  Per Cederqvist committed Apr 05, 1999 505 Max number of pending data blocks in the reply queue to a client. If  David Byers committed Dec 30, 1998 506 507 508 509 there is ever more than this many data blocks in the queue the client will be disconnected. Each atomic question typically generates two data blocks. Default is 300.  Per Cederqvist committed Apr 03, 1999 510 @item Max simultaneous client replies: @var{int}  David Byers committed Dec 30, 1998 511 512 513 This is a performance tuning parameter of little real interest. Default is 10.  Per Cederqvist committed Apr 03, 1999 514 @item Open files: @var{int}  David Byers committed Dec 30, 1998 515 516 517 518 519 Try to persuade the operating system to allow lyskomd to have this many open file descriptors simultaneously. Each client that is connected to the server occupies one file descriptor, and lyskomd needs several file descriptors for internal purposes. Default is to not use this parameter.  Per Cederqvist committed Apr 03, 1999 520 @item Anyone can create new persons: @var{bool}  David Byers committed Dec 30, 1998 521 522 523 If this is set, anyone can create a new person, even if he lacks special bits for doing so. Default is on.  Per Cederqvist committed Apr 03, 1999 524 @item Anyone can create new conferences: @var{bool}  David Byers committed Dec 30, 1998 525 526 527 If this is set, anyone can create a new conferences, even if he lacks special bits for doing so. Default is on.  Per Cederqvist committed Apr 03, 1999 528 @item Allow creation of persons before login: @var{bool}  David Byers committed Dec 30, 1998 529 530 531 532 533 If this is set, persons can connect the the server and create a new person without logging in. This is how new users register in open environments. If this option is off, then new persons can only be created by existing users. The default is on.  Per Cederqvist committed Apr 03, 1999 534 @item Default change name capability: @var{bool}  David Byers committed Dec 30, 1998 535 536 537 If this is set, new users are created with the ability to change their own name. Default is on.  Per Cederqvist committed Apr 03, 1999 538 @item Ident-authentication: @var{policy}  David Byers committed Dec 30, 1998 539 540 Decide how strictly the server should use the IDENT protocol. The policy can take any of three values:  Per Cederqvist committed Apr 03, 1999 541   David Byers committed Dec 30, 1998 542 543 544 545 546 547 548 549 550 551 552 553 @table @asis @item @code{off} or @code{never} Do not use the IDENT protocol. @item @code{on} or @code{try} Use it, but allow logins even if the lookup fails. @item @code{require} or @code{required} Disallow connections if the server cannot find a IDENT login name. @end table  Per Cederqvist committed Apr 03, 1999 554 @item Log login: @var{bool}  David Byers committed Dec 30, 1998 555 556 Should logins be logged to the log file? Default value is off.  Per Cederqvist committed Apr 03, 1999 557 @item Cache conference limit: @var{int}  David Byers committed Dec 30, 1998 558 559 560 561 How many conference statuses the server cache should hold in main memory. Default is 20. This parameter should be set to at least the number of expected simultaneous logins.  Per Cederqvist committed Apr 03, 1999 562 @item Cache person limit: @var{int}  David Byers committed Dec 30, 1998 563 564 565 566 How many person statuses the server cache should hold in main memory. Default is 20. This parameter should be set to at least the number of expected simultaneous logins.  Per Cederqvist committed Apr 03, 1999 567 @item Cache text_stat limit: @var{int}  David Byers committed Dec 30, 1998 568 569 570 571 How many text statuses the server cache should hold in main memory. The default is 20. This parameter should be increased on busy servers.  Per Cederqvist committed Apr 03, 1999 572 573 @item Echo: @var{string} Write @var{string} in the log when the config file is read.  David Byers committed Dec 30, 1998 574   Per Cederqvist committed Apr 03, 1999 575 576 577 @item Jubel: @var{pers_no} @var{text_no} States that @var{pers_no} is not allowed to create text number @var{text_no}. Default is unset.  David Byers committed Dec 30, 1998 578   Per Cederqvist committed Apr 03, 1999 579 580 581 @item Jubel: @var{pers_no} @var{dividend} @var{remainder} States that @var{pers_no} is not allowed to create any text number @var{T} which meets the condition @var{T} % @var{dividend} == @var{remainder}.  David Byers committed Dec 30, 1998 582 583 Default is unset.  Per Cederqvist committed Apr 03, 1999 584 @item Add members by invitation: @var{bool}  David Byers committed Dec 30, 1998 585 586 587 588 If this is set, then adding others as members to a conference sets the invitation bit of the membership. If this is off, the membership bit is set to whatever the caller specifies. The default is on.  Per Cederqvist committed Apr 03, 1999 589 @item Allow secret memberships: @var{bool}  David Byers committed Dec 30, 1998 590 591 592 593 If this is set, then memberships may be secret. Otherwise any attempt to create a secret membership or change an existing membership to a secret membership will fail. The default is on.  Per Cederqvist committed Apr 03, 1999 594 @item Allow reinvitations: @var{bool}  David Byers committed Dec 30, 1998 595 596 597 598 599 600 If this is set, then it is possible to set the invitation bit of a membership even after it has been cleared. If it is not set, then the invitation bit of a conference type can only be set when the membership is created. It can be cleared at any time. The default is off.  Per Cederqvist committed Apr 18, 1999 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 @item lyskomd path: @var{path} Path to the @code{lyskomd} binary. This is used by @code{updateLysKOM} to find the right program to run. Defaults to @file{bin/lyskomd}. @item savecore path: @var{path} Path to the @code{savecore} program. If a file named @file{core} exists in the directory specified with @code{Core directory} when @code{updateLysKOM} is about to start @code{lyskomd}, this program will be called first. It could, for instance, move the core file so that it is available for later debugging. @item Normal shutdown time: @var{int} In a normal setup, @code{updateLysKOM} will be run from @code{cron} once every ten minutes or so. If it detects that it has taken @code{lyskomd} more than @var{int} minutes to shut down it will print a warning message. @item Mail after downtime: @var{int} @itemx Mail until downtime: @var{int} If @code{lyskomd} has been down for X minutes, where @code{Mail after downtime} <= X < @code{Mail until downtime}, @code{updateLysKOM} will send a mail message to the mail address found on the first line of the status file. Actually, it is the age of the status file (named with @code{Status file}) that is measured.  David Byers committed Dec 30, 1998 627 628 629 @end table  Per Cederqvist committed May 23, 1999 630 @node Aux-Item Definition File  David Byers committed Dec 30, 1998 631 632 633 634 635 636 @section Aux-Item Definition File The default aux-item definition file should not be changed unless it is really necessary. The need to change the definitions will probably only arise at installations used for client or server development.  Per Cederqvist committed Apr 03, 1999 637 638 The location of the aux-item definition file is specified by the @code{Aux-item definition file} option in the server configuration  Per Cederqvist committed Apr 03, 1999 639 file. The default location is @file{/usr/lyskom/etc/aux-items.conf}.  David Byers committed Dec 30, 1998 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659  @subsection Syntax of the Aux-Item Definition File The aux-item definition file contains a sequence of aux-item definitions. Each definition specifies one type of predefined aux-item: its number, name, and properties. Empty lines and all characters from a # character to the end of the line are ignored. Each entry has the following format: @example tag : name (target, target, ... ) @{ field = value; field = value; ... @} @end example  Per Cederqvist committed May 23, 1999 660 661 @var{tag} is an integer, the aux-item's tag. If a tag is defined more than once, the last definition is used.  David Byers committed Dec 30, 1998 662   Per Cederqvist committed Apr 03, 1999 663 The @var{target}s specify what kind of objects aux-items with tag @var{tag}  David Byers committed Dec 30, 1998 664 665 666 667 668 669 670 671 672 673 674 675 can be added to. Valid targets are: @table @code @item any Aux-items with the specified tag can be added to any object in the database. This is shorthand for @code{text,conference,letterbox,server}. @item text Aux-items with the specified tag can be added to texts. @item conference Aux-items with the specified tag can be added to conferences that are  David Byers committed May 23, 1999 676 @emph{not} letterboxes.  David Byers committed Dec 30, 1998 677 678 679 680  @item letterbox Aux-items with the specified tag can be added to conferences that are letterboxes.  Per Cederqvist committed Apr 03, 1999 681 682 683 684  @item server Aux-items with the specified tag can be added to the server itself.  David Byers committed Dec 30, 1998 685 686 687 688 689 690 691 692 693 694 @end table It is legal to add one of the keywords @code{create} or @code{modify} before any target except @code{server}. If @code{create} is specified, aux-items with the specified tag can only be added when an object is being created. They cannot be added later. If @code{modify} is specified, aux-items with the specified tag can only be added after an object has been created. They cannot be added when the object is being created.  Per Cederqvist committed May 23, 1999 695 Each @var{field}/@var{value} pair specifies a property of aux-items with the  David Byers committed Dec 30, 1998 696 697 698 699 700 701 702 703 specified tag. Most values are boolean or trillian. Legal values for either type are @code{true} and @code{false}. Boolean values have reasonable defaults; trillian values can be unset. @table @code @item author-only Boolean, default false. When true, only the author of a text or  Per Cederqvist committed May 23, 1999 704 supervisor of a conference can create items with this tag.  David Byers committed Dec 30, 1998 705 706 707 708  @item supervisor-only Boolean, default false. When true, only the supervisors of the author or letterbox can create items with this tag. In all likelihood, the  David Byers committed May 12, 1999 709 710 711 implementation of this flag is screwed up in version 2.0 of lyskomd. @item system-only  Per Cederqvist committed May 23, 1999 712 Boolean, default false. When true, only the server can initiate creation  David Byers committed May 12, 1999 713 714 of items with this tag. This is normally used for items that are created automatically in response to events in the system.  David Byers committed Dec 30, 1998 715   Per Cederqvist committed May 23, 1999 716 @item permanent  Per Cederqvist committed Apr 03, 1999 717 718 719 Boolean, default false. When true, aux-items with this tag cannot be deleted once they have been created. (They will be deleted automatically when the object they are assigned to is deleted.)  David Byers committed Dec 30, 1998 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739  @item unique Boolean, default false. When true, there can only be one non-deleted item with this tag per creator. @item inherit-limit Integer, default 0. The maximum number of times items with this tag can be inherited, plus one. Zero means an unlimited number of times, one means no times, 2 means once and so forth. This number overrides the inherit-limit set by the client only if that number is higher than this one. @item inherit Trillian. When set, the inherit bit on new items with this tag is forced to the specified value. @item secret Trillian. When set, the secret bit on new items with this tag is forced to the specified value.  Per Cederqvist committed May 23, 1999 740 @item hide-creator  David Byers committed Dec 30, 1998 741 742 743 Trillian. When set, the hide-creator bit on new items with this tag is forced to the specified value.  Per Cederqvist committed May 23, 1999 744 @item dont-garb  David Byers committed Dec 30, 1998 745 746 747 748 749 750 751 752 753 754 Trillian. When set, the dont-garb bit on new items will be forced to the specified value. @item reserved-2 @item reserved-3 @item reserved-4 Trillian. When set, these flags force the values of the three reserved bits in the aux-item flags field. These should only be used by lyskomd developers, and then only very carefully.  Per Cederqvist committed May 23, 1999 755 @item validate  David Byers committed May 12, 1999 756 757 758  String or function, default none. When set to a string, this specifies a regexp that must match the data field in newly created items with this  Per Cederqvist committed May 23, 1999 759 tag. If the regexp fails to match, then the item will not be created.  David Byers committed May 12, 1999 760 761 762 763 764 765 766 767 768 769 770 771 772 773 The syntax for strings is essentially the same as the syntax used in C files. When set to a function, this specified a built-in validation function to call. The following validator functions are currently implemented: @table @code @item existing-readable-text Creation is only allowed if the item contains the number of an existing text that the item creator has permission to read. @end table  David Byers committed Dec 30, 1998 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798  @end table There are a few fields which specify actions the server is to take when something happens to aux-items with the specified tag. Each of these values is a function specification, the name of a trigger function defined in lyskomd. The syntax for functions is the name followed by an empty pair of parens. It is not possible to pass arguments to the functions yet. @table @code @item add-trigger Function to call when an item with the specified tag is added to an object. @item delete-trigger Function to call when an item with the specified tag is scheduled for deletion. @item undelete-trigger Function to call when an item with the specified tag scheduled for deletion is unscheduled. It should undo the effects of the delete trigger. @end table  David Byers committed May 12, 1999 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 The following trigger functions are currently defined: @table @code @item mark-text Increase the mark count for the text the item refers to. The item must contain the number of a text. This trigger should be combined with the existing-readable-text validation function. @item unmark-text Decrease the mark count for the text the item refers to. The item must contain the number of a text. This trigger should be combined with the existing-readable-text validation function. @item link-faq Create a faq-for-conf item linked to a faq-text item. This trigger is used exclusively for faq-text items. The item must contain the number of a text. This trigger must be combined with the existing-readable-text validation function. @end table  David Byers committed Dec 30, 1998 821 822   Per Cederqvist committed May 23, 1999 823 @node Running lyskomd  David Byers committed Dec 30, 1998 824 825 826 827 828 829 830 831 832 833 834 835 @chapter Running lyskomd This section explains how to run lyskomd, the files it uses and how it can be controlled while running. @menu * Invoking lyskomd:: How to run lyskomd. * Signals:: How to control lyskomd with Unix signals. * Files:: Files used by lyskomd. @end menu  Per Cederqvist committed May 23, 1999 836 @node Invoking lyskomd  David Byers committed Dec 30, 1998 837 838 839 @section Invoking lyskomd @example  Per Cederqvist committed Apr 03, 1999 840  lyskomd [-d] [@var{config-file}]  David Byers committed Dec 30, 1998 841 842 @end example  David Byers committed May 23, 1999 843 The option @samp{-d} adds one to the debug level. The amount of output  David Byers committed Dec 30, 1998 844 845 846 847 on stderr is increased for each time the option is specified on the command line. Furthermore, if this option is used, lyskomd will not run as a daemon, but will stay in forground mode.  David Byers committed May 23, 1999 848 Using one @samp{-d} makes the process print a >' for every timeout, a  David Byers committed Dec 30, 1998 849 850 851 852 message for every person that is connecting or disconnecting and a message for every successful or unsuccessful communication to the process.  Per Cederqvist committed Apr 03, 1999 853 The optional @var{config-file} argument can be used to specify the server  David Byers committed Dec 30, 1998 854 855 856 configuration file. @xref{Server Configuration File}.  Per Cederqvist committed May 23, 1999 857 @node Signals  David Byers committed Dec 30, 1998 858 859 860 861 862 @section Signals It is possible to control some aspects of lyskomd using Unix signals. The following signals have special meaning to the server:  David Byers committed May 23, 1999 863 @table @samp  David Byers committed Dec 30, 1998 864 865 866 867 868 869 870 871 872 873 874 875 876 @item SIGHUP Logs out all sessions, saves the database and exits normally. @item SIGQUIT Saves the database and dump core. (This should only be used for debugging purposes.) @item SIGUSR1 Print statistics about how often different commands have been used since the process started. @item SIGUSR2 Forks a child that immediately dumps core. The main process just waits  Per Cederqvist committed Apr 03, 1999 877 until the child is done and then continues.  Per Cederqvist committed Sep 06, 2000 878 879 880  @item SIGWINCH Re-read the aux-item definition file.  David Byers committed Dec 30, 1998 881 882 883 @end table  Per Cederqvist committed May 23, 1999 884 @node Files  David Byers committed Dec 30, 1998 885 886 887 888 889 @section Files Used by lyskomd All file names can be changed in the server configuration file. @xref{Parameters}.  Per Cederqvist committed Apr 03, 1999 890 @table @file  David Byers committed Dec 30, 1998 891 @item /usr/lyskom  Per Cederqvist committed Apr 03, 1999 892 893 894 Default value of the @code{Prefix} parameter. The default of this value is set at compile time, but it can be changed in the server configuration file. @xref{Parameters}.  David Byers committed Dec 30, 1998 895   David Byers committed May 23, 1999 896 @item @var{prefix}/db/lyskomd-data  Per Cederqvist committed Apr 03, 1999 897 Half of the database: all status information.  David Byers committed Dec 30, 1998 898   David Byers committed May 23, 1999 899 @item @var{prefix}/db/lyskomd-texts  David Byers committed Dec 30, 1998 900 901 The other half of the database: the actual texts.  David Byers committed May 23, 1999 902 @item @var{prefix}/db/lyskomd-backup  Per Cederqvist committed Apr 03, 1999 903 A backup copy of @file{lyskomd-data}. Never, ever delete this file  David Byers committed Dec 30, 1998 904 905 906 unless you know what you are doing, or you may lose the entire data base. Most of the time this is the only complete database file!  David Byers committed May 23, 1999 907 @item @var{prefix}/etc/pid  David Byers committed Dec 30, 1998 908 909 File with the pid of the lyskom-process.  David Byers committed May 23, 1999 910 911 @item @var{prefix}/etc/memory-usage On normal exit, @code{lyskomd} will append some statistics to this file.  David Byers committed Dec 30, 1998 912 913 It can be used for detecting memory leaks.  David Byers committed May 23, 1999 914 @item @var{prefix}/etc/aux-items.conf  David Byers committed Dec 30, 1998 915 This file contains definitions of the aux-items that the server should  Per Cederqvist committed May 23, 1999 916 support. It is read by @code{lyskomd} at startup.  David Byers committed Dec 30, 1998 917   David Byers committed May 12, 1999 918 919 920 921 922 @item /etc/nologin If this file exists, lyskomd will not allow anyone to connect to the server. This path can be set with the @code{Nologin file} parameter in the server configuration file.  David Byers committed Dec 30, 1998 923 924 925 @end table  Per Cederqvist committed May 23, 1999 926 @node Invoking updateLysKOM  Per Cederqvist committed May 16, 1999 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 @chapter Invoking updateLysKOM @example updateLysKOM [-c @var{config-file}] [ -v ] [ -V ] @end example @code{updateLysKOM} determines if @code{lyskomd} should be running. It can start or stop @code{lyskomd} if needed. It uses the same configuration file as @code{lyskomd} (@pxref{Server Configuration File}). You can use @samp{-c @var{config-file}} to override the compiled-in default. Note, however, that this option is not passed along to @code{lyskomd} if @code{updateLysKOM} starts it, so the option should be used with extreme caution. @samp{-v} and @samp{-V} causes @code{updateLysKOM} to report its version number and exit. @code{updateLysKOM} is normally run from @code{cron}; @pxref{Administration}.  Per Cederqvist committed May 23, 1999 947 @node Invoking komrunning  Per Cederqvist committed May 16, 1999 948 949 950 951 952 953 @chapter Invoking komrunning @example komrunning [-c config-file] [start | stop] komrunning -v | -V @end example  David Byers committed Dec 30, 1998 954   Per Cederqvist committed May 16, 1999 955 956 @code{komrunning}, when invoked with no arguments, reports whether @code{lyskomd} is currently running or not, and whether it should be  David Byers committed May 23, 1999 957 958 running or not. @samp{komrunning start} attempts to start @code{lyskomd}. @samp{komrunning stop} attempts to stop @code{lyskomd},  Per Cederqvist committed May 16, 1999 959 960 961 962 963 964 965 966 967 968 969 970 971 972 and it will not return until the server has saved its database and exited. @code{komrunning} uses the same configuration file as @code{lyskomd} (@pxref{Server Configuration File}). You can use @samp{-c @var{config-file}} to override the compiled-in default. Note, however, that this option is not passed along to @code{updateLysKOM} if @code{komrunning} invokes it, so the option should be used with extreme caution. The @code{komrunning} can be installed in @file{/etc/init.d/}. Be careful, however, to ensure that the pid file is removed earlier during the boot sequence.  Per Cederqvist committed May 16, 1999 973 974 975 @samp{-v} and @samp{-V} causes @code{komrunning} to report its version number and exit.  Per Cederqvist committed May 23, 1999 976 @node Administration  David Byers committed Dec 30, 1998 977 978 979 @chapter Administration The first thing you will have to do is to follow the instructions in the  Per Cederqvist committed May 16, 1999 980 981 982 files @file{INSTALL} and @file{README}. This will set up the LysKOM system with a database containing a few necessary conferences and one person - the administrator.  David Byers committed Dec 30, 1998 983 984 985 986 987 988 989 990 991 992  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 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.  Per Cederqvist committed Apr 03, 1999 993 994 995 996 997 998 999 1000 There is a program called @code{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 @samp{dbck -g}. @xref{(dbck)}. When @code{dbck} is to be run on the database, the LysKOM server @emph{must} be stopped, or unrepairable damage may result. See below for a description on how to stop the server. There is a program called @code{updateLysKOM} which is used to ensure `