BoxServer Readme file

Updated on: March 1, 2004
BoxServer version: 1.0

Table of Contents

1. BoxServer: general information
2. Installation
3. Configuration
4. Stability
5. Security
6. Authentication
7. Spawners
8. Modules
   1. Core
   2. Builder
   3. Retrieve Datafiles
   4. Script Explorer
   5. Spawn Groups
   6. Client List
9. Uninstallation
10. Support

1. BoxServer: general information

BoxServer is a set of scripts for RunUO that allow Pandora's Box to access additional functions. For a complete list of functions please review section 7: Modules.

This file provides important information about running BoxServer, regarding its security and features. Please take a few moments to read it before installing the server exstensions.

BoxServer has been introduced with Pandora's Box 2.0 and is based on .NET remoting, an architecture for inter domain communication. Simply put, BoxServer creates a special object of type BoxRemote on the RunUO server, and registers this object for remote access. The BoxRemote object is inside a library called BoxServer.dll that's installed into your \RunUO\folder. This is necessary, as opposed to just script it, because .NET remoting identifies the remote object through its type and assembly. The remote object has one public method called PerformRemoteRequest() that allows Pandora's Box to send and process a message (or packet) on the server.

The basic transaction mechanism is as follows:

1. Pandora creates a message (any object inherited from BoxMessage) and compresses it into a byte stream using ZLib.
2. Pandora connects to the remote server and invokes the PerformRemoteRequest method on the registered BoxRemote object, passing the data stream as parameter to the method.
3. The server decompresses the packet, performs authentication and if it succeeds, performs the action requested.
4. If the outcome of the process is an error, or if the action requires data sent from the server back to Pandora, the server will create a message as well, compress it using ZLib and send it back.

2. Installation

Installation is performed through a wizard which will perform the following actions:

1. Copy BoxServer.dll into your \RunUO\ folder
2. Update your \RunUO\Data\Assemblies.cfg file ensuring that the BoxServer.dll and System.Runtime.Remoting.dll libraries are loaded by RunUO.
3. Copy all the scripts to the target folder. You will be able to select which modules you wish to install.

3. Configuration

Configuration for the BoxServer is located in the Configuration.cs file in your BoxServer installation folder. You can configure the following properties:

• Port: BoxServer requires an unused port on the host machine. By default this value is 8035, but you might need to change it if this port is already used on your system. If this is the case, you will receive an error message in the RunUO console stating that the BoxServer port is already in use.
• Message Hue: this allows you to specify a hue for all the messages generated in game by the BoxServer scripts.
• Minimum AccessLevel: specifies the minimum AccessLevel required to access BoxServer functions. This can be overriden for a specific feature: review section 6: Authentication for more details.

4. Stability

The scripts composing BoxServer have been tested and are believed to be stable. .NET Remoting itself provides for additional stability because in most cases, errors in the BoxServer code are sent to the Pandora's Box client rather than to the RunUO process. This doesn't happen all the time though, here's a brief description of the process and of its implications.

1. Pandora's Box performs an operation on the BoxServer. This includes authentication followed by the Perform() method of the message being processed. Anything that happens in this scope is managed by Pandora's Box, so if this code leads to an Exception, this Exception will NOT crash the server.
2. In some cases the Perform() method will interact with the user. For example, when placing a spawn group, it will assign a special target to the calling client. This is where the separation occurs: whatever happens after the target is assigned is managed by the server, so if this code ( namely OnTarget() ) leads to an Exception, it will crash the server. A lot of care has been put into evaluating such situations to ensure the maximum stability possible.

5. Security

5.1 Account Information Security

Account information is used by Pandora's Box to authenticate the user on the BoxServer. BoxServer has naturally access to this information through the Server.Accounting.Accounts class. Pandora's Box will collect this information from the user. The account name will be stored in the Pandora's Box profile in plain text, while the password will be hashed using a M5D hash.

Pandora's Box will never store on file or permanently in memory a password in plain text. Instead, once the user has provided the password, it will perform the hashing. The hashing process implies loss of data about the original string, which makes it pretty much impossible for anyone to revert the hash into the original string. Also, even if not proved, it is strongly believed that no two different strings can lead to the same hash. In other words, there's no way to retrieve the account password from Pandora's Box.

On the server, authentication is performed by calculating the hash on the password stored in the Accounts class. If the two hashes match, authentication succeeds.

