// TinyPoker.org // Copyright (C) 2007, 2008 Thomas Cort // // Permission is granted to copy, distribute and/or modify this document // under the terms of the GNU Free Documentation License, Version 1.2 or // any later version published by the Free Software Foundation; with no // Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A // copy of the license is included in the section entitled "GNU Free // Documentation License". Server Setup ============ This document explains how to build, configure and run the TinyPoker server, *tinypokerd*. Install the Dependencies ------------------------ TinyPoker makes use of several software libraries. Each one must be installed before building and running *tinypokerd*. A complete list can be found on the http://tinypoker.org/download.html[download] page. Obtain the Source Code ---------------------- The next step is to get a copy of the *libtinypoker* and *tinypokerd* source code. This can be done by checking out a fresh copy from the http://subversion.tigris.org/[subversion] http://tinypoker.org/subversion.html[repository] or by http://tinypoker.org/download.html[downloading] the latest release. Build and Install libtinypoker ------------------------------ .Configure, make and install -------------------------------------- $ cmake -D CMAKE_INSTALL_PREFIX=/usr . $ make # make install -------------------------------------- Build and Install tinypokerd ---------------------------- .Configure, make and install -------------------------------------- $ cmake -D CMAKE_INSTALL_PREFIX=/usr . $ make # make install -------------------------------------- Generate X.509 Certificates --------------------------- *libtinypoker* uses TLS to secure client/server communications. This is not a standard part of the Internet Poker Protocol, but it adds a layer of security that preventing players from snooping on each other with packet sniffers. Later in this document, we will show how to setup a proxy server with stunnel that will allow unmodified legacy clients to connect. For *libtinypoker* to work, it needs a server side certificate. You can obtain a certificate from a trusted certificate authority or you can create your own certificate authority and sign your own certificates. The example below demonstrates how to create your own certificate authority and sign your own certificates using the *certtool* program that comes with http://www.gnu.org/software/gnutls/[GNU TLS]. .ca.tmpl -------------------------------- cn = Dummy Certificate Authority ca cert_signing_key -------------------------------- .localhost.tmpl --------------------------------- organization = Dummy Organization cn = localhost tls_www_server encryption_key signing_key dns_name = localhost --------------------------------- ------------------------------------------ $ certtool --generate-privkey > ca-key.pem $ certtool --generate-privkey > key.pem $ certtool --generate-self-signed --load-privkey ca-key.pem \ --template ca.tmpl --outfile ca.pem $ certtool --generate-certificate --load-privkey key.pem \ --load-ca-certificate ca.pem --load-ca-privkey ca-key.pem \ --template localhost.tmpl --outfile cert.pem ------------------------------------------ Once you have the certificate files generated, you should copy them to the '/etc/tinypokerd/' directory. In that directory, you will also need to create an empty file named 'crl.pem'. Add a tinypokerd User and Group ------------------------------- *tinypokerd* needs root privileges to do some setup when it first starts up, and as soon as it's done, *tinypokerd* drops root privileges. A user must exist for *tinypokerd* to run as after it drops root privileges. In the example below we create that user and set the shell to 'nologin'. ------------------------------------------ # useradd tinypokerd # chsh tinypokerd Login Shell [/bin/sh]: /bin/nologin ------------------------------------------ You can pick a different username and group if you wish. Both are configurable. Create a run Directory ---------------------- *tinypokerd* creates a PID file when it starts up. The PID file keeps track of the running instance of *tinypokerd*. It can be used to tell if the daemon is running or not as well as stopping a running daemon. In the example below we create the directory and give the 'tinypokerd' user permission to it. ------------------------------------------ # mkdir /var/run/tinypokerd/ # chown tinypokerd:tinypokerd /var/run/tinypokerd/ ------------------------------------------ Configure PAM ------------- *tinypokerd* uses http://www.kernel.org/pub/linux/libs/pam/[Pluggable Authentication Modules for Linux] to handle user authentication. This provides an integrated and extremely configurable authentication system. It allows *tinypokerd* to authenticate players against any PAM supported authentication system (example: LDAP server, system accounts, a simple password file or something else). In this example we only show how to setup a simple password file. Read more about PAM to find out how to configure something more fancy. The first thing to do is to create a *tinypoker* file. See the example below. ./etc/pam.d/tinypoker -------------------------------- auth required pam_pwdfile.so pwdfile /etc/tinypokerd/passwd account required pam_permit.so -------------------------------- Next, we create the password file and add two users, *JDOE* and *JSMITH*. The *-c* option is only needed for the first user. ------------------------------------------ htpasswd -c /etc/tinypokerd/passwd JDOE htpasswd /etc/tinypokerd/passwd JSMITH ------------------------------------------ Note: the Internet Poker Protocol is case insensitive and PAM is case sensitive. To resolve the difference, everything is converted to upper case. So when you create your users, the username should be in upper case and the password should be in upper case. Legacy Client Support (Optional) -------------------------------- With *tinypokerd*, all client/server communications are secured with TLS. Most Internet Poker Protocol 2.0 clients do not support TLS. You can use a program called http://www.stunnel.org/[stunnel] to act as a proxy server, allowing older IPP clients to connect to *tinypokerd* without any changes. After you have stunnel installed on the client machine, create a stunnel configuration file (see example below) and start stunnel. ./etc/stunnel/stunnel.conf ------------- client = yes CAfile = /path/to/ca.pem [tinypoker] accept = 127.0.0.1:9898 connect = server.example.org:9899 ------------- Change *CAfile* to point to the certificate authority certificate you created above. Change *server.example.org* to point to the host running *tinypokerd*. Point the legacy client application to *localhost* port 9898. Password authentication is not covered in the Internet Poker Protocol 2.0 specification, so most legacy clients won't implement it. There are two workarounds for this. In the client application, set your username to "username:password" or on the server, set the password to "NOPASS". Configuration File ------------------ The *tinypokerd* configuration file provides the server with operating parameters. The defaults should work fine in most use cases. Below is a list of every possible configuration option. List of Configuration Options ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ [frame="all", grid="all"] `--------------`---------------`---------------------------------------------------`---------------------------------- *key* *value* *description* *default* setuid username Name of the user to run as tinypokerd setgid groupname Name of the group to run as tinypokerd x509_ca /path/to/file Certificate Authority File /etc/tinypokerd/ca.pem x509_crl /path/to/file Certificate Revocation List File /etc/tinypokerd/crl.pem x509_cert /path/to/file Server Certificate File /etc/tinypokerd/cert.pem x509_key /path/to/file Server Certificate Private Key File /etc/tinypokerd/key.pem game_type 1-3 Specify the type of game (holdem, draw or stud). 1 ---------------------------------------------------------------------------------------------------------------------- Example Configuration File ~~~~~~~~~~~~~~~~~~~~~~~~~~ ./etc/tinypokerd/tinypokerd.conf -------------------------------------- # This is a comment setuid = tinypokerd setgid = tinypokerd x509_ca = /etc/tinypokerd/ca.pem x509_crl = /etc/tinypokerd/crl.pem x509_cert = /etc/tinypokerd/cert.pem x509_key = /etc/tinypokerd/key.pem # Texas Hold'em game_type = 1 -------------------------------------- Add tinypoker to /etc/services ------------------------------ You must add the following line to your services file or *tinypokerd* will not work. ./etc/services -------------------------------------- tinypoker 9899/tcp -------------------------------------- Run tinypokerd -------------- List of Command Line Options ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ [frame="all", grid="all"] `--------------`---------------`---------------`--------------------------- *short option* *long option* *argument* *description* -h --help no Show a help message -v --version no Show version information -k --kill no Kill the running instance -f --foreground no Run in the foreground -c [file] --config=file '/path/to/file' Use an alternate config --------------------------------------------------------------------------- Example Commands ~~~~~~~~~~~~~~~~ .Start the Tiny Poker Daemon -------------------------------------- # /usr/sbin/tinypokerd -------------------------------------- .Stop a running Tiny Poker Daemon -------------------------------------- # /usr/sbin/tinypokerd --kill -------------------------------------- .Run in the Foreground (i.e. do not daemonize) -------------------------------------- # /usr/sbin/tinypokerd --foreground --------------------------------------