OpenUru - User contributions [en]

MOSS/Project Ideas

2012-01-07T19:54:35Z

A'moaca': /* Fairly contained changes */ remove item fixed for bug MOSS-18

The initial list was generated over the lengthy period of MOSS's initial
development. These project ideas mostly cover missing functionality. None of
the missing functionality is known to cause gameplay issues so these did not
really seem like bugs. These ideas are grouped by general type of change
required, and sort of by increasing approximate difficulty level and sort of by
decreasing value.

Bigger ideas, such as entirely new functionality now made possible by the
release of the client, could go here too. Be realistic, though. Remember that
protocol changes are not to be made lightly, because it causes an
incompatibility problem. It is probably better to propose large changes in
discussion format on the forums. Do not ''expect'' someone else to take up and
implement your proposal.

The whole idea of this list is to provide some ideas for anyone wishing to dive
into MOSS. Sometimes a little direction helps.

== Terminology ==
The terms "frontend" and "backend" are used throughout this document. If the meaning is not clear from context, the terminology is explained in the [[MOSS-Developer_Notes#terminology | Developer Notes]].

The "vault" is basically the database, though it could be abstractly thought of as a collection of trees of vault nodes. Generally when referring to it as a set of node trees, "vault" is written and when referring to it as something with tables and rows, "DB" is written. The "vault server" is that portion of the backend concerned with handling the Vault* messages and working with the database.

== Fix bugs ==

The bug tracker is here: https://foundry.openuru.org/jira/browse/MOSS

== Detail work (little Uru-specific knowledge required) ==

* Try disabling the Nagle algorithm on sockets. This should result in less latency to the client when small messages are involved. Make sure to test the whole game thoroughly.

* Figure out and implement a good way to use autoconf to compile in default pathnames. This would apply to the default config file, key file, moss_serv binary, and log/auth/game/file directory locations. The idea is if I say --prefix=/foo the defaults become /foo/etc/moss.cfg and so forth instead of ./etc/moss.cfg. Don't forget autoconf lets you override the etcdir, bindir, etc. separately.

* Treat SDL filenames case-insensitively. This is very annoying in Unix, since it requires using readdir() and strcasecmp() instead of just open().

* Make it so the game/state directory location can be separately configured. This is so the whole MOSS install can be read-only and just the log directory and game/state moved somewhere read-write. (The easy workaround is to symlink a writable directory to game/state.)

* Log the PID of all forked servers in moss.log.

* See if we can switch to libevent for inter-thread communication instead of raw signals. This should be fairly portable and take advantage of the different per-OS lightweight signalling mechanisms.

* Allow ''skipping'' overlong messages (messages MOSS thinks are too big). This requires, upon catching the exception, tossing out the message, and if it has not all been read in yet, keeping track of how much more to toss in the future. The RC4 state must be updated too for the tossed message length.

* It would be nice to use atomic operations for refcounts instead of having to use (bigger, slower) mutexes for them. This does make MOSS not architecture-independent, which is part of why I have been resisting it. (See also signal handling next.)

* Signal handlers and the operations to read and reset the values in the main loops should be using atomic operations.

* Catch and handle std::bad_alloc whenever possible.

== Fairly contained changes ==

* Make it so game servers can be forked as separate processes. This helps a lot for debugging and also would help for age development, making it easier to change SDL and retest. Otherwise you have to shut down the whole frontend server or wait out the age's linger time. This work was started but not completed, and that code can be found inside <tt>FORK_GAME_TOO</tt> #ifdefs. If you do this, I suggest you consider separating <tt>FORK_GAME_TOO</tt> from <tt>FORK_ENABLE</tt> so that one could have forked game servers and *not* forked auth/file servers.

* Age population limits are unimplemented. The value is in the vault, but the server does not look at it.

* Figure out how to throw out clones and SDL when a player leaves the age. Please see the "clean up clone, SDL" section in GameServer::conn_shutdown(). Right now this is full of special cases: it handles the Kemo bugs and and Quabs specially (a different thing for each). It may be that this is required for best behavior, but I still feel like I've missed something despite heavy scrutiny of the data. This is more of a research project and not much of a code project.

* MOUL parsed SDL nodes on the way into the vault. It probably only updated the node with fields having the Dirty bit set. In addition it added timestamps to the fields because the client does not put in the timestamps (reasonably so, as its time may be wrong). MOSS currently saves the SDL wholesale. This basically works, but with the timestamps properly added, the game server can merge the vault, age, and global SDL in any order and without strange rules. Note: if you do this, you also need to write a script or some other way to update all the SDL nodes in existing MOSS DBs.

* The kickable SDL filtering algorithm is the same one I put in Alcugs ages ago. It is better than nothing but not as good as Plasma's. You will see more warping of kickables than with Cyan's server. This project is to come up with a better way of deciding what physical SDL to send to all the clients, based on those messages all the clients are sending to the server.

* The server is probably supposed to use RelevanceRegion information to avoid sending SDL updates to clients who don't share a relevance region with the originating client. (The idea being to reduce network traffic, since hopefully the client already avoids rendering/physics on things in irrelevant regions.) Things work if the server doesn't filter, so MOSS doesn't. Also, I do not have strong evidence to believe this supposition is actually correct. Which is the other reason MOSS doesn't do it. Finding out, and implementing it if so, would be a nice project.

* Figure out what the server is supposed to do with plSetNetGroupIDMsg and do it. Right now MOSS just drops it to no apparent ill effect. I am deeply suspicious of this message due to seeing it at aurally unpleasant times in UU. (Old, old notes: "may have to do with infinitely looping scraping noises".)

* <tt>kCli2Auth_SendFriendInviteRequest</tt> is not fully supported (it is dropped on the floor).

== Bigger changes ==

* The following messages are unimplemented.
** <tt>kCli2Auth_VaultSetSeen</tt> -- unimplemented in client
** <tt>kCli2Auth_ScoreDelete</tt> -- never saw one, so couldn't implement it
** <tt>kCli2Auth_ScoreSetPoints</tt> -- never saw one, so couldn't implement it
** <tt>kCli2Auth_ScoreGetRanks</tt> -- never saw one, so couldn't implement it
** <tt>kCli2Csr_PingRequest</tt> -- no recorded Csr messages
** <tt>kCli2Csr_RegisterRequest</tt>
** <tt>kCli2Csr_LoginRequest</tt>
** <tt>kCsr2Cli_PingReply</tt>
** <tt>kCsr2Cli_RegisterReply</tt>
** <tt>kCsr2Cli_LoginReply</tt>

* Add hood randomization to DRC hoods. Player-created hoods are randomized by the Python in the Nexus when the hood is created. DRC hoods, however, are created by the server. In MOSS's case, they are created entirely by SQL code. So adding DRC hood randomization means noticing when the DB has created a new DRC hood, creating and modifying SDL in the backend, and then finding and modifying the age SDL node for that new hood. All before responding to the client creating the new avatar and thus the new DRC hood.

* The MessageQueue class has a concept of priorities. The idea was to enable dropping of lower-priority messages if a queue to a given client starts to back up. (The lowest priority being voice chat, then avatar movements, with world state changes being highest.) The measurement of queue length or throughput necessary for that is not implemented. So, neither is the dropping. (There is the very beginnings of some if <tt>DO_PRIORITIES</tt> is #defined.) As such, queue users don't do a good job of priority-setting, although VOICE and FRONT are properly used. The idea wasn't to order the queue (except for FRONT), but to skip sending, say, a VOICE message when we encounter one, if the queue congestion measure says to.

* '''Vault security'''
: The MOSS vault is as insecure as the MOUL vault. Need I say more? Here are some starter thoughts.
:* MOSS should parse incoming SDL messages and sanity-check them. See also [[#SDL_timestamps | adding timestamps]].
:* MOSS could probably verify other blob contents too.
:* Anyone can save anything to any node, and can fetch any node if they know its type and ID. We can deny these requests if the user shouldn't have access. Possibly [[MOSS-Developer_Notes#notifier | the notifier field]] can help.
:* Much more, I'm sure. Better vault security ''is'' possible.

* Eliminate excessive byteswapping of opaque server IDs in BackendMessages. This is to say, in the backend server, when reading in the messages, it byte-swaps the IDs to store them, only ever uses them in equality tests with other IDs, and then byte-swaps them back when sending new messages. (On a little-endian box there's no swapping so it does not cost much, but it's the principle of the matter.) Unfortunately this really needs to be tested on a big-endian machine.

* Try changing the File server to do [[MOSS-Setup#ackless | ackless downloads]], too. Maybe only if there is only one download at a time, though.

== Scalability issues ==

Performance and scalability are always interesting questions. And frequently ignored, because they only matter for larger installations.

These are ideas unimplemented because they only really matter for large
shards. Large as in having, let's say, 50+ concurrent '''busy''' users. (50
people standing in the city chatting doesn't actually do much.) Maybe MOSS is
okay with that number now, in which case "large" is more. It is entirely
unknown.

* Performance testing. Instrumentation. There should be a load generator to do this. This was not high on the list during development, with a user base of 3.

* See the last paragraph in the comments at the top of FileTransaction.h about how multiple file transactions of the same file should share a single opened file.

* Allow speculative pre-caching of AgeInfoNodes and PlayerInfoNodes when node changed notifications come from the vault server and are forwarded to any connected client. Cache in the auth server, vault server, or both. The goal is to reduce latency on those requests the client freezes for.

* The backend protocol supports game servers requesting batches of GameMgr IDs. However, there is no code on either side to actually do so. The idea for this was that more populated ages, like the city, would benefit from doing batch requests. Every person who links in with a marker game needs a new global game ID, and it would be nice to cut out any extra backend round trips for links, even though this particular round trip does not block the link process (aside from being something the backend is doing when it could be doing something else).

* Database performance could be measured and the SQL or even tables optimized.

* MOSS currently uses a single blocking connection to the DB. Implement and investigate performance of multiple DB connections, or asynchronous ones. Maybe the backend server has to become threaded to gain the best advantage.

* In a big shard, we may need to split the backend server work up. The [[MOSS-Developer_Notes#backend_typecodes | backend protocol]] is designed to support separating backend work between threads. The "classes" of backend messages in a bitfield are meant as a way to quickly route a backend message to an appropriate backend thread or process.

== Frontend/backend interactions ==

* Add encryption to the backend protocol. This itself is not a big deal (though you have to pick a good key negotiation, and do not forget to consider authentication mechanisms), but it does mean all the BackendMessage fill_buffer() code paths would be newly exercised, so a lot of regression testing would be in order.

* It would be much easier on the DB if updates to markers are batched by the game server. This especially applies to capturing markers. See the comments in the setmarkerto() and startmarkergame() SQL functions.

* The backend protocol allows for frontends hosting ages to specify only a subset of ages that can be hosted there. This is unused right now; the message has a field saying, "this is the length of the following age restriction list" and it is always zero. When there are no restrictions the backend can request any frontend to host any age.
** The need for splitting hostable ages is unclear, but in a very large shard you might, for example, put all city instances, or even only the public one, on a separate server. It would also allow someone to join a shard and host just their own age, or whatever.
** Since the frontend never sends restrictions, the backend currently has no way to store and use them. So there is work on both sides.
** Presumably which ages a frontend server can host would be a configuration option but it could be done instead by restricting the contents of the game/age directory. That would not allow even finer-grained restrictions, but this whole project kind of needs a real use case to flesh out what is needed.

* Having one backend TCP connection per frontend server is probably not a good thing, in terms of efficiency, or of scalability with a cluster of machines. We could change it to have one backend connection per frontend ''process'' and funnel everything through it. The mostly-implemented but unused and untested MultiWriterMessageQueue was meant, in part, to support this (there are multiple threads writing, but only one thread reading, which writes to the socket).

: Then when messages are received in the frontend there needs to be some way of passing the message to the right thread and signaling them something is present to be handled. This is all unimplemented but the format of the backend messages is meant to take care of this case (in particular, the two "server IDs" in the header are for dispatching messages to the correct thread).

: However, essentially the same changes would be necessary if the backend server is folded into the main server so there is only one process; then "sending" messages to the backend server is just putting them on the (shared) queue that would have been used to funnel everything through one connection, and "receiving" them is just taking them off that queue since there's no TCP connection to deal with.

== New functionality ==

* I am guessing Cyan's server handles the GameMgr stuff with server-side scripting. At the time MOSS was implemented there was no expectation that new game types may be added so adding in a scripting language was not worth the problems incumbent with doing so. Also the overall value of scripting is not clear (especially for the cost in server complication). However, it could be done. The project would have to include embedding the scripting and then rewriting stuff using scripts.
: Please note, a lot of effort went into getting the Heek right, handling ties, allowing people to accidentally stand up and sit back down in the game, and probably other details I forgot. If you want to script Heek, it really ought to still work as well.

* Really adventurous hardcore project: destroy KI hacks. The server would have to be able to analyze all game traffic to decide whether it looks okay. To do it right the server would have to have and understand PRP files and do physics. Also "console" commands have to be wisely filtered. If you're daunted, join the club.

* Add a data export API; see Blizzard's Armory as an example. This could enable players to have web-visible "Achievements" and even allow for automation of integration with social media. This can add value to the game without requiring any client changes. A well-designed website taking advantage of this API might:
** Permit players to control privacy settings on whether their profiles should be public or private (default should be private!)
** View/Display their current game accomplishments (relto pages, sparks, ages completed)
** Enable automated posting to social media when the player accomplishes a new goal

== Redesigns ==
{{tba}}

[[Category:MOSS]]

MOSS/Setup

2011-04-11T06:32:13Z

A'moaca': /* Key Files */ MOSS-3 is fixed, and make_cyan_dh has -C now

MOSS currently only runs on Unix. Not Windows. It ought to work on Mac OS/X
(even PowerPC) but nobody has tried yet.

Please also see the
[http://foundry.openuru.org/fisheye/browse/MOSS/doc/setup main setup instructions].

== Compile ==

=== Prerequisites ===

Before you start, 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)
* 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
* gcc, g++, whatever all you need for compiling C++

If you are compiling from a clone of an Hg respository and there is no
"configure" script, you also need the autotools:
* autoconf
* automake
* libtool

'''If you are reading this, please go over to'''
[[MOSS-Distribution_Specific_Instructions]] '''and fill in how to install all that 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 set up the server to match the
way Cyan's works. Here are the options you are probably interested in:
; --prefix
: Specify 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 [[MOSS-Notes#RSA | 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".

Install the postgres module in your postgres install. 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 if it's not there already. 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
will have to edit the 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 my 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_Files | 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!

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, but the
Minkata one is still broken.

== 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 | configuration files]]; you may find it easiest to
specify absolute paths (starting with "/") there.

=== 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
manifets MOSS needs. This seems a reasonable assumption when the client itself
is a Windows app.

Copy support/ManifestCreator.exe and support/Mainfests.zip to your Windows
box. Unzip Manifests.zip. This will make 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. To generate a manifest, click "Make Manifest" and it
brings up a dialog. Navigate to the CyanStructure folder, and select all the
.txt files there. Then click OK and when it pops up a 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 which will run MOSS, create a file server directory. The
default is "./file" (relative to where you start it up). I recommend you make
it ''prefix''/file, where ''prefix'' is the installed location. Copy all the
.mbm files created in the CyanStructure folder to this directory. If you are
serving up a CWE client (built from open source) you will 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, also should be copied. Make sure to match the
directory structures when copying them over.

Finally, 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 ===

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

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

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
[http://assets.openuru.org/cyan/AuthFiles.zip 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 with contains one
line per file in the SDL directory. The lines look like
"SDL\BaronCityOffice.sdl". I just toss these in the auth/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 will also create the files. 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 ===

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.

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

The game servers need unencrypted .sdl and .age files. The easiest way to get a
set of these files is from the Cyan-provided
[http://assets.openuru.org/cyan/Scripts.zip 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 which will be 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. 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".

Do the same 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 for 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:
<tt>auth_download_dir</tt>, <tt>auth_key_file</tt>, <tt>file_download_dir</tt>,
<tt>game_data_dir</tt>, <tt>game_key_file</tt>,
<tt>gatekeeper_key_file</tt>. In addition I recommend you set <tt>log_dir</tt>
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
<tt>pid_file</tt> 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
<tt>external_address</tt>.

For moss_backend.cfg look especially into <tt>log_dir</tt> and
<tt>pid_file</tt>. In addition, depending on how your DB is
[[#Set_Up_the_Database | set up]] you likely need to specify <tt>db_user</tt>,
and maybe other DB parameters.

== Security Considerations ==

'''Please''' read about them at the end of
[http://foundry.openuru.org/fisheye/browse/MOSS/doc/setup doc/setup].

Do not run MOSS as root.

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

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

* 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 [http://assets.openuru.org/cyan/Scripts.zip original source]. If you modify it for any reason, you must make your changes available and tell your users where to get it.

* If you are providing client executables from a CWE build:
** 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'll 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.
** 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.
** Unless someone changes the jpeg library again, you need to credit IJG for jpeglib. 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:
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 [[CyanWorlds.com_Engine/FAQ#What_are_my_open_source_license_.28GPLv3.29_responsibilities_as_a_user.2C_developer_or_server_operator_.28e.g._shard_owner.29.3F | 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 ==

Now you should be set to run your server. Hopefully someone will contribute a
nice startup script. 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:
bin/moss_backend
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.

== Create Accounts ==

Don't forget to create accounts for your users, or it will be difficult to log
in... Please just refer directly to
[http://foundry.openuru.org/fisheye/browse/MOSS/doc/user-management doc/user-management].

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

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

== More Hints ==

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

* [[MOSS-Notes]]
* [http://foundry.openuru.org/fisheye/browse/MOSS/doc/running doc/running]

[[Category:MOSS]]

Wireshark Plugin

2011-04-11T05:57:45Z

A'moaca': /* How to compile it */ note guest svn access is not working

{{UruDocProj}}
Welcome to the main page for the Uru Wireshark plugin!

= Do I care about this? =

Wireshark is a GUI-based network protocol analysis tool. (There is a command-line version too.) In short, it lets you look at network traffic to see what is going on, even in real-time. a'moaca' has figured out Uru bugs based on real-time behavior related to what is seen on the network, in addition to more subtle bugs discovered with detailed later analysis.

Generally this tool will only be of interest to those working on the protocol or client/server code. It is also interesting for a more hobbyist "figure out how it works" perspective.

But there is a caveat. The MOUL protocol (which the plugin calls "UruLive") is protected by a form of public-key encryption. This means that the Uru plugin cannot read the contents of any but the very first packets of each connection, unless you have the private key or some means of determining the negotiated session key.

Only Cyan should have the private key. Anyone writing new clients can choose to expose the session key for use with the Wireshark plugin. When people can run their own servers, they will in turn have their own private keys and they can use the plugin too. If you wish to use the plugin otherwise, I leave you to your creativity.

The plugin will work on old UU/Alcugs traffic, though, should you happen to have any to look at.

= History (why are things this weird way?) =

a'moaca' first started the plugin while debugging a linking hang with old Alcugs (unet2) code. The resulting bare-bones transport-layer only version of the plugin was checked into the Alcugs repository (where some Alcugs-specific code was later added that is not present in this version as of now). Later, in support of other projects, a'moaca' began adding dissection of the rest of the protocol, based almost entirely on the Alcugs server code itself. This is the reason many of the names in the plugin are what they are.

The hobbyist perspective led to gradually more dissection, proceeding on to the MOUL protocol. Over time, cjkelly1 has contributed a lot to the plugin as well, including some code contributions, effort spent figuring things out, testing, a lot of Windows-specific testing (usually unintentional but sometimes planned), and providing some of the correct names for things.

Very little of the knowledge added by a'moaca' and cjkelly1 after what originated from the Alcugs source came from disassembly, the "usual" method of Uru reverse-engineering. It was done by looking at real traffic and educated guessing. This is the reason many other names are what they are, and this is why there are still some gaps in the dissection.

If you want to fix any of this, submit a patch!

= How to use it =

(At the moment there isn't a compiled executable to distribute. This could change in the future. Until/unless a precompiled version is available, you will have to compile your own. For that, see the next section.)

Using the Uru plugin is not much different than using Wireshark for any other protocol. Here are some extra notes:
* There are two configuration sections, "Uru" and "UruLive". The "Uru" section covers configuration specific to the Prologue/UU/PotS protocol. The "UruLive" section covers configuration specific to the MOUL/MOULa protocol. Anything common to both is also in the "Uru" section (this is the toggle for hiding fields, and all SDL-related configuration).
* Be careful with your SDL files. Unfortunately, the MOUL SDL files are not a strict superset of PotS files (I believe there is at least one mismatch with the same version number, for example). Genrally one copy will suffice, though. If you do not provide SDL files, the plugin will use a crummy but serviceable algorithm that guesses the field types.
* The UruLive configuration contains several choices for protocol versioning. These apply to MOUL versions. You can basically ignore them unless you have ''old'' uncrypted traces. The default (Live 9, autodetect) should be good.
* Two ways to decrypt MOUL connections are provided: giving Wireshark each session key, or giving it the private key data for each type of connection.
** The first way requires configuring the 7-byte session key, if you have a way to determine it. This key is negotiated each connection. The input box accepts a comma-separated list of port=key pairs. Use the client port number (the one that is not 14617); this is how the plugin associates each key with a connection. The 7 bytes of the key should be in hexadecimal. An example value might be:
1050=1A2B3C4D5E6F70,1053=1234ABCD5678EF
:* The second way requires knowledge of the server private key. Provide a key file for each connection type (auth, game, gatekeeper). The format of the key file is 128 bytes of binary data. The first 64 bytes are the modulus in '''big-endian''' order (note it is little-endian in the exectuables), and the second 64-bytes are the private key, again '''big-endian'''. (This key file choice is based on the baseless assumption that the actual key files are stored in a common format such as DER, which is big-endian.)

= How to compile it =

The code is present in OpenUru.org's Subversion repository at [http://foundry.openuru.org/svn/wireshark_plugin http://foundry.openuru.org/svn/wireshark_plugin].

<big>NOTE (2011-04-10): Currently "guest" Subversion access is not working. You will need to register for a [https://foundry.openuru.org/jira JIRA account] and use that username and password as described below. Hopefully guest access will be restored soon.</big>

To check it out, use your favorite Subversion GUI with username "guest" and password "guest", or on the command line:
svn co --username guest --password guest http://foundry.openuru.org/svn/wireshark_plugin
This will check out the latest version of the source in the current directory. You will also need a copy of the Wireshark source. It may be downloaded from [http://www.wireshark.org/download.html the Wireshark site]. Using 1.4.x or the "Development Release" is recommended, as the patch provided will work with that tree. Version 1.2.8 or newer will also work, but you will need to patch plugins\Makefile.nmake yourself, as the structure of the file differs between 1.2.x and newer releases.

In the plugin directory, the INSTALL file provides build directions. The basic idea is that you patch the plugin into the Wireshark build and then build Wireshark normally. So you should be able to follow Wireshark's build documentation.

The [http://www.wireshark.org/docs/wsdg_html_chunked Developer's Guide] contains [http://www.wireshark.org/docs/wsdg_html_chunked/ChSrcBuildFirstTime.html build instructions], which are pretty minimal. If you are building for Windows, check [http://www.wireshark.org/docs/wsdg_html_chunked/ChSetupWin32.html the additional instructions] and a'moaca' uses [http://wiki.wireshark.org/Development/MSVC7 this wiki page].

= Contributing =

OpenUru.org has a JIRA installation. You may use it for [http://foundry.openuru.org:7080/browse/WIREPLUG bugs and patch contributions]. JIRA account registration is public. Please register there to submit bugs.

Code contributions will be code-reviewed for safety and correctness. Please keep code to 79 columns or fewer. There are currently no plans to reject anything based on content unless it is actually incorrect. If you want commit access, contribute a couple working patches and then ask for access. This protocol may change in the future if it does not work.

[[Category:Documentation]]

MOSS/Setup

2011-04-10T06:01:09Z

A'moaca': /* Key Files */ openssl also likes 3 for D-H generators

MOSS currently only runs on Unix. Not Windows. It ought to work on Mac OS/X
(even PowerPC) but nobody has tried yet.

Please also see the
[http://foundry.openuru.org/fisheye/browse/MOSS/doc/setup main setup instructions].

== Compile ==

=== Prerequisites ===

Before you start, 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)
* 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
* gcc, g++, whatever all you need for compiling C++

If you are compiling from a clone of an Hg respository and there is no
"configure" script, you also need the autotools:
* autoconf
* automake
* libtool

'''If you are reading this, please go over to'''
[[MOSS-Distribution_Specific_Instructions]] '''and fill in how to install all that 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 set up the server to match the
way Cyan's works. Here are the options you are probably interested in:
; --prefix
: Specify 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 [[MOSS-Notes#RSA | 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".

Install the postgres module in your postgres install. 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 if it's not there already. 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
will have to edit the 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 my 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_Files | 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!

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, but the
Minkata one is still broken.

== 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 | configuration files]]; you may find it easiest to
specify absolute paths (starting with "/") there.

=== 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
manifets MOSS needs. This seems a reasonable assumption when the client itself
is a Windows app.

Copy support/ManifestCreator.exe and support/Mainfests.zip to your Windows
box. Unzip Manifests.zip. This will make 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. To generate a manifest, click "Make Manifest" and it
brings up a dialog. Navigate to the CyanStructure folder, and select all the
.txt files there. Then click OK and when it pops up a 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 which will run MOSS, create a file server directory. The
default is "./file" (relative to where you start it up). I recommend you make
it ''prefix''/file, where ''prefix'' is the installed location. Copy all the
.mbm files created in the CyanStructure folder to this directory. If you are
serving up a CWE client (built from open source) you will 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, also should be copied. Make sure to match the
directory structures when copying them over.

Finally, 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 ===

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

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

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
[http://assets.openuru.org/cyan/AuthFiles.zip 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 with contains one
line per file in the SDL directory. The lines look like
"SDL\BaronCityOffice.sdl". I just toss these in the auth/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 will also create the files. 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 ===

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.

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

The game servers need unencrypted .sdl and .age files. The easiest way to get a
set of these files is from the Cyan-provided
[http://assets.openuru.org/cyan/Scripts.zip 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 which will be 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 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 auth_key.bin

If you're compiling a CWE client, make_cyan_dh does not currently output data
in that format. See [https://foundry.openuru.org/jira/browse/MOSS-3 the bug]
for the workaround. If you're not compiling a client, 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".

Do the same 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 for 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:
<tt>auth_download_dir</tt>, <tt>auth_key_file</tt>, <tt>file_download_dir</tt>,
<tt>game_data_dir</tt>, <tt>game_key_file</tt>,
<tt>gatekeeper_key_file</tt>. In addition I recommend you set <tt>log_dir</tt>
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
<tt>pid_file</tt> 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
<tt>external_address</tt>.

For moss_backend.cfg look especially into <tt>log_dir</tt> and
<tt>pid_file</tt>. In addition, depending on how your DB is
[[#Set_Up_the_Database | set up]] you likely need to specify <tt>db_user</tt>,
and maybe other DB parameters.

== Security Considerations ==

'''Please''' read about them at the end of
[http://foundry.openuru.org/fisheye/browse/MOSS/doc/setup doc/setup].

Do not run MOSS as root.

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

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

* 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 [http://assets.openuru.org/cyan/Scripts.zip original source]. If you modify it for any reason, you must make your changes available and tell your users where to get it.

* If you are providing client executables from a CWE build:
** 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'll 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.
** 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.
** Unless someone changes the jpeg library again, you need to credit IJG for jpeglib. 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:
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 [[CyanWorlds.com_Engine/FAQ#What_are_my_open_source_license_.28GPLv3.29_responsibilities_as_a_user.2C_developer_or_server_operator_.28e.g._shard_owner.29.3F | 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 ==

Now you should be set to run your server. Hopefully someone will contribute a
nice startup script. 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:
bin/moss_backend
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.

== Create Accounts ==

Don't forget to create accounts for your users, or it will be difficult to log
in... Please just refer directly to
[http://foundry.openuru.org/fisheye/browse/MOSS/doc/user-management doc/user-management].

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

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

== More Hints ==

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

* [[MOSS-Notes]]
* [http://foundry.openuru.org/fisheye/browse/MOSS/doc/running doc/running]

[[Category:MOSS]]

MOSS/Notes

2011-04-06T05:34:04Z

A'moaca': /* Questions */ typo

This page just holds various notes about running a MOSS server.

== Questions ==

I can't really call this a FAQ until the questions have been asked frequently.

; How do I add a user?
: [[MOSS-Setup#Create_Accounts]]
; How do I change the Python?
: Start with the source Cyan has generously provided us under the GPL. To compile that source you'll have to add in the glue. Maybe there is a tool to do that in the CWE source. Make your changes. After compiling and creating the .pak (another tool?), copy the .pak to the [[MOSS-Setup#Auth_Server_Data | correct server directory]] and encrypt it. Make a new .mbam file.
; How do I add a new age?
: Copy the encrypted .pak to the [[MOSS-Setup#Auth_Server_Data | correct server directory]], add the file to the Python.txt, and make a new .mbam file. Copy any SDL files to the auth SDL directory and encrypt them. Add them to SDL.txt and make a new .mbam file. Copy unencrypted SDL files to the [[MOSS-Setup#Game_Server_Data | correct server directory]]. Note if you have more than one SDL file for your age, or the file is not named the same as the age, you'll need to put the age's SDL file(s) in a directory named after the age. Copy the unencrypted .age file to the game server directory.
; Why would I use --enable-fork?
: This is primarily useful for testing. It's easier to debug a non-threaded process.
; What resource limitations are there (file descriptors, memory, etc.)?
: This is a question that's not obvious to answer. But here is what is known:
:* Currently MOSS uses about 5 file descriptors when idle. It uses about 10 per connected user. (4 are for the game server, so if the user links around a lot, it will be more, and if you have multiple users in one age it will be less.) If you are running a large shard, you may need to adjust per-process file descriptor limits (see the "ulimit" command) or even kernel (global) limits. If you adjust the global limit, pay attention to <tt>FD_SETSIZE</tt>. See the select() man page.
:* Currently MOSS uses 7 big buffers for network data per connected user. The buffer size is set by <tt>BUFSIZE</tt> in constants.h. The default is 64k, so a total of 448k per user. If you have enough users that your moss processes grow too large you can reduce the <tt>BUFSIZE</tt>.
:* There is not a lot of disk I/O, except for whatever the database has to write. If you set the log levels very low (DEBUG or worse, MSGS) then there will be a lot of I/O for log files.
; Does MOSS work on my Power PC?
: It is supposed to! Testing of big-endian systems was done, but not a full, complete run-through of all game mechanics and multiplayer testing. If it does not work, [[MOSS#How_to_Contribute | it's a bug]].
; Does MOSS work on Windows? OS X?
: Not Windows. There is a fair bit of porting work to do. OS X theoretically works but nobody has tried yet. (If you try and it works, let us know!)
; What is the "status" server type?
: MOSS will provide the status string normally fetched from a web server. You do have to make the client send the HTTP request to port 14617 or it won't do much good. This is a feature that perhaps only the author wants.

== Warnings ==

* Please note: The MOSS vault is as insecure as MOUL's. (I don't know what was done to MOULagain.) The MOSS server is almost as trusting of the client as MOUL's. (Or maybe more, in other ways; for example, there is no server-side profanity filter.) This is because a MOUL server was implemented, not some other server. Doing better is definitely possible. But to do it right is a very big project, because the entire ''system'' was designed with this trust model. You can't always change just one part of it to get where you want to be.

* Don't change the .mbm or file server files while you have clients doing File transactions. Doing so will give everything indigestion.

* I'm sure the same applies for .mbam and auth server files.

* The SDL mechanism depends on all servers in the shard having synchronized time. Use NTP if you have more than one server. (You'll also need to NFS mount the game/state directory on all the servers so the age SDL is available to all.)

== Setup Choices ==

* Disabling the client<->server encryption is NOT recommended. However, if you subscribe to the shortsighted idea that protecting your users is not important, go ahead. But be warned, there are code paths in MOSS that are completely untested when all encryption is disabled. You'll have to fix any bugs. (The [[Wireshark Plugin]] does support decrypting connections when you have the key, so you ''can'' use encrypted connections during development/testing.)

* MOSS supports using RSA for key negotiation. The client contribution to the session key is RSA-encrypted with the server public key and then sent to the server, which decrypts the message. Ironically, this actually is less crypto work, while using a non-modified standard encryption technology. And it has the same pseudo-authentication properties as the Cyan-style modified Diffie-Hellman. The assembler changes required for this are astonishingly small, but there's not much value in using RSA. Nonetheless, there's no need to remove working server support for it...

== While Running the Server ==

* You can change age SDL state server-side by modifying the state saved in files in the game/state directory. Keeping backups is advised. You may modify the files with the "sdl_reader" program (which you need to build separately using "make sdl_reader"). This is a very simple command-line program. Use the -l option to specify a saved file to read. When in the program, use the "h" command to see the help. Saving this file while a game server for that age is running is pointless; the new version won't be read and it will be overwritten when the server exits.

== Client Bug Workarounds ==

MOSS works around a few client bugs.

* MOSS "fixes" the KI light bug. It is a bug in the PRP files. MOSS has an extra check for determining whether SDL state is avatar-related, instead of relying on the flag that says whether to keep the SDL state around. That check covers the KI light, so the light SDL is tossed along with the rest of avatar SDL when a person leaves an age.

* MOSS may "fix" the footstep region bug. This bug is when you get the wrong footstep sound stuck, like that wooden bridge you left long ago clumping around while you're on stone. Everyone in the age hears the wrong footstep sounds. I believe that in normal play (that is, without things like /spawn) it is due to a race with the exclusive locking mechanism used to keep things like multiple button presses from being processed at the same time. Why footstep regions take a server-side exclusive lock is beyond me**, so MOSS grants '''all''' footstep region lock requests. This should make the problem occur less frequently, if at all (depending on how the client actually responds to receiving the lock after leaving the region). MOSS decides you are asking for a footstep region lock by looking for the word "Footstep" in the object name. ''Do not name buttons, door regions, or whatever with "Footstep" in your new ages.'' I suggest you do name footstep regions with "Footstep". The special case can be removed by removing <tt>#define GRANT_ALL_FOOTSTEPS</tt> from GameState.cc and recompiling.
:: **In fact, as a friend of mine pointed out, why are footstep sounds decided by the represented avatar's client and propagated to everyone else in the first place? It should be a purely local decision based on the location of each avatar as seen by that client. That would save on traffic and always be accurate, never mind the race with locking on the region since there would be no need to coordinate anything for a purely local decision.

* Quab game Python is not really complete. The first person to link to the age becomes the "owner" of the quab game. The Python sort of attempts to handle the situation where the game owner leaves the age while there are still quabs around, but it does not actually handle it. If the server attempts to pass ownership to someone else, that client will break. And the current MOULagain client even crashes. So MOSS works around the problem by intentionally breaking the whole game when the owner leaves the age and quabs are still present. All the quabs will remain frozen in place until the age has been cleared of all players. The age does not have to restart to revive the game, just be empty.

* The client supports two kinds of passwords, depending on the format of the username. If the username has the format x@x.x it uses algorithm 1 (a more secure one but also one with a fencepost error), and otherwise algorithm 2. Unfortunately the /changepassword command does not know about algorithm 2 and if you logged in with algorithm 2, it will try to change your password hash to the one for algorithm 1. This would result in you being unable to log in. So MOSS rejects requests to change the password if the username does not have the x@x.x format.

== Server Non-Bugs ==

These are problems with Cyan's server that MOSS does not have.

* MOSS does not have the infamous "zero seconds remaining" bug. Thus it is possible to do the auth downloads without the server waiting for acks from the client. This speeds up the download substantially as now the bandwidth can be fully utilized. (The [[MOSS-Setup#configure | --enable-fast-download]] configure option turns this on.)

* The MOUL server has a bug with quabs in Ahnonay. If you are the first person who linked into the age, the quabs are associated with your ID. When you link out of the age, the server is supposed to send a LoadClone message telling other clients to unload your clone (the avatar). The MOUL server sends the message, but it says to unload one of the quabs with your ID in it instead of the player avatar. Oddly, the client seems just fine with that. MOSS does not have this bug.

* You should see less client hitching while moving around with MOSS. The MOUL server sends a ton of node update messages for the (unchanged) city AgeInfo node. Each node update causes the client to fetch your pellet scores. The client is frozen during this (and most any) vault transaction. The MOSS server does not send all those useless updates. Interesting note: One measurement during MOUL was approximately 400 pellet score fetches an hour. That is the client freezing every 9 seconds regardless of what age you are in or how many people are in it or on your buddy list. (The pellet score fetch itself can probably be fixed in the Python but you'd still be wasting time on the city node.)

* The pellet score freeze can be further reduced by #defining <tt>PELLET_SCORE_CACHE</tt>, which does what it sounds like: it caches the client's pellet score in the Auth server to cut out the round-trip time to the DB. However, there's little value to it without the city node update problem; when you open the KI it fetches the score but it's also fetching other vault nodes. Plus you aren't trying to move at the time so the freeze is less obvious. So <tt>PELLET_SCORE_CACHE</tt> is undefined by default, and in fact it is ''untested''.

[[Category:MOSS]]

MOSS/Project Ideas

2011-04-05T07:14:48Z

A'moaca': add Terminology

The initial list was generated over the lengthy period of MOSS's initial
development. These project ideas mostly cover missing functionality. None of
the missing functionality is known to cause gameplay issues so these did not
really seem like bugs. These ideas are grouped by general type of change
required, and sort of by increasing approximate difficulty level and sort of by
decreasing value.

Bigger ideas, such as entirely new functionality now made possible by the
release of the client, could go here too. Be realistic, though. Remember that
protocol changes are not to be made lightly, because it causes an
incompatibility problem. It is probably better to propose large changes in
discussion format on the forums. Do not ''expect'' someone else to take up and
implement your proposal.

The whole idea of this list is to provide some ideas for anyone wishing to dive
into MOSS. Sometimes a little direction helps.

== Terminology ==
The terms "frontend" and "backend" are used throughout this document. If the meaning is not clear from context, the terminology is explained in the [[MOSS-Developer_Notes#terminology | Developer Notes]].

The "vault" is basically the database, though it could be abstractly thought of as a collection of trees of vault nodes. Generally when referring to it as a set of node trees, "vault" is written and when referring to it as something with tables and rows, "DB" is written. The "vault server" is that portion of the backend concerned with handling the Vault* messages and working with the database.

== Fix bugs ==

The bug tracker is here: https://foundry.openuru.org/jira/browse/MOSS

== Detail work (little Uru-specific knowledge required) ==

* Try disabling the Nagle algorithm on sockets. This should result in less latency to the client when small messages are involved. Make sure to test the whole game thoroughly.

* Figure out and implement a good way to use autoconf to compile in default pathnames. This would apply to the default config file, key file, moss_serv binary, and log/auth/game/file directory locations. The idea is if I say --prefix=/foo the defaults become /foo/etc/moss.cfg and so forth instead of ./etc/moss.cfg. Don't forget autoconf lets you override the etcdir, bindir, etc. separately.

* Treat SDL filenames case-insensitively. This is very annoying in Unix, since it requires using readdir() and strcasecmp() instead of just open().

* Make it so the game/state directory location can be separately configured. This is so the whole MOSS install can be read-only and just the log directory and game/state moved somewhere read-write. (The easy workaround is to symlink a writable directory to game/state.)

* Log the PID of all forked servers in moss.log.

* See if we can switch to libevent for inter-thread communication instead of raw signals. This should be fairly portable and take advantage of the different per-OS lightweight signalling mechanisms.

* Allow ''skipping'' overlong messages (messages MOSS thinks are too big). This requires, upon catching the exception, tossing out the message, and if it has not all been read in yet, keeping track of how much more to toss in the future. The RC4 state must be updated too for the tossed message length.

* It would be nice to use atomic operations for refcounts instead of having to use (bigger, slower) mutexes for them. This does make MOSS not architecture-independent, which is part of why I have been resisting it. (See also signal handling next.)

* Signal handlers and the operations to read and reset the values in the main loops should be using atomic operations.

* Catch and handle std::bad_alloc whenever possible.

== Fairly contained changes ==

* Make it so game servers can be forked as separate processes. This helps a lot for debugging and also would help for age development, making it easier to change SDL and retest. Otherwise you have to shut down the whole frontend server or wait out the age's linger time. This work was started but not completed, and that code can be found inside <tt>FORK_GAME_TOO</tt> #ifdefs. If you do this, I suggest you consider separating <tt>FORK_GAME_TOO</tt> from <tt>FORK_ENABLE</tt> so that one could have forked game servers and *not* forked auth/file servers.

* In the getpublicagelist() SQL function, there is a comment about the 50-hood limit. The current code returns the first 50 hoods. We should return the most recently used 50 hoods. The hard part is knowing which those are. This is mostly if not wholly DB/SQL work.

* Age population limits are unimplemented. The value is in the vault, but the server does not look at it.

* Figure out how to throw out clones and SDL when a player leaves the age. Please see the "clean up clone, SDL" section in GameServer::conn_shutdown(). Right now this is full of special cases: it handles the Kemo bugs and and Quabs specially (a different thing for each). It may be that this is required for best behavior, but I still feel like I've missed something despite heavy scrutiny of the data. This is more of a research project and not much of a code project.

* MOUL parsed SDL nodes on the way into the vault. It probably only updated the node with fields having the Dirty bit set. In addition it added timestamps to the fields because the client does not put in the timestamps (reasonably so, as its time may be wrong). MOSS currently saves the SDL wholesale. This basically works, but with the timestamps properly added, the game server can merge the vault, age, and global SDL in any order and without strange rules. Note: if you do this, you also need to write a script or some other way to update all the SDL nodes in existing MOSS DBs.

* The kickable SDL filtering algorithm is the same one I put in Alcugs ages ago. It is better than nothing but not as good as Plasma's. You will see more warping of kickables than with Cyan's server. This project is to come up with a better way of deciding what physical SDL to send to all the clients, based on those messages all the clients are sending to the server.

* The server is probably supposed to use RelevanceRegion information to avoid sending SDL updates to clients who don't share a relevance region with the originating client. (The idea being to reduce network traffic, since hopefully the client already avoids rendering/physics on things in irrelevant regions.) Things work if the server doesn't filter, so MOSS doesn't. Also, I do not have strong evidence to believe this supposition is actually correct. Which is the other reason MOSS doesn't do it. Finding out, and implementing it if so, would be a nice project.

* Figure out what the server is supposed to do with plSetNetGroupIDMsg and do it. Right now MOSS just drops it to no apparent ill effect. I am deeply suspicious of this message due to seeing it at aurally unpleasant times in UU. (Old, old notes: "may have to do with infinitely looping scraping noises".)

* <tt>kCli2Auth_SendFriendInviteRequest</tt> is not fully supported (it is dropped on the floor).

== Bigger changes ==

* The following messages are unimplemented.
** <tt>kCli2Auth_VaultSetSeen</tt> -- unimplemented in client
** <tt>kCli2Auth_ScoreDelete</tt> -- never saw one, so couldn't implement it
** <tt>kCli2Auth_ScoreSetPoints</tt> -- never saw one, so couldn't implement it
** <tt>kCli2Auth_ScoreGetRanks</tt> -- never saw one, so couldn't implement it
** <tt>kCli2Csr_PingRequest</tt> -- no recorded Csr messages
** <tt>kCli2Csr_RegisterRequest</tt>
** <tt>kCli2Csr_LoginRequest</tt>
** <tt>kCsr2Cli_PingReply</tt>
** <tt>kCsr2Cli_RegisterReply</tt>
** <tt>kCsr2Cli_LoginReply</tt>

* Add hood randomization to DRC hoods. Player-created hoods are randomized by the Python in the Nexus when the hood is created. DRC hoods, however, are created by the server. In MOSS's case, they are created entirely by SQL code. So adding DRC hood randomization means noticing when the DB has created a new DRC hood, creating and modifying SDL in the backend, and then finding and modifying the age SDL node for that new hood. All before responding to the client creating the new avatar and thus the new DRC hood.

* The MessageQueue class has a concept of priorities. The idea was to enable dropping of lower-priority messages if a queue to a given client starts to back up. (The lowest priority being voice chat, then avatar movements, with world state changes being highest.) The measurement of queue length or throughput necessary for that is not implemented. So, neither is the dropping. (There is the very beginnings of some if <tt>DO_PRIORITIES</tt> is #defined.) As such, queue users don't do a good job of priority-setting, although VOICE and FRONT are properly used. The idea wasn't to order the queue (except for FRONT), but to skip sending, say, a VOICE message when we encounter one, if the queue congestion measure says to.

* '''Vault security'''
: The MOSS vault is as insecure as the MOUL vault. Need I say more? Here are some starter thoughts.
:* MOSS should parse incoming SDL messages and sanity-check them. See also [[#SDL_timestamps | adding timestamps]].
:* MOSS could probably verify other blob contents too.
:* Anyone can save anything to any node, and can fetch any node if they know its type and ID. We can deny these requests if the user shouldn't have access. Possibly [[MOSS-Developer_Notes#notifier | the notifier field]] can help.
:* Much more, I'm sure. Better vault security ''is'' possible.

* Eliminate excessive byteswapping of opaque server IDs in BackendMessages. This is to say, in the backend server, when reading in the messages, it byte-swaps the IDs to store them, only ever uses them in equality tests with other IDs, and then byte-swaps them back when sending new messages. (On a little-endian box there's no swapping so it does not cost much, but it's the principle of the matter.) Unfortunately this really needs to be tested on a big-endian machine.

* Try changing the File server to do [[MOSS-Setup#ackless | ackless downloads]], too. Maybe only if there is only one download at a time, though.

== Scalability issues ==

Performance and scalability are always interesting questions. And frequently ignored, because they only matter for larger installations.

These are ideas unimplemented because they only really matter for large
shards. Large as in having, let's say, 50+ concurrent '''busy''' users. (50
people standing in the city chatting doesn't actually do much.) Maybe MOSS is
okay with that number now, in which case "large" is more. It is entirely
unknown.

* Performance testing. Instrumentation. There should be a load generator to do this. This was not high on the list during development, with a user base of 3.

* See the last paragraph in the comments at the top of FileTransaction.h about how multiple file transactions of the same file should share a single opened file.

* Allow speculative pre-caching of AgeInfoNodes and PlayerInfoNodes when node changed notifications come from the vault server and are forwarded to any connected client. Cache in the auth server, vault server, or both. The goal is to reduce latency on those requests the client freezes for.

* The backend protocol supports game servers requesting batches of GameMgr IDs. However, there is no code on either side to actually do so. The idea for this was that more populated ages, like the city, would benefit from doing batch requests. Every person who links in with a marker game needs a new global game ID, and it would be nice to cut out any extra backend round trips for links, even though this particular round trip does not block the link process (aside from being something the backend is doing when it could be doing something else).

* Database performance could be measured and the SQL or even tables optimized.

* MOSS currently uses a single blocking connection to the DB. Implement and investigate performance of multiple DB connections, or asynchronous ones. Maybe the backend server has to become threaded to gain the best advantage.

* In a big shard, we may need to split the backend server work up. The [[MOSS-Developer_Notes#backend_typecodes | backend protocol]] is designed to support separating backend work between threads. The "classes" of backend messages in a bitfield are meant as a way to quickly route a backend message to an appropriate backend thread or process.

== Frontend/backend interactions ==

* Add encryption to the backend protocol. This itself is not a big deal (though you have to pick a good key negotiation, and do not forget to consider authentication mechanisms), but it does mean all the BackendMessage fill_buffer() code paths would be newly exercised, so a lot of regression testing would be in order.

* It would be much easier on the DB if updates to markers are batched by the game server. This especially applies to capturing markers. See the comments in the setmarkerto() and startmarkergame() SQL functions.

* The backend protocol allows for frontends hosting ages to specify only a subset of ages that can be hosted there. This is unused right now; the message has a field saying, "this is the length of the following age restriction list" and it is always zero. When there are no restrictions the backend can request any frontend to host any age.
** The need for splitting hostable ages is unclear, but in a very large shard you might, for example, put all city instances, or even only the public one, on a separate server. It would also allow someone to join a shard and host just their own age, or whatever.
** Since the frontend never sends restrictions, the backend currently has no way to store and use them. So there is work on both sides.
** Presumably which ages a frontend server can host would be a configuration option but it could be done instead by restricting the contents of the game/age directory. That would not allow even finer-grained restrictions, but this whole project kind of needs a real use case to flesh out what is needed.

* Having one backend TCP connection per frontend server is probably not a good thing, in terms of efficiency, or of scalability with a cluster of machines. We could change it to have one backend connection per frontend ''process'' and funnel everything through it. The mostly-implemented but unused and untested MultiWriterMessageQueue was meant, in part, to support this (there are multiple threads writing, but only one thread reading, which writes to the socket).

: Then when messages are received in the frontend there needs to be some way of passing the message to the right thread and signaling them something is present to be handled. This is all unimplemented but the format of the backend messages is meant to take care of this case (in particular, the two "server IDs" in the header are for dispatching messages to the correct thread).

: However, essentially the same changes would be necessary if the backend server is folded into the main server so there is only one process; then "sending" messages to the backend server is just putting them on the (shared) queue that would have been used to funnel everything through one connection, and "receiving" them is just taking them off that queue since there's no TCP connection to deal with.

== New functionality ==

* I am guessing Cyan's server handles the GameMgr stuff with server-side scripting. At the time MOSS was implemented there was no expectation that new game types may be added so adding in a scripting language was not worth the problems incumbent with doing so. Also the overall value of scripting is not clear (especially for the cost in server complication). However, it could be done. The project would have to include embedding the scripting and then rewriting stuff using scripts.
: Please note, a lot of effort went into getting the Heek right, handling ties, allowing people to accidentally stand up and sit back down in the game, and probably other details I forgot. If you want to script Heek, it really ought to still work as well.

* Really adventurous hardcore project: destroy KI hacks. The server would have to be able to analyze all game traffic to decide whether it looks okay. To do it right the server would have to have and understand PRP files and do physics. Also "console" commands have to be wisely filtered. If you're daunted, join the club.

== Redesigns ==
{{tba}}

[[Category:MOSS]]

MOSS/Developer Notes

2011-04-05T07:06:21Z

A'moaca': /* Implementation Choices */ add anchor

Comments of interest to those working with the MOSS code should go here. If
you plan to just run a server and not modify it, you don't need to be here.

== Working with the Code ==

=== Requirements ===

* Handle byte-swapping. A networking person wrote MOSS, and such people care about working with both endiannesses. Do not break it.

* This does mean you cannot drop in someone else's code handling the MOUL protocol if it assumes you are using a little-endian machine. This is '''the''' reason for not casting incoming byte data to structs and writing out structs.

* Including "config.h" should always look like this:
#ifdef HAVE_CONFIG_H
#include "config.h"
#endif

=== Code Conventions ===

* Keep C++-style comments out of preprocessor lines.

* Keep code to 78 columns whenever possible.

* Include (.h) files have comments at the top listing which other include files are required before including this file. (Some may be missing but I tried.)

* I use emacs. Please keep the <tt>/* -*- c++ -*- */</tt> at the top of .h files if they are indeed C++. Feel free to add similar magic for your editor.

* Please match indentation, spacing, and brace styles, etc. (It is the default "gnu" style in emacs.)

* Limit direct including of other include files in .h files. I don't remember why, but it's the project's convention. (It does help with dependencies sometimes.)

=== Advice ===

* If you add a client message type, make sure to add it to check_useable(). Otherwise the server will toss the message and drop the client.

* If you add a client message type, test compiling with the --enable-old-protocol=yes configure option set. You don't need to run it, just compile it. The purpose of the compile test is to make sure that your new message is not referred to when using the older protocols, unless it's supposed to be. If the new message did not exist at all in these older protocols, code referring to them won't compile, and that needs to be fixed.

* When handling byte-swapping, never assign the result of readNNle() to a larger variable. This is wrong. Consider a 16-bit little-endian number with two bytes ''XY'', represented as <tt>YX</tt>. read16le() returns <tt>YX</tt>, and assigned to a 32-bit number on a big-endian system, the result is <tt>00YX</tt>. A 32-bit little-endian number of value ''XY'' is '''correctly''' represented as <tt>YX00</tt>. Assigning the result of readNN() is fine, as that value is in host order. Similarly you can't writeNNle() a number stored in a smaller type, but this is a harder mistake to make.

* As a corollary, don't save anything explicitly kept little-endian in anything other than a sized int type. Don't use size_t, enum types, or anything along those lines. Especially not size_t.

* Remember that protocol changes are not to be made lightly, because it causes an incompatibility problem.

* Be very, very, careful about any changes to game server startup code in the backend. Triple-check all the logic (or more). Do not forget to take into account the client disconnecting/timing out after the request, the game server never starting, the game server shutting down as the request arrives, and everything in between.

* Before writing new DB query code or changing how current ones work, make sure to read up on the [http://pqxx.org/devprojects/libpqxx/doc/stable/html/Tutorial/ch03s07.html pqxx transactor model].

* There is a reftree.sql file in the test directory. If you are working with the DB and need a view into the trees of data the change notification routines are working with, you may find this file useful. Load it into the DB, and it adds a "reftree" function which, given a node, will generate a list of the whole tree below it by following the noderefs. The output includes node and folder type '''names''' and the information used to determine where change notifications have to be sent.

== Implementation Choices ==

Oftentimes, in a hobbyist project such as MOSS was in the beginning, there is not a lot of design documentation. MOSS had some, but most of it became obsolete as goals changed. Here are some short descriptions answering some "Why did you do it this way?" questions.

Terminology used here: the "backend" server is that process named moss_backend, which talks to the DB and handles anything needing centralized management, while "frontend" servers are everything else (auth/file/game/gatekeeper servers talking to the client, and the dispatcher listening for connections). The "backend protocol" is the protocol used between the frontend and backend servers.

; Why is there all this read32/read32le stuff?
: [[#Requirements | A networking person wrote MOSS.]] readNN() byte-swaps a little-endian value (from the protocol on the wire) to host order. writeNN() byte-swaps from host to little-endian. If you run it on a little-endian box this is a no-op. readNNle() ''doesn't'' byte-swap, returning a number of size NN in little-endian order. If you run it on a little-endian box this is a no-op. On a big-endian box these are critical. In addition, these macros/functions handle hardware that does not allow unaligned access of memory locations. At the time of release, MOSS appeared to work correctly on big-endian machines.

; Why are there two ways to write every message?
: For larger messages, the writev() syscall is considered more efficient, because less data has to be copied when crossing the user/kernel memory boundary. In other words, you save one copy of the entire contents of what you write at the price of computing and copying the set of iovecs. However, writev() won't work when you have to encrypt the data first, so for encrypted connections we have to copy the data into a buffer and then encrypt it.

; Why do the backend message classes have "little-endian" comments all over?
: The backend protocol is handled somewhat differently in MOSS. For frontend servers, any data read in and used by the server is stored in host order. But for the backend messages, the data is mostly stored in ''little-endian'' order, because the protocol is (currently!) unencrypted and I can use writev() and skip copying into a buffer. For many messages, writev() may not be better than copying, because the iovec is bigger than the data it represents. On the other hand, the actual copy into the buffer is avoided. The performance of each approach is unknown. There is no MessageQueue support for mixing the iovec and buffer strategies in a single queue based on message type.

; Why do you use a single-threaded big select loop for each game server?
: The other typical strategy would be to have a thread per client and pass messages between threads. The MultiWriterMessageQueue class was originally intended to cover that case (in addition to [[MOSS-Project_Ideas#connection_merging | others]]). But the fundamental problem with this plan is that I did not have a good portable way to wake up threads when a message is queued. It can be done, but signals are probably not the way to do it.

; Speaking of signals, why do you use them between threads instead of epoll()?
: I don't have epoll() on my development machine. Signals are the most portable. [[MOSS-Project_Ideas#libevent | Replacing the use of signals + select() with libevent]] might be the right answer because part of its goal is to work on many OSes.

; Explain the funky backend protocol numbering scheme?
: The protocol was designed to facilitate using multiple processes or servers in the backend. Thus messages have a bitmask "class" which would allow them to be quickly routed to the right location by checking the bitmask, rather than having a giant case statement to decide.

: Then, I wanted the pairs of messages to be recognizable from the number, so a message TO the backend is numbered the same the corresponding message FROM the backend, with the addition of a bit to mark which direction the message is going. Since each server knows its own identity, this bit is basically a big favor for the Wireshark dissector. Trust me, it's really nice.

: Finally, because once upon a time I knew many messages by their number, I assigned backend messages the same number as a corresponding frontend (client) message. When it made sense. We don't need to do this going forward, but we aren't allowed to change the current ones.

: There are some bits in the middle "left over". Maybe someone will need them for something creative someday!

; Why did you choose [http://www.postgresql.org/ PostgreSQL]?
: There were not a lot of differentiators between it and MySQL. But, PostgreSQL provides "triggers" -- this is a way to request that when a table is changed, the DB tells anything subscribed to the triggers about the change. I was intrigued by them, and thought they could prove useful for providing the vault node update notifications to clients (VaultNodeChanged/VaultNodeAdded/VaultNodeDeleted). Unfortunately, doing this ended up requiring at least two connections to the DB, one like the current one, and another to listen for triggers. So triggers were not used in the interest of simplicity in the backend server. Nothing else is preventing their use.

; What is up with this giant DB schema!
: First, it was a conscious decision to put as much SQL code as possible into stored procedures. This makes it so you can modify the DB functionality without recompiling the server, and it reduces the amount of data you have to push over the socket.

: The single giant table as seen in PotS, UU, and to some extent (how much exactly is unknown) MOUL/MOULa is so hard to work with. And it has scalability, relations, and clarity built right out of it. We were thinking of how to split the database load up to help with the bottleneck the DB still proved to be in MOUL. While no implementation was done for that (realistic expectations of MOSS suggest it is not needed), this did lead to the decision to experiment with splitting the table up into many tables by node type.

: There's no way to know if these design choices are more efficient, without changing the design, implementing it, and comparing the performance of the two in a like-for-like way. But it sure is a lot easier to write queries with the stored procedures and tables by node type!

; What is this new "notifier" thing in the noderefs table?
: It is the answer to the question "How do I know which client to tell about changes to this reference or referred-to node?"

: After drawing many pictures of node trees, it became clear that the "owner", coming from the client, was mostly but not really right for this. I was left with the impression that's what the "owner" field is for... but since it wasn't what I wanted I added a new one. For player trees, the notifier is the player. For age trees, it's the age, and then the DB looks up what players are interested in that age.

: I do not know how Cyan solved the problem, but this was the way to push the decision about who to tell into the DB where most of the data is. Otherwise, the backend (vault) server would have to cache all the active trees itself in order to find the answer.

; Why did you make the SDL files be in a directory tree instead of a single directory?
: The goal was to improve the age development experience. If the server loads all the SDL at startup, and you want to change the SDL because you have a new version to test, you have to restart the server. If instead, a given age's SDL is loaded at the time the game server starts up, you only need to restart the game server. I then put the files common to all ages in a "common" directory so that it is loaded once, and the data can be shared between game servers, but that is just a small optimization. If users have serious issues with this they can put ''all'' the SDL files in the common subdirectory.

; Why .mbm and .mbam files?
: I did not want the server to have to stat and checksum files all the time. File and auth files don't change much.

; Why didn't you put Python in to script Heek?
: I suspect Cyan did this. I am not a fan of embedding scripting where it is not needed, and at the time I had no reason to believe there would ever be new GameMgr types requiring the kind of dynamic rapid development that embedded scripting is good for. Still, it's in the [[MOSS-Project_Ideas#scripting | project ideas]] for those who are into that sort of thing.

== Project Ideas ==

The whole idea of this list is to provide some ideas for anyone wishing to dive
into MOSS. Sometimes a little direction helps. See [[MOSS-Project_Ideas]]. Of
course, you are not limited to this list!

[[Category:MOSS]]

MOSS/Developer Notes

2011-04-05T07:05:16Z

A'moaca': /* Advice */ clarify --enable-old-protocol compile test

Comments of interest to those working with the MOSS code should go here. If
you plan to just run a server and not modify it, you don't need to be here.

== Working with the Code ==

=== Requirements ===

* Handle byte-swapping. A networking person wrote MOSS, and such people care about working with both endiannesses. Do not break it.

* This does mean you cannot drop in someone else's code handling the MOUL protocol if it assumes you are using a little-endian machine. This is '''the''' reason for not casting incoming byte data to structs and writing out structs.

* Including "config.h" should always look like this:
#ifdef HAVE_CONFIG_H
#include "config.h"
#endif

=== Code Conventions ===

* Keep C++-style comments out of preprocessor lines.

* Keep code to 78 columns whenever possible.

* Include (.h) files have comments at the top listing which other include files are required before including this file. (Some may be missing but I tried.)

* I use emacs. Please keep the <tt>/* -*- c++ -*- */</tt> at the top of .h files if they are indeed C++. Feel free to add similar magic for your editor.

* Please match indentation, spacing, and brace styles, etc. (It is the default "gnu" style in emacs.)

* Limit direct including of other include files in .h files. I don't remember why, but it's the project's convention. (It does help with dependencies sometimes.)

=== Advice ===

* If you add a client message type, make sure to add it to check_useable(). Otherwise the server will toss the message and drop the client.

* If you add a client message type, test compiling with the --enable-old-protocol=yes configure option set. You don't need to run it, just compile it. The purpose of the compile test is to make sure that your new message is not referred to when using the older protocols, unless it's supposed to be. If the new message did not exist at all in these older protocols, code referring to them won't compile, and that needs to be fixed.

* When handling byte-swapping, never assign the result of readNNle() to a larger variable. This is wrong. Consider a 16-bit little-endian number with two bytes ''XY'', represented as <tt>YX</tt>. read16le() returns <tt>YX</tt>, and assigned to a 32-bit number on a big-endian system, the result is <tt>00YX</tt>. A 32-bit little-endian number of value ''XY'' is '''correctly''' represented as <tt>YX00</tt>. Assigning the result of readNN() is fine, as that value is in host order. Similarly you can't writeNNle() a number stored in a smaller type, but this is a harder mistake to make.

* As a corollary, don't save anything explicitly kept little-endian in anything other than a sized int type. Don't use size_t, enum types, or anything along those lines. Especially not size_t.

* Remember that protocol changes are not to be made lightly, because it causes an incompatibility problem.

* Be very, very, careful about any changes to game server startup code in the backend. Triple-check all the logic (or more). Do not forget to take into account the client disconnecting/timing out after the request, the game server never starting, the game server shutting down as the request arrives, and everything in between.

* Before writing new DB query code or changing how current ones work, make sure to read up on the [http://pqxx.org/devprojects/libpqxx/doc/stable/html/Tutorial/ch03s07.html pqxx transactor model].

* There is a reftree.sql file in the test directory. If you are working with the DB and need a view into the trees of data the change notification routines are working with, you may find this file useful. Load it into the DB, and it adds a "reftree" function which, given a node, will generate a list of the whole tree below it by following the noderefs. The output includes node and folder type '''names''' and the information used to determine where change notifications have to be sent.

== Implementation Choices ==

Oftentimes, in a hobbyist project such as MOSS was in the beginning, there is not a lot of design documentation. MOSS had some, but most of it became obsolete as goals changed. Here are some short descriptions answering some "Why did you do it this way?" questions.

Terminology used here: the "backend" server is that process named moss_backend, which talks to the DB and handles anything needing centralized management, while "frontend" servers are everything else (auth/file/game/gatekeeper servers talking to the client, and the dispatcher listening for connections). The "backend protocol" is the protocol used between the frontend and backend servers.

; Why is there all this read32/read32le stuff?
: [[#Requirements | A networking person wrote MOSS.]] readNN() byte-swaps a little-endian value (from the protocol on the wire) to host order. writeNN() byte-swaps from host to little-endian. If you run it on a little-endian box this is a no-op. readNNle() ''doesn't'' byte-swap, returning a number of size NN in little-endian order. If you run it on a little-endian box this is a no-op. On a big-endian box these are critical. In addition, these macros/functions handle hardware that does not allow unaligned access of memory locations. At the time of release, MOSS appeared to work correctly on big-endian machines.

; Why are there two ways to write every message?
: For larger messages, the writev() syscall is considered more efficient, because less data has to be copied when crossing the user/kernel memory boundary. In other words, you save one copy of the entire contents of what you write at the price of computing and copying the set of iovecs. However, writev() won't work when you have to encrypt the data first, so for encrypted connections we have to copy the data into a buffer and then encrypt it.

; Why do the backend message classes have "little-endian" comments all over?
: The backend protocol is handled somewhat differently in MOSS. For frontend servers, any data read in and used by the server is stored in host order. But for the backend messages, the data is mostly stored in ''little-endian'' order, because the protocol is (currently!) unencrypted and I can use writev() and skip copying into a buffer. For many messages, writev() may not be better than copying, because the iovec is bigger than the data it represents. On the other hand, the actual copy into the buffer is avoided. The performance of each approach is unknown. There is no MessageQueue support for mixing the iovec and buffer strategies in a single queue based on message type.

; Why do you use a single-threaded big select loop for each game server?
: The other typical strategy would be to have a thread per client and pass messages between threads. The MultiWriterMessageQueue class was originally intended to cover that case (in addition to [[MOSS-Project_Ideas#connection_merging | others]]). But the fundamental problem with this plan is that I did not have a good portable way to wake up threads when a message is queued. It can be done, but signals are probably not the way to do it.

; Speaking of signals, why do you use them between threads instead of epoll()?
: I don't have epoll() on my development machine. Signals are the most portable. [[MOSS-Project_Ideas#libevent | Replacing the use of signals + select() with libevent]] might be the right answer because part of its goal is to work on many OSes.

; Explain the funky backend protocol numbering scheme?
: The protocol was designed to facilitate using multiple processes or servers in the backend. Thus messages have a bitmask "class" which would allow them to be quickly routed to the right location by checking the bitmask, rather than having a giant case statement to decide.

: Then, I wanted the pairs of messages to be recognizable from the number, so a message TO the backend is numbered the same the corresponding message FROM the backend, with the addition of a bit to mark which direction the message is going. Since each server knows its own identity, this bit is basically a big favor for the Wireshark dissector. Trust me, it's really nice.

: Finally, because once upon a time I knew many messages by their number, I assigned backend messages the same number as a corresponding frontend (client) message. When it made sense. We don't need to do this going forward, but we aren't allowed to change the current ones.

: There are some bits in the middle "left over". Maybe someone will need them for something creative someday!

; Why did you choose [http://www.postgresql.org/ PostgreSQL]?
: There were not a lot of differentiators between it and MySQL. But, PostgreSQL provides "triggers" -- this is a way to request that when a table is changed, the DB tells anything subscribed to the triggers about the change. I was intrigued by them, and thought they could prove useful for providing the vault node update notifications to clients (VaultNodeChanged/VaultNodeAdded/VaultNodeDeleted). Unfortunately, doing this ended up requiring at least two connections to the DB, one like the current one, and another to listen for triggers. So triggers were not used in the interest of simplicity in the backend server. Nothing else is preventing their use.

; What is up with this giant DB schema!
: First, it was a conscious decision to put as much SQL code as possible into stored procedures. This makes it so you can modify the DB functionality without recompiling the server, and it reduces the amount of data you have to push over the socket.

: The single giant table as seen in PotS, UU, and to some extent (how much exactly is unknown) MOUL/MOULa is so hard to work with. And it has scalability, relations, and clarity built right out of it. We were thinking of how to split the database load up to help with the bottleneck the DB still proved to be in MOUL. While no implementation was done for that (realistic expectations of MOSS suggest it is not needed), this did lead to the decision to experiment with splitting the table up into many tables by node type.

: There's no way to know if these design choices are more efficient, without changing the design, implementing it, and comparing the performance of the two in a like-for-like way. But it sure is a lot easier to write queries with the stored procedures and tables by node type!

; What is this new "notifier" thing in the noderefs table?
: It is the answer to the question "How do I know which client to tell about changes to this reference or referred-to node?"

: After drawing many pictures of node trees, it became clear that the "owner", coming from the client, was mostly but not really right for this. I was left with the impression that's what the "owner" field is for... but since it wasn't what I wanted I added a new one. For player trees, the notifier is the player. For age trees, it's the age, and then the DB looks up what players are interested in that age.

: I do not know how Cyan solved the problem, but this was the way to push the decision about who to tell into the DB where most of the data is. Otherwise, the backend (vault) server would have to cache all the active trees itself in order to find the answer.

; Why did you make the SDL files be in a directory tree instead of a single directory?
: The goal was to improve the age development experience. If the server loads all the SDL at startup, and you want to change the SDL because you have a new version to test, you have to restart the server. If instead, a given age's SDL is loaded at the time the game server starts up, you only need to restart the game server. I then put the files common to all ages in a "common" directory so that it is loaded once, and the data can be shared between game servers, but that is just a small optimization. If users have serious issues with this they can put ''all'' the SDL files in the common subdirectory.

; Why .mbm and .mbam files?
: I did not want the server to have to stat and checksum files all the time. File and auth files don't change much.

; Why didn't you put Python in to script Heek?
: I suspect Cyan did this. I am not a fan of embedding scripting where it is not needed, and at the time I had no reason to believe there would ever be new GameMgr types requiring the kind of dynamic rapid development that embedded scripting is good for. Still, it's in the [[MOSS-Project_Ideas#scripting | project ideas]] for those who are into that sort of thing.

== Project Ideas ==

The whole idea of this list is to provide some ideas for anyone wishing to dive
into MOSS. Sometimes a little direction helps. See [[MOSS-Project_Ideas]]. Of
course, you are not limited to this list!

[[Category:MOSS]]

MOSS/Notes

2011-04-05T06:57:36Z

A'moaca': /* Questions */ add missing step

This page just holds various notes about running a MOSS server.

== Questions ==

I can't really call this a FAQ until the questions have been asked frequently.

; How do I add a user?
: [[MOSS-Setup#Create_Accounts]]
; How do I change the Python?
: Start with the source Cyan has generously provided us under the GPL. To compile that source you'll have to add in the glue. Maybe there is a tool do that in the CWE source. Make your changes. After compiling and creating the .pak (another tool?), copy the .pak to the [[MOSS-Setup#Auth_Server_Data | correct server directory]] and encrypt it. Make a new .mbam file.
; How do I add a new age?
: Copy the encrypted .pak to the [[MOSS-Setup#Auth_Server_Data | correct server directory]], add the file to the Python.txt, and make a new .mbam file. Copy any SDL files to the auth SDL directory and encrypt them. Add them to SDL.txt and make a new .mbam file. Copy unencrypted SDL files to the [[MOSS-Setup#Game_Server_Data | correct server directory]]. Note if you have more than one SDL file for your age, or the file is not named the same as the age, you'll need to put the age's SDL file(s) in a directory named after the age. Copy the unencrypted .age file to the game server directory.
; Why would I use --enable-fork?
: This is primarily useful for testing. It's easier to debug a non-threaded process.
; What resource limitations are there (file descriptors, memory, etc.)?
: This is a question that's not obvious to answer. But here is what is known:
:* Currently MOSS uses about 5 file descriptors when idle. It uses about 10 per connected user. (4 are for the game server, so if the user links around a lot, it will be more, and if you have multiple users in one age it will be less.) If you are running a large shard, you may need to adjust per-process file descriptor limits (see the "ulimit" command) or even kernel (global) limits. If you adjust the global limit, pay attention to <tt>FD_SETSIZE</tt>. See the select() man page.
:* Currently MOSS uses 7 big buffers for network data per connected user. The buffer size is set by <tt>BUFSIZE</tt> in constants.h. The default is 64k, so a total of 448k per user. If you have enough users that your moss processes grow too large you can reduce the <tt>BUFSIZE</tt>.
:* There is not a lot of disk I/O, except for whatever the database has to write. If you set the log levels very low (DEBUG or worse, MSGS) then there will be a lot of I/O for log files.
; Does MOSS work on my Power PC?
: It is supposed to! Testing of big-endian systems was done, but not a full, complete run-through of all game mechanics and multiplayer testing. If it does not work, [[MOSS#How_to_Contribute | it's a bug]].
; Does MOSS work on Windows? OS X?
: Not Windows. There is a fair bit of porting work to do. OS X theoretically works but nobody has tried yet. (If you try and it works, let us know!)
; What is the "status" server type?
: MOSS will provide the status string normally fetched from a web server. You do have to make the client send the HTTP request to port 14617 or it won't do much good. This is a feature that perhaps only the author wants.

== Warnings ==

* Please note: The MOSS vault is as insecure as MOUL's. (I don't know what was done to MOULagain.) The MOSS server is almost as trusting of the client as MOUL's. (Or maybe more, in other ways; for example, there is no server-side profanity filter.) This is because a MOUL server was implemented, not some other server. Doing better is definitely possible. But to do it right is a very big project, because the entire ''system'' was designed with this trust model. You can't always change just one part of it to get where you want to be.

* Don't change the .mbm or file server files while you have clients doing File transactions. Doing so will give everything indigestion.

* I'm sure the same applies for .mbam and auth server files.

* The SDL mechanism depends on all servers in the shard having synchronized time. Use NTP if you have more than one server. (You'll also need to NFS mount the game/state directory on all the servers so the age SDL is available to all.)

== Setup Choices ==

* Disabling the client<->server encryption is NOT recommended. However, if you subscribe to the shortsighted idea that protecting your users is not important, go ahead. But be warned, there are code paths in MOSS that are completely untested when all encryption is disabled. You'll have to fix any bugs. (The [[Wireshark Plugin]] does support decrypting connections when you have the key, so you ''can'' use encrypted connections during development/testing.)

* MOSS supports using RSA for key negotiation. The client contribution to the session key is RSA-encrypted with the server public key and then sent to the server, which decrypts the message. Ironically, this actually is less crypto work, while using a non-modified standard encryption technology. And it has the same pseudo-authentication properties as the Cyan-style modified Diffie-Hellman. The assembler changes required for this are astonishingly small, but there's not much value in using RSA. Nonetheless, there's no need to remove working server support for it...

== While Running the Server ==

* You can change age SDL state server-side by modifying the state saved in files in the game/state directory. Keeping backups is advised. You may modify the files with the "sdl_reader" program (which you need to build separately using "make sdl_reader"). This is a very simple command-line program. Use the -l option to specify a saved file to read. When in the program, use the "h" command to see the help. Saving this file while a game server for that age is running is pointless; the new version won't be read and it will be overwritten when the server exits.

== Client Bug Workarounds ==

MOSS works around a few client bugs.

* MOSS "fixes" the KI light bug. It is a bug in the PRP files. MOSS has an extra check for determining whether SDL state is avatar-related, instead of relying on the flag that says whether to keep the SDL state around. That check covers the KI light, so the light SDL is tossed along with the rest of avatar SDL when a person leaves an age.

* MOSS may "fix" the footstep region bug. This bug is when you get the wrong footstep sound stuck, like that wooden bridge you left long ago clumping around while you're on stone. Everyone in the age hears the wrong footstep sounds. I believe that in normal play (that is, without things like /spawn) it is due to a race with the exclusive locking mechanism used to keep things like multiple button presses from being processed at the same time. Why footstep regions take a server-side exclusive lock is beyond me**, so MOSS grants '''all''' footstep region lock requests. This should make the problem occur less frequently, if at all (depending on how the client actually responds to receiving the lock after leaving the region). MOSS decides you are asking for a footstep region lock by looking for the word "Footstep" in the object name. ''Do not name buttons, door regions, or whatever with "Footstep" in your new ages.'' I suggest you do name footstep regions with "Footstep". The special case can be removed by removing <tt>#define GRANT_ALL_FOOTSTEPS</tt> from GameState.cc and recompiling.
:: **In fact, as a friend of mine pointed out, why are footstep sounds decided by the represented avatar's client and propagated to everyone else in the first place? It should be a purely local decision based on the location of each avatar as seen by that client. That would save on traffic and always be accurate, never mind the race with locking on the region since there would be no need to coordinate anything for a purely local decision.

* Quab game Python is not really complete. The first person to link to the age becomes the "owner" of the quab game. The Python sort of attempts to handle the situation where the game owner leaves the age while there are still quabs around, but it does not actually handle it. If the server attempts to pass ownership to someone else, that client will break. And the current MOULagain client even crashes. So MOSS works around the problem by intentionally breaking the whole game when the owner leaves the age and quabs are still present. All the quabs will remain frozen in place until the age has been cleared of all players. The age does not have to restart to revive the game, just be empty.

* The client supports two kinds of passwords, depending on the format of the username. If the username has the format x@x.x it uses algorithm 1 (a more secure one but also one with a fencepost error), and otherwise algorithm 2. Unfortunately the /changepassword command does not know about algorithm 2 and if you logged in with algorithm 2, it will try to change your password hash to the one for algorithm 1. This would result in you being unable to log in. So MOSS rejects requests to change the password if the username does not have the x@x.x format.

== Server Non-Bugs ==

These are problems with Cyan's server that MOSS does not have.

* MOSS does not have the infamous "zero seconds remaining" bug. Thus it is possible to do the auth downloads without the server waiting for acks from the client. This speeds up the download substantially as now the bandwidth can be fully utilized. (The [[MOSS-Setup#configure | --enable-fast-download]] configure option turns this on.)

* The MOUL server has a bug with quabs in Ahnonay. If you are the first person who linked into the age, the quabs are associated with your ID. When you link out of the age, the server is supposed to send a LoadClone message telling other clients to unload your clone (the avatar). The MOUL server sends the message, but it says to unload one of the quabs with your ID in it instead of the player avatar. Oddly, the client seems just fine with that. MOSS does not have this bug.

* You should see less client hitching while moving around with MOSS. The MOUL server sends a ton of node update messages for the (unchanged) city AgeInfo node. Each node update causes the client to fetch your pellet scores. The client is frozen during this (and most any) vault transaction. The MOSS server does not send all those useless updates. Interesting note: One measurement during MOUL was approximately 400 pellet score fetches an hour. That is the client freezing every 9 seconds regardless of what age you are in or how many people are in it or on your buddy list. (The pellet score fetch itself can probably be fixed in the Python but you'd still be wasting time on the city node.)

* The pellet score freeze can be further reduced by #defining <tt>PELLET_SCORE_CACHE</tt>, which does what it sounds like: it caches the client's pellet score in the Auth server to cut out the round-trip time to the DB. However, there's little value to it without the city node update problem; when you open the KI it fetches the score but it's also fetching other vault nodes. Plus you aren't trying to move at the time so the freeze is less obvious. So <tt>PELLET_SCORE_CACHE</tt> is undefined by default, and in fact it is ''untested''.

[[Category:MOSS]]

MOSS/Project Ideas

2011-04-05T06:53:20Z

A'moaca': /* Detail work (little Uru-specific knowledge required) */ new idea

The initial list was generated over the lengthy period of MOSS's initial
development. These project ideas mostly cover missing functionality. None of
the missing functionality is known to cause gameplay issues so these did not
really seem like bugs. These ideas are grouped by general type of change
required, and sort of by increasing approximate difficulty level and sort of by
decreasing value.

Bigger ideas, such as entirely new functionality now made possible by the
release of the client, could go here too. Be realistic, though. Remember that
protocol changes are not to be made lightly, because it causes an
incompatibility problem. It is probably better to propose large changes in
discussion format on the forums. Do not ''expect'' someone else to take up and
implement your proposal.

The whole idea of this list is to provide some ideas for anyone wishing to dive
into MOSS. Sometimes a little direction helps.

== Fix bugs ==

The bug tracker is here: https://foundry.openuru.org/jira/browse/MOSS

== Detail work (little Uru-specific knowledge required) ==

* Try disabling the Nagle algorithm on sockets. This should result in less latency to the client when small messages are involved. Make sure to test the whole game thoroughly.

* Figure out and implement a good way to use autoconf to compile in default pathnames. This would apply to the default config file, key file, moss_serv binary, and log/auth/game/file directory locations. The idea is if I say --prefix=/foo the defaults become /foo/etc/moss.cfg and so forth instead of ./etc/moss.cfg. Don't forget autoconf lets you override the etcdir, bindir, etc. separately.

* Treat SDL filenames case-insensitively. This is very annoying in Unix, since it requires using readdir() and strcasecmp() instead of just open().

* Make it so the game/state directory location can be separately configured. This is so the whole MOSS install can be read-only and just the log directory and game/state moved somewhere read-write. (The easy workaround is to symlink a writable directory to game/state.)

* Log the PID of all forked servers in moss.log.

* See if we can switch to libevent for inter-thread communication instead of raw signals. This should be fairly portable and take advantage of the different per-OS lightweight signalling mechanisms.

* Allow ''skipping'' overlong messages (messages MOSS thinks are too big). This requires, upon catching the exception, tossing out the message, and if it has not all been read in yet, keeping track of how much more to toss in the future. The RC4 state must be updated too for the tossed message length.

* It would be nice to use atomic operations for refcounts instead of having to use (bigger, slower) mutexes for them. This does make MOSS not architecture-independent, which is part of why I have been resisting it. (See also signal handling next.)

* Signal handlers and the operations to read and reset the values in the main loops should be using atomic operations.

* Catch and handle std::bad_alloc whenever possible.

== Fairly contained changes ==

* Make it so game servers can be forked as separate processes. This helps a lot for debugging and also would help for age development, making it easier to change SDL and retest. Otherwise you have to shut down the whole frontend server or wait out the age's linger time. This work was started but not completed, and that code can be found inside <tt>FORK_GAME_TOO</tt> #ifdefs. If you do this, I suggest you consider separating <tt>FORK_GAME_TOO</tt> from <tt>FORK_ENABLE</tt> so that one could have forked game servers and *not* forked auth/file servers.

* In the getpublicagelist() SQL function, there is a comment about the 50-hood limit. The current code returns the first 50 hoods. We should return the most recently used 50 hoods. The hard part is knowing which those are. This is mostly if not wholly DB/SQL work.

* Age population limits are unimplemented. The value is in the vault, but the server does not look at it.

* Figure out how to throw out clones and SDL when a player leaves the age. Please see the "clean up clone, SDL" section in GameServer::conn_shutdown(). Right now this is full of special cases: it handles the Kemo bugs and and Quabs specially (a different thing for each). It may be that this is required for best behavior, but I still feel like I've missed something despite heavy scrutiny of the data. This is more of a research project and not much of a code project.

* MOUL parsed SDL nodes on the way into the vault. It probably only updated the node with fields having the Dirty bit set. In addition it added timestamps to the fields because the client does not put in the timestamps (reasonably so, as its time may be wrong). MOSS currently saves the SDL wholesale. This basically works, but with the timestamps properly added, the game server can merge the vault, age, and global SDL in any order and without strange rules. Note: if you do this, you also need to write a script or some other way to update all the SDL nodes in existing MOSS DBs.

* The kickable SDL filtering algorithm is the same one I put in Alcugs ages ago. It is better than nothing but not as good as Plasma's. You will see more warping of kickables than with Cyan's server. This project is to come up with a better way of deciding what physical SDL to send to all the clients, based on those messages all the clients are sending to the server.

* The server is probably supposed to use RelevanceRegion information to avoid sending SDL updates to clients who don't share a relevance region with the originating client. (The idea being to reduce network traffic, since hopefully the client already avoids rendering/physics on things in irrelevant regions.) Things work if the server doesn't filter, so MOSS doesn't. Also, I do not have strong evidence to believe this supposition is actually correct. Which is the other reason MOSS doesn't do it. Finding out, and implementing it if so, would be a nice project.

* Figure out what the server is supposed to do with plSetNetGroupIDMsg and do it. Right now MOSS just drops it to no apparent ill effect. I am deeply suspicious of this message due to seeing it at aurally unpleasant times in UU. (Old, old notes: "may have to do with infinitely looping scraping noises".)

* <tt>kCli2Auth_SendFriendInviteRequest</tt> is not fully supported (it is dropped on the floor).

== Bigger changes ==

* The following messages are unimplemented.
** <tt>kCli2Auth_VaultSetSeen</tt> -- unimplemented in client
** <tt>kCli2Auth_ScoreDelete</tt> -- never saw one, so couldn't implement it
** <tt>kCli2Auth_ScoreSetPoints</tt> -- never saw one, so couldn't implement it
** <tt>kCli2Auth_ScoreGetRanks</tt> -- never saw one, so couldn't implement it
** <tt>kCli2Csr_PingRequest</tt> -- no recorded Csr messages
** <tt>kCli2Csr_RegisterRequest</tt>
** <tt>kCli2Csr_LoginRequest</tt>
** <tt>kCsr2Cli_PingReply</tt>
** <tt>kCsr2Cli_RegisterReply</tt>
** <tt>kCsr2Cli_LoginReply</tt>

* Add hood randomization to DRC hoods. Player-created hoods are randomized by the Python in the Nexus when the hood is created. DRC hoods, however, are created by the server. In MOSS's case, they are created entirely by SQL code. So adding DRC hood randomization means noticing when the DB has created a new DRC hood, creating and modifying SDL in the backend, and then finding and modifying the age SDL node for that new hood. All before responding to the client creating the new avatar and thus the new DRC hood.

* The MessageQueue class has a concept of priorities. The idea was to enable dropping of lower-priority messages if a queue to a given client starts to back up. (The lowest priority being voice chat, then avatar movements, with world state changes being highest.) The measurement of queue length or throughput necessary for that is not implemented. So, neither is the dropping. (There is the very beginnings of some if <tt>DO_PRIORITIES</tt> is #defined.) As such, queue users don't do a good job of priority-setting, although VOICE and FRONT are properly used. The idea wasn't to order the queue (except for FRONT), but to skip sending, say, a VOICE message when we encounter one, if the queue congestion measure says to.

* '''Vault security'''
: The MOSS vault is as insecure as the MOUL vault. Need I say more? Here are some starter thoughts.
:* MOSS should parse incoming SDL messages and sanity-check them. See also [[#SDL_timestamps | adding timestamps]].
:* MOSS could probably verify other blob contents too.
:* Anyone can save anything to any node, and can fetch any node if they know its type and ID. We can deny these requests if the user shouldn't have access. Possibly [[MOSS-Developer_Notes#notifier | the notifier field]] can help.
:* Much more, I'm sure. Better vault security ''is'' possible.

* Eliminate excessive byteswapping of opaque server IDs in BackendMessages. This is to say, in the backend server, when reading in the messages, it byte-swaps the IDs to store them, only ever uses them in equality tests with other IDs, and then byte-swaps them back when sending new messages. (On a little-endian box there's no swapping so it does not cost much, but it's the principle of the matter.) Unfortunately this really needs to be tested on a big-endian machine.

* Try changing the File server to do [[MOSS-Setup#ackless | ackless downloads]], too. Maybe only if there is only one download at a time, though.

== Scalability issues ==

Performance and scalability are always interesting questions. And frequently ignored, because they only matter for larger installations.

These are ideas unimplemented because they only really matter for large
shards. Large as in having, let's say, 50+ concurrent '''busy''' users. (50
people standing in the city chatting doesn't actually do much.) Maybe MOSS is
okay with that number now, in which case "large" is more. It is entirely
unknown.

* Performance testing. Instrumentation. There should be a load generator to do this. This was not high on the list during development, with a user base of 3.

* See the last paragraph in the comments at the top of FileTransaction.h about how multiple file transactions of the same file should share a single opened file.

* Allow speculative pre-caching of AgeInfoNodes and PlayerInfoNodes when node changed notifications come from the vault server and are forwarded to any connected client. Cache in the auth server, vault server, or both. The goal is to reduce latency on those requests the client freezes for.

* The backend protocol supports game servers requesting batches of GameMgr IDs. However, there is no code on either side to actually do so. The idea for this was that more populated ages, like the city, would benefit from doing batch requests. Every person who links in with a marker game needs a new global game ID, and it would be nice to cut out any extra backend round trips for links, even though this particular round trip does not block the link process (aside from being something the backend is doing when it could be doing something else).

* Database performance could be measured and the SQL or even tables optimized.

* MOSS currently uses a single blocking connection to the DB. Implement and investigate performance of multiple DB connections, or asynchronous ones. Maybe the backend server has to become threaded to gain the best advantage.

* In a big shard, we may need to split the backend server work up. The [[MOSS-Developer_Notes#backend_typecodes | backend protocol]] is designed to support separating backend work between threads. The "classes" of backend messages in a bitfield are meant as a way to quickly route a backend message to an appropriate backend thread or process.

== Frontend/backend interactions ==

* Add encryption to the backend protocol. This itself is not a big deal (though you have to pick a good key negotiation, and do not forget to consider authentication mechanisms), but it does mean all the BackendMessage fill_buffer() code paths would be newly exercised, so a lot of regression testing would be in order.

* It would be much easier on the DB if updates to markers are batched by the game server. This especially applies to capturing markers. See the comments in the setmarkerto() and startmarkergame() SQL functions.

* The backend protocol allows for frontends hosting ages to specify only a subset of ages that can be hosted there. This is unused right now; the message has a field saying, "this is the length of the following age restriction list" and it is always zero. When there are no restrictions the backend can request any frontend to host any age.
** The need for splitting hostable ages is unclear, but in a very large shard you might, for example, put all city instances, or even only the public one, on a separate server. It would also allow someone to join a shard and host just their own age, or whatever.
** Since the frontend never sends restrictions, the backend currently has no way to store and use them. So there is work on both sides.
** Presumably which ages a frontend server can host would be a configuration option but it could be done instead by restricting the contents of the game/age directory. That would not allow even finer-grained restrictions, but this whole project kind of needs a real use case to flesh out what is needed.

* Having one backend TCP connection per frontend server is probably not a good thing, in terms of efficiency, or of scalability with a cluster of machines. We could change it to have one backend connection per frontend ''process'' and funnel everything through it. The mostly-implemented but unused and untested MultiWriterMessageQueue was meant, in part, to support this (there are multiple threads writing, but only one thread reading, which writes to the socket).

: Then when messages are received in the frontend there needs to be some way of passing the message to the right thread and signaling them something is present to be handled. This is all unimplemented but the format of the backend messages is meant to take care of this case (in particular, the two "server IDs" in the header are for dispatching messages to the correct thread).

: However, essentially the same changes would be necessary if the backend server is folded into the main server so there is only one process; then "sending" messages to the backend server is just putting them on the (shared) queue that would have been used to funnel everything through one connection, and "receiving" them is just taking them off that queue since there's no TCP connection to deal with.

== New functionality ==

* I am guessing Cyan's server handles the GameMgr stuff with server-side scripting. At the time MOSS was implemented there was no expectation that new game types may be added so adding in a scripting language was not worth the problems incumbent with doing so. Also the overall value of scripting is not clear (especially for the cost in server complication). However, it could be done. The project would have to include embedding the scripting and then rewriting stuff using scripts.
: Please note, a lot of effort went into getting the Heek right, handling ties, allowing people to accidentally stand up and sit back down in the game, and probably other details I forgot. If you want to script Heek, it really ought to still work as well.

* Really adventurous hardcore project: destroy KI hacks. The server would have to be able to analyze all game traffic to decide whether it looks okay. To do it right the server would have to have and understand PRP files and do physics. Also "console" commands have to be wisely filtered. If you're daunted, join the club.

== Redesigns ==
{{tba}}

[[Category:MOSS]]

MOSS/Setup

2011-04-05T06:48:49Z

A'moaca': finishing touches

MOSS currently only runs on Unix. Not Windows. It ought to work on Mac OS/X
(even PowerPC) but nobody has tried yet.

Please also see the
[http://foundry.openuru.org/fisheye/browse/MOSS/doc/setup main setup instructions].

== Compile ==

=== Prerequisites ===

Before you start, 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)
* 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
* gcc, g++, whatever all you need for compiling C++

If you are compiling from a clone of an Hg respository and there is no
"configure" script, you also need the autotools:
* autoconf
* automake
* libtool

'''If you are reading this, please go over to'''
[[MOSS-Distribution_Specific_Instructions]] '''and fill in how to install all that 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 set up the server to match the
way Cyan's works. Here are the options you are probably interested in:
; --prefix
: Specify 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 [[MOSS-Notes#RSA | 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".

Install the postgres module in your postgres install. 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 if it's not there already. 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
will have to edit the 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 my 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_Files | 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!

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, but the
Minkata one is still broken.

== 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 | configuration files]]; you may find it easiest to
specify absolute paths (starting with "/") there.

=== 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
manifets MOSS needs. This seems a reasonable assumption when the client itself
is a Windows app.

Copy support/ManifestCreator.exe and support/Mainfests.zip to your Windows
box. Unzip Manifests.zip. This will make 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. To generate a manifest, click "Make Manifest" and it
brings up a dialog. Navigate to the CyanStructure folder, and select all the
.txt files there. Then click OK and when it pops up a 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 which will run MOSS, create a file server directory. The
default is "./file" (relative to where you start it up). I recommend you make
it ''prefix''/file, where ''prefix'' is the installed location. Copy all the
.mbm files created in the CyanStructure folder to this directory. If you are
serving up a CWE client (built from open source) you will 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, also should be copied. Make sure to match the
directory structures when copying them over.

Finally, 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 ===

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

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

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
[http://assets.openuru.org/cyan/AuthFiles.zip 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 with contains one
line per file in the SDL directory. The lines look like
"SDL\BaronCityOffice.sdl". I just toss these in the auth/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 will also create the files. 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 ===

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.

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

The game servers need unencrypted .sdl and .age files. The easiest way to get a
set of these files is from the Cyan-provided
[http://assets.openuru.org/cyan/Scripts.zip 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 which will be 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 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 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 auth_key.bin

If you're compiling a CWE client, make_cyan_dh does not currently output data
in that format. See [https://foundry.openuru.org/jira/browse/MOSS-3 the bug]
for the workaround. If you're not compiling a client, 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".

Do the same 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 for 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:
<tt>auth_download_dir</tt>, <tt>auth_key_file</tt>, <tt>file_download_dir</tt>,
<tt>game_data_dir</tt>, <tt>game_key_file</tt>,
<tt>gatekeeper_key_file</tt>. In addition I recommend you set <tt>log_dir</tt>
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
<tt>pid_file</tt> 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
<tt>external_address</tt>.

For moss_backend.cfg look especially into <tt>log_dir</tt> and
<tt>pid_file</tt>. In addition, depending on how your DB is
[[#Set_Up_the_Database | set up]] you likely need to specify <tt>db_user</tt>,
and maybe other DB parameters.

== Security Considerations ==

'''Please''' read about them at the end of
[http://foundry.openuru.org/fisheye/browse/MOSS/doc/setup doc/setup].

Do not run MOSS as root.

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

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

* 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 [http://assets.openuru.org/cyan/Scripts.zip original source]. If you modify it for any reason, you must make your changes available and tell your users where to get it.

* If you are providing client executables from a CWE build:
** 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'll 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.
** 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.
** Unless someone changes the jpeg library again, you need to credit IJG for jpeglib. 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:
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 [[CyanWorlds.com_Engine/FAQ#What_are_my_open_source_license_.28GPLv3.29_responsibilities_as_a_user.2C_developer_or_server_operator_.28e.g._shard_owner.29.3F | 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 ==

Now you should be set to run your server. Hopefully someone will contribute a
nice startup script. 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:
bin/moss_backend
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.

== Create Accounts ==

Don't forget to create accounts for your users, or it will be difficult to log
in... Please just refer directly to
[http://foundry.openuru.org/fisheye/browse/MOSS/doc/user-management doc/user-management].

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

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

== More Hints ==

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

* [[MOSS-Notes]]
* [http://foundry.openuru.org/fisheye/browse/MOSS/doc/running doc/running]

[[Category:MOSS]]

MOSS/Distribution Specific Instructions

2011-04-05T06:11:00Z

A'moaca': Undo revision 982 - forgot this was in the Setup page

This document is meant to collect any known distribution-specific instructions
for installing MOSS. There are two main parts: installing the prerequisite
packages, and setting up the PostgreSQL database. Feel free to add any other
notes you may find useful.

== Prerequisite Packages ==

=== NetBSD pkgsrc ===

Only PostgreSQL and the autotools are needed. You can build the packages
or use the prebuilt packages with pkg_add.

pkg_add automake
pkg_add libtool
pkg_add libpqxx
I recommend starting with libpqxx because it seems to lag the postgresql-client
package, and installing libpqxx will get the correct client.
pkg_add postgresqlNN-server
Get the version number to match the client installed for pqxx.

Now follow the instructions:
* copy /usr/pkg/share/examples/rc.d/pgsql to /etc/rc.d/pgsql
* chmod 555 /etc/rc.d/pgsql
* append pgsql=YES to /etc/rc.conf

== Database Setup ==

=== NetBSD pkgsrc ===

Copy moss_uuidgen.so to /usr/pkg/lib/postgresql/

The database user is <tt>pgsql</tt>. It has root access to the DB by default.
Connect from localhost (the default).

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

Then set db_user=moss in moss_backend.cfg.

== Additional Notes ==

[[Category:MOSS]]

MOSS/Distribution Specific Instructions

2011-04-05T06:00:00Z

A'moaca': /* NetBSD pkgsrc */

MOSS

2011-04-05T05:46:11Z

A'moaca': /* How to Contribute */

MOSS is a unix-based server for the Myst Online: Uru Live client. Development
began after the announcement of the shutdown of MOUL. It is complete enough to
play the entire game, supports multiplayer use, is licensed under GPLv3, and is
not ported to Windows.

MOSS was developed by a'moaca' and cjkelly1. a'moaca' wrote all the C/C++ code,
and cjkelly1 wrote most of the SQL code, including doing research to determine
how to set up the vault. cjkelly1 wrote a tool to create the manifest files
required by the server, and also made the invaluable contribution of a lot of
testing over the years. Weldergeek helped with some of the multiplayer testing,
especially Heek. a'moaca' sincerely hopes there will be more contributors now
that MOSS is released.
<div style="float: right; padding: 10px;">http://assets.openuru.org/logos/gpl/gplv3-127x51.png</div>

== Why Use MOSS? ==

If you just want to host a private shard, MOSS should serve your purposes.
[[MOSS-Setup#Before You Open Your Server | "Before You Open Your Server"]]
has some help on what you need to do if you host an Uru shard.

The server definitely works with the [[CyanWorlds.com_Engine | CWE client]]! If
you are thinking of doing client development you will probably find a server
that is not MOULagain to test with quite valuable. (MOSS was also tested with
PlasmaClient, but it does not fully work for PlasmaClient because it does some
things that a'moaca' argues are bugs from the system perspective. Let's fix
PlasmaClient.)

The server has some features meant to help make it a little easier to test ages
you are creating. The SDL files for an age are loaded each time the age is
started up so you can change them without restarting MOSS. There is full
support for multiple .pak files. So, run your own server, test at your own
pace. Test in the CWE client and not the PotS one.

== How to Get It ==

{{tba}}

The source code is hosted in a Mercurial repository here at OpenUru.org.
You can clone (download) a copy of the repository using Mercurial, or you can
use a snapshot. If you are considering making changes to the code, you will
probably prefer using the version control. If you just want to compile and run
a server, a snapshot should do. In addition, a compiled version is
available for the TBD platform.

If you are new to Mercurial, you may want to check the
[http://mercurial.selenic.com/wiki/QuickStart QuickStart]. There are links to
more complete documentation at the bottom. The Foundry is secured via SSL
throughout the site. A browser security certificate is needed. Instructions are
available on the [[Foundry_Certificate_Installation | certificate installation
page]].

'''Repository address:''' https://foundry.openuru.org/hg/MOSS

'''Snapshot location:''' TBD

'''Binary package:''' TBD

== How to Set Up a Server ==

The [http://foundry.openuru.org/fisheye/browse/MOSS/doc/setup setup] file
contains a complete set of installation instructions. They do assume you are
conversant with setting up software and basic management of a database. For
additional setup instructions, see [[MOSS-Setup]]. Feel free to add any hints
specific to your distribution [[MOSS-Distribution_Specific_Instructions | here]].

Cyan has provided a copy of the files needed for a server hosting MOUL content.
The .sdl, .age, and Python source are all available at
http://assets.openuru.org/cyan/Scripts.zip. If you are not interested in
compiling your own Python from this source, you can also get a copy of the
compiled Python from http://assets.openuru.org/cyan/AuthFiles.zip.

There is some Q&A and other notes of possible interest to someone running a
server at [[MOSS-Notes]].

== How to Contribute ==

Contributing to the wiki pages is welcome. Adding extra setup instructions, or
adding documentation about how MOSS works, are two good examples. It's a wiki,
please contribute anything you think others might want to read.

Almost any code contribution is welcome. What is unwelcome? Protocol/behavior
changes without corresponding client support (obviously). Changes that remove
security without the option of keeping it. Changes that introduce security
holes, either in the server itself or the vault. Changes that break big-endian
support (call it a pet peeve if you like, it's still unwelcome). Changes that
break the build (accidents do happen, but don't break it on purpose). Hopefully
it is not difficult to see why these things are unwelcome.

If you find a bug, please report it. Please, please, please search first to see
if it's already reported. The bug tracker is here:
https://foundry.openuru.org/jira/browse/MOSS

If you find a bug and fix it, include the patch with the bug report! This
increases the chances of it getting fixed rather a lot.

Bug fixes are very valuable.
[https://foundry.openuru.org/jira/browse/MOSS Grab a bug] and fix it! Check
out [[MOSS-Project_Ideas]] for more ideas.

If you want to add a feature or change something, you can file a feature
request or task bug to get your change considered for the
[https://foundry.openuru.org/hg/MOSS central repository].

If you want write access to the central repository, contribute. The best choice
for MOSS will probably be to use similar standards for determining who is given
write access as CWE. At this time that's undecided, so the plan for MOSS is
equally undecided. However, MOSS's original author is more involved than CWE's
so if only a couple people show up to help then it's pretty clear a couple
people will get write access soon enough!

Code reviewers might be needed. If you are willing to be a reviewer, say so! It
is a very valuable contribution.

== See Also ==

[[MOSS-Notes]]

[[MOSS-Setup]]

[[MOSS-Developer_Notes]]

[[CyanWorlds.com_Engine]]

[[Category:MOSS]]

MOSS

2011-04-05T05:44:23Z

A'moaca':

MOSS is a unix-based server for the Myst Online: Uru Live client. Development
began after the announcement of the shutdown of MOUL. It is complete enough to
play the entire game, supports multiplayer use, is licensed under GPLv3, and is
not ported to Windows.

MOSS was developed by a'moaca' and cjkelly1. a'moaca' wrote all the C/C++ code,
and cjkelly1 wrote most of the SQL code, including doing research to determine
how to set up the vault. cjkelly1 wrote a tool to create the manifest files
required by the server, and also made the invaluable contribution of a lot of
testing over the years. Weldergeek helped with some of the multiplayer testing,
especially Heek. a'moaca' sincerely hopes there will be more contributors now
that MOSS is released.
<div style="float: right; padding: 10px;">http://assets.openuru.org/logos/gpl/gplv3-127x51.png</div>

== Why Use MOSS? ==

If you just want to host a private shard, MOSS should serve your purposes.
[[MOSS-Setup#Before You Open Your Server | "Before You Open Your Server"]]
has some help on what you need to do if you host an Uru shard.

The server definitely works with the [[CyanWorlds.com_Engine | CWE client]]! If
you are thinking of doing client development you will probably find a server
that is not MOULagain to test with quite valuable. (MOSS was also tested with
PlasmaClient, but it does not fully work for PlasmaClient because it does some
things that a'moaca' argues are bugs from the system perspective. Let's fix
PlasmaClient.)

The server has some features meant to help make it a little easier to test ages
you are creating. The SDL files for an age are loaded each time the age is
started up so you can change them without restarting MOSS. There is full
support for multiple .pak files. So, run your own server, test at your own
pace. Test in the CWE client and not the PotS one.

== How to Get It ==

{{tba}}

The source code is hosted in a Mercurial repository here at OpenUru.org.
You can clone (download) a copy of the repository using Mercurial, or you can
use a snapshot. If you are considering making changes to the code, you will
probably prefer using the version control. If you just want to compile and run
a server, a snapshot should do. In addition, a compiled version is
available for the TBD platform.

If you are new to Mercurial, you may want to check the
[http://mercurial.selenic.com/wiki/QuickStart QuickStart]. There are links to
more complete documentation at the bottom. The Foundry is secured via SSL
throughout the site. A browser security certificate is needed. Instructions are
available on the [[Foundry_Certificate_Installation | certificate installation
page]].

'''Repository address:''' https://foundry.openuru.org/hg/MOSS

'''Snapshot location:''' TBD

'''Binary package:''' TBD

== How to Set Up a Server ==

The [http://foundry.openuru.org/fisheye/browse/MOSS/doc/setup setup] file
contains a complete set of installation instructions. They do assume you are
conversant with setting up software and basic management of a database. For
additional setup instructions, see [[MOSS-Setup]]. Feel free to add any hints
specific to your distribution [[MOSS-Distribution_Specific_Instructions | here]].

Cyan has provided a copy of the files needed for a server hosting MOUL content.
The .sdl, .age, and Python source are all available at
http://assets.openuru.org/cyan/Scripts.zip. If you are not interested in
compiling your own Python from this source, you can also get a copy of the
compiled Python from http://assets.openuru.org/cyan/AuthFiles.zip.

There is some Q&A and other notes of possible interest to someone running a
server at [[MOSS-Notes]].

== How to Contribute ==

Contributing to the wiki pages is welcome. Adding extra setup instructions, or
adding documentation about how MOSS works, are two good examples. It's a wiki,
please contribute anything you think others might want to read.

Almost any code contribution is welcome. What is unwelcome? Protocol/behavior
changes without corresponding client support (obviously). Changes that remove
security without the option of keeping it. Changes that introduce security
holes, either in the server itself or the vault. Changes that break big-endian
support (call it a pet peeve if you like, it's still unwelcome). Changes that
break the build (accidents do happen, but don't break it on purpose). Hopefully
it is not difficult to see why these things are unwelcome.

If you find a bug, please report it. Please, please, please search first to see
if it's already reported. The bug tracker is here:
https://foundry.openuru.org/jira/browse/MOSS

If you find a bug and fix it, include the patch with the bug report! This
increases the chances of it getting fixed rather a lot.

Bug fixes are very valuable.
[https://foundry.openuru.org/jira/browse/MOSS Grab a bug] and fix it! Check
out [[MOSS-Project_Ideas]] for more ideas.

If you want to add a feature or change something, you can file a feature
request or task bug to get your change considered for the
[https://foundry.openuru.org/hg/MOSS central repository].

If you want write access to the central repository, contribute. I think the
best for MOSS will be to use similar standards for determining who is given
write access as CWE. At this time that's undecided, so I leave MOSS equally
undecided. However, MOSS's original author is more involved than CWE's so if
only a couple people show up to help then it's pretty clear a couple people
will get write access soon enough!

Code reviewers might be needed. If you are willing to be a reviewer, say so! It
is a very valuable contribution.

== See Also ==

[[MOSS-Notes]]

[[MOSS-Setup]]

[[MOSS-Developer_Notes]]

[[CyanWorlds.com_Engine]]

[[Category:MOSS]]

MOSS/Notes

2011-04-04T06:41:52Z

A'moaca':

This page just holds various notes about running a MOSS server.

== Questions ==

I can't really call this a FAQ until the questions have been asked frequently.

; How do I add a user?
: [[MOSS-Setup#Create_Accounts]]
; How do I change the Python?
: Start with the source Cyan has generously provided us under the GPL. To compile that source you'll have to add in the glue. Maybe there is a tool do that in the CWE source. Make your changes. After compiling and creating the .pak (another tool?), copy the .pak to the [[MOSS-Setup#Auth_Server_Data | correct server directory]] and encrypt it. Make a new .mbam file.
; How do I add a new age?
: Copy the encrypted .pak to the [[MOSS-Setup#Auth_Server_Data | correct server directory]], add the file to the Python.txt, and make a new .mbam file. Copy any SDL files to the auth SDL directory and encrypt them. Copy unencrypted SDL files to the [[MOSS-Setup#Game_Server_Data | correct server directory]]. Note if you have more than one SDL file for your age, or the file is not named the same as the age, you'll need to put the age's SDL file(s) in a directory named after the age. Copy the unencrypted .age file to the game server directory.
; Why would I use --enable-fork?
: This is primarily useful for testing. It's easier to debug a non-threaded process.
; What resource limitations are there (file descriptors, memory, etc.)?
: This is a question that's not obvious to answer. But here is what is known:
:* Currently MOSS uses about 5 file descriptors when idle. It uses about 10 per connected user. (4 are for the game server, so if the user links around a lot, it will be more, and if you have multiple users in one age it will be less.) If you are running a large shard, you may need to adjust per-process file descriptor limits (see the "ulimit" command) or even kernel (global) limits. If you adjust the global limit, pay attention to <tt>FD_SETSIZE</tt>. See the select() man page.
:* Currently MOSS uses 7 big buffers for network data per connected user. The buffer size is set by <tt>BUFSIZE</tt> in constants.h. The default is 64k, so a total of 448k per user. If you have enough users that your moss processes grow too large you can reduce the <tt>BUFSIZE</tt>.
:* There is not a lot of disk I/O, except for whatever the database has to write. If you set the log levels very low (DEBUG or worse, MSGS) then there will be a lot of I/O for log files.
; Does MOSS work on my Power PC?
: It is supposed to! Testing of big-endian systems was done, but not a full, complete run-through of all game mechanics and multiplayer testing. If it does not work, [[MOSS#How_to_Contribute | it's a bug]].
; Does MOSS work on Windows? OS X?
: Not Windows. There is a fair bit of porting work to do. OS/X theoretically works but nobody has tried yet. (If you try and it works, fix this!)
; What is the "status" server type?
: MOSS will provide the status string normally fetched from a web server. You do have to make the client send the HTTP request to port 14617 or it won't do much good. This is a feature that perhaps only the author wants.

== Warnings ==

* Please note: The MOSS vault is as insecure as MOUL's. (I don't know what was done to MOULagain.) The MOSS server is almost as trusting of the client as MOUL's. (Or maybe more, in other ways; for example, there is no server-side profanity filter.) This is because a MOUL server was implemented, not some other server. Doing better is definitely possible. But to do it right is a very big project, because the entire ''system'' was designed with this trust model. You can't always change just one part of it to get where you want to be.

* Don't change the .mbm or file server files while you have clients doing File transactions. Doing so will give everything indigestion.

* I'm sure the same applies for .mbam and auth server files.

* The SDL mechanism depends on all servers in the shard having synchronized time. Use NTP if you have more than one server. (You'll also need to NFS mount the game/state directory on all the servers so the age SDL is available to all.)

== Setup Choices ==

* Disabling the client<->server encryption is NOT recommended. However, if you subscribe to the shortsighted idea that protecting your users is not important, go ahead. But be warned, there are code paths in MOSS that are completely untested when all encryption is disabled. You'll have to fix any bugs. (The Wireshark plugin does support decrypting connections when you have the key, so you ''can'' use encrypted connections during development/testing.)

* MOSS supports using RSA for key negotiation. The client contribution to the session key is RSA-encrypted with the server public key and then sent to the server, which decrypts the message. Ironically, this actually is less crypto work, while using a non-modified standard encryption technology. And it has the same pseudo-authentication properties as the Cyan-style modified Diffie-Hellman. The assembler changes required for this are astonishingly small, but there's not much value in using RSA. Nonetheless, there's no need to remove working server support for it...

== While Running the Server ==

* You can change age SDL state server-side by modifying the state saved in files in the game/state directory. Keeping backups is advised. You may modify the files with the "sdl_reader" program (which you need to build separately using "make sdl_reader"). This is a very simple command-line program. Use the -l option to specify a saved file to read. When in the program, use the "h" command to see the help. Saving this file while a game server for that age is running is pointless; the new version won't be read and it will be overwritten when the server exits.

== Client Bug Workarounds ==

MOSS works around a few client bugs.

* MOSS "fixes" the KI light bug. It is a bug in the PRP files. MOSS has an extra check for determining whether SDL state is avatar-related, instead of relying on the flag that says whether to keep the SDL state around. That check covers the KI light, so the light SDL is tossed along with the rest of avatar SDL when a person leaves an age.

* MOSS may "fix" the footstep region bug. This bug is when you get the wrong footstep sound stuck, like that wooden bridge you left long ago clumping around while you're on stone. Everyone in the age hears the wrong footstep sounds. I believe that in normal play (that is, without things like /spawn) it is due to a race with the exclusive locking mechanism used to keep things like multiple button presses from being processed at the same time. Why footstep regions take a server-side exclusive lock is beyond me**, so MOSS grants '''all''' footstep region lock requests. This should make the problem occur less frequently, if at all (depending on how the client actually responds to receiving the lock after leaving the region). MOSS decides you are asking for a footstep region lock by looking for the word "Footstep" in the object name. ''Do not name buttons, door regions, or whatever with "Footstep" in your new ages.'' I suggest you do name footstep regions with "Footstep". The special case can be removed by removing <tt>#define GRANT_ALL_FOOTSTEPS</tt> from GameState.cc and recompiling.
:: **In fact, as a friend of mine pointed out, why are footstep sounds decided by the represented avatar's client and propagated to everyone else in the first place? It should be a purely local decision based on the location of each avatar as seen by that client. That would save on traffic and always be accurate, never mind the race with locking on the region since there would be no need to coordinate anything for a purely local decision.

* Quab game Python is not really complete. The first person to link to the age becomes the "owner" of the quab game. The Python sort of attempts to handle the situation where the game owner leaves the age while there are still quabs around, but it does not actually handle it. If the server attempts to pass ownership to someone else, that client will break. And the current MOULagain client even crashes. So MOSS works around the problem by intentionally breaking the whole game when the owner leaves the age and quabs are still present. All the quabs will remain frozen in place until the age has been cleared of all players. The age does not have to restart to revive the game, just be empty.

* The client supports two kinds of passwords, depending on the format of the username. If the username has the format x@x.x it uses algorithm 1 (a more secure one but also one with a fencepost error), and otherwise algorithm 2. Unfortunately the /changepassword command does not know about algorithm 2 and if you logged in with algorithm 2, it will try to change your password hash to the one for algorithm 1. This would result in you being unable to log in. So MOSS rejects requests to change the password if the username does not have the x@x.x format.

== Server Non-Bugs ==

These are problems with Cyan's server that MOSS does not have.

* MOSS does not have the infamous "zero seconds remaining" bug. Thus it is possible to do the auth downloads without the server waiting for acks from the client. This speeds up the download substantially as now the bandwidth can be fully utilized. (The [[MOSS-Setup#configure | --enable-fast-download]] configure option turns this on.)

* The MOUL server has a bug with quabs in Ahnonay. If you are the first person who linked into the age, the quabs are associated with your ID. When you link out of the age, the server is supposed to send a LoadClone message telling other clients to unload your clone (the avatar). The MOUL server sends the message, but it says to unload one of the quabs with your ID in it instead of the player avatar. Oddly, the client seems just fine with that. MOSS does not have this bug.

* You should see less client hitching while moving around with MOSS. The MOUL server sends a ton of node update messages for the (unchanged) city AgeInfo node. Each node update causes the client to fetch your pellet scores. The client is frozen during this (and most any) vault transaction. The MOSS server does not send all those useless updates. Interesting note: One measurement during MOUL was approximately 400 pellet score fetches an hour. That is the client freezing every 9 seconds regardless of what age you are in or how many people are in it or on your buddy list. (The pellet score fetch itself can probably be fixed in the Python but you'd still be wasting time on the city node.)

* The pellet score freeze can be further reduced by #defining <tt>PELLET_SCORE_CACHE</tt>, which does what it sounds like: it caches the client's pellet score in the Auth server to cut out the round-trip time to the DB. However, there's little value to it without the city node update problem; when you open the KI it fetches the score but it's also fetching other vault nodes. Plus you aren't trying to move at the time so the freeze is less obvious. So <tt>PELLET_SCORE_CACHE</tt> is undefined by default, and in fact it is ''untested''.

[[Category:MOSS]]

MOSS/Developer Notes

2011-04-04T06:40:56Z

A'moaca':

Comments of interest to those working with the MOSS code should go here. If
you plan to just run a server and not modify it, you don't need to be here.

== Working with the Code ==

=== Requirements ===

* Handle byte-swapping. A networking person wrote MOSS, and such people care about working with both endiannesses. Do not break it.

* This does mean you cannot drop in someone else's code handling the MOUL protocol if it assumes you are using a little-endian machine. This is '''the''' reason for not casting incoming byte data to structs and writing out structs.

* Including "config.h" should always look like this:
#ifdef HAVE_CONFIG_H
#include "config.h"
#endif

=== Code Conventions ===

* Keep C++-style comments out of preprocessor lines.

* Keep code to 78 columns whenever possible.

* Include (.h) files have comments at the top listing which other include files are required before including this file. (Some may be missing but I tried.)

* I use emacs. Please keep the <tt>/* -*- c++ -*- */</tt> at the top of .h files if they are indeed C++. Feel free to add similar magic for your editor.

* Please match indentation, spacing, and brace styles, etc. (It is the default "gnu" style in emacs.)

* Limit direct including of other include files in .h files. I don't remember why, but it's the project's convention. (It does help with dependencies sometimes.)

=== Advice ===

* If you add a client message type, make sure to add it to check_useable(). Otherwise the server will toss the message and drop the client.

* If you add a client message type, test compiling with the --enable-old-protocol=yes configure option set.

* When handling byte-swapping, never assign the result of readNNle() to a larger variable. This is wrong. Consider a 16-bit little-endian number with two bytes ''XY'', represented as <tt>YX</tt>. read16le() returns <tt>YX</tt>, and assigned to a 32-bit number on a big-endian system, the result is <tt>00YX</tt>. A 32-bit little-endian number of value ''XY'' is '''correctly''' represented as <tt>YX00</tt>. Assigning the result of readNN() is fine, as that value is in host order. Similarly you can't writeNNle() a number stored in a smaller type, but this is a harder mistake to make.

* As a corollary, don't save anything explicitly kept little-endian in anything other than a sized int type. Don't use size_t, enum types, or anything along those lines. Especially not size_t.

* Remember that protocol changes are not to be made lightly, because it causes an incompatibility problem.

* Be very, very, careful about any changes to game server startup code in the backend. Triple-check all the logic (or more). Do not forget to take into account the client disconnecting/timing out after the request, the game server never starting, the game server shutting down as the request arrives, and everything in between.

* Before writing new DB query code or changing how current ones work, make sure to read up on the [http://pqxx.org/devprojects/libpqxx/doc/stable/html/Tutorial/ch03s07.html pqxx transactor model].

* There is a reftree.sql file in the test directory. If you are working with the DB and need a view into the trees of data the change notification routines are working with, you may find this file useful. Load it into the DB, and it adds a "reftree" function which, given a node, will generate a list of the whole tree below it by following the noderefs. The output includes node and folder type '''names''' and the information used to determine where change notifications have to be sent.

== Implementation Choices ==

Oftentimes, in a hobbyist project such as MOSS was in the beginning, there is not a lot of design documentation. MOSS had some, but most of it became obsolete as goals changed. Here are some short descriptions answering some "Why did you do it this way?" questions.

Terminology used here: the "backend" server is that process named moss_backend, which talks to the DB and handles anything needing centralized management, while "frontend" servers are everything else (auth/file/game/gatekeeper servers talking to the client, and the dispatcher listening for connections). The "backend protocol" is the protocol used between the frontend and backend servers.

; Why is there all this read32/read32le stuff?
: [[#Requirements | A networking person wrote MOSS.]] readNN() byte-swaps a little-endian value (from the protocol on the wire) to host order. writeNN() byte-swaps from host to little-endian. If you run it on a little-endian box this is a no-op. readNNle() ''doesn't'' byte-swap, returning a number of size NN in little-endian order. If you run it on a little-endian box this is a no-op. On a big-endian box these are critical. In addition, these macros/functions handle hardware that does not allow unaligned access of memory locations. At the time of release, MOSS appeared to work correctly on big-endian machines.

; Why are there two ways to write every message?
: For larger messages, the writev() syscall is considered more efficient, because less data has to be copied when crossing the user/kernel memory boundary. In other words, you save one copy of the entire contents of what you write at the price of computing and copying the set of iovecs. However, writev() won't work when you have to encrypt the data first, so for encrypted connections we have to copy the data into a buffer and then encrypt it.

; Why do the backend message classes have "little-endian" comments all over?
: The backend protocol is handled somewhat differently in MOSS. For frontend servers, any data read in and used by the server is stored in host order. But for the backend messages, the data is mostly stored in ''little-endian'' order, because the protocol is (currently!) unencrypted and I can use writev() and skip copying into a buffer. For many messages, writev() may not be better than copying, because the iovec is bigger than the data it represents. On the other hand, the actual copy into the buffer is avoided. The performance of each approach is unknown. There is no MessageQueue support for mixing the iovec and buffer strategies in a single queue based on message type.

; Why do you use a single-threaded big select loop for each game server?
: The other typical strategy would be to have a thread per client and pass messages between threads. The MultiWriterMessageQueue class was originally intended to cover that case (in addition to [[MOSS-Project_Ideas#connection_merging | others]]). But the fundamental problem with this plan is that I did not have a good portable way to wake up threads when a message is queued. It can be done, but signals are probably not the way to do it.

; Speaking of signals, why do you use them between threads instead of epoll()?
: I don't have epoll() on my development machine. Signals are the most portable. [[MOSS-Project_Ideas#libevent | Replacing the use of signals + select() with libevent]] might be the right answer because part of its goal is to work on many OSes.

; Explain the funky backend protocol numbering scheme?
: The protocol was designed to facilitate using multiple processes or servers in the backend. Thus messages have a bitmask "class" which would allow them to be quickly routed to the right location by checking the bitmask, rather than having a giant case statement to decide.

: Then, I wanted the pairs of messages to be recognizable from the number, so a message TO the backend is numbered the same the corresponding message FROM the backend, with the addition of a bit to mark which direction the message is going. Since each server knows its own identity, this bit is basically a big favor for the Wireshark dissector. Trust me, it's really nice.

: Finally, because once upon a time I knew many messages by their number, I assigned backend messages the same number as a corresponding frontend (client) message. When it made sense. We don't need to do this going forward, but we aren't allowed to change the current ones.

: There are some bits in the middle "left over". Maybe someone will need them for something creative someday!

; Why did you choose [http://www.postgresql.org/ PostgreSQL]?
: There were not a lot of differentiators between it and MySQL. But, PostgreSQL provides "triggers" -- this is a way to request that when a table is changed, the DB tells anything subscribed to the triggers about the change. I was intrigued by them, and thought they could prove useful for providing the vault node update notifications to clients (VaultNodeChanged/VaultNodeAdded/VaultNodeDeleted). Unfortunately, doing this ended up requiring at least two connections to the DB, one like the current one, and another to listen for triggers. So triggers were not used in the interest of simplicity in the backend server. Nothing else is preventing their use.

; What is up with this giant DB schema!
: First, it was a conscious decision to put as much SQL code as possible into stored procedures. This makes it so you can modify the DB functionality without recompiling the server, and it reduces the amount of data you have to push over the socket.

: The single giant table as seen in PotS, UU, and to some extent (how much exactly is unknown) MOUL/MOULa is so hard to work with. And it has scalability, relations, and clarity built right out of it. We were thinking of how to split the database load up to help with the bottleneck the DB still proved to be in MOUL. While no implementation was done for that (realistic expectations of MOSS suggest it is not needed), this did lead to the decision to experiment with splitting the table up into many tables by node type.

: There's no way to know if these design choices are more efficient, without changing the design, implementing it, and comparing the performance of the two in a like-for-like way. But it sure is a lot easier to write queries with the stored procedures and tables by node type!

; What is this new "notifier" thing in the noderefs table?
: It is the answer to the question "How do I know which client to tell about changes to this reference or referred-to node?"

: After drawing many pictures of node trees, it became clear that the "owner", coming from the client, was mostly but not really right for this. I was left with the impression that's what the "owner" field is for... but since it wasn't what I wanted I added a new one. For player trees, the notifier is the player. For age trees, it's the age, and then the DB looks up what players are interested in that age.

: I do not know how Cyan solved the problem, but this was the way to push the decision about who to tell into the DB where most of the data is. Otherwise, the backend (vault) server would have to cache all the active trees itself in order to find the answer.

; Why did you make the SDL files be in a directory tree instead of a single directory?
: The goal was to improve the age development experience. If the server loads all the SDL at startup, and you want to change the SDL because you have a new version to test, you have to restart the server. If instead, a given age's SDL is loaded at the time the game server starts up, you only need to restart the game server. I then put the files common to all ages in a "common" directory so that it is loaded once, and the data can be shared between game servers, but that is just a small optimization. If users have serious issues with this they can put ''all'' the SDL files in the common subdirectory.

; Why .mbm and .mbam files?
: I did not want the server to have to stat and checksum files all the time. File and auth files don't change much.

; Why didn't you put Python in to script Heek?
: I suspect Cyan did this. I am not a fan of embedding scripting where it is not needed, and at the time I had no reason to believe there would ever be new GameMgr types requiring the kind of dynamic rapid development that embedded scripting is good for. Still, it's in the [[MOSS-Project_Ideas#scripting | project ideas]] for those who are into that sort of thing.

== Project Ideas ==

The whole idea of this list is to provide some ideas for anyone wishing to dive
into MOSS. Sometimes a little direction helps. See [[MOSS-Project_Ideas]]. Of
course, you are not limited to this list!

[[Category:MOSS]]

MOSS/Project Ideas

2011-04-04T06:40:28Z

A'moaca':

The initial list was generated over the lengthy period of MOSS's initial
development. These project ideas mostly cover missing functionality. None of
the missing functionality is known to cause gameplay issues so these did not
really seem like bugs. These ideas are grouped by general type of change
required, and sort of by increasing approximate difficulty level and sort of by
decreasing value.

Bigger ideas, such as entirely new functionality now made possible by the
release of the client, could go here too. Be realistic, though. Remember that
protocol changes are not to be made lightly, because it causes an
incompatibility problem. It is probably better to propose large changes in
discussion format on the forums. Do not ''expect'' someone else to take up and
implement your proposal.

The whole idea of this list is to provide some ideas for anyone wishing to dive
into MOSS. Sometimes a little direction helps.

== Fix bugs ==

The bug tracker is here: https://foundry.openuru.org/jira/browse/MOSS

== Detail work (little Uru-specific knowledge required) ==

* Try disabling the Nagle algorithm on sockets. This should result in less latency to the client when small messages are involved. Make sure to test the whole game thoroughly.

* Figure out and implement a good way to use autoconf to compile in default pathnames. This would apply to the default config file, key file, moss_serv binary, and log/auth/game/file directory locations. The idea is if I say --prefix=/foo the defaults become /foo/etc/moss.cfg and so forth instead of ./etc/moss.cfg. Don't forget autoconf lets you override the etcdir, bindir, etc. separately.

* Treat SDL filenames case-insensitively. This is very annoying in Unix, since it requires using readdir() and strcasecmp() instead of just open().

* Log the PID of all forked servers in moss.log.

* See if we can switch to libevent for inter-thread communication instead of raw signals. This should be fairly portable and take advantage of the different per-OS lightweight signalling mechanisms.

* Allow ''skipping'' overlong messages (messages MOSS thinks are too big). This requires, upon catching the exception, tossing out the message, and if it has not all been read in yet, keeping track of how much more to toss in the future. The RC4 state must be updated too for the tossed message length.

* It would be nice to use atomic operations for refcounts instead of having to use (bigger, slower) mutexes for them. This does make MOSS not architecture-independent, which is part of why I have been resisting it. (See also signal handling next.)

* Signal handlers and the operations to read and reset the values in the main loops should be using atomic operations.

* Catch and handle std::bad_alloc whenever possible.

== Fairly contained changes ==

* Make it so game servers can be forked as separate processes. This helps a lot for debugging and also would help for age development, making it easier to change SDL and retest. Otherwise you have to shut down the whole frontend server or wait out the age's linger time. This work was started but not completed, and that code can be found inside <tt>FORK_GAME_TOO</tt> #ifdefs. If you do this, I suggest you consider separating <tt>FORK_GAME_TOO</tt> from <tt>FORK_ENABLE</tt> so that one could have forked game servers and *not* forked auth/file servers.

* In the getpublicagelist() SQL function, there is a comment about the 50-hood limit. The current code returns the first 50 hoods. We should return the most recently used 50 hoods. The hard part is knowing which those are. This is mostly if not wholly DB/SQL work.

* Age population limits are unimplemented. The value is in the vault, but the server does not look at it.

* Figure out how to throw out clones and SDL when a player leaves the age. Please see the "clean up clone, SDL" section in GameServer::conn_shutdown(). Right now this is full of special cases: it handles the Kemo bugs and and Quabs specially (a different thing for each). It may be that this is required for best behavior, but I still feel like I've missed something despite heavy scrutiny of the data. This is more of a research project and not much of a code project.

* MOUL parsed SDL nodes on the way into the vault. It probably only updated the node with fields having the Dirty bit set. In addition it added timestamps to the fields because the client does not put in the timestamps (reasonably so, as its time may be wrong). MOSS currently saves the SDL wholesale. This basically works, but with the timestamps properly added, the game server can merge the vault, age, and global SDL in any order and without strange rules. Note: if you do this, you also need to write a script or some other way to update all the SDL nodes in existing MOSS DBs.

* The kickable SDL filtering algorithm is the same one I put in Alcugs ages ago. It is better than nothing but not as good as Plasma's. You will see more warping of kickables than with Cyan's server. This project is to come up with a better way of deciding what physical SDL to send to all the clients, based on those messages all the clients are sending to the server.

* The server is probably supposed to use RelevanceRegion information to avoid sending SDL updates to clients who don't share a relevance region with the originating client. (The idea being to reduce network traffic, since hopefully the client already avoids rendering/physics on things in irrelevant regions.) Things work if the server doesn't filter, so MOSS doesn't. Also, I do not have strong evidence to believe this supposition is actually correct. Which is the other reason MOSS doesn't do it. Finding out, and implementing it if so, would be a nice project.

* Figure out what the server is supposed to do with plSetNetGroupIDMsg and do it. Right now MOSS just drops it to no apparent ill effect. I am deeply suspicious of this message due to seeing it at aurally unpleasant times in UU. (Old, old notes: "may have to do with infinitely looping scraping noises".)

* <tt>kCli2Auth_SendFriendInviteRequest</tt> is not fully supported (it is dropped on the floor).

== Bigger changes ==

* The following messages are unimplemented.
** <tt>kCli2Auth_VaultSetSeen</tt> -- unimplemented in client
** <tt>kCli2Auth_ScoreDelete</tt> -- never saw one, so couldn't implement it
** <tt>kCli2Auth_ScoreSetPoints</tt> -- never saw one, so couldn't implement it
** <tt>kCli2Auth_ScoreGetRanks</tt> -- never saw one, so couldn't implement it
** <tt>kCli2Csr_PingRequest</tt> -- no recorded Csr messages
** <tt>kCli2Csr_RegisterRequest</tt>
** <tt>kCli2Csr_LoginRequest</tt>
** <tt>kCsr2Cli_PingReply</tt>
** <tt>kCsr2Cli_RegisterReply</tt>
** <tt>kCsr2Cli_LoginReply</tt>

* Add hood randomization to DRC hoods. Player-created hoods are randomized by the Python in the Nexus when the hood is created. DRC hoods, however, are created by the server. In MOSS's case, they are created entirely by SQL code. So adding DRC hood randomization means noticing when the DB has created a new DRC hood, creating and modifying SDL in the backend, and then finding and modifying the age SDL node for that new hood. All before responding to the client creating the new avatar and thus the new DRC hood.

* The MessageQueue class has a concept of priorities. The idea was to enable dropping of lower-priority messages if a queue to a given client starts to back up. (The lowest priority being voice chat, then avatar movements, with world state changes being highest.) The measurement of queue length or throughput necessary for that is not implemented. So, neither is the dropping. (There is the very beginnings of some if <tt>DO_PRIORITIES</tt> is #defined.) As such, queue users don't do a good job of priority-setting, although VOICE and FRONT are properly used. The idea wasn't to order the queue (except for FRONT), but to skip sending, say, a VOICE message when we encounter one, if the queue congestion measure says to.

* '''Vault security'''
: The MOSS vault is as insecure as the MOUL vault. Need I say more? Here are some starter thoughts.
:* MOSS should parse incoming SDL messages and sanity-check them. See also [[#SDL_timestamps | adding timestamps]].
:* MOSS could probably verify other blob contents too.
:* Anyone can save anything to any node, and can fetch any node if they know its type and ID. We can deny these requests if the user shouldn't have access. Possibly [[MOSS-Developer_Notes#notifier | the notifier field]] can help.
:* Much more, I'm sure. Better vault security ''is'' possible.

* Eliminate excessive byteswapping of opaque server IDs in BackendMessages. This is to say, in the backend server, when reading in the messages, it byte-swaps the IDs to store them, only ever uses them in equality tests with other IDs, and then byte-swaps them back when sending new messages. (On a little-endian box there's no swapping so it does not cost much, but it's the principle of the matter.) Unfortunately this really needs to be tested on a big-endian machine.

* Try changing the File server to do [[MOSS-Setup#ackless | ackless downloads]], too. Maybe only if there is only one download at a time, though.

== Scalability issues ==

Performance and scalability are always interesting questions. And frequently ignored, because they only matter for larger installations.

These are ideas unimplemented because they only really matter for large
shards. Large as in having, let's say, 50+ concurrent '''busy''' users. (50
people standing in the city chatting doesn't actually do much.) Maybe MOSS is
okay with that number now, in which case "large" is more. It is entirely
unknown.

* Performance testing. Instrumentation. There should be a load generator to do this. This was not high on the list during development, with a user base of 3.

* See the last paragraph in the comments at the top of FileTransaction.h about how multiple file transactions of the same file should share a single opened file.

* Allow speculative pre-caching of AgeInfoNodes and PlayerInfoNodes when node changed notifications come from the vault server and are forwarded to any connected client. Cache in the auth server, vault server, or both. The goal is to reduce latency on those requests the client freezes for.

* The backend protocol supports game servers requesting batches of GameMgr IDs. However, there is no code on either side to actually do so. The idea for this was that more populated ages, like the city, would benefit from doing batch requests. Every person who links in with a marker game needs a new global game ID, and it would be nice to cut out any extra backend round trips for links, even though this particular round trip does not block the link process (aside from being something the backend is doing when it could be doing something else).

* Database performance could be measured and the SQL or even tables optimized.

* MOSS currently uses a single blocking connection to the DB. Implement and investigate performance of multiple DB connections, or asynchronous ones. Maybe the backend server has to become threaded to gain the best advantage.

* In a big shard, we may need to split the backend server work up. The [[MOSS-Developer_Notes#backend_typecodes | backend protocol]] is designed to support separating backend work between threads. The "classes" of backend messages in a bitfield are meant as a way to quickly route a backend message to an appropriate backend thread or process.

== Frontend/backend interactions ==

* Add encryption to the backend protocol. This itself is not a big deal (though you have to pick a good key negotiation, and do not forget to consider authentication mechanisms), but it does mean all the BackendMessage fill_buffer() code paths would be newly exercised, so a lot of regression testing would be in order.

* It would be much easier on the DB if updates to markers are batched by the game server. This especially applies to capturing markers. See the comments in the setmarkerto() and startmarkergame() SQL functions.

* The backend protocol allows for frontends hosting ages to specify only a subset of ages that can be hosted there. This is unused right now; the message has a field saying, "this is the length of the following age restriction list" and it is always zero. When there are no restrictions the backend can request any frontend to host any age.
** The need for splitting hostable ages is unclear, but in a very large shard you might, for example, put all city instances, or even only the public one, on a separate server. It would also allow someone to join a shard and host just their own age, or whatever.
** Since the frontend never sends restrictions, the backend currently has no way to store and use them. So there is work on both sides.
** Presumably which ages a frontend server can host would be a configuration option but it could be done instead by restricting the contents of the game/age directory. That would not allow even finer-grained restrictions, but this whole project kind of needs a real use case to flesh out what is needed.

* Having one backend TCP connection per frontend server is probably not a good thing, in terms of efficiency, or of scalability with a cluster of machines. We could change it to have one backend connection per frontend ''process'' and funnel everything through it. The mostly-implemented but unused and untested MultiWriterMessageQueue was meant, in part, to support this (there are multiple threads writing, but only one thread reading, which writes to the socket).

: Then when messages are received in the frontend there needs to be some way of passing the message to the right thread and signaling them something is present to be handled. This is all unimplemented but the format of the backend messages is meant to take care of this case (in particular, the two "server IDs" in the header are for dispatching messages to the correct thread).

: However, essentially the same changes would be necessary if the backend server is folded into the main server so there is only one process; then "sending" messages to the backend server is just putting them on the (shared) queue that would have been used to funnel everything through one connection, and "receiving" them is just taking them off that queue since there's no TCP connection to deal with.

== New functionality ==

* I am guessing Cyan's server handles the GameMgr stuff with server-side scripting. At the time MOSS was implemented there was no expectation that new game types may be added so adding in a scripting language was not worth the problems incumbent with doing so. Also the overall value of scripting is not clear (especially for the cost in server complication). However, it could be done. The project would have to include embedding the scripting and then rewriting stuff using scripts.
: Please note, a lot of effort went into getting the Heek right, handling ties, allowing people to accidentally stand up and sit back down in the game, and probably other details I forgot. If you want to script Heek, it really ought to still work as well.

* Really adventurous hardcore project: destroy KI hacks. The server would have to be able to analyze all game traffic to decide whether it looks okay. To do it right the server would have to have and understand PRP files and do physics. Also "console" commands have to be wisely filtered. If you're daunted, join the club.

== Redesigns ==

[[Category:MOSS]]

MOSS/Distribution Specific Instructions

2011-04-04T06:39:54Z

A'moaca':

MOSS/Setup

2011-04-04T06:39:30Z

A'moaca':

MOSS currently only runs on Unix. Not Windows. It ought to work on Mac OS/X
(even PowerPC) but nobody has tried yet.

Please also see the
[http://foundry.openuru.org/fisheye/browse/MOSS/doc/setup main setup instructions].

== Compile ==

=== Prerequisites ===

Before you start, 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)
* 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
* gcc, g++, whatever all you need for compiling C++

If you are compiling from a clone of an Hg respository and there is no
"configure" script, you also need the autotools:
* autoconf
* automake
* libtool

'''If you are reading this, please go over to'''
[[MOSS-Distribution_Specific_Instructions]] '''and fill in how to install all
that 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 set up the server to match the
way Cyan's works. Here are the options you are probably interested in:
; --prefix
: Specify 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 [[MOSS-Notes#RSA | 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".

Install the postgres module in your postgres install. 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 if it's not there already. 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. It 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 my 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_Files | configuration file]]. Make sure to use the 'UTF8'
encoding. Then create the user in the new database. If you want to use a
different username, you will have to edit the moss.sql file to match. 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 postgres -f moss.sql"
After this, you can connect to the database as the "moss" user:
pgql -U moss

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

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, but the
Minkata one is still broken.

== 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 | configuration files]]; you may find it easiest to
specify absolute paths (starting with "/") there.

=== 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
manifets MOSS needs. This seems a reasonable assumption when the client itself
is a Windows app.

Copy support/ManifestCreator.exe and support/Mainfests.zip to your Windows
install. Unzip Manifests.zip. This will make a "CyanStructure" folder. The .txt
files in this folder are input. They describe the files which need to be in the
final manifests.

Start up ManifestCreator. To generate a manifest, click "Make Manifest" and it
brings up a dialog. Navigate to the CyanStructure folder, and select all the
.txt files there. Then click OK and when it pops up a 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 which will run MOSS, create a file server directory. The
default is "./file" (relative to where you start it up). I recommend you make
it ''prefix''/file, where ''prefix'' is the installed location. Copy all the
.mbm files created in the CyanStructure folder to this directory. If you are
serving up a CWE client (built from open source) you will 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, also should be copied. Make sure to match the
directory structures when copying them over.

Finally, 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.exe and the support/macExternal.txt file.

=== Auth Server Data ===

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

A script automating all the following steps in this section is in the works.

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
[http://assets.openuru.org/cyan/AuthFiles.zip 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 with contains one
line per file in the SDL directory. The lines look like
"SDL\BaronCityOffice.sdl". I just toss these in the auth/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 will also create the files. 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 ===

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.

A script automating all the following steps in this section is in the works.

The game servers need unencrypted .sdl and .age files. The easiest way to get a
set of these files is from the Cyan-provided
[http://assets.openuru.org/cyan/Scripts.zip 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 serer 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.

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-Helman 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 which will be 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 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 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 auth_key.bin

If you're compiling a CWE client, make_cyan_dh does not currently output data
in that format. See [https://foundry.openuru.org/jira/browse/MOSS-3 the bug]
for the workaround. If you're not compiling a client, 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".

Do the same 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 for 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:
<tt>auth_download_dir</tt>, <tt>auth_key_file</tt>, <tt>file_download_dir</tt>,
<tt>game_data_dir</tt>, <tt>game_key_file</tt>,
<tt>gatekeeper_key_file</tt>. In addition I recommend you set <tt>log_dir</tt>
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
<tt>pid_file</tt> 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
<tt>external_address</tt>.

For moss_backend.cfg look especially into <tt>log_dir</tt> and
<tt>pid_file</tt>. In addition, depending on how your DB is
[[#Set_Up_the_Database | set up]] you likely need to specify <tt>db_user</tt>,
and maybe other DB parameters.

== Security Considerations ==

'''Please''' read about them at the end of
[http://foundry.openuru.org/fisheye/browse/MOSS/doc/setup doc/setup].

Do not run MOSS as root.

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

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

* 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 [http://assets.openuru.org/cyan/Scripts.zip original source]. If you modify it for any reason, you must make your changes available.

* If you are providing client executables from a CWE build:
** You must add the GPL license file to the client install. This means you'll have to add it to ThinExternal.txt and generate a new .mbm file, copying the .mbm file and LICENSE.txt.gz over to the appropriate locations.
** You must provide a way to acquire the source for your client. If you use an unmodified version you should be able to link to the repository (make sure you point to the 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.
** Unless someone changes the jpeg library again, you need to credit IJG for jpeglib. 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:
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. I would put links to a copy of the
files on your shard's home page or something.

See also [[CyanWorlds.com_Engine/FAQ#What_are_my_open_source_license_.28GPLv3.29_responsibilities_as_a_user.2C_developer_or_server_operator_.28e.g._shard_owner.29.3F | 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 ==

Now you should be set to run your server. Hopefully someone will contribute a
nice startup script. 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:
bin/moss_backend
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.

== Create Accounts ==

Don't forget to create accounts for your users, or it will be difficult to log
in... Please just refer directly to
[http://foundry.openuru.org/fisheye/browse/MOSS/doc/user-management doc/user-management].

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

== More Hints ==

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

* [[MOSS-Notes]]
* [http://foundry.openuru.org/fisheye/browse/MOSS/doc/running doc/running]

[[Category:MOSS]]

MOSS

2011-04-04T06:39:04Z

A'moaca':

MOSS is a unix-based server for the Myst Online: Uru Live client. Development
began after the announcement of the shutdown of MOUL. It is complete enough to
play the entire game, supports multiplayer use, is licensed under GPLv3, and is
not ported to Windows.

MOSS was developed by a'moaca' and cjkelly1. a'moaca' wrote all the C/C++ code,
and cjkelly1 wrote most of the SQL code, including doing research to determine
how to set up the vault. cjkelly1 wrote a tool to create the manifest files
required by the server, and also made the invaluable contribution of a lot of
testing over the years. Weldergeek helped with some of the multiplayer testing,
especially Heek. a'moaca' sincerely hopes there will be more contributors now
that MOSS is released.

== Why Use MOSS? ==

If you just want to host a private shard, MOSS should serve your purposes. Do
be sure to consult [[MOSS-Setup#Before You Open Your Server]] for some help on
what you need to do if you host an Uru shard.

The server definitely works with the [[CyanWorlds.com_Engine | CWE client]]! If
you are thinking of doing client development you will probably find a server
that is not MOULagain to test with quite valuable. (MOSS was also tested with
PlasmaClient, but it does not fully work for PlasmaClient because it does some
things that a'moaca' argues are bugs from the system perspective. Let's fix
PlasmaClient.)

The server has some features meant to help make it a little easier to test ages
you are creating. The SDL files for an age are loaded each time the age is
started up so you can change them without restarting MOSS. There is full
support for multiple .pak files. So, run your own server, test at your own
pace. Test in the CWE client and not the PotS one.

== How to Get It ==

{{tba}}

The source code is hosted in a Mercurial repository here at OpenUru.org.
You can clone (download) a copy of the repository using Mercurial, or you can
use a snapshot. If you are considering making changes to the code, you will
probably prefer using the version control. If you just want to compile and run
a server, a snapshot should do. In addition, a compiled version is
available for the TBD platform.

If you are new to Mercurial, you may want to check the
[http://mercurial.selenic.com/wiki/QuickStart QuickStart]. There are links to
more complete documentation at the bottom. The Foundry is secured via SSL
throughout the site. A browser security certificate is needed. Instructions are
available on the [[Foundry_Certificate_Installation | certificate installation
page]].

'''Repository address:''' https://foundry.openuru.org/hg/MOSS

'''Snapshot location:''' TBD

'''Binary package:''' TBD

== How to Set Up a Server ==

The [http://foundry.openuru.org/fisheye/browse/MOSS/doc/setup setup] file
contains a complete set of installation instructions. They do assume you are
conversant with setting up software and basic management of a database. For
additional setup instructions, see [[MOSS-Setup]]. Feel free to add any hints
specific to your distribution [[MOSS-Distribution_Specific_Instructions | here]].

Cyan has provided a copy of the files needed for a server hosting MOUL content.
The .sdl, .age, and Python source are all available at
http://assets.openuru.org/cyan/Scripts.zip. If you are not interested in
compiling your own Python from this source, you can also get a copy of the
compiled Python from http://assets.openuru.org/cyan/AuthFiles.zip.

== How to Contribute ==

Contributing to the wiki pages is welcome. Adding extra setup instructions, or
adding documentation about how MOSS works, are two good examples. It's a wiki,
please contribute anything you think others might want to read.

Almost any code contribution is welcome. What is unwelcome? Protocol/behavior
changes without corresponding client support (obviously). Changes that remove
security without the option of keeping it. Changes that introduce security
holes, either in the server itself or the vault. Changes that break big-endian
support (call it a pet peeve if you like, it's still unwelcome). Changes that
break the build (accidents do happen, but don't break it on purpose). Hopefully
it is not difficult to see why these things are unwelcome.

If you find a bug, please report it. Please, please, please search first to see
if it's already reported. The bug tracker is here:
https://foundry.openuru.org/jira/browse/MOSS

If you find a bug and fix it, include the patch with the bug report! This
increases the chances of it getting fixed rather a lot.

Bug fixes are very valuable.
[https://foundry.openuru.org/jira/browse/MOSS Grab a bug] and fix it! Check
out [[MOSS-Project_Ideas]] for more ideas.

If you want to add a feature or change something, you can file a feature
request or task bug to get your change considered for the
[https://foundry.openuru.org/hg/MOSS central repository].

If you want write access to the central repository, contribute. I think the
best for MOSS will be to use similar standards for determining who is given
write access as CWE. At this time that's undecided, so I leave MOSS equally
undecided. However, MOSS's original author is more involved than CWE's so if
only a couple people show up to help then it's pretty clear a couple people
will get write access soon enough!

Code reviewers might be needed. If you are willing to be a reviewer, say so! It
is a very valuable contribution.

== See Also ==

[[MOSS-Setup]]

[[MOSS-Developer_Notes]]

[[CyanWorlds.com_Engine]]

[[Category:MOSS]]

MOSS/Project Ideas

2011-04-04T06:36:52Z

A'moaca': Created page with "The initial list was generated over the lengthy period of MOSS's initial development. These project ideas mostly cover missing functionality. None of the missing functionality is..."

The initial list was generated over the lengthy period of MOSS's initial
development. These project ideas mostly cover missing functionality. None of
the missing functionality is known to cause gameplay issues so these did not
really seem like bugs. These ideas are grouped by general type of change
required, and sort of by increasing approximate difficulty level and sort of by
decreasing value.

Bigger ideas, such as entirely new functionality now made possible by the
release of the client, could go here too. Be realistic, though. Remember that
protocol changes are not to be made lightly, because it causes an
incompatibility problem. It is probably better to propose large changes in
discussion format on the forums. Do not ''expect'' someone else to take up and
implement your proposal.

The whole idea of this list is to provide some ideas for anyone wishing to dive
into MOSS. Sometimes a little direction helps.

== Fix bugs ==

The bug tracker is here: https://foundry.openuru.org/jira/browse/MOSS

== Detail work (little Uru-specific knowledge required) ==

* Try disabling the Nagle algorithm on sockets. This should result in less latency to the client when small messages are involved. Make sure to test the whole game thoroughly.

* Figure out and implement a good way to use autoconf to compile in default pathnames. This would apply to the default config file, key file, moss_serv binary, and log/auth/game/file directory locations. The idea is if I say --prefix=/foo the defaults become /foo/etc/moss.cfg and so forth instead of ./etc/moss.cfg. Don't forget autoconf lets you override the etcdir, bindir, etc. separately.

* Treat SDL filenames case-insensitively. This is very annoying in Unix, since it requires using readdir() and strcasecmp() instead of just open().

* Log the PID of all forked servers in moss.log.

* See if we can switch to libevent for inter-thread communication instead of raw signals. This should be fairly portable and take advantage of the different per-OS lightweight signalling mechanisms.

* Allow ''skipping'' overlong messages (messages MOSS thinks are too big). This requires, upon catching the exception, tossing out the message, and if it has not all been read in yet, keeping track of how much more to toss in the future. The RC4 state must be updated too for the tossed message length.

* It would be nice to use atomic operations for refcounts instead of having to use (bigger, slower) mutexes for them. This does make MOSS not architecture-independent, which is part of why I have been resisting it. (See also signal handling next.)

* Signal handlers and the operations to read and reset the values in the main loops should be using atomic operations.

* Catch and handle std::bad_alloc whenever possible.

== Fairly contained changes ==

* Make it so game servers can be forked as separate processes. This helps a lot for debugging and also would help for age development, making it easier to change SDL and retest. Otherwise you have to shut down the whole frontend server or wait out the age's linger time. This work was started but not completed, and that code can be found inside <tt>FORK_GAME_TOO</tt> #ifdefs. If you do this, I suggest you consider separating <tt>FORK_GAME_TOO</tt> from <tt>FORK_ENABLE</tt> so that one could have forked game servers and *not* forked auth/file servers.

* In the getpublicagelist() SQL function, there is a comment about the 50-hood limit. The current code returns the first 50 hoods. We should return the most recently used 50 hoods. The hard part is knowing which those are. This is mostly if not wholly DB/SQL work.

* Age population limits are unimplemented. The value is in the vault, but the server does not look at it.

* Figure out how to throw out clones and SDL when a player leaves the age. Please see the "clean up clone, SDL" section in GameServer::conn_shutdown(). Right now this is full of special cases: it handles the Kemo bugs and and Quabs specially (a different thing for each). It may be that this is required for best behavior, but I still feel like I've missed something despite heavy scrutiny of the data. This is more of a research project and not much of a code project.

* MOUL parsed SDL nodes on the way into the vault. It probably only updated the node with fields having the Dirty bit set. In addition it added timestamps to the fields because the client does not put in the timestamps (reasonably so, as its time may be wrong). MOSS currently saves the SDL wholesale. This basically works, but with the timestamps properly added, the game server can merge the vault, age, and global SDL in any order and without strange rules. Note: if you do this, you also need to write a script or some other way to update all the SDL nodes in existing MOSS DBs.

* The kickable SDL filtering algorithm is the same one I put in Alcugs ages ago. It is better than nothing but not as good as Plasma's. You will see more warping of kickables than with Cyan's server. This project is to come up with a better way of deciding what physical SDL to send to all the clients, based on those messages all the clients are sending to the server.

* The server is probably supposed to use RelevanceRegion information to avoid sending SDL updates to clients who don't share a relevance region with the originating client. (The idea being to reduce network traffic, since hopefully the client already avoids rendering/physics on things in irrelevant regions.) Things work if the server doesn't filter, so MOSS doesn't. Also, I do not have strong evidence to believe this supposition is actually correct. Which is the other reason MOSS doesn't do it. Finding out, and implementing it if so, would be a nice project.

* Figure out what the server is supposed to do with plSetNetGroupIDMsg and do it. Right now MOSS just drops it to no apparent ill effect. I am deeply suspicious of this message due to seeing it at aurally unpleasant times in UU. (Old, old notes: "may have to do with infinitely looping scraping noises".)

* <tt>kCli2Auth_SendFriendInviteRequest</tt> is not fully supported (it is dropped on the floor).

== Bigger changes ==

* The following messages are unimplemented.
** <tt>kCli2Auth_VaultSetSeen</tt> -- unimplemented in client
** <tt>kCli2Auth_ScoreDelete</tt> -- never saw one, so couldn't implement it
** <tt>kCli2Auth_ScoreSetPoints</tt> -- never saw one, so couldn't implement it
** <tt>kCli2Auth_ScoreGetRanks</tt> -- never saw one, so couldn't implement it
** <tt>kCli2Csr_PingRequest</tt> -- no recorded Csr messages
** <tt>kCli2Csr_RegisterRequest</tt>
** <tt>kCli2Csr_LoginRequest</tt>
** <tt>kCsr2Cli_PingReply</tt>
** <tt>kCsr2Cli_RegisterReply</tt>
** <tt>kCsr2Cli_LoginReply</tt>

* Add hood randomization to DRC hoods. Player-created hoods are randomized by the Python in the Nexus when the hood is created. DRC hoods, however, are created by the server. In MOSS's case, they are created entirely by SQL code. So adding DRC hood randomization means noticing when the DB has created a new DRC hood, creating and modifying SDL in the backend, and then finding and modifying the age SDL node for that new hood. All before responding to the client creating the new avatar and thus the new DRC hood.

* The MessageQueue class has a concept of priorities. The idea was to enable dropping of lower-priority messages if a queue to a given client starts to back up. (The lowest priority being voice chat, then avatar movements, with world state changes being highest.) The measurement of queue length or throughput necessary for that is not implemented. So, neither is the dropping. (There is the very beginnings of some if <tt>DO_PRIORITIES</tt> is #defined.) As such, queue users don't do a good job of priority-setting, although VOICE and FRONT are properly used. The idea wasn't to order the queue (except for FRONT), but to skip sending, say, a VOICE message when we encounter one, if the queue congestion measure says to.

* '''Vault security'''
: The MOSS vault is as insecure as the MOUL vault. Need I say more? Here are some starter thoughts.
:* MOSS should parse incoming SDL messages and sanity-check them. See also [[#SDL_timestamps | adding timestamps]].
:* MOSS could probably verify other blob contents too.
:* Anyone can save anything to any node, and can fetch any node if they know its type and ID. We can deny these requests if the user shouldn't have access. Possibly [[MOSS-Developer_Notes#notifier | the notifier field]] can help.
:* Much more, I'm sure. Better vault security ''is'' possible.

* Eliminate excessive byteswapping of opaque server IDs in BackendMessages. This is to say, in the backend server, when reading in the messages, it byte-swaps the IDs to store them, only ever uses them in equality tests with other IDs, and then byte-swaps them back when sending new messages. (On a little-endian box there's no swapping so it does not cost much, but it's the principle of the matter.) Unfortunately this really needs to be tested on a big-endian machine.

* Try changing the File server to do [[MOSS-Setup#ackless | ackless downloads]], too. Maybe only if there is only one download at a time, though.

== Scalability issues ==

Performance and scalability are always interesting questions. And frequently ignored, because they only matter for larger installations.

These are ideas unimplemented because they only really matter for large
shards. Large as in having, let's say, 50+ concurrent '''busy''' users. (50
people standing in the city chatting doesn't actually do much.) Maybe MOSS is
okay with that number now, in which case "large" is more. It is entirely
unknown.

* Performance testing. Instrumentation. There should be a load generator to do this. This was not high on the list during development, with a user base of 3.

* See the last paragraph in the comments at the top of FileTransaction.h about how multiple file transactions of the same file should share a single opened file.

* Allow speculative pre-caching of AgeInfoNodes and PlayerInfoNodes when node changed notifications come from the vault server and are forwarded to any connected client. Cache in the auth server, vault server, or both. The goal is to reduce latency on those requests the client freezes for.

* The backend protocol supports game servers requesting batches of GameMgr IDs. However, there is no code on either side to actually do so. The idea for this was that more populated ages, like the city, would benefit from doing batch requests. Every person who links in with a marker game needs a new global game ID, and it would be nice to cut out any extra backend round trips for links, even though this particular round trip does not block the link process (aside from being something the backend is doing when it could be doing something else).

* Database performance could be measured and the SQL or even tables optimized.

* MOSS currently uses a single blocking connection to the DB. Implement and investigate performance of multiple DB connections, or asynchronous ones. Maybe the backend server has to become threaded to gain the best advantage.

* In a big shard, we may need to split the backend server work up. The [[MOSS-Developer_Notes#backend_typecodes | backend protocol]] is designed to support separating backend work between threads. The "classes" of backend messages in a bitfield are meant as a way to quickly route a backend message to an appropriate backend thread or process.

== Frontend/backend interactions ==

* Add encryption to the backend protocol. This itself is not a big deal (though you have to pick a good key negotiation, and do not forget to consider authentication mechanisms), but it does mean all the BackendMessage fill_buffer() code paths would be newly exercised, so a lot of regression testing would be in order.

* It would be much easier on the DB if updates to markers are batched by the game server. This especially applies to capturing markers. See the comments in the setmarkerto() and startmarkergame() SQL functions.

* The backend protocol allows for frontends hosting ages to specify only a subset of ages that can be hosted there. This is unused right now; the message has a field saying, "this is the length of the following age restriction list" and it is always zero. When there are no restrictions the backend can request any frontend to host any age.
** The need for splitting hostable ages is unclear, but in a very large shard you might, for example, put all city instances, or even only the public one, on a separate server. It would also allow someone to join a shard and host just their own age, or whatever.
** Since the frontend never sends restrictions, the backend currently has no way to store and use them. So there is work on both sides.
** Presumably which ages a frontend server can host would be a configuration option but it could be done instead by restricting the contents of the game/age directory. That would not allow even finer-grained restrictions, but this whole project kind of needs a real use case to flesh out what is needed.

* Having one backend TCP connection per frontend server is probably not a good thing, in terms of efficiency, or of scalability with a cluster of machines. We could change it to have one backend connection per frontend ''process'' and funnel everything through it. The mostly-implemented but unused and untested MultiWriterMessageQueue was meant, in part, to support this (there are multiple threads writing, but only one thread reading, which writes to the socket).

: Then when messages are received in the frontend there needs to be some way of passing the message to the right thread and signaling them something is present to be handled. This is all unimplemented but the format of the backend messages is meant to take care of this case (in particular, the two "server IDs" in the header are for dispatching messages to the correct thread).

: However, essentially the same changes would be necessary if the backend server is folded into the main server so there is only one process; then "sending" messages to the backend server is just putting them on the (shared) queue that would have been used to funnel everything through one connection, and "receiving" them is just taking them off that queue since there's no TCP connection to deal with.

== New functionality ==

* I am guessing Cyan's server handles the GameMgr stuff with server-side scripting. At the time MOSS was implemented there was no expectation that new game types may be added so adding in a scripting language was not worth the problems incumbent with doing so. Also the overall value of scripting is not clear (especially for the cost in server complication). However, it could be done. The project would have to include embedding the scripting and then rewriting stuff using scripts.
: Please note, a lot of effort went into getting the Heek right, handling ties, allowing people to accidentally stand up and sit back down in the game, and probably other details I forgot. If you want to script Heek, it really ought to still work as well.

* Really adventurous hardcore project: destroy KI hacks. The server would have to be able to analyze all game traffic to decide whether it looks okay. To do it right the server would have to have and understand PRP files and do physics. Also "console" commands have to be wisely filtered. If you're daunted, join the club.

== Redesigns ==

MOSS/Developer Notes

2011-04-04T06:34:37Z

A'moaca': Created page with "Comments of interest to those working with the MOSS code should go here. If you plan to just run a server and not modify it, you don't need to be here. == Working with the Code..."

Comments of interest to those working with the MOSS code should go here. If
you plan to just run a server and not modify it, you don't need to be here.

== Working with the Code ==

=== Requirements ===

* Handle byte-swapping. A networking person wrote MOSS, and such people care about working with both endiannesses. Do not break it.

* This does mean you cannot drop in someone else's code handling the MOUL protocol if it assumes you are using a little-endian machine. This is '''the''' reason for not casting incoming byte data to structs and writing out structs.

* Including "config.h" should always look like this:
#ifdef HAVE_CONFIG_H
#include "config.h"
#endif

=== Code Conventions ===

* Keep C++-style comments out of preprocessor lines.

* Keep code to 78 columns whenever possible.

* Include (.h) files have comments at the top listing which other include files are required before including this file. (Some may be missing but I tried.)

* I use emacs. Please keep the <tt>/* -*- c++ -*- */</tt> at the top of .h files if they are indeed C++. Feel free to add similar magic for your editor.

* Please match indentation, spacing, and brace styles, etc. (It is the default "gnu" style in emacs.)

* Limit direct including of other include files in .h files. I don't remember why, but it's the project's convention. (It does help with dependencies sometimes.)

=== Advice ===

* If you add a client message type, make sure to add it to check_useable(). Otherwise the server will toss the message and drop the client.

* If you add a client message type, test compiling with the --enable-old-protocol=yes configure option set.

* When handling byte-swapping, never assign the result of readNNle() to a larger variable. This is wrong. Consider a 16-bit little-endian number with two bytes ''XY'', represented as <tt>YX</tt>. read16le() returns <tt>YX</tt>, and assigned to a 32-bit number on a big-endian system, the result is <tt>00YX</tt>. A 32-bit little-endian number of value ''XY'' is '''correctly''' represented as <tt>YX00</tt>. Assigning the result of readNN() is fine, as that value is in host order. Similarly you can't writeNNle() a number stored in a smaller type, but this is a harder mistake to make.

* As a corollary, don't save anything explicitly kept little-endian in anything other than a sized int type. Don't use size_t, enum types, or anything along those lines. Especially not size_t.

* Remember that protocol changes are not to be made lightly, because it causes an incompatibility problem.

* Be very, very, careful about any changes to game server startup code in the backend. Triple-check all the logic (or more). Do not forget to take into account the client disconnecting/timing out after the request, the game server never starting, the game server shutting down as the request arrives, and everything in between.

* Before writing new DB query code or changing how current ones work, make sure to read up on the [http://pqxx.org/devprojects/libpqxx/doc/stable/html/Tutorial/ch03s07.html pqxx transactor model].

* There is a reftree.sql file in the test directory. If you are working with the DB and need a view into the trees of data the change notification routines are working with, you may find this file useful. Load it into the DB, and it adds a "reftree" function which, given a node, will generate a list of the whole tree below it by following the noderefs. The output includes node and folder type '''names''' and the information used to determine where change notifications have to be sent.

== Implementation Choices ==

Oftentimes, in a hobbyist project such as MOSS was in the beginning, there is not a lot of design documentation. MOSS had some, but most of it became obsolete as goals changed. Here are some short descriptions answering some "Why did you do it this way?" questions.

Terminology used here: the "backend" server is that process named moss_backend, which talks to the DB and handles anything needing centralized management, while "frontend" servers are everything else (auth/file/game/gatekeeper servers talking to the client, and the dispatcher listening for connections). The "backend protocol" is the protocol used between the frontend and backend servers.

; Why is there all this read32/read32le stuff?
: [[#Requirements | A networking person wrote MOSS.]] readNN() byte-swaps a little-endian value (from the protocol on the wire) to host order. writeNN() byte-swaps from host to little-endian. If you run it on a little-endian box this is a no-op. readNNle() ''doesn't'' byte-swap, returning a number of size NN in little-endian order. If you run it on a little-endian box this is a no-op. On a big-endian box these are critical. In addition, these macros/functions handle hardware that does not allow unaligned access of memory locations. At the time of release, MOSS appeared to work correctly on big-endian machines.

; Why are there two ways to write every message?
: For larger messages, the writev() syscall is considered more efficient, because less data has to be copied when crossing the user/kernel memory boundary. In other words, you save one copy of the entire contents of what you write at the price of computing and copying the set of iovecs. However, writev() won't work when you have to encrypt the data first, so for encrypted connections we have to copy the data into a buffer and then encrypt it.

; Why do the backend message classes have "little-endian" comments all over?
: The backend protocol is handled somewhat differently in MOSS. For frontend servers, any data read in and used by the server is stored in host order. But for the backend messages, the data is mostly stored in ''little-endian'' order, because the protocol is (currently!) unencrypted and I can use writev() and skip copying into a buffer. For many messages, writev() may not be better than copying, because the iovec is bigger than the data it represents. On the other hand, the actual copy into the buffer is avoided. The performance of each approach is unknown. There is no MessageQueue support for mixing the iovec and buffer strategies in a single queue based on message type.

; Why do you use a single-threaded big select loop for each game server?
: The other typical strategy would be to have a thread per client and pass messages between threads. The MultiWriterMessageQueue class was originally intended to cover that case (in addition to [[MOSS-Project_Ideas#connection_merging | others]]). But the fundamental problem with this plan is that I did not have a good portable way to wake up threads when a message is queued. It can be done, but signals are probably not the way to do it.

; Speaking of signals, why do you use them between threads instead of epoll()?
: I don't have epoll() on my development machine. Signals are the most portable. [[MOSS-Project_Ideas#libevent | Replacing the use of signals + select() with libevent]] might be the right answer because part of its goal is to work on many OSes.

; Explain the funky backend protocol numbering scheme?
: The protocol was designed to facilitate using multiple processes or servers in the backend. Thus messages have a bitmask "class" which would allow them to be quickly routed to the right location by checking the bitmask, rather than having a giant case statement to decide.

: Then, I wanted the pairs of messages to be recognizable from the number, so a message TO the backend is numbered the same the corresponding message FROM the backend, with the addition of a bit to mark which direction the message is going. Since each server knows its own identity, this bit is basically a big favor for the Wireshark dissector. Trust me, it's really nice.

: Finally, because once upon a time I knew many messages by their number, I assigned backend messages the same number as a corresponding frontend (client) message. When it made sense. We don't need to do this going forward, but we aren't allowed to change the current ones.

: There are some bits in the middle "left over". Maybe someone will need them for something creative someday!

; Why did you choose [http://www.postgresql.org/ PostgreSQL]?
: There were not a lot of differentiators between it and MySQL. But, PostgreSQL provides "triggers" -- this is a way to request that when a table is changed, the DB tells anything subscribed to the triggers about the change. I was intrigued by them, and thought they could prove useful for providing the vault node update notifications to clients (VaultNodeChanged/VaultNodeAdded/VaultNodeDeleted). Unfortunately, doing this ended up requiring at least two connections to the DB, one like the current one, and another to listen for triggers. So triggers were not used in the interest of simplicity in the backend server. Nothing else is preventing their use.

; What is up with this giant DB schema!
: First, it was a conscious decision to put as much SQL code as possible into stored procedures. This makes it so you can modify the DB functionality without recompiling the server, and it reduces the amount of data you have to push over the socket.

: The single giant table as seen in PotS, UU, and to some extent (how much exactly is unknown) MOUL/MOULa is so hard to work with. And it has scalability, relations, and clarity built right out of it. We were thinking of how to split the database load up to help with the bottleneck the DB still proved to be in MOUL. While no implementation was done for that (realistic expectations of MOSS suggest it is not needed), this did lead to the decision to experiment with splitting the table up into many tables by node type.

: There's no way to know if these design choices are more efficient, without changing the design, implementing it, and comparing the performance of the two in a like-for-like way. But it sure is a lot easier to write queries with the stored procedures and tables by node type!

; What is this new "notifier" thing in the noderefs table?
: It is the answer to the question "How do I know which client to tell about changes to this reference or referred-to node?"

: After drawing many pictures of node trees, it became clear that the "owner", coming from the client, was mostly but not really right for this. I was left with the impression that's what the "owner" field is for... but since it wasn't what I wanted I added a new one. For player trees, the notifier is the player. For age trees, it's the age, and then the DB looks up what players are interested in that age.

: I do not know how Cyan solved the problem, but this was the way to push the decision about who to tell into the DB where most of the data is. Otherwise, the backend (vault) server would have to cache all the active trees itself in order to find the answer.

; Why did you make the SDL files be in a directory tree instead of a single directory?
: The goal was to improve the age development experience. If the server loads all the SDL at startup, and you want to change the SDL because you have a new version to test, you have to restart the server. If instead, a given age's SDL is loaded at the time the game server starts up, you only need to restart the game server. I then put the files common to all ages in a "common" directory so that it is loaded once, and the data can be shared between game servers, but that is just a small optimization. If users have serious issues with this they can put ''all'' the SDL files in the common subdirectory.

; Why .mbm and .mbam files?
: I did not want the server to have to stat and checksum files all the time. File and auth files don't change much.

; Why didn't you put Python in to script Heek?
: I suspect Cyan did this. I am not a fan of embedding scripting where it is not needed, and at the time I had no reason to believe there would ever be new GameMgr types requiring the kind of dynamic rapid development that embedded scripting is good for. Still, it's in the [[MOSS-Project_Ideas#scripting | project ideas]] for those who are into that sort of thing.

== Project Ideas ==

The whole idea of this list is to provide some ideas for anyone wishing to dive
into MOSS. Sometimes a little direction helps. See [[MOSS-Project_Ideas]]. Of
course, you are not limited to this list!

MOSS/Notes

2011-04-04T06:32:43Z

A'moaca': Created page with "This page just holds various notes about running a MOSS server. == Questions == I can't really call this a FAQ until the questions have been asked frequently. ; How do I add ..."

This page just holds various notes about running a MOSS server.

== Questions ==

I can't really call this a FAQ until the questions have been asked frequently.

; How do I add a user?
: [[MOSS-Setup#Create_Accounts]]
; How do I change the Python?
: Start with the source Cyan has generously provided us under the GPL. To compile that source you'll have to add in the glue. Maybe there is a tool do that in the CWE source. Make your changes. After compiling and creating the .pak (another tool?), copy the .pak to the [[MOSS-Setup#Auth_Server_Data | correct server directory]] and encrypt it. Make a new .mbam file.
; How do I add a new age?
: Copy the encrypted .pak to the [[MOSS-Setup#Auth_Server_Data | correct server directory]], add the file to the Python.txt, and make a new .mbam file. Copy any SDL files to the auth SDL directory and encrypt them. Copy unencrypted SDL files to the [[MOSS-Setup#Game_Server_Data | correct server directory]]. Note if you have more than one SDL file for your age, or the file is not named the same as the age, you'll need to put the age's SDL file(s) in a directory named after the age. Copy the unencrypted .age file to the game server directory.
; Why would I use --enable-fork?
: This is primarily useful for testing. It's easier to debug a non-threaded process.
; What resource limitations are there (file descriptors, memory, etc.)?
: This is a question that's not obvious to answer. But here is what is known:
:* Currently MOSS uses about 5 file descriptors when idle. It uses about 10 per connected user. (4 are for the game server, so if the user links around a lot, it will be more, and if you have multiple users in one age it will be less.) If you are running a large shard, you may need to adjust per-process file descriptor limits (see the "ulimit" command) or even kernel (global) limits. If you adjust the global limit, pay attention to <tt>FD_SETSIZE</tt>. See the select() man page.
:* Currently MOSS uses 7 big buffers for network data per connected user. The buffer size is set by <tt>BUFSIZE</tt> in constants.h. The default is 64k, so a total of 448k per user. If you have enough users that your moss processes grow too large you can reduce the <tt>BUFSIZE</tt>.
:* There is not a lot of disk I/O, except for whatever the database has to write. If you set the log levels very low (DEBUG or worse, MSGS) then there will be a lot of I/O for log files.
; Does MOSS work on my Power PC?
: It is supposed to! Testing of big-endian systems was done, but not a full, complete run-through of all game mechanics and multiplayer testing. If it does not work, [[MOSS#How_to_Contribute | it's a bug]].
; Does MOSS work on Windows? OS X?
: Not Windows. There is a fair bit of porting work to do. OS/X theoretically works but nobody has tried yet. (If you try and it works, fix this!)
; What is the "status" server type?
: MOSS will provide the status string normally fetched from a web server. You do have to make the client send the HTTP request to port 14617 or it won't do much good. This is a feature that perhaps only the author wants.

== Warnings ==

* Please note: The MOSS vault is as insecure as MOUL's. (I don't know what was done to MOULagain.) The MOSS server is almost as trusting of the client as MOUL's. (Or maybe more, in other ways; for example, there is no server-side profanity filter.) This is because a MOUL server was implemented, not some other server. Doing better is definitely possible. But to do it right is a very big project, because the entire ''system'' was designed with this trust model. You can't always change just one part of it to get where you want to be.

* Don't change the .mbm or file server files while you have clients doing File transactions. Doing so will give everything indigestion.

* I'm sure the same applies for .mbam and auth server files.

* The SDL mechanism depends on all servers in the shard having synchronized time. Use NTP if you have more than one server. (You'll also need to NFS mount the game/state directory on all the servers so the age SDL is available to all.)

== Setup Choices ==

* Disabling the client<->server encryption is NOT recommended. However, if you subscribe to the shortsighted idea that protecting your users is not important, go ahead. But be warned, there are code paths in MOSS that are completely untested when all encryption is disabled. You'll have to fix any bugs. (The Wireshark plugin does support decrypting connections when you have the key, so you ''can'' use encrypted connections during development/testing.)

* MOSS supports using RSA for key negotiation. The client contribution to the session key is RSA-encrypted with the server public key and then sent to the server, which decrypts the message. Ironically, this actually is less crypto work, while using a non-modified standard encryption technology. And it has the same pseudo-authentication properties as the Cyan-style modified Diffie-Hellman. The assembler changes required for this are astonishingly small, but there's not much value in using RSA. Nonetheless, there's no need to remove working server support for it...

== While Running the Server ==

* You can change age SDL state server-side by modifying the state saved in files in the game/state directory. Keeping backups is advised. You may modify the files with the "sdl_reader" program (which you need to build separately using "make sdl_reader"). This is a very simple command-line program. Use the -l option to specify a saved file to read. When in the program, use the "h" command to see the help. Saving this file while a game server for that age is running is pointless; the new version won't be read and it will be overwritten when the server exits.

== Client Bug Workarounds ==

MOSS works around a few client bugs.

* MOSS "fixes" the KI light bug. It is a bug in the PRP files. MOSS has an extra check for determining whether SDL state is avatar-related, instead of relying on the flag that says whether to keep the SDL state around. That check covers the KI light, so the light SDL is tossed along with the rest of avatar SDL when a person leaves an age.

* MOSS may "fix" the footstep region bug. This bug is when you get the wrong footstep sound stuck, like that wooden bridge you left long ago clumping around while you're on stone. Everyone in the age hears the wrong footstep sounds. I believe that in normal play (that is, without things like /spawn) it is due to a race with the exclusive locking mechanism used to keep things like multiple button presses from being processed at the same time. Why footstep regions take a server-side exclusive lock is beyond me**, so MOSS grants '''all''' footstep region lock requests. This should make the problem occur less frequently, if at all (depending on how the client actually responds to receiving the lock after leaving the region). MOSS decides you are asking for a footstep region lock by looking for the word "Footstep" in the object name. ''Do not name buttons, door regions, or whatever with "Footstep" in your new ages.'' I suggest you do name footstep regions with "Footstep". The special case can be removed by removing <tt>#define GRANT_ALL_FOOTSTEPS</tt> from GameState.cc and recompiling.
:: **In fact, as a friend of mine pointed out, why are footstep sounds decided by the represented avatar's client and propagated to everyone else in the first place? It should be a purely local decision based on the location of each avatar as seen by that client. That would save on traffic and always be accurate, never mind the race with locking on the region since there would be no need to coordinate anything for a purely local decision.

* Quab game Python is not really complete. The first person to link to the age becomes the "owner" of the quab game. The Python sort of attempts to handle the situation where the game owner leaves the age while there are still quabs around, but it does not actually handle it. If the server attempts to pass ownership to someone else, that client will break. And the current MOULagain client even crashes. So MOSS works around the problem by intentionally breaking the whole game when the owner leaves the age and quabs are still present. All the quabs will remain frozen in place until the age has been cleared of all players. The age does not have to restart to revive the game, just be empty.

* The client supports two kinds of passwords, depending on the format of the username. If the username has the format x@x.x it uses algorithm 1 (a more secure one but also one with a fencepost error), and otherwise algorithm 2. Unfortunately the /changepassword command does not know about algorithm 2 and if you logged in with algorithm 2, it will try to change your password hash to the one for algorithm 1. This would result in you being unable to log in. So MOSS rejects requests to change the password if the username does not have the x@x.x format.

== Server Non-Bugs ==

These are problems with Cyan's server that MOSS does not have.

* MOSS does not have the infamous "zero seconds remaining" bug. Thus it is possible to do the auth downloads without the server waiting for acks from the client. This speeds up the download substantially as now the bandwidth can be fully utilized. (The [[MOSS-Setup#configure | --enable-fast-download]] configure option turns this on.)

* The MOUL server has a bug with quabs in Ahnonay. If you are the first person who linked into the age, the quabs are associated with your ID. When you link out of the age, the server is supposed to send a LoadClone message telling other clients to unload your clone (the avatar). The MOUL server sends the message, but it says to unload one of the quabs with your ID in it instead of the player avatar. Oddly, the client seems just fine with that. MOSS does not have this bug.

* You should see less client hitching while moving around with MOSS. The MOUL server sends a ton of node update messages for the (unchanged) city AgeInfo node. Each node update causes the client to fetch your pellet scores. The client is frozen during this (and most any) vault transaction. The MOSS server does not send all those useless updates. Interesting note: One measurement during MOUL was approximately 400 pellet score fetches an hour. That is the client freezing every 9 seconds regardless of what age you are in or how many people are in it or on your buddy list. (The pellet score fetch itself can probably be fixed in the Python but you'd still be wasting time on the city node.)

* The pellet score freeze can be further reduced by #defining <tt>PELLET_SCORE_CACHE</tt>, which does what it sounds like: it caches the client's pellet score in the Auth server to cut out the round-trip time to the DB. However, there's little value to it without the city node update problem; when you open the KI it fetches the score but it's also fetching other vault nodes. Plus you aren't trying to move at the time so the freeze is less obvious. So <tt>PELLET_SCORE_CACHE</tt> is undefined by default, and in fact it is ''untested''.

MOSS/Distribution Specific Instructions

2011-04-04T06:29:36Z

A'moaca': Created page with "This document is meant to collect any known distribution-specific instructions for installing MOSS. There are two main parts: installing the prerequisite packages, and setting up..."

MOSS/Setup

2011-04-04T06:28:43Z

A'moaca': Created page with "MOSS currently only runs on Unix. Not Windows. It ought to work on Mac OS/X (even PowerPC) but nobody has tried yet. Please also see the [http://foundry.openuru.org/fisheye/brow..."

MOSS currently only runs on Unix. Not Windows. It ought to work on Mac OS/X
(even PowerPC) but nobody has tried yet.

Please also see the
[http://foundry.openuru.org/fisheye/browse/MOSS/doc/setup main setup instructions].

== Compile ==

=== Prerequisites ===

Before you start, 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)
* 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
* gcc, g++, whatever all you need for compiling C++

If you are compiling from a clone of an Hg respository and there is no
"configure" script, you also need the autotools:
* autoconf
* automake
* libtool

'''If you are reading this, please go over to'''
[[MOSS-Distribution_Specific_Instructions]] '''and fill in how to install all
that 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 set up the server to match the
way Cyan's works. Here are the options you are probably interested in:
; --prefix
: Specify 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 [[MOSS-Notes#RSA | 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".

Install the postgres module in your postgres install. 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 if it's not there already. 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. It 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 my 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_Files | configuration file]]. Make sure to use the 'UTF8'
encoding. Then create the user in the new database. If you want to use a
different username, you will have to edit the moss.sql file to match. 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 postgres -f moss.sql"
After this, you can connect to the database as the "moss" user:
pgql -U moss

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

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, but the
Minkata one is still broken.

== 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 | configuration files]]; you may find it easiest to
specify absolute paths (starting with "/") there.

=== 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
manifets MOSS needs. This seems a reasonable assumption when the client itself
is a Windows app.

Copy support/ManifestCreator.exe and support/Mainfests.zip to your Windows
install. Unzip Manifests.zip. This will make a "CyanStructure" folder. The .txt
files in this folder are input. They describe the files which need to be in the
final manifests.

Start up ManifestCreator. To generate a manifest, click "Make Manifest" and it
brings up a dialog. Navigate to the CyanStructure folder, and select all the
.txt files there. Then click OK and when it pops up a 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 which will run MOSS, create a file server directory. The
default is "./file" (relative to where you start it up). I recommend you make
it ''prefix''/file, where ''prefix'' is the installed location. Copy all the
.mbm files created in the CyanStructure folder to this directory. If you are
serving up a CWE client (built from open source) you will 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, also should be copied. Make sure to match the
directory structures when copying them over.

Finally, 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.exe and the support/macExternal.txt file.

=== Auth Server Data ===

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

A script automating all the following steps in this section is in the works.

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
[http://assets.openuru.org/cyan/AuthFiles.zip 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 with contains one
line per file in the SDL directory. The lines look like
"SDL\BaronCityOffice.sdl". I just toss these in the auth/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 will also create the files. 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 ===

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.

A script automating all the following steps in this section is in the works.

The game servers need unencrypted .sdl and .age files. The easiest way to get a
set of these files is from the Cyan-provided
[http://assets.openuru.org/cyan/Scripts.zip 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 serer 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.

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-Helman 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 which will be 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 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 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 auth_key.bin

If you're compiling a CWE client, make_cyan_dh does not currently output data
in that format. See [https://foundry.openuru.org/jira/browse/MOSS-3 the bug]
for the workaround. If you're not compiling a client, 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".

Do the same 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 for 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:
<tt>auth_download_dir</tt>, <tt>auth_key_file</tt>, <tt>file_download_dir</tt>,
<tt>game_data_dir</tt>, <tt>game_key_file</tt>,
<tt>gatekeeper_key_file</tt>. In addition I recommend you set <tt>log_dir</tt>
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
<tt>pid_file</tt> 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
<tt>external_address</tt>.

For moss_backend.cfg look especially into <tt>log_dir</tt> and
<tt>pid_file</tt>. In addition, depending on how your DB is
[[#Set_Up_the_Database | set up]] you likely need to specify <tt>db_user</tt>,
and maybe other DB parameters.

== Security Considerations ==

'''Please''' read about them at the end of
[http://foundry.openuru.org/fisheye/browse/MOSS/doc/setup doc/setup].

Do not run MOSS as root.

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

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

* 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 [http://assets.openuru.org/cyan/Scripts.zip original source]. If you modify it for any reason, you must make your changes available.

* If you are providing client executables from a CWE build:
** You must add the GPL license file to the client install. This means you'll have to add it to ThinExternal.txt and generate a new .mbm file, copying the .mbm file and LICENSE.txt.gz over to the appropriate locations.
** You must provide a way to acquire the source for your client. If you use an unmodified version you should be able to link to the repository (make sure you point to the 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.
** Unless someone changes the jpeg library again, you need to credit IJG for jpeglib. 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:
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. I would put links to a copy of the
files on your shard's home page or something.

See also [[CyanWorlds.com_Engine/FAQ#What_are_my_open_source_license_.28GPLv3.29_responsibilities_as_a_user.2C_developer_or_server_operator_.28e.g._shard_owner.29.3F | 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 ==

Now you should be set to run your server. Hopefully someone will contribute a
nice startup script. 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:
bin/moss_backend
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.

== Create Accounts ==

Don't forget to create accounts for your users, or it will be difficult to log
in... Please just refer directly to
[http://foundry.openuru.org/fisheye/browse/MOSS/doc/user-management doc/user-management].

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

== More Hints ==

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

* [[MOSS-Notes]]
* [http://foundry.openuru.org/fisheye/browse/MOSS/doc/running doc/running]

MOSS

2011-04-04T06:21:26Z

A'moaca': Created page with "MOSS is a unix-based server for the Myst Online: Uru Live client. Development began after the announcement of the shutdown of MOUL. It is complete enough to play the entire game,..."

MOSS is a unix-based server for the Myst Online: Uru Live client. Development
began after the announcement of the shutdown of MOUL. It is complete enough to
play the entire game, supports multiplayer use, is licensed under GPLv3, and is
not ported to Windows.

MOSS was developed by a'moaca' and cjkelly1. a'moaca' wrote all the C/C++ code,
and cjkelly1 wrote most of the SQL code, including doing research to determine
how to set up the vault. cjkelly1 wrote a tool to create the manifest files
required by the server, and also made the invaluable contribution of a lot of
testing over the years. Weldergeek helped with some of the multiplayer testing,
especially Heek. a'moaca' sincerely hopes there will be more contributors now
that MOSS is released.

== Why Use MOSS? ==

If you just want to host a private shard, MOSS should serve your purposes. Do
be sure to consult [[MOSS-Setup#Before You Open Your Server]] for some help on
what you need to do if you host an Uru shard.

The server definitely works with the [[CyanWorlds.com_Engine | CWE client]]! If
you are thinking of doing client development you will probably find a server
that is not MOULagain to test with quite valuable. (MOSS was also tested with
PlasmaClient, but it does not fully work for PlasmaClient because it does some
things that a'moaca' argues are bugs from the system perspective. Let's fix
PlasmaClient.)

The server has some features meant to help make it a little easier to test ages
you are creating. The SDL files for an age are loaded each time the age is
started up so you can change them without restarting MOSS. There is full
support for multiple .pak files. So, run your own server, test at your own
pace. Test in the CWE client and not the PotS one.

== How to Get It ==

{{tba}}

The source code is hosted in a Mercurial repository here at OpenUru.org.
You can clone (download) a copy of the repository using Mercurial, or you can
use a snapshot. If you are considering making changes to the code, you will
probably prefer using the version control. If you just want to compile and run
a server, a snapshot should do. In addition, a compiled version is
available for the TBD platform.

If you are new to Mercurial, you may want to check the
[http://mercurial.selenic.com/wiki/QuickStart QuickStart]. There are links to
more complete documentation at the bottom. The Foundry is secured via SSL
throughout the site. A browser security certificate is needed. Instructions are
available on the [[Foundry_Certificate_Installation | certificate installation
page]].

'''Repository address:''' https://foundry.openuru.org/hg/MOSS

'''Snapshot location:''' TBD

'''Binary package:''' TBD

== How to Set Up a Server ==

The [http://foundry.openuru.org/fisheye/browse/MOSS/doc/setup setup] file
contains a complete set of installation instructions. They do assume you are
conversant with setting up software and basic management of a database. For
additional setup instructions, see [[MOSS-Setup]]. Feel free to add any hints
specific to your distribution [[MOSS-Distribution_Specific_Instructions | here]].

Cyan has provided a copy of the files needed for a server hosting MOUL content.
The .sdl, .age, and Python source are all available at
http://assets.openuru.org/cyan/Scripts.zip. If you are not interested in
compiling your own Python from this source, you can also get a copy of the
compiled Python from http://assets.openuru.org/cyan/AuthFiles.zip.

== How to Contribute ==

Contributing to the wiki pages is welcome. Adding extra setup instructions, or
adding documentation about how MOSS works, are two good examples. It's a wiki,
please contribute anything you think others might want to read.

Almost any code contribution is welcome. What is unwelcome? Protocol/behavior
changes without corresponding client support (obviously). Changes that remove
security without the option of keeping it. Changes that introduce security
holes, either in the server itself or the vault. Changes that break big-endian
support (call it a pet peeve if you like, it's still unwelcome). Changes that
break the build (accidents do happen, but don't break it on purpose). Hopefully
it is not difficult to see why these things are unwelcome.

If you find a bug, please report it. Please, please, please search first to see
if it's already reported. The bug tracker is here:
https://foundry.openuru.org/jira/browse/MOSS

If you find a bug and fix it, include the patch with the bug report! This
increases the chances of it getting fixed rather a lot.

Bug fixes are very valuable.
[https://foundry.openuru.org/jira/browse/MOSS Grab a bug] and fix it! Check
out [[MOSS-Project_Ideas]] for more ideas.

If you want to add a feature or change something, you can file a feature
request or task bug to get your change considered for the
[https://foundry.openuru.org/hg/MOSS central repository].

If you want write access to the central repository, contribute. I think the
best for MOSS will be to use similar standards for determining who is given
write access as CWE. At this time that's undecided, so I leave MOSS equally
undecided. However, MOSS's original author is more involved than CWE's so if
only a couple people show up to help then it's pretty clear a couple people
will get write access soon enough!

Code reviewers might be needed. If you are willing to be a reviewer, say so! It
is a very valuable contribution.

== See Also ==

[[MOSS-Setup]]

[[MOSS-Developer_Notes]]

[[CyanWorlds.com_Engine]]

CyanWorlds.com Engine

2011-04-01T06:11:08Z

A'moaca': /* OpenUru.org Announcement */

<div style="float: right; padding: 10px;">http://assets.openuru.org/logos/gpl/gplv3-127x51.png</div>
== CyanWorlds.Com Engine Open Source Project ==

The wait is over!

=== Introduction ===
Cyan Worlds, Inc. and OpenUru.org jointly announce open source delivery of the CyanWorlds.com Engine client and 3ds Max plugin, aka Plasma, the engine used to power Myst Online: Uru Live.

==== Cyan Worlds Announcement ====
The following message was posted on the MystOnline.com forums on (date):
<blockquote class="bluebox">(Insert Cyan Worlds' announcement text here)</blockquote>

==== OpenUru.org Announcement ====
OpenUru.org introduces the CyanWorlds.Com Engine, Cyan Worlds' Plasma game engine used to power Myst Online: Uru Live. The OpenUru.org team is thrilled that the CyanWorlds.com Engine has been released by Cyan Worlds as open source. We are honored that Cyan Worlds has given OpenUru.org the opportunity to prepare and release it to the Uru community and the world. The initial release of the CyanWorlds.Com Engine includes Cyan Worlds' client and 3ds Max Plugin.

OpenUru.org is especially pleased to simultaneously announce MOSS, a CyanWorlds.Com Engine server, by a'moaca' with cjkelly1. MOSS was largely derived from a'moaca's work on her client protocol Wireshark plugin, a project also hosted on OpenUru.org. Cyan Worlds cannot release their server code until more is done to clear it for open source, so a'moaca's completion of her open source server couldn't have been more perfectly timed.

OpenUru.org is prepared with tools to support new development of the CyanWorlds.com Engine with MOSS. We welcome all developers, issue reporters and users to contribute to the effort. Contributors can work on our Foundry with Atlassian tools such as JIRA, Fisheye and Crucible to manage development projects and Jenkins (previously known as Hudson) for Continuous Integration to produce automated builds.

=== What It Is ===
CyanWorlds.Com Engine is the client, server and tools used to develop and operate the Myst Online: Uru Live MMO. The server code needs more work before Cyan Worlds can clear it for open source. However, the client and 3ds Max plugin are now available in open source.

=== How To Get It ===
CyanWorlds.Com Engine is available on OpenUru.org's Foundry, hosted on a Mercurial code repository. There was much discussion on the Myst Online forums about the strengths of various repositories after Cyan Worlds' initial open source announcement in 2008. We listened. Mercurial was selected due to the needs of a distributed developer community.

OpenUru.org needs to throttle the initial download traffic due to the expected extreme demand built up during the long wait for open source. Therefore, any developer wishing to get the initial release needs to register an account on the Foundry at https://Foundry.OpenUru.org/jira. The Foundry is secured via SSL throughout the site. A browser security certificate is needed. Instructions are available on the [[Foundry Certificate Installation|certificate installation page]].

Developers with an account will be given access to pull the CyanWorlds.Com Engine repository as quickly as possible. Once the developer traffic has subsided, the repository will be opened to the public and the curious.

'''Steps'''

1. Register for a Foundry account at https://Foundry.OpenUru.org/jira.

2. We will see the registration, place you in the queue, and note it in the forum thread given below.

3. Look for an asterisk by your account name in the forum thread, then download as soon as possible.

4. Pull the CWE repository from the address given below.

5. As downloads are completed, more accounts will be enabled for download.

'''View account queue:''' http://forums.OpenUru.org/viewtopic.php?f=91&t=507

'''Repository address:''' https://Foundry.OpenUru.org/hg/CWE

=== Development ===
Some developers will be invited to join the team in management and development positions for the CyanWorlds.Com Engine project. But generally, anyone who demonstrates the skills and becomes a positive force in the project may contribute to development.

CyanWorlds.Com Engine version 1.0 will consist only of a buildable client and plugin. There will be no new features and no bug fixes, except those necessary to replace proprietary third party libraries that Cyan Worlds needed to removed before the release. Once a successful build is released, phase two may begin to fix known issues. After that, the fun begins with new features and full steam ahead to keep on chugging down that open source track.

Once things get rolling, we'll be looking for people to fill or help with the following positions:

* Project lead (integration of job flow, patches, release schedules)
* Documentation lead (create and integrate cross-platform documentation for JIRA, web, Wiki, PDF, IDE)
* Technology lead (site integration, resource integration, security, builds)
* Development lead (prioritization of issues, issue assignments, tools, set up code review)
* Web community lead (development of web presence and content to introduce, educate and deliver open source projects

=== Documentation ===
What documentation? The code documents itself! Right? Actually, there was an apparent early effort to maintain directives used for automated Doxygen documentation from code. Their use fell off as time went on. Introduction of integrated documentation is considered crucial to the successful development of the CyanWorlds.Com Engine. Therefore, Doxygen directives will be accepted into the main trunk from the start. We want to build integrated documentation originating from the source code for use beginning with Fisheye (our repo browser), HTML, PDF, and the Visual Studio IDE.

=== Everyone ===
Everyone will be able to download and watch progress of the CyanWorlds.Com Engine project and enjoy the benefits of exploring new worlds.

=== The Team ===
The CyanWorlds.com Engine Project was brought to you by Cyan Worlds' Rand Miller, Tony Fryman, Mark DeForest and the collective talents of everyone at Cyan Worlds who ever worked on Uru Live over many years. The original release team at OpenUru.org who are helping to make the open source CyanWorlds.com Engine project possible are JWPlatt, Mac_Fife, rarified, a'moaca', and cjkelly1.

=== Building The Client ===
In the article "[[Build the client with MSVC 2003]]", cjkelly1 describes how to build a working client from the CWE sources. Note that this build uses sources and makefiles that have been modified to substitute some of the libraries that could not be distributed with the original sources.

== See Also ==

=== [[CyanWorlds.com Engine/FAQ|CyanWorlds.com Engine FAQ]] ===
=== [[Cyan Worlds Sources And Tools]] ===
=== [[CWE Libraries and SDKs|CyanWorlds.com Engine Libraries and SDKs]] ===

[[Category:Cyan_Worlds]]

Wireshark Plugin

2010-06-01T00:27:08Z

A'moaca': /* Contributing */

Welcome to the main page for the Uru Wireshark plugin!

= Do I care about this? =

Wireshark is a GUI-based network protocol analysis tool. (There is a command-line version too.) In short, it lets you look at network traffic to see what is going on, even in real-time. a'moaca' has figured out Uru bugs based on real-time behavior related to what is seen on the network, in addition to more subtle bugs discovered with detailed later analysis.

Generally this tool will only be of interest to those working on the protocol or client/server code. It is also interesting for a more hobbyist "figure out how it works" perspective.

But there is a caveat. The MOUL protocol (which the plugin calls "UruLive") is protected by a form of public-key encryption. This means that the Uru plugin cannot read the contents of any but the very first packets of each connection, unless you have the private key or some means of determining the negotiated session key.

Only Cyan should have the private key. Anyone writing new clients can choose to expose the session key for use with the Wireshark plugin. When people can run their own servers, they will in turn have their own private keys and they can use the plugin too. If you wish to use the plugin otherwise, I leave you to your creativity.

The plugin will work on old UU/Alcugs traffic, though, should you happen to have any to look at.

= History (why are things this weird way?) =

a'moaca' first started the plugin while debugging a linking hang with old Alcugs (unet2) code. The resulting bare-bones transport-layer only version of the plugin was checked into the Alcugs repository (where some Alcugs-specific code was later added that is not present in this version as of now). Later, in support of other projects, a'moaca' began adding dissection of the rest of the protocol, based almost entirely on the Alcugs server code itself. This is the reason many of the names in the plugin are what they are.

The hobbyist perspective led to gradually more dissection, proceeding on to the MOUL protocol. Over time, cjkelly1 has contributed a lot to the plugin as well, including some code contributions, effort spent figuring things out, testing, a lot of Windows-specific testing (usually unintentional but sometimes planned), and providing some of the correct names for things.

Very little of the knowledge added by a'moaca' and cjkelly1 after what originated from the Alcugs source came from disassembly, the "usual" method of Uru reverse-engineering. It was done by looking at real traffic and educated guessing. This is the reason many other names are what they are, and this is why there are still some gaps in the dissection.

If you want to fix any of this, submit a patch!

= How to use it =

(At the moment there isn't a compiled executable to distribute. This could change in the future. Until/unless a precompiled version is available, you will have to compile your own. For that, see the next section.)

Using the Uru plugin is not much different than using Wireshark for any other protocol. Here are some extra notes:
* There are two configuration sections, "Uru" and "UruLive". The "Uru" section covers configuration specific to the Prologue/UU/PotS protocol. The "UruLive" section covers configuration specific to the MOUL/MOULa protocol. Anything common to both is also in the "Uru" section (this is the toggle for hiding fields, and all SDL-related configuration).
* Be careful with your SDL files. Unfortunately, the MOUL SDL files are not a strict superset of PotS files (I believe there is at least one mismatch with the same version number, for example). Genrally one copy will suffice, though. If you do not provide SDL files, the plugin will use a crummy but serviceable algorithm that guesses the field types.
* The UruLive configuration contains several choices for protocol versioning. These apply to MOUL versions. You can basically ignore them unless you have ''old'' uncrypted traces. The default (Live 9, autodetect) should be good.
* Two ways to decrypt MOUL connections are provided: giving Wireshark each session key, or giving it the private key data for each type of connection.
** The first way requires configuring the 7-byte session key, if you have a way to determine it. This key is negotiated each connection. The input box accepts a comma-separated list of port=key pairs. Use the client port number (the one that is not 14617); this is how the plugin associates each key with a connection. The 7 bytes of the key should be in hexadecimal. An example value might be:
1050=1A2B3C4D5E6F70,1053=1234ABCD5678EF
:* The second way requires knowledge of the server private key. Provide a key file for each connection type (auth, game, gatekeeper). The format of the key file is 128 bytes of binary data. The first 64 bytes are the modulus in '''big-endian''' order (note it is little-endian in the exectuables), and the second 64-bytes are the private key, again '''big-endian'''. (This key file choice is based on the baseless assumption that the actual key files are stored in a common format such as DER, which is big-endian.)

= How to compile it =

The code is present in OpenURU.org's Subversion repository at [http://foundry.openuru.org/svn/wireshark_plugin http://foundry.openuru.org/svn/wireshark_plugin]. To check it out, use your favorite Subversion GUI with username "guest" and password "guest", or on the command line:
svn co --username guest --password guest http://foundry.openuru.org/svn/wireshark_plugin
This will check out the latest version of the source in the current directory. You will also need a copy of the Wireshark source. It may be downloaded from [http://www.wireshark.org/download.html the Wireshark site]. Using the "Development Release" is recommended, as the patch provided will work with that tree. Version 1.2.8 or newer will also work, but you will need to patch plugins\Makefile.nmake yourself, as the structure of the file differs between 1.2.x and the development trunk.

In the plugin directory, the INSTALL file provides build directions. The basic idea is that you patch the plugin into the Wireshark build and then build Wireshark normally. So you should be able to follow Wireshark's build documentation.

The [http://www.wireshark.org/docs/wsdg_html_chunked Developer's Guide] contains [http://www.wireshark.org/docs/wsdg_html_chunked/ChSrcBuildFirstTime.html build instructions], which are pretty minimal. If you are building for Windows, check [http://www.wireshark.org/docs/wsdg_html_chunked/ChSetupWin32.html the additional instructions] and a'moaca' uses [http://wiki.wireshark.org/Development/MSVC7 this wiki page].

= Contributing =

OpenURU.org has a JIRA installation. You may use it for [http://foundry.openuru.org:7080/browse/WIREPLUG bugs and patch contributions]. As of right now there is a limited number of JIRA accounts, so you can submit bugs "anonymously". Please include in the report a forum name or some other reasonable contact information!

Code contributions will be code-reviewed for safety and correctness. Please keep code to 79 columns or fewer. There are currently no plans to reject anything based on content unless it is actually incorrect. If you want commit access, contribute a couple working patches and then ask for access. This protocol may change in the future if it does not work.

Wireshark Plugin

2010-05-17T08:15:02Z

A'moaca': Created page with 'Welcome to the main page for the Uru Wireshark plugin! = Do I care about this? = Wireshark is a GUI-based network protocol analysis tool. (There is a command-line version too.)…'

Welcome to the main page for the Uru Wireshark plugin!

= Do I care about this? =

Wireshark is a GUI-based network protocol analysis tool. (There is a command-line version too.) In short, it lets you look at network traffic to see what is going on, even in real-time. a'moaca' has figured out Uru bugs based on real-time behavior related to what is seen on the network, in addition to more subtle bugs discovered with detailed later analysis.

Generally this tool will only be of interest to those working on the protocol or client/server code. It is also interesting for a more hobbyist "figure out how it works" perspective.

But there is a caveat. The MOUL protocol (which the plugin calls "UruLive") is protected by a form of public-key encryption. This means that the Uru plugin cannot read the contents of any but the very first packets of each connection, unless you have the private key or some means of determining the negotiated session key.

Only Cyan should have the private key. Anyone writing new clients can choose to expose the session key for use with the Wireshark plugin. When people can run their own servers, they will in turn have their own private keys and they can use the plugin too. If you wish to use the plugin otherwise, I leave you to your creativity.

The plugin will work on old UU/Alcugs traffic, though, should you happen to have any to look at.

= History (why are things this weird way?) =

a'moaca' first started the plugin while debugging a linking hang with old Alcugs (unet2) code. The resulting bare-bones transport-layer only version of the plugin was checked into the Alcugs repository (where some Alcugs-specific code was later added that is not present in this version as of now). Later, in support of other projects, a'moaca' began adding dissection of the rest of the protocol, based almost entirely on the Alcugs server code itself. This is the reason many of the names in the plugin are what they are.

The hobbyist perspective led to gradually more dissection, proceeding on to the MOUL protocol. Over time, cjkelly1 has contributed a lot to the plugin as well, including some code contributions, effort spent figuring things out, testing, a lot of Windows-specific testing (usually unintentional but sometimes planned), and providing some of the correct names for things.

Very little of the knowledge added by a'moaca' and cjkelly1 after what originated from the Alcugs source came from disassembly, the "usual" method of Uru reverse-engineering. It was done by looking at real traffic and educated guessing. This is the reason many other names are what they are, and this is why there are still some gaps in the dissection.

If you want to fix any of this, submit a patch!

= How to use it =

(At the moment there isn't a compiled executable to distribute. This could change in the future. Until/unless a precompiled version is available, you will have to compile your own. For that, see the next section.)

Using the Uru plugin is not much different than using Wireshark for any other protocol. Here are some extra notes:
* There are two configuration sections, "Uru" and "UruLive". The "Uru" section covers configuration specific to the Prologue/UU/PotS protocol. The "UruLive" section covers configuration specific to the MOUL/MOULa protocol. Anything common to both is also in the "Uru" section (this is the toggle for hiding fields, and all SDL-related configuration).
* Be careful with your SDL files. Unfortunately, the MOUL SDL files are not a strict superset of PotS files (I believe there is at least one mismatch with the same version number, for example). Genrally one copy will suffice, though. If you do not provide SDL files, the plugin will use a crummy but serviceable algorithm that guesses the field types.
* The UruLive configuration contains several choices for protocol versioning. These apply to MOUL versions. You can basically ignore them unless you have ''old'' uncrypted traces. The default (Live 9, autodetect) should be good.
* Two ways to decrypt MOUL connections are provided: giving Wireshark each session key, or giving it the private key data for each type of connection.
** The first way requires configuring the 7-byte session key, if you have a way to determine it. This key is negotiated each connection. The input box accepts a comma-separated list of port=key pairs. Use the client port number (the one that is not 14617); this is how the plugin associates each key with a connection. The 7 bytes of the key should be in hexadecimal. An example value might be:
1050=1A2B3C4D5E6F70,1053=1234ABCD5678EF
:* The second way requires knowledge of the server private key. Provide a key file for each connection type (auth, game, gatekeeper). The format of the key file is 128 bytes of binary data. The first 64 bytes are the modulus in '''big-endian''' order (note it is little-endian in the exectuables), and the second 64-bytes are the private key, again '''big-endian'''. (This key file choice is based on the baseless assumption that the actual key files are stored in a common format such as DER, which is big-endian.)

= How to compile it =

The code is present in OpenURU.org's Subversion repository at [http://foundry.openuru.org/svn/wireshark_plugin http://foundry.openuru.org/svn/wireshark_plugin]. To check it out, use your favorite Subversion GUI with username "guest" and password "guest", or on the command line:
svn co --username guest --password guest http://foundry.openuru.org/svn/wireshark_plugin
This will check out the latest version of the source in the current directory. You will also need a copy of the Wireshark source. It may be downloaded from [http://www.wireshark.org/download.html the Wireshark site]. Using the "Development Release" is recommended, as the patch provided will work with that tree. Version 1.2.8 or newer will also work, but you will need to patch plugins\Makefile.nmake yourself, as the structure of the file differs between 1.2.x and the development trunk.

In the plugin directory, the INSTALL file provides build directions. The basic idea is that you patch the plugin into the Wireshark build and then build Wireshark normally. So you should be able to follow Wireshark's build documentation.

The [http://www.wireshark.org/docs/wsdg_html_chunked Developer's Guide] contains [http://www.wireshark.org/docs/wsdg_html_chunked/ChSrcBuildFirstTime.html build instructions], which are pretty minimal. If you are building for Windows, check [http://www.wireshark.org/docs/wsdg_html_chunked/ChSetupWin32.html the additional instructions] and a'moaca' uses [http://wiki.wireshark.org/Development/MSVC7 this wiki page].

= Contributing =

OpenURU.org has a JIRA installation. You may use it for [http://foundry.openuru.org:7080/browse/WIREPLUG bugs and patch contributions]. As of right now there is a limited number of JIRA accounts, so you can submit bugs "anonymously". Please include in the report a forum name or some other reasonable contact information!

Code contributions will be code-reviewed for safety and correctness. There are currently no plans to reject anything based on content unless it is actually incorrect. If you want commit access, contribute a couple working patches and then ask for access. This protocol may change in the future if it does not work.

Projects and Resources

2010-05-17T08:06:23Z

A'moaca':

{{draft}}
Sample of an index to articles on Projects and Resources on the OpenURU.org site (and elsewhere?)


== Info & HowTo On OpenURU.org ==
* [http://forums.openuru.org/viewtopic.php?f=5&t=164 How to request a new project]

== Projects On OpenURU.org ==
* [http://forums.openuru.org/viewforum.php?f=17 System Concepts]
* [http://forums.openuru.org/viewforum.php?f=20 Building & Testing]
* [http://forums.openuru.org/viewforum.php?f=20 Building & Testing]
* [http://forums.openuru.org/viewforum.php?f=47 Myst/Uru-Style Hypergrid & Open Simulators]
* [[David's Journey]]
* [[SD&D_Overview|Standards For Discussion & Debate]]
* [[Wireshark Plugin]]
* Just some text 

An example of '''''some bold italic text taken out of context''''' just to show that it can work.


[[Category:OpenUru.org]]
[[Category:Documentation]]
[[Category:Age Projects]]