Running the Servers

From Multiverse

For step-by-step instructions to run the Multiverse servers, see Getting Started.

Using the server start scripts

Use the Multiverse server start scripts to start and stop the servers, and to find out whether the servers are currently running. There are two kinds of start scripts: Windows batch files and bash scripts. If you are on Linux or Unix, you must use the bash scripts. If you are on Windows, you must use the batch files, unless you have installed Cygwin. If you are on Windows and have installed Cygwin, you can use either the batch or bash scripts.

Using the Windows batch scripts

On Windows systems (when not using Cygwin), use the three batch files in the mv_home/bin directory to start, stop, and view the status of the servers:

• start-multiverse.bat - starts all the servers.

In general, start-multiverse.bat does the same things as the bash script. NOTE: You must run start-multiverse.bat from the mv_home/bin directory.

• stop-multiverse.bat - stops the servers.
• status-multiverse.bat - shows the status (running or not running) of the servers.

Using the bash scripts

On Linux, or when using Cygwin on Windows, use the bash shell script mv_home/bin/multiverse.sh to start the servers, to monitor their status, and to shut them down gracefully. On Windows, if you have not installed Cygwin, you must use the batch scripts to control the servers.

To run multiverse.sh in a shell window, make sure your current working directory is mv_home/bin. Then, use the following command syntax:

./multiverse.sh [-hvMC] [-p propertyfile] [-w worldname] {start | restart | stop | status}

For information on how to read this standard command line syntax statement, see Command Line Syntax.

The options are:

• -v (verbose): display information on what the script is doing.
• -h (help): dispaly usage synopsis.
• -M (management): Enable JMX management agent
• -C (client JVM): Use the Java "client" VM
• -p propertyfile: use this property file instead of the default multiverse.properties.
• -w worldname: start this work instead of the one specified in the property file.

The commands are:

• start: start all Multiverse servers (see below for list).
• restart: shut down and then restart all the servers.
• status: show the status (RUNNING or DOWN) of all multiverse servers.
• stop: stop (shutdown) all Multiverse servers.

See the sections below for details.

For more troubleshooting information, see Debugging Startup Errors.

Do not run multiverse.sh twice in a row, without first stopping the servers. If you do so by accident, use the stop command and then manually kill orphaned Java processes.

To set the verbose option permanently: Edit multiverse.sh and change

verbose=0

to

verbose=1

Property file

Most of the key server settings are specified in a property file, mv-home/bin/multiverse.properties by default. See Using the Server Property File for more information.

Setting the world file

Initially, it's a good idea to get the servers running with the sample game world ("sampleworld"), and then proceed to load your own world. By default, the servers will start up running sampleworld, so you don't need to do anything.

To use your own world file (.mvw file) that you created with World Editor, edit the properties file (by default multiverse.properties) and set the multiverse.worldname property. The servers will load the world file in mv-home/config/worldname/worldname.mvw, where worldname is the value of multiverse.worldname. To load an arbitrary world file, set the multiverse.mvwfile property.

You can also set the world name on the multiverse.sh command-line with the -w option, for example:

multiverse.sh -w my_world start

NOTE: A Multiverse world (.mvw) file references Multiverse collection (.mwc) files. So, if you copy the .mvw file to a directory, you must also copy the corresponding collection files.

Environment variable settings

You can optionally set these two environment variables:

• DEFAULT_MV_PROPERTYFILE specifies the default property file name. The script uses this value when you don't specify a property file on the command line. The default value of this is mv-home/bin/multiverse.properties.
• ENABLE_MGMT specifies whether to use JMX magagement and monitoring. Set to "true" to use JMX management and monitoring. For more information, see Monitoring and Managing the Servers.

For information on how to set an environment variable, see Setting Environment Variables.

To start the servers

Windows

To start the servers using the Windows Command Prompt, use this command:

start-multiverse

You must run start-multiverse.bat from the mv_home/bin directory.

Specify a file name as the argument to use a property file different from the default (multiverse.properties). For example:

start-multiverse myserver.properties

Linux and Cygwin/Windows

To start the servers and display startup information, use this command:

./multiverse.sh -w worldname -v start

The script displays a message when it starts each server.

The -v verbose command shows the processes being started; for example:

Starting domain server:         SUCCESS
Starting combat server:         SUCCESS
Starting object manager:        SUCCESS
Starting login manager:         SUCCESS
Starting world manager 1:       SUCCESS
Starting proxy server:          SUCCESS
Starting world reader:          SUCCESS
Starting mob server:            SUCCESS
Wait for finished initializing msg...

NOTE: If you are using Ubuntu Linux, see Running the start scripts on Ubuntu.

To restart the servers

To stop and then immediately start the servers and display startup information, use this command:

 ./multiverse.sh -v restart

Startup parameters and scripts

