Torus2, unlike the first Torus, comes with very little to none configuration - most of the user-facing behavior can be controlled via the Web Service.

The configuration that comes with the Torus2 controls low-level behavior of the torus server: record store type and location, caching, etc. This needs to be altered only in a fairly non-standard circumstances. See bottom of this chapter for configuration parameters.

Configuration scheme

Torus2 shares with other components of the MasterKey2 suite a uniform scheme for configuration.

The MasterKey2 configuration scheme includes:

  • Standard directory layout for holding configuration files
  • A mechanism allowing multiple virtual hosts to share a given Masterkey2 binary (a war file) while applying different configurations to that binary for each virtual host (multi-tenant set-up)
  • A standard format for specifying configuration parameters (key-value pairs)

Directory layout

The root directory for all MasterKey2 configuration files is by convention the /etc/masterkey on UNIX systems. This is configured as the default in the web.xml of the component and can be changed to something else by modification of web.xml. For special deployments configuration can be also packaged in the war file and referenced in web.xml (using the war:// prefix) but that obviously limits possibilities of altering the configuration after deployment.

The sub-directory structure depends on which MasterKey2 components are included and whether the installation is for just one host or for multiple virtual hosts. E.g by default Torsu2 keeps its entire configuration under /etc/masterkey/torus2/.

These directories have to be created and populated as part of the installation process - either manually or by a script constructed for the purpose.

Single host setup

The directory structure for a single host setup with a Torus2 (Service-Proxy configuration listed for clarity) would look like this:

  |-- service-proxy/
  |   |-- conf.d/
  |        `--
  `-- torus2/
      |-- conf.d/

For more detailed examples see the sample structure and property files in the Torus2 Git repository under torus/example-config/single-host/.

Multi host setup

The directory structure for a multi host setup, again with a Torus2 and Service-Proxy and with two virtual hosts ( and could look like this:

  |-- service-proxy/
  |   |-- conf.d/
  |   |   |-- host1-config/
  |   |   |   `--
  |   |   |-- host2-config/
  |   |       `--
  |   `-- host1.indexdata.com_confd
  |   `-- host2.indexdata.com_confd
  `-- torus2/
      |-- conf.d/
      |   |-- host1-config/
      |   |   `--
      |   |-- host2-config/
      |       `--
      `-- host1.indexdata.com_confd
      `-- host2.indexdata.com_confd

The files at the end of the list (those that start with a host name and end with '_confd') are host mapping files and contain the name of the sub-directory with conf.d in which the virtual host's specific configuration file resides.

So, for example, the file /etc/masterkey/torus2/host1.indexdata.com_confd contains one key-value pair:

  CONFIG_DIR = host1-config

, which tells the module to look for its configuration file in /etc/masterkey/torsu2/conf.d/host1-config when the requests are coming to that host.

For further details and examples see the sample structure in Git repository under torus/example-config/multi-host/.

Configuration parameters

Once the proper configuration file is discovered (according to the vhost-to- configuration mapping from above), the following settings are read from it:

  storage.ROOT_PATH = /path/on/the/fs

the storage.ROOT_PATH setting is used to control where the filesystem backend stores the Torus records, it will usually differer for each virtual host.

In case a relational backend is used (e.g SQL db) more configuration parameters applicable only to this backend will appear here.

  cache.HONOR_* = yes | no

boolean 'yes/no' flags inlcuding: cache.HONOR_PROTOCOL, cache.HONOR_AUTHORTITY, cache.HONOR_PORT. When set to 'no' (default) the parent record cache considers URLs with different protocol (eg http vs https), authority (HTTP user/password) and port (e.g explicitly specified 80 vs default) to be the same. This makes caching and propagation of changes more effective, but may not be desired in some cases.