Configuration scheme

The Service Proxy 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 /etc/masterkey on UNIX and Linux systems. This is configured as the default in the web.xml of the component and can be changed to something else by editing web.xml. For special deployments, configuration can be also packaged in the war file and referenced in web.xml (using the war:// prefix) but this approach obviously limits the 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. By default the Service Proxy keeps its entire configuration under /etc/masterkey/service-proxy/.

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 Service-Proxy (Torus 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 service-proxy Git repository under service-proxy/example-config/single-host/.

Multi host setup

The directory structure for a multi host setup, again with a Service Proxy and a Torus 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 within conf.d in which the virtual host'ss specific configuration file resides.

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

  CONFIG_DIR = host1-config

This tells the module to look for its configuration file in /etc/masterkey/service-proxy/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 service-proxy/example-config/multi-host/.

Standard format properties (for plugin developers)

This section is mostly relevant when you're developing new functionality, and thus new configuration parameters.

Each configuration parameter name consists of a module identifier and a propety name. Like this:

  module-name.PROPERTY-NAME = property-value

It's up to the application code to decide what constitutes a module and give it a name/prefix. A module could be a Servlet, a plugin, a REST service, or any other entity. The name is basically a tag that defines a name space for the entity's properties.

If you look at one of the files, you will see properties for a plugins module for instance. "plugins" is a tag used by the plugin framework to register plugin names.

Other module prefixes like relay or authn are actually dynamically defined plugin names. If the configuration names a plugin plugins.authn then this plugin must be configured by prefixing its properties with authn. It could be renamed to authntorus in the property file itself as long as it's done consistently. This means that plugins do not name themselves in the code -- this is handled by the property file and the plugin framework.

In the Service Proxy you can name a plugin with anything as long as it does not clash with the reserved keywords (plugins and chains).