A typical server startup command actually looks like this:

java 
-Dcom.sun.management.jmxremote 
-server 
-cp CLASSPATH
-Djava.system.class.loader=multiverse.server.marshalling.MarshallingClassLoader 
-Dmultiverse.propertyfile=../bin/multiverse.properties 
-Dmultiverse.logs=../logs/myworld 
-Dmultiverse.agenttype=wmgr 
-Dmultiverse.loggername=wmgr_1 
multiverse.server.marshalling.Trampoline 
multiverse.server.engine.Engine 
-i ../bin/wmgr_local1.py -i ../config/common/mvmessages.py -i ../config/myworld/worldmessages.py 
-m ../config/common/mvmarshallers.txt -m ../config/myworld/worldmarshallers.txt
../config/common/global_props.py ../config/myworld/global_props.py 
../config/common/world_mgr1.py ../config/myworld/extensions_wmgr.py

where CLASSPATH is a lenghty list of JAR files, that must include all the required Multiverse JAR files, the JDBC JAR file, and so on.

Domain server startup

The message domain server includes two extra parameters:

• AGENT_NAMES
• PLUGIN_TYPES

AGENT_NAMES="-a combat -a wmgr_1 -a mobserver -a objmgr -a login_manager -a startup -a proxy_1 
             -a instance -a voiceserver"
PLUGIN_TYPES="-p Login,1 -p Proxy,1 -p ObjectManager,1 -p WorldManager,1 -p Inventory,1 
              -p MobManager,1 -p Quest,1 -p Instance,1 -p Voice,1 -p Trainer,1 -p Group,1 
              -p Combat,1 -p ClassAbility,1 -p Startup,1"

Note: the above example includes line feeds for readability. They are not used in practice.

AGENT_NAMES is a list of all the server agent names, each precede by -a, that is passed to the domain server. Each -a identifies a message agent in the domain. A plug-in defines its type via setPluginType() in its constructor. The PLUGIN_TYPES are passed to the domain server. Each -p identifies a plugin type and the number of that type to expect during startup. These are used to evaluate when a plugin dependency is satisfied. For example: -p Beholder,2 means there are two plugins of type Beholder.

To display server status

Windows

To display server status, use this command:

status-multiverse.bat

This command displays server status similar to that show below for Linux.

Linux and Cygwin/Windows

To display server status, use this command:

 ./multiverse.sh status

The script displays "RUNNING" or "NOT RUNNING" for each server, for example:

domain server:           RUNNING
login server:            RUNNING
combat server:           RUNNING
object manager:          RUNNING
world manager 1:         RUNNING
proxy server:            RUNNING
world reader:            RUNNING
mob server:              RUNNING

To ping the servers:

On Linux and Cygwin/Windows, to try to connect to the servers with a test client:

./multiverse.sh -v test

This performs a "ping" on the servers and returns PASS or FAIL. There may be cases in which the servers are running, but do not respond for some reason.

To stop the servers

Windows

To stop the servers, use the command:

stop-multiverse.bat

Note: this batch file actually stops ALL Java processes running on the system, so be sure you want to do this before running it. This script will not affect Java programs (for example, Eclipse) that run as javaw.exe.

Linux and Cygwin/Windows

To stop the servers:

 ./multiverse.sh -v stop

The script displays a message when it stops each server.

If for some reason the Java processes won't terminate, use the following command to kill all Java processes:

./kill.sh

The kill.sh script may not work on all systems. On some Linux/Unix systems you can use the killall command as follows:

killall java

Restarting the servers conditionally

On Linux and Cygwin/Windows, use mv_home/bin/server-monitor.sh to restart the Multiverse servers as neccessary.

This script performs two health checks on each server process. If either check fails, the script will stop the process, rotate the logs, and restart the server process. Set the environment variable MV_MAILTO to send an email notification to that address about the activity.

Run the script manually as follows:

./server-monitor.sh -v

The output looks something like this:

Thu Oct 19 14:24:07 PDT 2006
server health check failed
stopping server: DONE
rotating logs: DONE
restarting: DONE

This script is suitable for running as a cron job. To do this, create a crontab file to run the script periodicallly. This will ensure that if a server does go down, it will be restarted when the cron job executes.

Running multiple servers on one system

It is possible to run more than one set of Multiverse servers on a single host system, assuming the hardware has the capacity. This may be useful, for example, to have one stable version of a world, and a version where developers can experiment.

You can use a single server installation, but each server must use unique:

• Message server port (multiverse.msgsvr_port property)
• Proxy server port (multiverse.proxyport property)
• World manager port (multiverse.worldmgrport property)
• Voice server port (multiverse.voiceport property)
• World name (multiverse.worldname property)

Since these values are set in the properties file, one way to do this would be to create one properties file for each server, then specify different property files when you start the servers.