5.2 Network Security

.NET remoting exposes an object on the host machine. This object can be instantiated by anyone who can connect to the remote service. The object called BoxRemote works in singletone mode, which means that only one object will be created and it will serve all remote requests coming from outside clients. A client can only call one method defined on the object, PerformRemoteRequest() that takes as parameters a Type name and a stream of bytes. The server will try to find the loaded type corresponding to the parameter provided: if not found, it will return a FeatureNotSupported message, otherwise it will try to decompress and deserialize the data. If this process is succesful, it will perform authentication on the message as described by the message class located on the server itself. This allows the server administrator to strictly control access to features of BoxServer, making the architecture as secure as desired.

NOTE: The architecture relies on the trust you put into your staff. If you don't fully trust your staff, limit their access to the BoxServer or set the minimum AccessLevel to Administrator or Seer (by default it's GameMaster). While the default BoxServer installation doesn't feature any potentially dangerous situations, it could lead to annoying situations if not used wisely (think of a huge roof created over Britain). Special care should be taken in configuring the Script Explorer, please review the corresponding section for details.

6. Authentication

There are two levels of authentication for each feature installed on the server:

1. Basic Authentication: this is built in by default in the server itself. Authentication of username and password as described in the Security section is performed always and should not be removed. There's also a minimum AccessLevel required to access the server specified in the Configuration.cs file. This should never be set to Player, otherwise anyone with an account on your shard will be able to use some features.
2. Advanced Authentication: this is done by implementing the IAuthenticable interface on a single message (or feature). The IAuthenticable interface is defined as follows:
   • AccessLevel MinAccessLevel { get; } : Overrides the minimum AccessLevel required to access this feature. Keep in mind that this can't be lower than the global minimum AccessLevel because that check is always performed first.
   • bool RequireOnlineMobile { get; } : Specifies if a feature requires the user to be actually online while using it. An example is creating a spawn group: the user must be logged into the server in order to target the location of the spawner.

