README

   1
   2                 Running a server
   3
   4         By default, the server is configured to be run inside a dedicated
   5 directory, where its data is stored. So the start-up script must change to
   6 that directory prior to launching the software.
   7
   8         Although, it is possible to change all file names in sources to
   9 include absolute paths to make it able to run from any directory.
  10
  11         The server uses a custom termcap entry for internal terminal
  12 emulation. It should be compiled using tic command
  13                 tic term.rls
  14         by default, the resulting compiled binary description is placed
  15 into ~/.terminfo You need to copy it to some place accessible for the server.
  16 Unless you put it to the standard location (usually /usr/share/terminfo),
  17 you should use TERMINFO environment variable to point to the location.
  18
  19         Environment variable TERM=rls must be set in order for the remote
  20 playing and observing to work properly.
  21
  22         At the start, the software tries to read the config file named
  23 'confg'. It defines a TCP/IP port to listen for incoming telnet connections,
  24 a command to be used to run external editor to edit config files, and
  25 other settings.
  26
  27         The suggested editor to use is easyedit. There is a patch provided
  28 to disable 'Save As' and 'Print' functionality.
  29
  30         Server continues to run until it receives SIGTERM. Then it gracefully
  31 tries to terminate all running games (by sending SIGTERM to them) and close
  32 network connections.
  33
  34         To set up the server as daemon, use an init script template (usually
  35 found in /etc/rc.d/init.d/) and fill with something like the following to
  36 start the server
  37                 cd /home/rlserver       # or where did you place it
  38                 TERMINFO=/home/rlserver/.terminfo TERM=rls ./rlserver
  39 it is likely there is a mechanism provided for terminating daemon, if not
  40 you can simply use
  41                 killall rlserver
  42 as long as you are reasonably sure there are no other processes
  43 named 'rlserver'.
  44
  45         Server uses syslog utility to write logs.
  46
  47
  48                 Security considerations
  49
  50         While the server was developed to minimise exposure to remote
  51 users, its very nature of running arbitraty software makes it impossible
  52 to achieve the task.
  53
  54         If possible, a dedicated chroot jail should be used. If that is
  55 impractical in some particular case, server should be run with mimimal
  56 user privilegies.
  57
  58         In any case, the user account used to run server or games should not
  59 have write permissions other than necessary to save games and high score
  60 lists.
  61
  62         Some games may prompt user for a file name for a save file, character
  63 dump, etc. Malicious players may enter arbitrary file names to damage score
  64 files or saved games of other players. This feature should be disabled for
  65 every game.
  66
  67         As it advisable to treat the games as untrustworthy malicious code
  68 and users as crackers trying to break in. There can never be too much
  69 paranoia.
  70
  71         If a game provide some way to disable access to unnecessary
  72 functionality completely, such as sound effects or using an X11 window, it
  73 should be used. It is better to disable such access for the user at the
  74 system level. Just note that using chroot jail may be not enough by itself.
  75
  76         Most games do not bother with file locking while updating the scores
  77 file, so it is possible for two games run by different players to try to update
  78 it at the same time, leading to corruption. Since there is not much that
  79 can be done about that (aside from patching a game to implement proper file
  80 locking) regular backups seem to be the only measure.
  81
  82         You might want to use nice in start-up to reduce the priority of the
  83 games relative to other tasks unsing the computer. Also, ulimit (built-in to
  84 bash shell) may be helpfull to limit memory and/or CPU consumption to
  85 prevent a single game from degrading experience for other users.
  86
  87
  88                 Statistics
  89
  90         If stat file is defined in the config, the sever will track and
  91 update statistics for every game played. Stats file keeps accumulated
  92 counters for several numbers, one per line: number of sessions played, total
  93 time of sessions in seconds, total count of bytes received from the players,
  94 and total count of bytes sent to players (observers are not counted).
  95
  96         If log file is defined, more detailed data will be written for
  97 every session: time of the session end, user, session duration in seconds,
  98 bytes received from the player and bytes sent to him (observers are not
  99 counted).
 100
 101
 102                 Users
 103
 104         All user accounts are stored in file 'users' in the server directory
 105 in simple text format.
 106
 107         It is possible to edit the file manually, but in this case the server
 108 must be offline or the editor must temporarily lock file via POSIX lockf()
 109 to prevent simultaneous writes if a remote player register an account or
 110 changes password.
 111
 112
 113                 Running games
 114
 115         All game profiles are read from file 'games' in the server directory.
 116 The file is re-read every time a player enters the game selection menu, so
 117 there is no need to restart server to add a new game or edit profile of an
 118 old one.
 119
 120         Every game has its own section in the file. A typical section may
 121 look like the following:
 122
 123 [myrl]
 124 name: My Roguelike v 0.1.2
 125 chdir: myrl-0.1.2
 126 copy: data/newtemplate.save $USER$.save
 127 copy-edit: data/keys keys-$USER$
 128 run: ./myrl --user $USER$
 129 score: ./myrl --showscore
 130 enter: lf
 131
 132         The first line in brackets denotes section start. The string inside
 133 brackets is the game id. It will be used when players are selecting a game
 134 to run in the server menu. The following directives may be used in any
 135 order.
 136
 137         Mandatory parameter name: specifies the game name to be displaed in
 138 server menus.
 139
 140         Mandatory run: defines a command to run the game. All instances of
 141 substring $USER$ will be replaced with player's login name.
 142
 143         Optional chdir: specifies game direcory. It may be relative to the
 144 server direcory or an absolute path. The game will be run from this
 145 directory.
 146
 147         Optional copy: makes a copy of specified file prior to running a
 148 game if the file does not exist. It can be used to make personal copies
 149 of game configurations. If chdir: is defined for the game, the direcory
 150 will be used for both file names.
 151
 152         Optional copy-edit: is very similar to copy:. The only difference
 153 is that the copied file will be allowed to be edited by player.
 154
 155         There can be multiple copy: and copy-edit: entries for a single
 156 game. By default the limit for both combined is 8. It can be changed by
 157 editing GAME_FILES constant in games.h and recompiling.
 158
 159         Optional enter: specifies how to translate the Enter key character
 160 prior to passing the input to player. Possible values are LF (default) for
 161 '\n' and CR for '\r'. Try setting this option if some game does not
 162 recoginse the ENTER key.
 163
 164         Optional score: defines a command to run game in view-scores mode.
 165 The command should run the game in a mode where it does not allow any other
 166 action than browse score lists.
 167
 168
 169                 Game requirements
 170
 171         In order for games to work properly with the server, they should meet
 172 some requirements:
 173
 174         If game allows to save progress, it should support multipe
 175 independent save file by accepting a name from command line and do not
 176 allow to change it from within the game itself.
 177
 178         As mentioned in the security section, a game should not allow player to
 179 enter arbitrary file names for any purpose.
 180
 181         A game should save data and exit gracefully upon receiving SIGTERM.
 182 This signal is sent when remote players disconnects from the game or when
 183 the server is going through shutdown.
 184
 185         If game writes to files other than personalised saves and configs,
 186 it should employ some file locking mechanism to protect these file from
 187 corruption due to simultaneous writes initiated by different players.
 188
 189         It is not necessary, but if a game has a command-line option to display
 190 a high-score list, it can be used. The game should exit after displaying the
 191 list and do not allow any other actions, such as starting to play.