Introducing RealityServer

RealityServer Web Services: File System

Two of the main objectives of the new architecture is to:

  • Allow you to structure applications in any manner that suits your needs. If you prefer, you can forego the application concept completely.
  • Remove restrictions regarding the sharing of data between applications.

Content Root

Location of user-generated content: You store all user-generated content in a single directory hierarchy on your local file system. In the configuration file, you specify the location of this directory as a relative path to the site root directory:

 content_root = "content" 

Security issues: The top level directory forms a weak chroot jail so no content can reach out from this structure. However, note the following:

  • Any commands that you create, given that they are implemented in C++ or a script language such as Server-Side JavaScript, will likely have access to the entire file system.
  • If content references files outside the root, such as an .mi file referencing a texture outside the root, the system is not be able to prevent the referenced files from loading.

Serving content: The root of the content directory is used as the root of the RSWS HTTP server. By default, serving content from this directory is denied. If you wish to make use of RSWS as an HTTP server, then you need to specifically allow access to the directories you wish to serve.

Structure of the File System

Simply put: none. RSWS does not impose restrictions about how you lay out the content file system. For example, you can create anything from a flat system with all content in one directory (which would not be recommended) to a full hierarchy of applications and sub-applications. Example: See the content_root directory shipped with RealityServer. This directory uses three sub-directories--applications, client_libraries, and scenes--to organize user-generated content.

Configuration

Directives: Due to the arbitrary nature of the content directory layout, RealityServer requires a mechanism to provide access control for the HTTP server to prevent sensitive or irrelevant data from being served and to configure usage of these directories within RSWS. For example, RSWS needs to know which directories contain custom service commands so that it can load and register the commands. In addition it is necessary to be able to control which scene directories are available. To satisfy these requirements, RealityServer uses Apache-style directives. This solution is well known to users and has a simple, but effective, access control mechanism.

Note: By default, RSWS denies serving any content within the content root. You can change this default setting.

Configuration options: RealityServer configuration is supplied by both a configuration file and by command-line options. Most options are configured by file, some by file or on the command line and some (mostly ones related to specific machine configuration) are by command line only.

Required command-line option: The only required command-line option is --config_file which specifies the location of the configuration file:

$ realityserver_ws --config_file
                realityserver.conf

Location of the configuration file: Unlike earlier versions of RealityServer, you can store the configuration file anywhere in the file system rather than in the hardcoded directory config/sitemain. There is no concept of a site root and you can store different components of the system in different locations in the file sytem. Any relative directories you specify are relative to the location of the configuration file.

Directive syntax: The configuration file format has changed significantly from version 3.0. Rather than taking simple key=value pairs the file format is now based on the Apache 2.0 directive format. There are two types of directives, simple and container. Simple directives consist of a space separated key/value pair. EG:

content_root my_content http_address
                0.0.0.0:8080

Container directives provide context to a set of directives, for example:

<directory /scenes> deny from all
                </directory>
This container directive applies the deny directive with the value from all to the directory /scenes.

More information: For more information about configuration directives and command-line options, see the RealityServer Configuration Guide accessible from the Getting Started menu.