CONNECT [directory]

The CONNECT command makes a regular, non-administrative connection to an object repository server running in a directory. The connection usually gets placed into a sandbox area, according to the namespace rules defined for the given object repository.

directory is optional when there's exactly one object repository server node directory installed in the default installation directory, which is usually /var/stasher/nodes or /usr/local/var/stasher/nodes. If there's more than one node directory, or if it's not in the default location, the directory parameter is required.

This example makes a connection to an object repository cluster node running from nodekey.dir. stasher prompts with a “>” when its not connected to any server. When connected the node's name is included with the prompt. stasher can connect to only one server at a time. After connecting, stasher reports the server's limits. In this example, the server will accept a maximum of ten objects per transaction, with their total aggregate size not exceeding a megabyte; and the server accepts a maximum of ten object subscriptions at a time.

ADMIN [directory]

The ADMIN command makes an administrative connection to an object repository server running in a directory. The directory must be owned by the same user-id that's running stasher otherwise the connection fails.

directory is optional when there's exactly one object repository server node directory installed in the default installation directory, which is usually /var/stasher/nodes or /usr/local/var/stasher/nodes. If there's more than one node directory, or if it's not in the default location, the directory parameter is required.

START {directory}

The START command starts a child process that runs an object repository server in the directory, which must've been previously created by stashermg --nodekey --generate. An administrative connection gets immediately established with the newly started server process, as if by the “ADMIN” command.

DISCONNECT

The DISCONNECT command drops the connection with the server. stasher can only connect to one server at a time, and an existing connection must be dropped before another CONNECT or ADMIN command.

GETPROPS

This command displays a list of current server property settings. Server property settings are low level configuration settings that control the server's operation. The GETPROPS command displays a list of property settings, and each setting's current value.

SETPROP {name} {value}

The SETPROP command changes an internal server property setting name to value. Generally, the setting takes effect immediately, and is permanent. The new setting remains in effect when the server gets restarted.

RESETPROP {name}

The RESETPROP command resets a property setting to its default value the next time the server restarts. The default property setting value does not take effect immediately. It's necessary to stop and restart the server for the property to revert to its default value.

SETLIMITS {maxobjects} {maxobjectsize}

Set a maximum limit of maxobjects objects updated per transaction, with the total aggregate size of all objects in the transaction no more than maxobjectsize. maxobjectsize can be given as “nMb”, in megabytes.

These limits take effect for new client connections only, and do not affect existing connections. In order to effectively manage the object repository's available space, all client connections must have the same uniform limit, so this command gets typically used when creating a new object repository cluster. If the limits of an existing cluster get changed, all object repository nodes should be restarted in an orderly fashion, to enforce consistent limits for all client connections.

Specifying “default” for maxobjects or maxobjectsize resets the correspoding limit to its “factory default” setting (10 objects, 32 megabytes).

STATUS

The STATUS command displays the connected node's current status. The result is a long report on the node's state, with mind-numbing detail.

STOP

The STOP command stops the repository cluster node and terminates the daemon process. The stoppage is immediate, and the administrative connection with the server gets dropped.

Stopping a slave cluster node generally has little impact, as long as the majority of nodes in the cluster remain in quorum. If the stopped node was a master node, the remaining nodes must elect a new master. This is a disruptive event and should be avoided, if possible. Once a new master gets elected, each slave has to synchronize its copy of the object repository with the master, before regular operations can resume. Depending on the size of the object repository, this can take a long time.

Use the “STATUS” command to verify which node is the current master node, and that there's sufficient number of nodes for the cluster to remain in quorum (the majority of nodes in the cluster are up, connected and synchronized with each other). If this node is a repository master node, use the “RESIGN” command to make another node a master, in an orderly fashion.

RESIGN

If this node is the current master of the cluster, another node takes its place. This is an orderly transition that does not require each node to re-synchronize itself with the new master.

The RESIGN command has no effect if the connected node is not the current master.

HALT

Halt the entire cluster. All nodes in the cluster get stopped. This command requires a full quorum (all nodes in the cluster are up, connected and synchronized with each other), and can only be issued when connected to the cluster's master node.

Use STATUS to show the cluster's master node and its quorum status. This is the safest way to stop an entire cluster and have any connected clients receive a reliable indication whether their last transaction succeeded, or not.

