MOSS/Setup

MOSS currently only runs on UNIX and other *nix operating systems (such as GNU/Linux). Not Microsoft Windows. It ought to work on Mac OS/X (even PowerPC) but nobody has tried yet. The following document assists in the setup of MOSS on any of the compatible afore-mentioned operating systems. For instructions pertaining to a particular OS or Linux distribution, take a look at MOSS/Distribution Specific Instructions.

Please also see the main setup instructions for an alternative set of installation instructions.

Compile

Prerequisites

Before you start, assuming you already have a compatible OS, you need to ensure you have the following:

• pthreads (almost certainly installed already)
• libiconv (almost certainly installed already)
• OpenSSL (also almost certainly installed) -- you need both the libraries and the development headers if that's separate (I'm looking at you, Debian)
  • Versions found to work: 1.0.1 – Versions found not to work: 0.9.7
• Zlib (also probably installed) -- both the library and the development stuff if separate
• PostgreSQL -- both the sever and client, plus any development packages
• libpqxx -- both the library and the development package
  • Versions found to work: 3.1 – Versions found not to work: 4.0
• gcc, g++, whatever all you need for compiling C++

If you are compiling from a clone of a Mercurial respository and there is no "configure" script, you also need the autotools:

• autoconf
  • Versions found to work: 2.68 – Versions found not to work: 2.59
• automake
  • Versions found to work: 1.11.3 – Versions found not to work: 1.6.3
• libtool
  • Versions found to work: 2.4.2 – Versions found not to work: 1.5

If you are reading this, please go over to MOSS/Distribution Specific Instructions and fill in how to install all these programs on YOUR distribution/OS. Thank you!

configure

If you don't have a "configure" file, it must be generated. Run the ./bootstrap.sh script to create it.

Run ./configure. The configure script takes many options. For a full listing run ./configure --help. The default options are set up in such a way as to make your server match the way Cyan's server works. Here are the options you are probably interested in:

--prefix

Specifies where make install places the files. If you are using a non-typical location you may need to add prefix/lib to your LDFLAGS or something.

--enable-fast-download

During auth file downloads, Cyan's server waits for the client to acknowledge every 32k of data sent. I believe this was to fix the "zero seconds remaining" bug. MOSS does not have that bug. Use --enable-fast-download to configure the server to send data as fast as it can, thereby using all the bandwidth available.

--disable-single-login

If you use this, multiple different avatars on the same account can be logged in at once. Logging into the same avatar will boot the other. Without disabling "single login", logging into the same account will boot whatever avatar is logged in from that account.

Other options:

--enable-require-secure-download

Boot users who don't download python.pak.

--enable-encryption=type

The default is "cyan_dh". MOSS allows you to disable encryption, or (legacy) use RSA.

--enable-fork

The primary use for this is if you need to debug auth or file servers. It is much easier to debug single-threaded programs.

--enable-debug

Anyone developing MOSS or willing to run some extra bug-hunting code should use this. If the bug-hunting code finds a bad thing it will make the server dump core so you can debug it.

--enable-old-protocol

This makes MOSS use older protocol versions. You probably don't need this.

If you have any trouble with configure finding the locations of various libraries, you can use these:

--with-postgres=PREFIX

--with-libpqxx=PREFIX

--with-openssl=PREFIX

--with-zlib=PREFIX

--with-iconv=PREFIX

Compile

Run make. Assuming that succeeds, you probably should use make install.

Now cd into the postgresql directory. Here you need to compile a custom PostgreSQL module that creates UUIDs. Follow the instructions in the README file there, but for most people this should just be running make, followed by make install.

Install the PostgreSQL module in your PostgreSQL install, if it's not there already by now. Do this by copying the moss_uuidgen.so file you just compiled. You'll need to log in as root to do this (sudo cp moss_uuidgen.so /path/to/postgres/modules on most systems). Please check MOSS/Distribution_Specific_Instructions and fill in where to copy it for your system. Consult PostgreSQL documentation if you're not sure. After the library is installed, restart the DB server.

Set Up the Database

The easiest way to set up the database is to create a "moss" user to be associated with the MOSS database. If you want to use a different username, you have to edit the postgresql/moss.sql file to match. The moss user needs to be able to modify tables in the MOSS DB.

Most distributions create some user that has root access to the DB when connecting from the local machine. In this example this user is "pgsql" but yours may be different. Please check MOSS-Distribution_Specific_Instructions for hints or to fill in the user for your distribution.

