Difference between revisions of "DIRTSAND:Getting Started"
(Added tutorial template.) |
Tsar hoikas (Talk | contribs) m (→Database Setup) |
||
| (14 intermediate revisions by 2 users not shown) | |||
| Line 4: | Line 4: | ||
== Prerequisites == | == 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): | 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) | + | * '''GCC 4.6+''' (other C++11-compliant compilers might work, but haven't been tested) |
| − | * '''PostgreSQL''': you will need | + | * '''PostgreSQL''': you will need the development libraries (for compiling), the database server (for the vault), and the database server's extensions package |
| − | * '''OpenSSL''' (libssl) | + | * '''[https://github.com/zrax/string_theory string_theory]''': (see also [https://github.com/zrax/string_theory build instructions]) |
| − | * '''libreadline''' | + | * '''OpenSSL''' (libssl) |
| − | * '''zlib''' | + | * '''libreadline''' |
| − | * '''git''': used to acquire the source code for DIRTSAND | + | * '''zlib''' |
| − | * '''cmake''': used to create the makefiles for GCC 4.6+ | + | * '''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 [[CWE:Getting Started|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. | Additionally, a client to test the working status would be useful. See the [[CWE:Getting Started|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: | Finally, it is recommended that you create a UNIX user to run DIRTSAND with an associated home directory containing DIRTSAND: | ||
| − | + | <source lang="bash">sudo useradd dirtsand -d /opt/dirtsand -m -p <password> -s /bin/bash</source> | |
== Compiling == | == 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: | 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: | ||
| − | + | <source lang="bash">~$ git clone git://github.com/H-uru/dirtsand.git dirtsand | |
| − | + | ~$ cd dirtsand</source> | |
| − | Once you have the sources, you'll need to run CMake and G++ to compile the code: | + | |
| − | + | Once you have the sources ready, you'll need to run CMake and G++ to compile the code: | |
| − | + | <source lang="bash">~/dirtsand$ mkdir build && cd build | |
| − | + | ~/dirtsand/build$ cmake -DCMAKE_INSTALL_PREFIX=/opt/dirtsand .. | |
| − | + | ~/dirtsand/build$ make && sudo make install | |
| + | ~/dirtsand/build$ cd ..</source> | ||
If your system complains about missing libraries but you have installed them, you can use the CMake GUI to point to the libraries' location. | 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 == | == 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 <code>dirtsand</code> database with ownership set to a <code>dirtsand</code> user (such as the one created beforehand in this tutorial). | 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 <code>dirtsand</code> database with ownership set to a <code>dirtsand</code> user (such as the one created beforehand in this tutorial). | ||
| − | + | <source lang="bash">~/dirtsand$ sudo -u postgres psql -d template1</source> | |
| + | You will be taken into the psql interactive terminal: | ||
template1=# CREATE USER dirtsand WITH PASSWORD '<password>'; | template1=# CREATE USER dirtsand WITH PASSWORD '<password>'; | ||
template1=# CREATE DATABASE dirtsand WITH TEMPLATE = template0 ENCODING = 'UTF8'; | template1=# CREATE DATABASE dirtsand WITH TEMPLATE = template0 ENCODING = 'UTF8'; | ||
template1=# ALTER DATABASE dirtsand OWNER TO dirtsand; | template1=# ALTER DATABASE dirtsand OWNER TO dirtsand; | ||
template1=# \q | template1=# \q | ||
| − | The next step is to enable UUID functionnality for PostgreSQL. | + | 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 <code>uuid-ossp</code> extension installed on your system. On Debian-based distributions, this package is '''posgres-contrib'''. |
| − | + | <source lang="bash">~/dirtsand$ sudo -u postgres psql -d dirtsand</source> | |
| − | + | 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: | Now you need to load the initial structure for your DB, the SQL files being available in DIRTSAND's source code: | ||
| − | + | <source lang="bash">~/dirtsand$ sudo -u postgres psql -d dirtsand < db/dbinit.sql | |
| − | + | ~/dirtsand$ sudo -u postgres psql -d dirtsand < db/functions.sql</source> | |
Your database should now be ready. | Your database should now be ready. | ||
== Configuring == | == 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 <code>dirtsand.ini</code> 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 is configured from a <code>dirtsand.ini</code> 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: | ||
| − | + | <source lang="bash">~/dirtsand$ /opt/dirtsand/bin/dirtsand | |
| − | + | ds-918> keygen new | |
| − | + | ds-918> quit</source> | |
After running for a bit, this will output six keys to be copied into your <code>dirtsand.ini</code> file and six others into your client's <code>server.ini</code> (this requires either PlasmaClient or the H'uru fork of [[CWE]]). You can safely ignore all startup errors. A sample file for <code>dirtsand.ini</code> 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): | After running for a bit, this will output six keys to be copied into your <code>dirtsand.ini</code> file and six others into your client's <code>server.ini</code> (this requires either PlasmaClient or the H'uru fork of [[CWE]]). You can safely ignore all startup errors. A sample file for <code>dirtsand.ini</code> 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): | ||
| − | + | <source lang="bash">~/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</source> | |
| − | + | ||
Replace the dummy values with the output under "Server keys". | Replace the dummy values with the output under "Server keys". | ||
| Line 73: | Line 76: | ||
=== File Server === | === 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 (<code>.mfs</code>) of the following format: | 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 (<code>.mfs</code>) of the following format: | ||
remote_filename.ext,local_filename.ext.gz,decompressed_hash,compressed_hash,decompressed_size,compressed_size,flags | 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 <code>bin/dsData.sh</code> script can automatically generate a manifest line for a specified file. The lines must reflect the details for the encrypted versions of the files. | Make sure the path to the local file is specified using Windows folder separators (backslahes: "\"). The <code>bin/dsData.sh</code> 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) [https://github.com/branan/moulbuild-scripts script]. It is available for download here: [https://github.com/Lyros/GUM Generator of Uru Manifests]. You will need a reference installation containing the unencrypted <code>.pak</code file and <code>.sdl</code> files in <code>Python</code> and <code>SDL</code>, along with all the files from the <code>dat</code> and <code>sfx</code> folders from MO:ULa. On top of the <code>dat<code> folder, you should then copy the <code>dat</code> folder from moul-scripts to get the unencrypted versions. It requires Python 2.7 and [[libHSPlasma#Python|libHSPlasma for Python]]. | + | 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' [https://github.com/branan/moulbuild-scripts script]. It is available for download here: [https://github.com/Lyros/GUM Generator of Uru Manifests]. You will need a reference installation containing the unencrypted <code>.pak</code> file and <code>.sdl</code> files in <code>Python</code> and <code>SDL</code>, along with all the files from the <code>dat</code> and <code>sfx</code> folders from MO:ULa. On top of the <code>dat</code> folder, you should then copy the <code>dat</code> folder from moul-scripts to get the unencrypted versions. It requires Python 2.7 and [[libHSPlasma#Python|libHSPlasma for Python]]. |
'''Note on Python:''' the Python scripts need to be compressed into a <code>Python.pak</code> file. This can be achieved using the <code>plPythonPack.exe</code> tool obtained from compiling CWE (the tool only uses relative paths). | '''Note on Python:''' the Python scripts need to be compressed into a <code>Python.pak</code> file. This can be achieved using the <code>plPythonPack.exe</code> tool obtained from compiling CWE (the tool only uses relative paths). | ||
| Line 83: | Line 88: | ||
== Running == | == Running == | ||
If all went well, you can now start your server: | If all went well, you can now start your server: | ||
| − | + | <source lang="bash">~/dirtsand$ /opt/dirtsand/bin/dirtsand /opt/dirtsand/dirtsand.ini</source> | |
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. | 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. | ||
Latest revision as of 20:03, 16 October 2019
|
|
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.
Contents
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.