DIRTSAND:Getting Started

Disambig gray.png

This is a tutorial page.
 

This tutorial will help you set up your own fully-functional shard using DIRTSAND, a server software for MO:UL clients by H'uru.

Prerequisites

You'll need a few tools to compile and set up DIRTSAND. Most of these consist of development libraries (frequently suffixed with -dev in repositories):

  • GCC 4.6+ (other C++11-compliant compilers might work, but haven't been tested)
  • PostgreSQL: you will need the development libraries (for compiling), the database server (for the vault), and the database server's extensions package
  • string_theory: (see also build instructions)
  • OpenSSL (libssl)
  • libreadline
  • zlib
  • git: used to acquire the source code for DIRTSAND
  • cmake: used to create the makefiles for GCC 4.6+

Additionally, a client to test the working status would be useful. See the getting started guide for help on this subject. Your client will need to be able to connect to port 14617, so you might have to open it up on your firewall.

Finally, it is recommended that you create a UNIX user to run DIRTSAND with an associated home directory containing DIRTSAND: 

sudo useradd dirtsand -d /opt/dirtsand -m -p <password> -s /bin/bash

Compiling

The first step is to download and compile DIRTSAND for your system; make sure you have all the appropriate libraries installed. First, clone the H'uru repository: 

~$ git clone git://github.com/H-uru/dirtsand.git dirtsand
~$ cd dirtsand

Once you have the sources ready, you'll need to run CMake and G++ to compile the code: 

~/dirtsand$ mkdir build && cd build
~/dirtsand/build$ cmake -DCMAKE_INSTALL_PREFIX=/opt/dirtsand ..
~/dirtsand/build$ make && sudo make install
~/dirtsand/build$ cd ..

If your system complains about missing libraries but you have installed them, you can use the CMake GUI to point to the libraries' location.

Database Setup

You will need a PostgreSQL server which DIRTSAND can access with a user capable of adding schemas, tables, etc. into. For the proposed installation here, a dirtsand database with ownership set to a dirtsand user (such as the one created beforehand in this tutorial). 

~/dirtsand$ sudo -u postgres psql -d template1

You will be taken into the psql interactive terminal: 

template1=# CREATE USER dirtsand WITH PASSWORD '<password>';
template1=# CREATE DATABASE dirtsand WITH TEMPLATE = template0 ENCODING = 'UTF8';
template1=# ALTER DATABASE dirtsand OWNER TO dirtsand;
template1=# \q

The next step is to enable UUID functionnality for PostgreSQL. From PostgresSQL 9.1, this extension is loaded inside the database itself. Before proceeding, you need to ensure that you have the package containing the uuid-ossp extension installed on your system. On Debian-based distributions, this package is posgres-contrib. 

~/dirtsand$ sudo -u postgres psql -d dirtsand

You will be taken into the psql interactive terminal: 

dirtsand=# CREATE EXTENSION "uuid-ossp";
dirtsand=# \q

Now you need to load the initial structure for your DB, the SQL files being available in DIRTSAND's source code: 

~/dirtsand$ sudo -u postgres psql -d dirtsand < db/dbinit.sql
~/dirtsand$ sudo -u postgres psql -d dirtsand < db/functions.sql

Your database should now be ready.

Configuring

Note: if you are using the minimal setup guide, you can skip the key generation process, configuring only DB access and so on.

DIRTSAND is configured from a dirtsand.ini file placed in the execution directory for DIRTSAND. It needs to be adjusted to connect to your database, to have all the appropriate RC4 keys, which DIRTSAND can automatically generate for you: 

~/dirtsand$ /opt/dirtsand/bin/dirtsand
ds-918> keygen new
ds-918> quit

After running for a bit, this will output six keys to be copied into your dirtsand.ini file and six others into your client's server.ini (this requires either PlasmaClient or the H'uru fork of CWE). You can safely ignore all startup errors. A sample file for dirtsand.ini has been placed in the source directory; you need to fill it in with your keys and database details (and any other configuration details you need to fill in): 

~/dirtsand$ sudo cp dirtsand.sample.ini /opt/dirtsand/dirtsand.ini
~/dirtsand$ sudo chown dirtsand /opt/dirtsand/dirtsand.ini
~/dirtsand$ sudo -u dirtsand nano /opt/dirtsand/dirtsand.ini

Replace the dummy values with the output under "Server keys".

You'll also have to specify the external host addresses for your DIRTSAND server (it can either be an IP number of a domain name).

Files Setup

Your server now needs to be provided with files to distribute to clients. These include SDL files, Python scripts, data files, client files, and so on.

You will need the files available from the moul-scripts repository.

WARNING: the current moul-scripts appear to be broken in some aspect which prevents GUM (see below) from generating the manifests. Until such a time as the issue is tracked down and fixed, it is recommended that you use the Gehn Shard scripts instead.

DISCLAIMER: it is currently forbidden to distribute Cyan-created content (age models, sound effects). Therefore, your clients must already have all the required data files (excluding fan content you are allowed to distribute).

Ages and SDL

You will first need to create two folders for the .age and .sdl files, as specified in your dirtsand.ini configuration. Into these folders you must copy only the .age and .sdl files, in unencrypted form (available from the moul-scripts repo).

File Server

Note: if you are using the minimal setup guide (or if you will be using only Internal clients), you can skip this step.

The file server is optional if you are using only Internal clients, but is required by External clients and to update automatically all client connecting to your server. This consists of a series of manifest files (.mfs) of the following format: 

remote_filename.ext,local_filename.ext.gz,decompressed_hash,compressed_hash,decompressed_size,compressed_size,flags

Make sure the path to the local file is specified using Windows folder separators (backslahes: "\"). The bin/dsData.sh script can automatically generate a manifest line for a specified file. The lines must reflect the details for the encrypted versions of the files.

There is currently no official manifest generator for DIRTSAND. However, Lyrositor has provided a script for this purpose heavily based on branan's (a.k.a PaladinOfKaos) and Hoikas' script. It is available for download here: Generator of Uru Manifests. You will need a reference installation containing the unencrypted .pak file and .sdl files in Python and SDL, along with all the files from the dat and sfx folders from MO:ULa. On top of the dat folder, you should then copy the dat folder from moul-scripts to get the unencrypted versions. It requires Python 2.7 and libHSPlasma for Python.

Note on Python: the Python scripts need to be compressed into a Python.pak file. This can be achieved using the plPythonPack.exe tool obtained from compiling CWE (the tool only uses relative paths).

Running

If all went well, you can now start your server: 

~/dirtsand$ /opt/dirtsand/bin/dirtsand /opt/dirtsand/dirtsand.ini

And that's it. You will obtain an interactive terminal to operate DIRTSAND which will output log messages as they are printed. You might find it useful however to start DIRTSAND in a GNU screen/Byobu or X session.

Adding Accounts

You might find it difficult to connect without an account. To add one in DIRTSAND, type the following command into DIRTSAND's terminal: 

addacct <username> <password>

Accounts can also be manually inserted into the DB.

Customizing

DIRTSAND allows for a certain degree of flexibility. Here are a few things you can do:

  • Changing default Neighborhood names: the prefixes for Hood names is set in the DB under "game->PublicAges", in the "AgeFilename" row and in the "AgeUserName"/"AgeDesc" fields; simply edit it to change the value.

Developing

If you are interested in lending a hand to DIRTSAND's development, visit the appropriate page.