Start by creating the database. The default database name is "moss"; if you use any other you'll have to set it in the MOSS configuration file. Make sure to use the "UTF8" encoding. Then create the "moss" user in the new database. Then load "postgresql/moss.sql into the new database.

I did the following:

su pgsql -c "psql postgres"
create database moss with encoding='UTF8';
\c moss
create role moss with login;
\q
su pgsql -c "psql moss -f moss.sql"

After this, you can connect to the database as the "moss" user:

psql -U moss

If all that works, you are done setting up the database!

Set Up Files

There are quite a few files that the server needs to use. All these files are located by default in locations relative to where you will *start* the server. The location of all the files can be configured in the configuration files; you may find it easiest to specify absolute paths (starting with /) there.

File hierarchy conventions used in this setup:

• No prefix: references the files found in your source download,
• ./: references the directory from where you will start MOSS,
• prefix: references the directory where MOSS is being installed.

File Server Data

You need to start with your current Uru install (MOULagain, presumably). This procedure assumes you can run a Windows application to create the file server manifest MOSS needs. This seems a reasonable assumption when the client itself is a Windows app. So temporarily leave your *nix server alone and switch to a Windows installation with Uru installed.

Copy support/ManifestCreator.exe and support/Manifests.zip to your Windows box. Unzip Manifests.zip. This makes a CyanStructure folder. The .txt files in this folder are input. They describe the files which need to be in the final manifests. It is important to use \ as the directory separator.

Start up ManifestCreator.exe. To generate a manifest, click "Make Manifest"; it brings up a dialog box. Navigate to the CyanStructure folder, and select all the .txt files in there. Then click OK and when it pops up with another dialog asking for the location of your Uru install, navigate to that directory, click OK and wait for a bit.

When it is done stop and consider which files you need the file server to actually give to clients. If you are making this shard for yourself it could be basically nothing, or everything. Note that we do not have a license to redistribute Cyan's data files. So it is recommended not to copy any files you should not distribute to your file server.

Back on the machine on which you are installing MOSS, create a file server directory. The default is ./file (relative to where you will start up your MOSS server). I recommend you make it prefix/file. Copy all the .mbm files created in the CyanStructure folder on your Windows box to this directory. If you are serving up a CWE client (built from open source) you want to copy the gzipped executable and libraries. They are located in CyanStructure\Client\External and need to be in file dir/Client/External on your server to match. Anything you can distribute and that clients will need to download, like a new Age, should also be copied. Make sure to match the directory structures when copying them over.

For Mac clients: Mac clients request the macExternal manifest instead of External. There are added files in the Mac manifest, but if you don't have them to generate a proper manifest from, just copy or symlink External.mbm to macExternal.mbm. If you do have the files, you can generate the proper manifest using ManifestCreator and the support/macExternal.txt file.

Auth Server Data

A script automating all the following steps in this section (except for any user-created ages) is in the works.

Like for the file server data, the default auth directory is ./auth (relative to where you start it up). I recommend using prefix/auth.

This directory is required to have another subdirectory named default. You must keep a copy here of the encrypted Python and SDL files for clients to download. The easiest way to get a set of these files is from the Cyan-provided AuthFiles.zip. Download this file, and unzip it. Copy the entire contents of the resulting AuthFiles/893 directory to auth dir/default/. The resulting directory structure is:

auth
  default
    Python
      python.pak
    SDL
      various .sdl files
    encryption.key

Now you have to make manifest files here as well. Make a Python.txt file which contains one line: Python\python.pak. Make an SDL.txt file which contains one line per file in the SDL directory, as in:

SDL\BaronCityOffice.sdl
SDL\Kveer.sdl
...

I just toss these manifest files in the auth dir/default directory but you don't have to. The server does not look at them.

If you have user-created ages with SDL files, be sure to add them to the SDL directory here. Encrypt them with the encryption.key (a tool to do this does exist in the CWE source). Similarly, if you want to add Python, you can rebuild the python.pak file, but if you are adding a new age, you may find it easier to add a new .pak file. If you do that, encrypt it and then add a new line to the Python.txt file for your new .pak. The client will download them all.

Once you have listed each SDL and Python file, you can use the Perl script support/make-mbam.pl to create the .mbam files. If you don't have Perl, ManifestCreator.exe can also create the files: simply select "Auth Server" in the "Manifest type" dropdown. If you use ManifestCreator, make sure it has the Python and SDL directories and their contents. Make sure to copy the resulting two .mbam files to your auth-dir/default directory.

Game Server Data

