5.3 Server Configuration

This section discusses the options for compiling and running the server that can affect the database and how the code within it runs.

5.3.1 Server Compilation Options

The following option values are specified (via #define) in the file ‘options.h’ in the server sources. Except for those cases where property values on $server_options take precedence, these settings cannot be changed at runtime.

This list is not intended to be exhaustive.

Network Options

NETWORK_PROTOCOL

This specifies the underlying protocol for the server to use for all connections and will be one of the following:

NP_TCP

The server uses TCP/IP protocols.

NP_LOCAL

The server uses local interprocess communication mechanisms (currently either BSD UNIX-domain sockets or SYSV named pipes).

NP_SINGLE

The server accepts only a single “connection” via the standard input and output streams of the server itself. Attempts to have multiple simultaneous listening points (via listen() will likewise fail.

DEFAULT_PORT

(for NP_TCP) the TCP port number on which the server listens when no port-number argument is given on the command line.

DEFAULT_CONNECT_FILE

(for NP_LOCAL) the local filename through which the server will listen for connections when no connect-file-name is given on the command line.

OUTBOUND_NETWORK

The server will include support for open_network_connection() if this constant is defined. If given a zero value, the function will be disabled by default and ‘+O’ will need to be specified on the command line in order to enable it, otherwise (nonzero or blank value) the function is enabled by default and ‘-O’ will needed to disable it.

When disabled or not supported, open_network_connection() raises E_PERM whenever it is called.

The NETWORK_PROTOCOL must be NP_TCP.

MAX_QUEUED_OUTPUT

The maximum number of output characters the server is willing to buffer for any given network connection before discarding old output to make way for new.

MAX_QUEUED_INPUT

The maximum number of input characters the server is willing to buffer from any given network connection before it stops reading from the connection at all.

Other Options

IGNORE_PROP_PROTECTED

Disables protection of builtin properties via $server_options.protect_property when set. See section Protected Properties.

OUT_OF_BAND_PREFIX

Specifies the out-of-band prefix. If this is defined as a non-empty string, then any lines of input from any player that begin with that prefix will not be consumed by reading tasks and will not undergo normal command parsing. See section Out-of-band Processing.

OUT_OF_BAND_QUOTE_PREFIX

Specifies the out-of-band quoting prefix. If this is defined as a non-empty string, then any lines of input from any player that begin with that prefix will have that prefixed stripped and the resulting string will bypass Out-of-Band Processing.

The following are discussed in Controlling the Execution of Tasks.

DEFAULT_MAX_STACK_DEPTH

Default value for $server_options.max_stack_depth.

DEFAULT_FG_TICKS

The number of ticks allotted to foreground tasks. Default value for $server_options.fg_ticks.

DEFAULT_BG_TICKS

The number of ticks allotted to background tasks. Default value for $server_options.bg_ticks.

DEFAULT_FG_SECONDS

The number of seconds allotted to foreground tasks. Default value for $server_options.fg_seconds.

DEFAULT_BG_SECONDS

The number of seconds allotted to background tasks. Default value for $server_options.bg_seconds.

DEFAULT_CONNECT_TIMEOUT

Default value for $server_options.connect_timeout.

5.3.2 Running the Server

The server command line has the following general form:

moo initial-arguments db-file-name dump-db-file-name network-arguments

The arguments must occur in this order, e.g., a log file name (-l) must come before db-file-name and dump-db-file-name while any port number must come afterwards.

Initial Arguments

-l log-file-name

(Optional) This specifies a file name for the server log output. If no log file name is specified, log output is directed to stderr.

-e

(Optional) This specifies that, once the database is loaded, Emergency Wizard Mode will be entered before starting any tasks or doing the initial listen to accept connections.

Database Arguments

db-file-name

(Required) This should be an existing database file in the appropriate format, whether this be a checkpoint or dump file from a prior run of the server, or one of the many distributed database files in existence (e.g., the ‘Minimal.db’ file provided with the server source distribution).

dump-db-file-name

(Required) This should indicate where to write checkpoint and final dump files. Note that the server does not immediately verify this path, i.e., there is no checking at startup that the file in question is actually writable; in fact, that the directory exists and is writable at the time the dump or checkpoint is attempted is all that really matters.

Network Arguments

The particular set of network arguments available depends on which NETWORK_PROTOCOL the server was compiled with. For a server compiled for single-user mode (NP_SINGLE), there are no additional arguments. For a server compiled for local interprocess communication (NP_LOCAL), there is just

connect-file-name

(Optional) This specifies the pathname for the (UNIX domain) socket or named-pipe that will be used for connecting to the server. If no connect file name is specfied, the compiled-in value of DEFAULT_CONNECT_FILE is used.

For a server compiled for general TCP/IP connections (NP_TCP), we have

-p port-number

(Optional) This specifies an initial port at which to listen for connections once the server successfully starts. If no port number is specfied, the compiled-in value of DEFAULT_PORT is used.

For the sake of backwards compatibility with prior server versions, the -p may be omitted.

-a n.n.n.n

This specifies a local IP address to bind for all listening and all outgoing connection attempts. n.n.n.n must be a valid numeric IP address assigned to one of the local host's network interfaces. If no specific IP address is specified, any listening (be this the initial listen implicit in server startup or any explicit listening invoked by the listen() function) will bind to all IP addresses on all available network interfaces; likewise outgoing connection attempts will use whatever address is available.

This is how, on a host with multiple network interfaces, one makes the server be visible only on one of them. At present, there is no way to specify that the server should bind to a subset of of the available IP addresses having more than one address but less than the entire set available. However, if the operating system offers port-forwarding and network address translation facilities, one can likely use those to achieve a similar effect.

Note that even on hosts with only a single physical network interface, there will typically be multiple logical ones. One may, for example, specify the loopback address (usually 127.0.0.1), forcing the server to use the loopback interface for all connections, thus guaranteeing that only local connections, whether incoming or outgoing, will be possible (and thus acheiving most of the safety of NP_LOCAL or NP_SINGLE without needing specialized clients).

+O

Explicitly enables open_network_connection() but only if the server has been compiled to include support for this function (i.e., OUTBOUND_NETWORK has been #defined).

-O

Explicitly disables open_network_connection(). Any calls to this function will raise E_PERM even if the server has been compiled to support it.

5.3.2.1 Emergency Wizard Mode

This is a mode that allows you to enter commands on standard input to examine objects or evaluate arbitrary code with wizard permissions in order to, e.g., blank out a forgotten wizard password or repair a database having a broken $do_login_command verb that otherwise would not allow anyone to connect.

When you start the server and supply the -e command line option, the database will load and you will then see a prompt indicating the identity of the wizard whose permissions you are using and the current state of the debug flag, e.g., one of

MOO (#2):
MOO (#2)[!d]:

the latter version of the prompt indicating that the debug flag is unset, and thus that errors will be returned rather than raised, as when you unset the d flag on a verb.

The following commands are available in Emergency Mode:

;expression

;;statements

Evaluate expression or statements, print the expression result or the statement return value.

Note that expression or statement can be omitted, in which case you will be prompted for multiple lines of input, as for the .program command. Type a period on a line by itself to finish.

Also note that no background code, whether resulting from fork statements or suspend() calls, will run until after the Emergency Mode is exited.

program object:verb

Set the code of an existing verb.

list object:verb

List the code of an existing verb.

disassemble object:verb

List the internal form of an existing verb.

debug

Toggle the debug flag.

wizard #objectid

Execute future commands as wizard #objectid, which must be an existing player object with ‘.wizard==1’.

continue

Exit the emergency mode, continuing with normal start-up. That is, the server will perform the initial listen and start accepting connections.

quit

Exit the emergency mode, save the database and shut down the server.

abort

Exit the emergency mode, and shut down the server without saving the database. This is useful for if you make a mistake

help

Print the list of commands.

Note that output from wizard mode commands appears on the server's standard output stream (stdout) and thus can be redirected independently of the log messages if those are being written to the standard error stream (stderr, i.e., if -l has not been specified on the command line).

Also note that unless the server has been compiled to use the NP_SINGLE networking variant, Emergency Wizard Mode is the only use of the server's standard input and output streams.

This document was generated by Roger Crew on March, 27 2010 using texi2html 1.78.