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 and use TERMINFO environment variable to point to the location.
  17
  18         Environment variable TERM=rls must be set in order for the remote
  19 playing and observing to work properly.
  20
  21         At the start, the software tries to read the config file named
  22 'confg'. It defines a TCP/IP port to listen for incoming telnet connections
  23 and a command to be used to run external editor to edit config files.
  24
  25         Server continues to run until it receives SIGTERM. Then it gracefully
  26 tries to terminate all running games (by sending SIGTERM to them) and close
  27 network connections.
  28
  29         To set up the server as daemon, use an init script template (usually
  30 found in /etc/rc.d/init.d/) and fill with something like the following to
  31 start the server
  32                 cd /home/rlserver       # or where did you place it
  33                 TERMINFO=/home/rlserver/.terminfo TERM=rls ./rlserver
  34 it is likely there is a mechanism provided for terminating daemon, if not
  35 you can simply use
  36                 killall rlserver
  37 as long as you are reasonably sure there are no other processes
  38 named 'rlserver'.
  39
  40         Server uses syslog utility to write logs.
  41
  42
  43                 Security considerations
  44
  45         While the server was developed to minimise exposure to remote
  46 users, its very nature of running arbitraty software makes it impossible
  47 to achieve the task.
  48
  49         If possible, a dedicated chroot jail should be used. If that is
  50 impractical in some particular case, server should be run with mimimal
  51 user privilegies.
  52
  53         In any case, the user account used to run server or games should not
  54 have write permissions other than necessary to save games and high score
  55 lists.
  56
  57         Some games may prompt user for a file name for a save file, character
  58 dump, etc. Malicious players may enter arbitrary file names to damage score
  59 files or saved games of other players. This feature should be disabled for
  60 every game.
  61
  62         As it advisable to treat the games as untrustworthy malicious code
  63 and users as crackers trying to break in. There can never be too much
  64 paranoia.
  65
  66         Most games do not bother with file locking while updating the scores
  67 file, so it is possible for two games run by different players to try to update
  68 it at the same time, leading to corruption. Since there is not much that
  69 can be done about that (aside from patching a game to implement proper file
  70 locking) regular backups seem to be the only measure.
  71
  72
  73                 Users
  74
  75         All user accounts are stored in file 'users' in the server directory
  76 in simple text format.
  77
  78         It is possible to edit the file manually, but in this case the server
  79 must be offline or the editor must temporarily lock file via POSIX lockf()
  80 to prevent simultaneous writes if a remote player register an account or
  81 changes password.
  82
  83
  84                 Running games
  85
  86         All game profiles are read from file 'games' in the server directory.
  87 The file is re-read every time a player enters the game selection menu, so
  88 there is no need to restart server to add a new game or edit profile of an
  89 old one.
  90
  91         Every game has its own section in the file. A typical section may
  92 look like the following:
  93
  94 [myrl]
  95 name: My Roguelike v 0.1.2
  96 chdir: myrl-0.1.2
  97 copy: data/newtemplate.save $USER$.save
  98 copy-edit: data/keys keys-$USER$
  99 run: ./myrl --user $USER$
 100 score: ./myrl --showscore
 101 enter: lf
 102
 103         The first line in brackets denotes section start. The string inside
 104 brackets is the game id. It will be used when players are selecting a game
 105 to run in the server menu. The following directives may be used in any
 106 order.
 107
 108         Mandatory parameter name: specifies the game name to be displaed in
 109 server menus.
 110
 111         Mandatory run: defines a command to run the game. All instances of
 112 substring $USER$ will be replaced with player's login name.
 113
 114         Optional chdir: specifies game direcory. It may be relative to the
 115 server direcory or an absolute path. The game will be run from this
 116 directory.
 117
 118         Optional copy: makes a copy of specified file prior to running a
 119 game if the file does not exist. It can be used to make personal copies
 120 of game configurations. If chdir: is defined for the game, the direcory
 121 will be used for both file names.
 122
 123         Optional copy-edit: is very similar to copy:. The only difference
 124 is that the copied file will be allowed to be edited by player.
 125
 126         There can be multiple copy: and copy-edit: entries for a single
 127 game. By default the limit for both combined is 8. It can be changed by
 128 editing GAME_FILES constant in games.h and recompiling.
 129
 130         Optional enter: specifies how to translate the Enter key character
 131 prior to passing the input to player. Possible values are LF (default) for
 132 '\n' and CR for '\r'. Try setting this option if some game does not
 133 recoginse the ENTER key.
 134
 135         Optional score: defines a command to run game in view-scores mode.
 136 The command should run the game in a mode where it does not allow any other
 137 action than browse score lists.
 138
 139
 140                 Game requirements
 141
 142         In order for games to work properly with the server, they should meet
 143 some requirements:
 144
 145         If game allows to save progress, it should support multipe
 146 independent save file by accepting a name from command line and do not
 147 allow to change it from within the game itself.
 148
 149         As mentioned in security section, a game should not allow player to
 150 enter arbitrary file names for any purpose.
 151
 152         A game should save data and exit gracefully upon receiving SIGTERM.
 153 This signal is sent when remote players disconnects from the game or when
 154 the server is going through shutdown.
 155
 156         If game writes to files other than personalised saves and configs,
 157 it should employ some file locking mechanism to protect these file from
 158 corruption due to simultaneous writes initiated by different players.
 159
 160         It is not necessary, but if a game has a command-line option to display
 161 a high-score list, it can be used. The game should exit after displaying the
 162 list and not allow any other actions, such as starting to play.
 163