Pwn Adventure 3 Server Setup Guide
==================================

The Pwn Adventure 3 server infrastructure will contain one Master Server and
one or more Game Servers.  Both binaries are provided.  In order to set up the
Game Server, you will first need to download the Linux client of the game from
pwnadventure.com, this contains the map files that are needed by the server.

Master Server Setup
-------------------

The Master Server requires the following setup to run:

* Ubuntu 14.04 64-bit
* postgresql installed
* A Unix user account on the postgres database, password accounts are
  not supported
* A database called "master" on which the Unix user account has access for
  creating and modifying tables

Once these requirements are met, change directory to the Master Server binary
directory and provision the database using the following command:

  psql master -f initdb.sql

A special account for the Game Servers must be created so that the Game
Servers can be registered to accept connections.  Create this account using
the following command:

  ./MasterServer --create-server-account

Keep the details of the account that are written to the console.  They should
look similar to the following:

  Created server user, use these credentials to connect a server to the system.
  Username: server_5451700dc668731a
  Password: a29eb785c128a76ef45e1543

You will need the account login information when configuring the Game Servers
later.  You will likely also want an administrator team.  This team has the
ability to teleport to regions and give items using an in-game console command.
This team can be created using the following command, using your team name of
choice:

  ./MasterServer --create-admin-team MyAwesomeAdminTeam

This command will give you the team hash that you can use to register yourself
and your other teammates using the in-game registration system.

Once these steps are complete, run the Master Server with no arguments to start
the server:

  ./MasterServer

It is recommended to run this under GNU Screen or tmux to keep the server
running after your session is disconnected.

Game Server Setup
-----------------

The Game Server requires the following setup to run:

* Ubuntu 14.04 64-bit
* A copy of the Linux game client (download from pwnadventure.com), the
  Game Server binary will be placed into this client alongside the client
  executable
* At least 2GB of RAM, more RAM will allow more instances to be run on a single
  machine

The Game Server does not need any graphics hardware and runs purely on console.
It is known to run well on Amazon AWS and Digital Ocean VPS instances.

The Game Server requires a lot of RAM to run, but uses fork and copy-on-write
memory to allow many instances to run on a single host.  For a server with
2GB of RAM, it is not recommended to run more than 5 instances, but a server
with 8GB of RAM can typically run as many as the CPU can handle.  It is
recommended to use 2-3 instances per CPU core if you have sufficient RAM.  You
may be able to run 4-5 instances per core, but doing so may introduce slight lag.

The total number of instances needed depend on the number of players you are
going to be serving.  Each active area needs its own Game Server instance, and
the Magmarok quest and Cowabungalow areas are per-team instances.  For Ghost in
the Shellcode 2015, there were 1800+ registered users, and the game was served
using 64 instances running on 4 hosts with 8 cores each. Private events for
individual team practices will likely only need 1 host with as few as 5
instances.

To set up a Game Server host, first copy the PwnAdventure3Server binary to the
same directory as PwnAdventure3-Linux-Shipping in the client files.  This should
be found in the following directory relative to the launcher:

  PwnAdventure3_Data/PwnAdventure3/PwnAdventure3/Binaries/Linux

Then, you will need to modify the server configuration to match your
environment.  This is in a file called "server.ini", and can be found in the
following directory relative to the launcher:

  PwnAdventure3_Data/PwnAdventure3/Content/Server/server.ini

This file should contain contents similar to the following:

  [MasterServer]
  Hostname=pa3-main.2015.ghostintheshellcode.com
  Port=3333

  [GameServer]
  Hostname=
  Port=3000
  Username=
  Password=

You need to change the hostname in the MasterServer section to point to the
Master Server you set up above.  The hostname in the GameServer must be
resolvable by the clients that are going to connect to the game.  This is
the hostname that will be passed to the clients by the Master Server when
they are trying to connect to the game.

Fill in the Username and Password fields in the GameServer section with the
information that was returned from the Master Server account creation process
above.

You will probably want to add an instance count option to the GameServer section
as well.  To use 5 instances, append "Instances=5" to the end of the section.  If
this is not provided, the server will try to guess the number of instances based
on memory available, but this may not be an ideal number for your configuration.

The port number given in the GameServer section is the port of the first
instance, and will increment for each instance.  For example, for a server
running 5 instances and Port set to 3000, there will be 5 ports used between
3000-3004.

Once you have configured the server, you can start it by changing directory to
the server binary and running it:

  ./PwnAdventure3Server

It will take at least 15 seconds to start up.  If the startup is successful and
it connects to your Master Server, you should see messages like the following
in your Master Server console:

  Game server game.example.com:3301 added
  Game server game.example.com:3300 added
  Game server game.example.com:3302 added
  Game server game.example.com:3303 added

Once this is complete, the server is ready for connections.  The final step is
to configure the clients to connect to the correct server

Client Setup
------------

The clients will default to attempting to connect to the official servers.  To
change this, find the "server.ini" file (this is the same file as described in
the Game Server setup above) and modify the Hostname field in the MasterServer
section to point to your Master Server.  Once this is complete, you can try
to connect to your server using the client.  You should see "Custom Server" on
the client's login screen.

Recommended Extras
------------------

You will probably want to replace the Master Server SSL certificate with your
own, as the private key for the example certificate is in this bundle.  Simply
create a self-signed certificate with OpenSSL and replace the server.crt and
server.key files in the Master Server directory.  Also, replace the server.crt
file on all clients so that the SSL connection will verify.

You can change the message displayed at login by modifying the database.  The
following queries can update the text, but the Master Server will need to be
restarted for the changes to take effect:

  UPDATE info SET contents='My Server' WHERE name='login_title';
  UPDATE info SET contents='My message' WHERE name='login_text';