EDITCLUSTER [FORCE] [NEW] [command]*

The EDITCLUSTER command loads the list of cluster nodes, for editing by the CLUSTER command. The cluster list is a list of nodes in the repository, the machines they run on, and their individual configurations. It's stored as an object in the repository itself, named “etc/cluster”. EDITCLUSTER loads this list. The CLUSTER command makes changes to the list, and SAVECLUSTER installs a new “etc/cluster” object.

Since the list of cluster nodes is saved as an object in the repository, changes made to the cluster configuration using an administrative connection on any node get automatically replicated to all nodes in the cluster.

In marginal situations it may be necessary to use EDITCLUSTER with the "force" or "new" option to recover from fatal errors that prevent normal object repository cluster operations.

The object repository cluster node configuration is stored as an object in its own repository. If the repository cluster is not in quorum, attempts to read or update objects hang, until the repository quorum gets established, and the EDITCLUSTER and SAVECLUSTER commands wait until quorum (the majority of nodes in the cluster are up, connected and synchronized with each other) gets established.

There are situations where a quorum can never be established. This can occur, for example, if: a node in the repository permanently disappears for some reason; the node is not yet removed from the cluster's configuration; and the remaining operational nodes are insufficient for a minimum quorum. The former node has to be deleted from the configuration, before the total number of nodes in the repository falls and the remaining nodes now comprise a majority quorum. So the cluster configuration cannot be loaded until a quorum is formed, and the quorum cannot be formed until a node gets removed from the cluster's configuration.

To recover from this situation, a new administrative connection must be established, and the “force” parameter specified to the EDITCLUSTER command. “force” loads “etc/cluster” from the node's copy of the object repository, even if the cluster is not in quorum. This permits editing to proceed.

If the “etc/cluster” object itself is corrupted or damaged, and cannot be parsed, the “new” parameter (which can be used together with “force”) ignores the contents of “etc/cluster”, and starts editing with an empty list.

Any additional words given to EDITCLUSTER, “[command]*”, if present, get processed as if they were given to the CLUSTER command.

CLUSTER [command]*

CLUSTER changes the list of nodes in the cluster and their configuration. A CLUSTER by itself shows the current list. If followed by a command, the command updates the list of nodes, and SHOW shows the changed list. The list of individual cluster commands follows. They are typically combined into a single CLUSTER directive, since they often must follow in a specific order, as described:

Examples:

Define a new node named “nodea” in the cluster, with the the setting “host” containing two values, “ip1.nodea.example.com” and “ip2.nodea.example.com”. The SET directive sets the first value for “host”, and ADD adds the second value (if it was also a SET the second SET replaces the value from the first one).

Additionally, the “nomaster” setting, that takes no value, is given.

This example removes the “nomaster” setting from “nodea”.

Move node “nodea” after “nodeb” in the node list.

SAVECLUSTER [FORCE]?

All changes specified by previous CLUSTER command take effect. A new “etc/cluster” objects is installed in the object repository, and distributed to all nodes in the cluster.

SAVECLUSTER fails with an error message if the list of nodes in the repository was independently updated, by another stasher on the same node, or another node in the cluster, after the initial EDITCLUSTER command.

The FORCE option should only be specified for the same reason that its given to EDITCLUSTER, and its full implication must be fully understood.

FORCE updates the “etc/cluster” object, with the new cluster configuration, on the connected node only. It's meant to be used as an emergency repair tool, to bring up the repository cluster under dire circumstances:

NAMESPACE {command}*

Make changes to global object repository namespace rules. An administrative connection has full read/write access to the entire object repository namespace. A non-administrative connection typically has read/write and read-only access to a subset of the entire object repository namespace. The namespace rules define the subset.

The namespace rules are processed when a non-administrative connection gets established. This defines the connection's view of the object repository namespace. Changes to the namespace rules take effect for new connections only, and do not affect existing connections.

Global namespace rules are stored in the “etc/namespaces” object in the repository itself, so changes are immediately replicated to all nodes, and take effect on all nodes. Global namespace rules get overridden by application namespace rules, see the section called “Application namespace rules”. The global namespce rules described here take effect only when application namespace rules are not in effect.

The “etc/namespaces” object gets updated by the NAMESPACE command in the same way that all objects are. The repository must be in quorum. If not, NAMESPACE waits until the repository is in quorum, before proceeding.