Implementing the IAuthenticable interface is very simple and can be done on any class that inherits from BoxMessage (wouldn't make much sense on other classes). If implemented correctly, the server will automatically perform the checks implied by the interface. You can see an example of this implementation in Modules\SpawnGroups\SpawnMessage.cs.

7. Spawners

BoxServer deals with spawner objects in two modules:

1. The SpawnData datafile: this is used to display the existing spawns on the Pandora's Box travel map. The generator evaluates each spawner object and converts it to a SpawnEntry object that carries information used in Pandora's Box.
2. The Spawn Groups module: as the name implies, this converts a spawn group defined in Pandora's Box to an actual spawn in the world.

Both of these actions require knowledge of the shard specific spawner object. The installation wizard currently supports the default Spawner and the XmlSpawner, providing users with code designed to work correctly with those objects.

All spawner specific code is located in the file Core\SpawnerHelper.cs. In case your spawner is not supported by default by BoxServer, you can choose the 'Other' option in the wizard and fill the methods yourself. The SpawnerHelper class consists of three static methods and one property:

1. public static Type SpawnerType { get; } : defines the type of the object used as spawner. This is used to identify the object that act as spawners when generating the SpawnData datafile.
2. public static SpawnEntry SpawnerToData( Item spawnerItem ) : this method converts a spawner item into a SpawnEntry object that carries information about the spawn ( location and so on ). This is used to build the SpawnData.
3. public static Item CreateBoxSpawn( BoxSpawn spawn ) : this method converts a BoxSpawn object that represents a spawn group, into a spawner object filled with the creatures that will be spawning. The spawner object returned by this method should not be active.
4. public static void StartSpawner( Item spawner ) : this method is called when the spawner carrying the spawn group has been placed in the world and must be actived and spawned.

When you select the 'Other' option, you will be provided with skeleton code in SpawnerHelper.cs and commented out code for the default RunUO Spawner so you have an idea of how you can code your specific implementation.

NOTE: I will be providing support for custom spawners in my free time. You can contact me about this through the forums on my site. I am also willing to add more spawners into the installer, if you're the author of a spawner object and wish to be officially supported by Pandora's Box please compile a SpawnerHelper class specific for your spawner, and email me both scripts at arya@box.it

8. Modules

BoxServer is composed of modules. You can choose which modules you wish to install during the installation wizard, and in case you wish to remove a module at a later time you can simply delete its folder in the Modules directory and restart your server. Please don't remove any files from the Core folder as they might compromise the BoxServer. I will not provide support for such situations.

1. Core

As the name implies, the Core module includes classes used for the main functionality of BoxServer:

• Login functionality: provides Pandora's Box with a quick authentication for the user before allowing access to other BoxServer features.
• Various data structures used throughout the BoxServer.
• Various methods used by the BoxServer scripts.
• Error messages
• Datafile generators: even if in a separate directory for easier identification, these scripts are part of the BoxServer core and should not be removed (otherwise other modules might fail to compile). The generation scripts can be accessed through the BoxServer control panel (see the in game commands sections for more details).

Attempting to modify the core features is totally unsupported because it might break the behaviour of the BoxServer, of Pandora's Box and might place security threats on your server.

2. Builder

Authentication: IAuthenticable
MinAccessLevel: GameMaster
RequireOnlineMobile: true

This module is used by two and possibly more features of Pandora's Box (namely roofing and the random tiler). When you create a structure of items through the roofing tool, for instance, using the Generate through Server option, the structure will be automatically saved in the Builder class. This will allow users of Pandora's Box to quickly move, remove or hue the whole structure.

3. Retrieve Datafiles

Authentication: Basic
MinAccessLevel: BoxServer default
RequireOnlineMobile: none (false)

This module allows users to retrieve datafiles used in Pandora's Box to display custom items, mobiles and so on. The datafiles available are:

• BoxData [ RunUO\TheBox\BoxData.xml ] : contains the definitions of all constructable items and mobiles scripted on the server.
• PropsData [ RunUO\TheBox\PropsData.xml ] : contains the definitions of all the properties defined on constructable items and mobiles. It is used on the Props tab in Pandora's Box.
• SpawnData [ RunUO\TheBox\SpawnData.xml ] : contains information about the spawns in the world, used to display them on the travel map in Pandora's Box.

This module is very useful for distributing shard specific information to the staff. All the datafiles are generated in the RunUO\TheBox folder by default. If you wish to allow users to retrieve only a part of available datafiles (for example only BoxData), simply don't generate (or delete) the other datafiles from the RunUO\TheBox folder.

4. Script Explorer

Authentication: Custom
MinAccessLevel: BoxServer default
RequireOnlineMobile: none (false)

This is a powerful yet potentially dangerous module. Simply put, it's a FTP architecture limited to .cs, .vb, .xml and .txt files. It allows remote users to download, upload, delete and move files and is intended to aid remote scripting.

In order to minimize risks associated with this module, it requires a special configuration located in the file \Modules\ScriptExplorer\Configuration.cs. You must provide a user esplicit permission for this module by specifying their account name and the folders they are allowed to access. All folders are specified relatively to the \Scripts\ folder on the server. The Configuration.cs file explains in detail how to register a user for this module.

Whenever a user tries to use this module, the script will check if the user is registered, and if so it will check if the file being modified belongs to the user's registered folder(s).

IMPORTANT: This module is active only when the server is running. If a remote user modifies a script, or uploads code that fails to compile, and then restarts the server, the server will not restart and will need mainteinance by other means. Please use this module carefully.

5. Spawn Groups

Authentication: IAuthenticable
MinAccessLevel: GameMaster
RequireOnlineMobile: true

This module allows users to spawn full spawn groups as defined in Pandora's Box. For more information about spawners refer to section 7.

6. Client List

Authentication: IAuthenticable to perform commands on clients
MinAccessLevel: GameMaster
RequireOnlineMobile: true to perform commands on clients

This module transfers the client list to Pandora's Box. Information collected include: player and account name, last login time, location, map and serial. This module is used in Pandora's Box by the Client Map which displays where clients are located on a world map, and by the Client List which lists (allowing different sorting orders) all the clients connected. This second mode also allows to quickly go to the selected client, view their props or client information and for administrators also their account details.

9. Uninstallation

Uninstalling the BoxServer is very easy and is done in three steps:

1. Delete the file \RunUO\BoxServer.dll
2. Open the file \RunUO\Data\Assemblies.cfg and remove the following entries:
   1. BoxServer.dll
   2. System.Runtime.Remoting.dll (keep in mind that other software might need this, such as UOArchitect or other Orbsydia programs)
3. Delete all the scripts within the BoxServer folder.

10. Support

Support for the BoxServer is provided through the BoxServer forum located at http://arya.runuo.com/