Introduction

RealityServer Web Services configuration is achieved via a configuration file and command line options. The configuration file to be used is specified on the command line using the compulsory config_file option

realityserver --config_file realityserver.conf

The configuration file does not need to reside in any specific location in the file system. However any relative paths within the file will be taken relative to the configuration file rather than relative to the current working directory.

The configuration file format is based on Apache style configuration. This consists of simple directives, which are a space separated key and value and container directives which contain, and provide context to, other directives.

Command line options follow the same pattern as in RealityServer 3.0 command line options and many are unchanged.

Configuration File Format

Configuration is line based with 1 directive specified per line. Lines are terminated with either the standard UNIX '\n' terminator or the standard WINDOWS two character "\r\n" terminator. Both usages may exist within a single file. The back-slash "\" may be used as the last character on a line to indicate that the directive continues onto the next line. There must be no other characters or white space between the back-slash and the end of the line. Once multi-line concatenation is complete any leading whitespace is stripped from the line and directive processing may begin. Trailing whitespace is not stripped. Lines consisting of whitespace only are ignored.

Comments

A line beginning with the '#' character is considered a comment and is ignored by the configuration parser. Note that this means that any '#' character found within a directive is interpreted as part of the directive.

Keys

Keys identify the name of a directive and are identified by the following POSIX regular expression:

[A-Za-z0-9_]+

Keys are not case sensitive

Values

Values identify the value of a directive and may contain any character. The only restriction is they may not begin with a whitespace character. The configuration format imposes no other restriction or interpretation (other than environment variable substitution) on the format of a value. Formatting, including the interpretation of quotation marks is defined on a per directive basis. Values are identified by the following POSIX regular expression:

[^[:space:]].*

Environment variable substitution

All values undergo environment variable substitution. This would typically be used when you have multiple RealityServer instances running over a shared file system and need to provide slightly different configurations to each. Rather than providing separate configuration files you can simply use environment variables to modify the differing parts at start up.

Substitutions are identified using ${ENV_VAR_NAME}. EG: ${HOSTNAME} will substitute the machines hostname on a linux system. If the supplied environment variable is not found a warning is issued and an empty string is substituted instead. Environment substitutions are identified by the following POSIX regular expression:

\${[^}]*}

Conditional configuration

Sections of configuration can be conditionally included based on the existence of particular environment variables. A guarded block begins with the directive

ifdef ENV_VAR

And ends with the directive

endif

All directives between these two lines are only included if the environment variable ENV_VAR is defined. Note that the value should not be wrapped in the substitution tags ${...} unless you wish to indirectly provide the variable name. Conditional blocks can be nested.

ifndef

else

ifdef/ifndef

Echo

During configuration file parsing messages can be echoed to standard error. Note this is explicity standard error as the logger is not available during configuration file parsing.

echo message

Echo statements can appear any where in the configuration file and as such cannot be used as keys inside <user> directives.

Container Directives

A line beginning with the character '<' and ending with '>' defines a container directive. Container directives provide a context in which the enclosed directives apply. This context is identified by a key/value pair within the delimiters. A container begins with a directive of the following form:

^<[[:space:]]*Key[[:space:]]+Value>[[:space:]]*$

And ends with the following:

^<[[:space:]]*/Key[[:space:]]*>[[:space:]]*$

All directives between these two directives are to be stored in the context of the containers key and value.

Simple Directives

Simple directives are a key/value pair within a single line. A valid directive within a line is defined by the following:

^Key[[:space:]]+Value$

Supported Directives

The following sections list the directives supported by RealityServer Web Services.

Note that any relative file name or directory values are interpreted as relative to the configuration file itself. Absolute paths are filesystem absolute unless otherwise specified.