The primary namespace setting is the namespace root. This restricts the connection's view to the specified subset of the object repository hierarchy.

Example: the namespace root is “apps/acct”. This is the top-level hierarchy from the connection's view. If the connection accesses an object named “index” it actually ends up with “apps/acct/index”. Objects in the repository outside of “apps/acct” are inaccessible, except through an auxiliary namespace mapping.

The namespace rules may also define auxiliary namespace mappings, which act as a virtual pointer from the connection's namespace root. Example: a connection whose root is “apps/acct”, and an auxiliary mapping of “system” to “etc”. A connection accesses “system/cluster”. Instead of “apps/acct/system/cluster”, the actual object accessed is “etc/cluster”. An auxiliary mapping is like a pointer from the connection's namespace root to some other part of the object repository's hierarchy. From the connection's view, the “system” hierarchy provides access to anything in “etc” in the object repository namespace, notwithstanding that the connection's namespace root is “apps/acct”.

Typically, applications create and use objects in a top-level namespace, and namespace rules separate applications' objects from each other.

The namespace rules specify each connection's root, and any auxiliary mappings. The rules define them based on the user-id and the group-id of the process that connected to a repository node, the filename of the binary that the process is running, and on the name of the node itself.

NAMESPACE (RW|RO) [command]*

The namespace command with no arguments displays the current list of namespace rules. Otherwise the first argument must be either RW or RO.

There are two separate lists of namespace rules, the read/write rules and the read-only rules. In order to define a namespace view for a connection, the read-only rules gets processed first. The namespace they specify gets defined as a read-only namespace, where the connection can access objects, but not modify them.

Afterwords, the read-write rules modify the read-only view, and specify which parts of the namespace may be modified. If an auxiliary mapping gets initially defined by read-only rules, accessing objects through that mapping is restricted to reading them, and the objects cannot be modified. If an auxiliary mapping gets defined by read-write rules, objects in that auxiliary mapping are modifiable by the connection.

An auxiliary mapping defined by read-write rules does not require that the mapping must be defined by read-only rules, first. The read-write rules simply supersede the read-only ones. The auxiliary mapping may or may not be defined in the read-only list. If the read-write list does not redefine the mapping, it gets left as it is, otherwise the read-write mapping supersedes, and the read-write mapping can specify a different part of the entire object repository namespace for the read-write mapping, than the read-only one.

The connection's name root setting can appear in either the read-only or the read-write list. If specified by a read-write rule, the application may access and modify objects under the specified namespace. If specified by a read-only rule, and not overridden by a read-write rule, the application may access any existing objects, but not modify them. If the application has any read-write auxiliary mappings, the application can still modify objects through the read-write mapping.

If a top-level namespace root does not get specified by either read-only or read-write rules, the top-level namespace gets set to “sandbox”.

NAMESPACE (RW|RO) ADD [selector]* [rule]*

The ADD commands adds a new namespace read-write or read-only rule. One or more following clauses follow the ADD command:

ADD is followed by a list of selectors, then by a list of rules. The selectors restrict the following rules to be applicable only to connections that meet a specified criteria. If no selectors are given, the rules apply to all connections:

One or more of the following rules follow the selectors:

NAMESPACE (RW|RO) MODIFY [selector]* [rule]*

This is similar to ADD except that this modifies an existing read-write or a read-only rule definition. The first read-write or read-only rule that matches the list of selector gets modified according to the rules given by MODIFY. Alternatively, “LABEL {label}” selects a rule that has the specified label. This is more convenient than having to laboriously repeat the existing selectors, exactly.

MODIFY's rules are the same as ADD, but may also include the following:

To remove a namespace entry completely, DELADD all of its ADDs and UNADDs, and DELSETROOT any SETROOT or UNSETROOT.

NAMESPACE (RW|RO) MOVE [selector]* (BEFORE | AFTER) [selector]*

The order of rules often matters with a complex namespace configuration. The MOVE command rearranges the order of the existing rules. The MOVE command takes two lists of selectors. Each list selects an existing rule, the same way that the ADD and MODIFY, preferably using an existing label to make this operation easier.

The rule selected by the first list of selectors gets moved before or after the rule selected by the second list, as specified. The read-write and read-only rules are separate from each other, and a read-write rule can be re-positioned only relative to another read-write rule, and a read-only rule can be repositioned only relative to another read-only rule.