A script automating all the following steps in this section (except for any user-created ages) is in the works.

Just like for the file and auth server data, the default game directory is ./game (relative to where you start it up). I recommend using prefix/game.

The game servers need unencrypted .sdl and .age files. The easiest way to get a set of these files is from the Cyan-provided Scripts.zip. Download this file and unzip it. Copy/move the Scripts/SDL directory to game-dir. Then create game-dir/age and copy Scripts/dat/*.age to it (MOSS does not use the .fni files).

Do not forget to copy any user-created ages' SDL and .age files here. This copy needs to be unencrypted.

Now there is one more step. The SDL files the game server uses need to be moved around, some into subdirectories, and some renamed because UNIX treats file names case-sensitively. Please read the details in the doc/setup file (linked at the top of this page).

You should have three subdirectories when you're done. User-created ages may need subdirectories too, if they have multiple .sdl files. If you find this way too complex, just move all the .sdl files into the common subdirectory. You lose some small optimizations this way and you will need to restart the server if any SDL files change.

At the end the directory structure should be:

game
  age
    various .age files
  SDL
    common
      some .sdl files
    Garrison
      a couple of .sdl files
    Teledahn
      other .sdl files
    more .sdl files

Key Files

The modified Diffie-Hellman algorithm used in the client and MOSS by default requires the server to have private keys. Do not share them with anyone. They should not be world-readable.

You can generate keys using the make_cyan_dh program is installed in prefix/bin. Or, there might be a program to generate keys in the CWE source, but the chance of it outputting the private keys in the format MOSS wants is basically zero. Generate a key for each of auth, game, and gatekeeper. Run make_cyan_dh -h to see what generators to use if you want to match those MOULagain is using. If you're building your own client you can use whatever generator you want.

Note: I see no reason not to use OpenSSL default generators such as 2, 3, or 5. In fact, unless you are a cryptographer, I do not recommend departing from these. If you are a cryptographer, you probably did not need to hear that from me!

The -s and -c/-C options direct the program to write the data for the server and client to files, respectively, e.g.:

make_cyan_dh -g 2 -s auth_key.der -C pnNbAuthKey.hpp

or

make_cyan_dh -g 2 -s auth_key.der -c auth_key.bin

If you're compiling a CWE client, you can use the -C option to output a C++ file that should be a drop-in replacement for the current key files (under CWE/MOULOpenSourceClientPlugin/Plasma20/Sources/Plasma/NucleusLib/pnNetBase). Make sure you have at least revision 2 of the MOSS source to use -C (you may need to do a clean and a rebuild if you have previously compiled CWE with a different key; the dependencies in the projects are not set up perfectly). If you're not compiling a client, you probably want the -c option, and it's up to you what to do with the .bin file.

Take the .der file (contains the PRIVATE key) and move it to prefix. I suggest using prefix/etc/auth_key.der. Make it readable only by the user which will be running the server:

chmod 400 prefix/etc/auth_key.der
chown mossuser prefix/etc/auth_key.der

Repeat this process for the game and gatekeeper keys: prefix/etc/game_key.der and prefix/etc/gatekeeper_key.der.

Configuration Files

Now that you have all the other files set up, it's time to configure MOSS itself. There is a configuration file for each server process. The default location for moss_backend is ./etc/moss_backend.cfg and the default location for moss is ./etc/moss.cfg. I recommend copying main.cfg to prefix/etc/moss.cfg and backend.cfg to prefix/etc/moss_backend.cfg.

Now open each up in your text editor. The files contain instructions on how to set the various options.

I recommend you set the following in moss.cfg to the absolute paths corresponding to where you installed these files in earlier steps: auth_download_dir, auth_key_file, file_download_dir, game_data_dir, game_key_file, gatekeeper_key_file. In addition I recommend you set log_dir to somewhere you want log files to go. Remember the log directory has to be writable by the user that will run the server. You may also need to set pid_file to a location writable by that user. If you want the .pid file to be created. Read through all the options to make sure your setup is as you want. The only mandatory configuration directive is external_address.

For moss_backend.cfg look especially into log_dir and pid_file. In addition, depending on how your DB is set up you likely need to specify db_user, db_password and maybe other DB parameters.

Security Considerations

Please read about them at the end of doc/setup. Short version:

• Never run MOSS as root.
• moss_backend.cfg contains your DB user's password; do not make it world-readable (or even group-readable).
• Private key files (files finishing in .der) should never be made public.
• No encryption is currently available for all the backend connections.
• Should you decide to install the front-end server and the back-end server on separate machine, make sure the connection between the two is secured. Same goes for database server.

Before You Open Your Server

If you plan to let anyone other than you connect to your server, you have certain obligations under the licenses of the software/data you will be distributing from the file and auth servers.

• Cyan content: the MOULagain EULA still does not provide for you to modify and redistribute the files. So do not put original or modified Cyan files on your file server. You can still have them listed in the .mbm (manifest) files. If someone has an incomplete install they will be forced to get the files from Cyan's file server. That is as yet still the only place from which you're supposed to get those files.
• Python code: you are supplying GPL'd Python code. You must provide a way to acquire that code. If you are using unmodified Python you can link to the original source. If you modify it for any reason, you must make your changes available and tell your users where to get it.
• CWE clients: if you are providing client executables from a CWE build:
  • GPL license: you probably need to add the GPL license file to the client install. The license is supposed to be conveyed with the executable, and the only sure way to do that is to install it from the file server same as the executable. This means you have to add it to ThinExternal.txt and External.txt and generate the new .mbm files, copying the .mbm files and LICENSE.txt.gz over to the appropriate locations. You probably should also arrange for the license to be available along with UruLauncher.exe.
  • Client source: you must provide a way to acquire the source for your client. The means is supposed to be "equivalent" to the way the executable is acquired. Links are probably sufficient. If you use an unmodified version you should be able to link to the repository (make sure you point to the actual changeset you used). If you modify files for your shard's public keys, status hostname, and/or gatekeeper/auth addresses, you have to additionally provide that source. Note: these are public keys, so don't worry, you're not giving anything away.
  • Library credits: Unless someone changes the jpeg library again, you need to credit IJG for jpeglib: "This software is based in part on the work of the Independent JPEG Group." Similarly, if the client uses OpenSSL, credit should be given: "This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit (http://www.openssl.org/). This product includes cryptographic software written by Eric A. Young (eay@cryptsoft.com). This product includes software written by Tim J. Hudson (tjh@cryptsoft.com)." The easiest may be to add another file doing so to the install. Or, if you are modifying Python for some reason, you could add it to the in-game credits along with all the other licenses (files: xUruCreditsJournalEnglish.py, xUruCreditsJournalFrench.py, xUruCreditsJournalGerman.py, xUruCreditsJournalItalian.py, xUruCreditsJournalSpanish.py). The links or whatever means you use to provide access to the source of the binaries and Python don't have to go into the client install, but they must be somewhere reasonable for your users to find, "equivalent" to installing the software for your shard. I would put links to a copy of the files on your shard's home page or something.

See also the CWE FAQ.

Please do not consider this advice the final or complete word on the matter. All the licenses of all the data you use expect you to follow them. So you have to do your due diligence. If you find something obviously missing from this section, please add it!

Start It Up

Hopefully someone will contribute a nice startup script.

Now you should be set to run your server. For now, cd to the directory you planned from the start to start the server from (that's prefix in the earlier recommendations). Make sure you are su'd to the user you want to run as. NOT root! Start moss_backend first, then moss. E.g., if you have put the config files in prefix/etc, you can just do:

prefix/bin/moss_backend
prefix/bin/moss

You can instead specify the location of the config file with the -c option. If you've used absolute paths in the config files, you can thus easily run the server from any directory.

After Initial Startup

To set up AllAgeGlobalSDLNodes, use global_sdl_manager (we have no VaultManager to do it). This program is installed in prefix/bin. To aid setup, the support/set_to_moul.txt file can be used to set the global SDL state to a reasonable default (with no sparks) by running something like:

global_sdl_manager game/SDL < set_to_moul.txt

If you want sparks, you can turn them on yourself using this program.

Note: this program does NOT work unless the MOSS server has already been started at least once. You might also need to provide your database details to the program; just type global_sdl_manager to get a list of all the appropriate options.

Create Accounts

Hopefully someone will contribute a script to add users. A CGI script to automatically add users would be neat too.

Don't forget to create accounts for your users, or it will be difficult to log in... Please just refer directly to doc/user-management.

Really short version:

INSERT INTO accounts (name, hash, id, class, visitor)
VALUES ('foo@example.com', '11223344...', uuid(), 'default', false);

Where '11223344' is a SHA-1 password hash.

See Also

• MOSS
• MOSS/Notes
• MOSS/Setup
• MOSS/Distribution Specific Instructions
• MOSS/Developer Notes
• MOSS/FAQ

Please see the following for more information of interest to running a server.

• MOSS/Notes
• doc/running