TinyPoker

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 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 subversion repository or by downloading the latest release.

Build and Install libtinypoker

Example: Configure, make and install
 $ cmake -D CMAKE_INSTALL_PREFIX=/usr .
 $ make
 # make install

Build and Install tinypokerd

Example: Configure, make and install
 $ cmake -D CMAKE_INSTALL_PREFIX=/usr .
 $ make
 # make install

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 via tinypokerd.conf.

Create a directory for configuration Data

The certificate files and configuration file are stored in /etc/tinypokerd by default. You can use an alternate location by invoking tinypokerd with a command line argument (see the bottom of this document for details).

 # mkdir /etc/tinypokerd
 # chown tinypokerd:tinypokerd /etc/tinypokerd
 # chmod 700 /etc/tinypokerd

Create a directory for protocol Logs (Optional)

The server provides the option to log all protocol messages sent and received. This could be useful for statistics or research. The feature is disabled by default since it eats up disk space and may make the server slightly slower. It can be enabled via tinypokerd.conf. If enabled, a directory is needed to store the log.

 # mkdir /var/log/tinypokerd
 # chown tinypokerd:tinypokerd /var/log/tinypokerd
 # chmod 700 /var/log/tinypokerd

Note, regular log messages generally will not show up in this directory. They are sent directly to syslog.

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 GNU TLS. The package in gNewSense is gnutls-bin.

Example: ca.tmpl
cn = Dummy Certificate Authority
ca
cert_signing_key
Example: 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.

 # cp ca.pem /etc/tinypokerd/ca.pem
 # chmod 400 /etc/tinypokerd/ca.pem
 # chown tinypokerd:tinypokerd /etc/tinypokerd/ca.pem
 # cp cert.pem /etc/tinypokerd/cert.pem
 # chmod 400 /etc/tinypokerd/cert.pem
 # chown tinypokerd:tinypokerd /etc/tinypokerd/cert.pem
 # cp key.pem /etc/tinypokerd/key.pem
 # chmod 400 /etc/tinypokerd/key.pem
 # chown tinypokerd:tinypokerd /etc/tinypokerd/key.pem
 # touch /etc/tinypokerd/crl.pem
 # chown 400 /etc/tinypokerd/crl.pem
 # chown tinypokerd:tinypokerd /etc/tinypokerd/crl.pem

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 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. Be sure that you have the pwdfile PAM module installed. The package in gNewSense is libpam-pwdfile.

The first thing to do is to create a tinypoker file. See the example below.

Example: /etc/pam.d/tinypoker
auth    required pam_pwdfile.so pwdfile /etc/tinypokerd/passwd
account required pam_permit.so

The permissions should be configured as shown below.

 # chown root:root /etc/pam.d/tinypoker
 # chmod 644 /etc/pam.d/tinypoker

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 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.

Example: /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

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
protocol_log_enabled true/false Switch protocol logging on or off false
protocol_log_file /path/to/file XML log file containing protocol messages /var/log/tinypokerd/protocol.log
game_type 1-3 Specify the type of game (holdem, draw or stud). 1

Example Configuration File

Example: /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

protocol_log_enabled = true
protocol_log_file = /var/log/tinypokerd/protocol.log

# 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.

Example: /etc/services
tinypoker       9899/tcp

Run tinypokerd

List of Command Line Options

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

Example: Start the Tiny Poker Daemon
 # /usr/sbin/tinypokerd
Example: Stop a running Tiny Poker Daemon
 # /usr/sbin/tinypokerd --kill
Example: Run in the Foreground (i.e. do not daemonize)
 # /usr/sbin/tinypokerd --foreground