PUT ( (DEL name:uuid | NEW name | UPD name:uuid) (VALUE literal | FILE filename) )+

The PUT command adds, modifies, or removes objects in the object repository. More than one object can be processed at the same time. If the PUT fails for any reason, as described below, none of the changes take effect; otherwise all objects get updated atomically. Another process doing a PUT, GET, or another command at the same time will either use the previous contents of the modified objects, or the contents as updated by this PUT.

Atomicity is guaranteed only as long as the object repository cluster remains in quorum. Like all other commands, PUT waits until the repository cluster is in quorum before proceeding. If the repository cluster loses quorum in the middle of a PUT, the command waits until a quorum gets reestablished, before resuming, but the results of the command, when it's reported to succeed, or to fail, are undefined. The command may report a failure, but some of its objects might still get updated, as the contents of the object repository get re-synchronized between all the nodes in the quorum.

The maximum number of objects in a PUT, and the maximum aggregate sizes of new object values, are limited by the server. These limits are reported when stasher connects to its object repository node server.

PUT takes a list of objects to process, as follows. Each object's name is interpreted according to the NAMESPACE rules, in force.

The value of NEW or UPDated objects may be specified in two ways, immediately after the NEW or the UPDate command: “VALUE literal” gives the new value for the object explicitly, as a single word; “FILE filename” reads the value from the specified file. The entire contents of the given file are taken as the new value of the object.

If successful, the UPD command responds with the uuid of all objects added or updated by the command. A uuid is an opaque serial number or a timestamp. Each time an object gets updated, it gets a new uuid, which is shown as a list of meaningless letters, numbers, and some symbols. The actual value is unimportant, except that it's always unique, and each update to an object changes its uuid. The UPD and DEL operation require a matching uuid. If the affected objects get updated by someone else, since the objects' uuid were obtained, they'll have a different uuid, and PUT fails.

DIR [hierarchy]

The DIR command lists objects at the specified hierarchy level, or at the top level if a hierarchy is not specified.

This example shows that the top level hierarchy contains an object named “pi” and a sub-hierarchy named “etc”. A trailing “/” designates a hierarchy level, not an object.

There are two objects in the “etc” hierarchy, whose names are shown. Object names are shown with their full hierarchy, as in this example.

UIDS {object}+

The UIDS command shows the uuids of listed objects:

Each object's name is affixed with “:” and its current uuid value. In this example the object “e” did not exist, and its uuid shows empty.

RMRF {hierarchy}*

RMRF run the DIR, UIDS and PUT commands to remove all objects in the listed hierarchies.

If no parameters are given, everything in the connecting client's sandbox gets removed. Since this would be a disaster if the client had an administrative connection, an RMRF reports an error if no arguments are provided, and the connection is an administrative connection.

This is typically used to clean up a generic, shared, sandbox hierarchy.

GET {object}+

Retrieve and display the contents of the selected objects:

The output of GET is similar to UIDS's output, and includes the value of each object.

Objects may contain any data, and it's not necessarily human-readable, so the GET is not very useful if an object contains binary data.

SAVE ({object} {filename})+

The SAVE command is similar to GET except that the value of each object is saved in a file, rather than shown. Each object's name is followed by the filename where the object's value is saved to:

/tmp/pi and /tmp/e now contain the values of the corresponding objects.

SUB {object}+

After subscribing to one or more objects, the server sends a “push”-type notification every time the object's value changes. The maximum number of concurrent subscription is limited by the server. stasher shows how many concurrent subscription the server accepts, after connecting to the server.

The subscription facility is mostly useful when using the C++ API for accessing the object repository. Here, with stasher it's implemented for demonstrative purposes, mostly. Each time stasher reads a command and executes it, it reports the names of any objects that the server, in the meantime, has pushed to stasher:

After reporting that both subscribed objects have been updated, the UIDS command returns “pi”'s new uuid, and shows that the “e” object was deleted.

Append a trailing "/" to the object name to subscribe to all changes in a hierarchy. A notification gets sent when any object in the hierarchy changes. Note that the subscription is for the immediate objects in the hierarchy, and won't cover any nested hierarchies.

UNSUB {object}+

The UNSUB command cancels the subscription for the specified objects.