Configuration

In order to be able to tailor a Corus installation to specific needs, one needs understanding the file layout, and the main configuration elements.

File System Layout

When deploying a distribution to Corus, it is unzipped on the server-side, according to a predefined layout.

Corus Home

After installation, your CORUS_HOME environment variable should have been set, and point to the directory where you've extracted the Corus package. Under CORUS_HOME, other directories will appear (or be created when Corus first starts up). The directories are as follows:

  • config: holds the Corus configuration files (at least one: corus.properties.
  • bin: holds the Corus executables.
  • db: holds the directory where Corus' database state is kept (on a per-Corus instance basis).
  • deploy: holds the directory deployed distributions are extracted (on a per-Corus instance basis).
  • files: holds the directory deployed files are extracted (on a per-Corus instance basis).
  • logs: holds the directory where Corus' logs are kept (on a per-Corus instance basis).

What is meant by "on a per-Corus instance basis" is explained in the next section.

Instance Directory

You can start multiple Corus instances on the same hosts if you please, as part of the same domain, or as part of different ones. In any case, each server instance will have its own working directory under each per-instance directory (see the previous section for what these directories are). The working directory of a given server instance is identified by the following pattern:

port_<port_number>

For example, a Corus server instance listening on port 33000 (Corus' default port) would have port_33000 as its working directory.

To be clearer, for a Corus instance running on port 33000 would have the following directory layout under CORUS_HOME:

config/
bin/
db/
  port_33000/
deploy/
  port_33000/
files/
  port_33000/
logs/
  port_33000/

Corus Distribution Directories

As was mentioned previously, when a distribution is deployed into Corus, it is extracted under the server's deploy directory. More precisely, Corus creates the following structure under the deployment directory:

<distribution_name>
  /<version_number>
    /common
    /processes

The actual distribution archive is extracted under the common directory. When executing a process of that distribution, Corus internally assigns an identifier to that process; it then creates a directory under the processes directory that is given the process identifier as a name. For example, if the process identifier is 1234567, then the 1234567 directory is created under the processes directory.

As is described in the Corus System Properties section further below, processes are passed the above information (their common and process directories) as the following system properties, respectively: user.dir and corus.process.dir.

Configuration Properties

A Corus server takes into account two configuration files (actually, Java property files), both in the $CORUS_HOME/config directory. It also supports remotely overriding the properties in these files: in such cases, the properties are kept in Corus' internal database - see the Remote Property Update subsection further below on that topic). These files are:

  • $CORUS_HOME/config/corus.properties: holds the server's configuration parameters.
  • $CORUS_HOME/config/corus_process.properties: holds properties that are passed to each started process.

Both of these files must respect the Java properties format. The corus_process.properties file holds arbitratry properties that are passed to executed processes (through the command-line) as Java system properties. This means a command-line option respecting the format below is created for every property in the file:

-D<property_name>=<property_value>

For its part, as stated, the file named corus.properties, contains the server's configuration properties. Note that since Corus rests on Sapia's Ubik distributed computing framework, it also supports all Ubik properties (which is of interest when wanting to use Avis as a node discovery mechanism).

Additionally, as a convenience when running multiple Corus instances on the same host, additional files can be specified allowing for configuration that is specific to each instance. Such configuration files must respect the following naming convention to be loaded at startup:

$CORUS_HOME/config/corus_<port>.properties

Where <port> corresponds to the port of the Corus instance to which this file is destined.

Configuration can also be kept under the HOME directory of the user under which the Corus server is running. See the Home Directory Overrides subsection below for more details.

The Corus server's configuration properties are described in the table below. The table indicates if the current property can be remotely updated - the Remote Property Update section, further below, describes the mechanism for storing configuration properties within the Corus server itself. Please see that section for it provides relevant information about where to keep configuration properties.

PropertyDescriptionRequiredRemote Update

corus.server.properties.include.01
[corus.server.properties.include.02
corus.server.properties.include.
...]

One ore more property includes, each consisting of the path to one or more property files that should be included and are stored in arbitrary locationiuin the file system (potentiallly in mounted network drives). The files in each path should be separated by either ':' or ';' - without the quotes. This mechanism allows sharing configuration across multiple Corus instances. No No
corus.server.domain The name of this property corresponds to the name of the domain to which the Corus server belongs. If the domain is specified at the startup script of the Corus server (through the -d option), this property is not taken into account. No (if not specified in the file, must be given as the -d option at the Corus server startup script). No
corus.server.port The port on which the Corus server should listen. If the port is specified at the startup script of the Corus server (through the -p option), this property is not taken into account. No (defaults to 33000) No
corus.server.tmp.dir The directory where distributions are deployed, pending their extraction under the deploy directory. No (defaults to (defaults to $CORUS_HOME/tmp /<instance_dir>) Yes (requires server restart)
corus.server.deploy.dir The directory where distributions are extracted and kept. No (defaults to (defaults to $CORUS_HOME/deploy /<instance_dir>) Yes (requires server restart)
corus.server.db.dir The directory where Corus' internal database stores its files. No (defaults to (defaults to $CORUS_HOME/db /<instance_dir>) Yes (requires server restart)
corus.server.uploads.dir The directory where file uploads (that is, files deployed with the -f switch in the CLI) are kept. See the File Uploads section for details. No (defaults to (defaults to $CORUS_HOME/deploy /files/uploads/<instance_dir>) Yes (requires server restart)
corus.server.scripts.dir The directory where deployed shell scripts (deployed with the -s switch in the CLI) are kept. See the Shell Scripts section for details. No (defaults to (defaults to $CORUS_HOME/deploy /files/scripts/<instance_dir>) Yes (requires server restart)
corus.process.start-at-boot.enabled Indicates if a processes should be started automatically at Corus server boot time, provided these processes have an execution configuration that is flagged as startable on boot – i.e: the startOnBoot flag is set to true. No (defaults to true) Yes
corus.process.timeout Delay(in seconds) after which processes that have not polled their Corus server are considered stale. Yes Yes
corus.process.check-interval Interval(in seconds) at which the Corus server checks for timed out processes. Yes Yes
corus.process.kill-interval Interval(in seconds) at which the Corus server attempts killing a crashed process. Yes Yes
corus.process.start-interval Amount of time that Corus will wait for between process startups, when multiple processes are started at once by end-users. No (defaults to 15). Yes
corus.process.restart-interval Amount of time (in seconds) a process must have been running for before it crashed and in order for an automatic restart to be authorized. Yes Yes
ubik.rmi.naming.mcast.address and ubik.rmi.naming.mcast.port The values of these properties are by default made to correspond with the default values used by Ubik (the distributed computing framework on which Corus is based). Yes Yes (requires server restart)
ubik.rmi.address-pattern A regexp specifying on which network address the Corus server should listen. It is preferrable to set that property if the host on which Corus is installed has more than one network interface. By default, Corus will listen on all network interfaces. It will also attempt to return as part of the remote stubs that it generates the first network address it finds that is not localhost – otherwise, localhost will be used. No No
corus.server.security.hostPattern.allow and corus.server.security.hostPattern.deny Each property is expected to hold a comma-delimited list of patterns of IP addresses from which clients are either allowed or denied connection, respectively.

Here are valid patterns:

192.168.*.*
192.*.*.*
192.**
192.**.*
No Yes
corus.server.syslog.protocol The protocol to use to connect to the Syslog daemon - value may be udp, tcp. Note: for Syslog integration to be activated, all properties under corus.servder.syslog.* must be set. No No
corus.server.syslog.host The host of the Syslog daemon. No No
corus.server.syslog.port The port of the Syslog daemon. No No
corus.server.alert.enabled Indicates if email alerting should be enabled. No (defaults to false) Yes
corus.server.alert.smtp.host The host of the SMTP relay to use to send alert emails. No (defaults to false) Yes
corus.server.alert.smtp.port The port of the SMTP relay to use to send alert emails. No (defaults to 25) Yes
corus.server.alert.smtp.password The SMTP password to use when connecting to the SMTP relay upon sending email alerts. No Yes
corus.server.alert.recipients The semicolon-delimited list of recipient email addresses to use when sending alert emails. Yes Yes
corus.server.alert.sender The email address that should appear in the “from" field when sending alert emails. Yes (if not specified, a default is built based on the host of the SMTP relay) Yes

Remote Property Update

Corus supports remotely updating server or process properties. In such cases, it is not the actual property files that are modified: rather, Corus adds/removes the properties to/from its internal database; if specified, the properties will override the corresponding ones in the file.

The updates are performed using the Corus command line interface. The conf command allows adding, deleting, and listing either server or process properties. The command also supports updating so-called “tags" (explained in the next section). The syntax goes as follows:

Adding Properties

To add a property, or a list of properties:

conf add -s s|p -p name1=value1[,name2=value2[,nameN=valueN[...]]

Where:

  • s specifies the scope (indicating if the property is a server (s) or process (p) property – the scope defaults to process when not specified).
  • p consists of a comma-delimited list of name-value pairs corresponding to actual properties (there must be no space in the list for it to be parsed properly).

Listing Properties

To list properties:

conf ls [-p <name>] -s s|p

Where:

  • p specifies a name or name pattern (using wildcards)
  • s specifies the scope (indicating if the property is a server (s) or process (p) property – the scope defaults to process when not specified).

Removing Properties

To remove a property

conf del -s s|p -p some.property
conf del -s s|p -p some.*

Where:

  • s specifies the scope (indicating if the property is a server or process property)
  • p specifies the property to remove (may include wildcards corresponding to a property name pattern – in which case all matching properties will be removed
For the properties with the “server" scope, the Corus instance might have to be restarted for the new values to be taken into account.

Property Includes

It may be convenient to share configuration properties across multiple Corus instances. This is possible through a mechanism dubbed “property includes". How this works is very simple: you configure includes in the corus.properties file, as follows:

corus.server.properties.include.01=${user.home}/.corus/corus.properties 
corus.server.properties.include.02=/opt/corus/corus.properties:/etc/corus/corus.properties

To configure includes, you have to follow the format below for property names:

corus.server.properties.include.<suffix>

This format allows configuring multiple includes on different lines. The suffix can be any string, but you should design them keeping in mind that Corus will evaluate includes based on the sort order of their corresponding suffix.

On the right-hand side, the property value is expected to be a path composed of multiple segments, each pointing to a file to include, and where each segment is separated by either a colon (:) or semicolon (;).

As you can see, property values may also contain variables in the following format:

${<name>}

Variables are expected to correspond to JVM properties (such as user.dir, user.home, etc.). Such variables are evaluated at Corus startup.

Home Directory Overrides

Corus server properties files can be kept under the $HOME/.corus directory, where $HOME corresponds to the home directory of the user under which the Corus server is running. The following files will be automatically loaded at startup, and will override the ones found under $CORUS_HOME/config:

$HOME/.corus/corus.properties
$HOME/.corus/corus_&lt;port&gt;.properties

In the above <port> stands for the port of Corus instance to which the given properties are targeted.

Property Categories

As of version 4.5, Corus supports so-called property “categories" - for process properties only. Property categories really allow grouping properties so that not necessarily all properties apply to all processes.

To be clearer: when adding process properties to Corus, such properties are “global" by default, in the sense that they are passed to all processes at startup. This might not be the desired effect when deploying unrelated applications to the same Corus instances. In such cases, one may wish to isolate certain sets of properties so that these are passed to only certain applications.

The conf command supports assigning categories to properties. This is done through the -c option, as shown by the following example:

conf add myapp.properties -c server-apps

The -c option allows passing a comma-delimited list of categories (there must be no space between the categories):

conf add myapp.properties -c server-apps,admin-apps

Passing the right set of properties to given processes is specified through the Corus descriptor (corus.xml). To sum it up:

  • Global process properties (those that are in the $CORUS_HOME/config/corus_process.properties file, and those stored in Corus with no category assigned to them) are always passed to all processes;
  • the properties corresponding to the different categories are passed only if these categories are specified in the Corus descriptor, for the given distribution/process. Such properties will override global process properties with identical names).

To better undersand the above, let's examine the following Corus descriptor sample:

<distribution
	xmlns="http://www.sapia-oss.org/xsd/corus/distribution-5.0.xsd" 
	name="demo" 
	version="1.0" propertyCategories="myproduct" >
  <process name="myServer" 
           ...
           propertyCategories="server-apps">
    <port name="test" />
    ...
  </process>  
</distribution>

The descriptor shows the propertyCategories attribute defined both on the <distribution> and on the <process> elements. Both support a comma-delimited list of property categories, for which order matters: for identically-named properties, the ones whose category came first will be overridden by the properties of subsequent categories.

Furthermore, property categories defined at the <process> level will override those defined at the <distribution> level, for identically-named properties.

The CLI's conf command allows viewing properties and their categories, as well adding/updating/deleting properties, taking categories into account – type man conf in the CLI for more details.

In the end then, the set of properties passed to a process includes (in that order, which also is the order in which overriding is done):

  • The properties that are created at startup by Corus for a given process (corus.process.id, corus.process.dir, etc.).
  • The properties defined in the $CORUS_HOME/conf/corus_process.properties.
  • The global process properties stored in Corus (those added with conf add, and not assigned to a category).
  • The process properties corresponding to the categories specified at the <distribution> level (if any).
  • The process properties corresponding to the categories specified at the <process> level (if any), for the currently starting process.

Dynamic Domain Change

The domain of a Corus instance (or of a whole cluster) can be dynamically changed, without restarting Corus, either through the CLI or through the REST API. Here's an example using the CLI:

cluster domain my-new-domain -cluster

When the name of a Corus cluster is changed this way, Corus saves it in a file named .corus-readonly-<corus-server-port>.properties, under the $HOME/.corus directory (where $HOME corresponds to the home directory of the user under which the Corus server process runs, and <corus-server-port> to the port of the current Corus instance).

Corus always looks for the presence of that file at startup, and the properties it contains will supplement/override all other server properties.

As its name implies, this file should not be manually edited by system administrators.