doc/README.fcdb

   1 ===========================================================================
   2  Authentication and Freeciv database support (fcdb)
   3 ===========================================================================
   4
   5 The Freeciv server allows the authentication of users, although by default
   6 it is not enabled, and anyone can connect with any name.
   7
   8 In order to support authentication, the Freeciv server needs access to a
   9 database backend in which to store the credentials. To support different
  10 database backends, the database access code is written in Lua using luasql.
  11 In principle, luasql supports SQLite3, MySQL, and Postgres backends, and
  12 the Freeciv server can be built with any or all of these; however, the
  13 supplied scripts currently do not support Postgres out of the box.
  14
  15 As well as storing and retrieving usernames and passwords, the supplied
  16 database access script logs the time and IP address of each attempted
  17 login, although this information is not used by the Freeciv server itself.
  18
  19 To use the Freeciv database and authentication, the server has to be built
  20 with the '--enable-fcdb' and '--enable-auth' options to 'configure'. It
  21 must also be installed properly, as it searches for database.lua in the
  22 install location; the server cannot simply be run from a build directory if
  23 authentication is required.
  24
  25 ================================
  26  Quick setup: SQLite
  27 ================================
  28
  29 The simplest setup is to use the SQLite backend, and this is probably the
  30 best option for new deployments. In this setup, the authentication data is
  31 stored in a simple file accessed directly by the Freeciv server; there is
  32 no need for a separate database server process.
  33
  34 In order to use this, the server must have been built with
  35 '--enable-fcdb=sqlite3'.
  36
  37 To set this up, first create a database configuration file called something
  38 like fc_auth.conf, with the 'database' key specifying where the database
  39 file is to live (of course it must be readable and writable by the Freeciv
  40 server):
  41
  42   [fcdb]
  43   backend="sqlite"
  44   database="/my/path/to/freeciv.sqlite"
  45
  46 If you have experimental xml registry backend built in to freeciv, above
  47 configuration can also be given as
  48
  49 <?xml version="1.0" encoding="UTF-8"?>
  50 <Freeciv options="+xml">
  51   <fcdb>
  52     <database>"/my/path/to/freeciv.sqlite"</database>
  53     <backend>"sqlite"</backend>
  54   </fcdb>
  55 </Freeciv>
  56
  57 (For more information on the format of this file, see below. There are more
  58 settings available, but this file is entirely sufficient for a SQLite
  59 setup.)
  60
  61 Now start the server with
  62   freeciv-server --Database fc_auth.conf --auth --Newusers
  63
  64 The first time you do this, you need to create the database file and its
  65 tables with the following server command:
  66   /fcdb lua sqlite_createdb()
  67
  68 Now you can create some users by connecting with the client; due to the
  69 --Newusers flag, when you connect with the client with a previously unknown
  70 username, the server will prompt for a password and save the new account to
  71 the database.
  72
  73 You may want to prepopulate the users table this way and then restart the
  74 server without --Newusers for the actual game, or you can run the game with
  75 --Newusers.
  76
  77 --------------------------------
  78  Advanced SQLite usage
  79 --------------------------------
  80
  81 SQLite supports working with a temporary database in memory which is never
  82 written to disk. To do this, specify 'database=":memory:"' in the
  83 configuration file. The database will last only for the lifetime of the
  84 freeciv-server process; its contents will be lost if the server quits or
  85 crashes (it is not saved in the saved game file). You'll probably need the
  86 --Newusers option :)
  87
  88 ================================
  89  MySQL
  90 ================================
  91
  92 This setup uses a network connection to a separate MySQL database server.
  93 MySQL was the only backend supported before Freeciv version 2.4, so is
  94 supported for backward compatibility, but SQLite is probably a better
  95 option for new deployments unless you have special requirements.
  96
  97 In order to use this, the server must have been built with
  98 '--enable-fcdb=mysql'.
  99
 100 You can still use an existing pre-2.4 MySQL authentication database with
 101 Freeciv 2.4 or later. Note however that the format of the configuration
 102 file has changed slightly from that which used to be supplied to the --auth
 103 option:
 104  - Section header is now '[fcdb]' instead of '[auth]'
 105  - You should add 'backend="mysql"'
 106  - the 'table' directive is now called 'table_user', and the default table
 107    name is now 'fcdb_auth'; if your setup relied on the old default, you'll
 108    need 'table_user="auth"'
 109  - the 'login_table' directive is now called 'table_log', and the default
 110    table name is now 'fcdb_log'; if your setup relied on the old default,
 111    you'll need 'table_log="loginlog"'
 112
 113 If you want to use MySQL for a fresh userbase, the supplied
 114 scripts/setup_auth_server.sh can be used to create database tables in an
 115 existing MySQL database, and a suitable config file describing that
 116 database, which can be passed to the server's '--Database' option.
 117
 118 Before running this script, you will need to have a MySQL database server
 119 running, with a user account for the Freeciv server and a database to
 120 contain the data (ideally empty). (The space required for a Freeciv user
 121 database is very small.)
 122
 123 Having created the tables and config file, you should be able to invoke the
 124 server in a similar way to SQLite.
 125
 126 ================================
 127  Command-line options
 128 ================================
 129
 130 The following server command-line options are relevant to authentication:
 131
 132   -D, --Database <conffile>
 133       Specifies a configuration file describing how to connect to the
 134       database. Without this, all authentication will fail.
 135   -a, --auth
 136       Enable authentication. Without this, anyone will be able to connect
 137       without authentication, and --Database has no effect.
 138   -G, --Guests
 139       Allow guests. These are usernames with names starting "guest". If
 140       enabled, any number of guests may connect without accounts in the
 141       database; if a guest name is already in use by a connection, a new
 142       guest name is generated.
 143       Once connected, guests have the same privileges as any other account.
 144       If this option is not specified, accounts are required to connect,
 145       and guest account names are forbidden.
 146   -N, --Newusers
 147       Allow Freeciv clients to create new user accounts through the Freeciv
 148       protocol.
 149       Without this, only accounts which already exist in the database can
 150       connect (which might be desirable if you wants users to register via
 151       a web front end, for instance).
 152
 153 ================================
 154  Lua script database.lua
 155 ================================
 156
 157 This script is responsible for checking usernames, fetching passwords, and
 158 saving new users (if --Newusers is enabled). It encapsulates access to the
 159 database backend, and hence the details of the table layout.
 160
 161 The script lives in data/database.lua in the source tree, and is installed
 162 to 'sysconfdir'; depending on the options given to 'configure' at build
 163 time, this may be a location like /usr/local/etc/freeciv/database.lua.
 164
 165 The supplied version supports basic authentication against a SQLite or
 166 MySQL database; it supports configuration as shown in the following
 167 example (for MySQL; SQLite does not need all of these options).
 168
 169   [fcdb]
 170   backend="mysql"
 171   host="localhost"
 172   user="Freeciv"
 173   port="3306"
 174   password="s3krit"
 175   database="Freeciv"
 176   table_user="auth"
 177   table_log="loginlog"
 178
 179 If that's sufficient for you, it's not necessary to read on.
 180
 181 Freeciv expects the following lua functions to be defined in database.lua:
 182
 183   -- try to load data for an existing user
 184   -- return TRUE if user exists, FALSE otherwise
 185   function user_load(conn)
 186   -- save a new user to the database
 187   function user_save(conn)
 188   -- log the connection attempt (success is boolean)
 189   function user_log(conn, success)
 190
 191   -- test and initialise the database connection
 192   function database_init()
 193   -- free the database connection
 194   function database_free()
 195
 196 Where 'conn' is on object representing the connection to the client which
 197 requests access.
 198
 199 The return status of all of these functions should be one of
 200
 201   fcdb.status.ERROR
 202   fcdb.status.TRUE
 203   fcdb.status.FALSE
 204
 205 indicating an error, a positive or a negative result.
 206
 207 The following lua functions are provided by Freeciv:
 208
 209   -- return the client-specified username
 210   auth.get_username(conn)
 211   -- return the client IP address (string)
 212   auth.get_ipaddr(conn)
 213   -- tell the server (the MD5 hash of) the correct password to check against
 214   -- for this connection (usually to be called by user_load())
 215   -- returns whether this succeeded
 216   auth.set_password(conn, password)
 217   -- return (the MD5 hash of) the password for this connection (as specified
 218   -- by the client in user_save(), or as previously set by set_password()).
 219   auth.get_password(conn)
 220
 221   -- return a value from the --Database configuration file
 222   fcdb.option(type)
 223
 224 'type' selects one of the entries in the configuration file by name (for
 225 instance fcdb.option("backend")). For backward compatibility with Freeciv
 226 2.4, definitions such as fcdb.param.BACKEND are provided for conventional
 227 option names, but there's no need to use them in new code.
 228
 229 Freeciv also provides some of the same Lua functions that ruleset scripts
 230 get -- log.*(), _(), etc -- but the script is executing in a separate
 231 context from ruleset scripts, and does not have access to signals, game
 232 data, etc.
 233
 234 ================================
 235  TODO
 236 ================================
 237
 238 * Move password comparison / policy to Lua script
 239   <http://www.hostedredmine.com/issues/660267>
 240 * Give database.lua access to do more stuff
 241   <https://www.hostedredmine.com/issues/657141>
 242 * Allow setting cmdlevel per-user, etc
 243   <https://www.hostedredmine.com/issues/657143>
 244 * Give database.lua access to game signals and events
 245   <https://www.hostedredmine.com/issues/657142>
 246 * Improve this README