Port Management

Corus has a port management feature allowing the specification of so-called “port ranges". Network ports belonging to these ranges are leased to started processes and “recuperated" upon process termination – in order to be leased to other processes.

This feature was implemented as an answer to the classical problem of port assignment in the context of distributed applications, especially when multiple instances of such applications are meant to be deployed on the same host.

Since ports on a given host cannot be shared, applications using static ports must have them explicitly configured, which quickly becomes burdensome when dealing with multiple running instances of applications performing the same service.

Hence the Corus port management feature, which works as follows:

  • The administrator creates port ranges (with a minimum and a maximum port) that are given a unique name.
  • As part of the corus.xml descriptor, if a process requires a port, then a corresponding <port> XML element should appear for that process' configuration. The element takes a name attribute whose value must correspond to the name of a configured port range.
  • Upon process start-up, the Corus server remove an available port from the range that matches the port specified as part of the process configuration (Corus keeps a an internal list of leased and available ports for every configured port range).
  • The acquired port is "passed" to the process as a system property (through the commandline that starts the process). The system property format is given below: -Dcorus.process.port.<range_name>=<port>
  • That property can then be recuperated by the started process from application code.

The port manager built within Corus can be administered through the Corus command-line interface (type man port at the command-line for more information). The configuration snippet below shows how a port is configured; of course multiple port elements can be configured for each <process> element.

<distribution xmlns="http://www.sapia-oss.org/xsd/corus/distribution-5.0.xsd" name="demo" version="1.0">
  <process name="httpServer" maxKillRetry="3" shutdownTimeout="30000" invoke="true">
    <port name="http" />
    <magnet magnetFile="httpServer.magnet.xml" profile="test" vmType="server">
      <property name="http.port" value="${corus.server.port.http}" />
      <xoption name="ms" value="16M" />
    </magnet>
  </process>
</distribution>

In the above example, a port named http is referred to in the configuration, by the <port> element. This indicates to Corus that upon starting the httpServer process, it should pass a port from the http range to it.

The following command illustrates how such a range would have been created beforehand:

port add -n http -min 8080 -max 8085

So the above command creates the port range named "http". As processes are started that require a port from that range, the number of available ports in the range decreases (until all ports are taken and none can be allocated anymore). The above-configured range would allow for 6 processes to be started in this manner.

Note in the Corus descriptor above that a ${corus.server.port.http} is used: as was mentioned further above, when Corus allocates a port to a process, it makes the value of that port available as a property - which can then be used as a variable in configured, and which is also passed to the JVM being started as a system property, through a -D option.