An example rollout of SteamWorks, where configuration information from multiple sources is collected and locally stored for local consistency and independency of cross-site downtime.

This site reflects work in progress.

In a factory driven by a steam engine, the Shaft carries rotary motion from the steam engine's Crank wheel to the Pulley's that drive machinery.

Likewise, the Shaft program is "just" a transporter of configuration data and changes. Vital about this facility is that it crosses site boundaries and helps to do this without sacrificing stability or security.

Read the specification for this tool (written in preparation of coding)

Read the examples for this tool (although the specification prevails)

<!-- Read the man page for this tool (written in preparation of coding) -->

The purpose of the Shaft component is to form a locally consistent image of configuration data within a site. To this end, it forms a cache of the configuration data, which attempts to stay up to date with remote sources of configuration data through LDAP Sync as defined in RFC 4533. The loose term "site" refers to what is also known as a security realm, or an operation domain.

As a client, the Shaft is useful to connect across site boundaries. This means that the client side of the Shaft knows where it should connect, how to use redundancy/fallback support at the remote site, and how to authenticate to such remote realms, possibly with peer-to-peer credentials.

By localising these remote-realm credentials inside the Shaft component, this sensitive information is isolated from application components elsewhere that would otherwise need to store it and make it vulnerable to dedicated application attacks.

By locally storing the retrieved information, the Shaft helps to survive downtime of cross-site connections, which may be extremely hard to overcome. What happens during such downtime situations is that processing of updates is temporarily frozen, but at least the last-known-good configuration is available for intra-site processing so there is no downtime, or a need to fallback to default behaviours.

The Shaft is somewhat intelligent, in that it can integrate information from various remote sites. This enables such things as taking in configuration data from various sources, possibly including local overrides. In this capacity, parts of the configuration data tree are each assigned to a single source; it can hang the remote subtree anywhere in a local subtree.

It is possible to instruct the Shaft to dynamically follow the subtrees that a server can provide, and automatically incorporate any new or removed subtrees in the local Shaft client's list of followed configuration data trees.

As a server, the Shaft component offers LDAP service including LDAP Sync facilities. This means that both Shaft and Pulley components can connect to the server side of the Shaft. Such clients will usually be run on other machines within the same site.

The local buffer maintained by the Shaft suffices to provide the configuration data required for LDAP Sync operation, even if the client-side of the Shaft cannot connect to one or more of its sources.

A vital distinction to notice:

  • Shaft as a client will retrieve complete trees of configuration data, without constraining its intake in any way;
  • Pulley as a client will only retrieve the information that is needed to configure local Machines (meaning, programs).

The setup of the Shaft component is a list of remote server setups, each holding the following information:

  • Information to find the remote server
  • Authentication credentials
  • A list of configuration data trees subscribed to, and for each of those: - Whether this tree is manually setup by the Shaft operator - Whether this tree is currently active; if not, what its queue ranking is - The distinguishedName of the tree as retrieved from the server - The distinguishedName of the tree as stored on the Shaft component
  • Possibly a query that can introduce additional configuration trees

Automatic pickup of new configuration data trees from more than one location may cause clashes, and in this case the first setting prevails, until it is removed on the server side, or manually overridden in the remote server setup in the Shaft. Generally, new arrivals are checked to ensure that they are unique, and if not they are assigned a ranking number that places them in a queue. When the current server for a configuration data tree removes it, a check for this queue is made, and the next in line can take over. Manual overrides are also possible.

In service of monitoring, the Shaft component will output lists of both client and server connections. This can be used by monitoring tools to ensure that all intended connections are active.