README

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