stashermg — Object repository management


stashermg {options...}


The stashermg command manages object repository certificates. Object repository servers running on different machines connect with each other, and use certificates to mutually authenticate and identify each other.

Repository cluster keys

A cluster key serves as an identifier for a distributed object repository. This is the signing key that signs the certificates of all nodes in the object repository. It's analogous to a certificate authority.

stashermg --clustkey --generate { -n | --name }=name [{ -b | --bits }=strength] [{ -d | --digest }=algorithm] [{ -e | --expires }=interval] [{ -t | --type }=type] [directory]

The --name parameter is required. It specifies a name for the object repository. The object repository server uses this name to register itself with the system portmapper. The name must comply with the naming convention for portmapper registrations: basically the name must look like a domain name. The actual domain name does not actually need to exist, as long as it falls within a valid governing domain. For example, when organization's policy assigns for its object repositories:

stashermg --clustkey --generate \
          --expires="8 years"

The other parameters are optional: --bits specifies the bit strength of the signing key, weak, low, normal (default), high, or ultra; --digest specifies the signing algorithm, the default is sha256; and --expires specifies the certificate's duration (default is 5 years), this parameter understands n days, n months, and n years; --type specifies the certificate type, either rsa (default) or dsa.

The given directory gets created for the new cluster key, with group and world permissions turned off, and the new cluster certificate and key gets saved there. The cluster key directory must be kept secure, and should exist on a machine that runs (or will run) one of the nodes in the cluster repository. It does not need to be copied to every node's machine.

If not specified, directory gets defaulted to @localstatedir@/stasher/clusters/name, where name is the specified cluster name.

Repository cluster keys sign individual repository node keys, which have a shorter expiration interval. Node keys must expire before the cluster key that signed them.

Before an existing cluster key expires, a new repository cluster key gets generated by running the same command, and pointing it to an existing cluster key directory. The --name parameter is not needed for the new key, the cluster name remains the same, and it's retrieved from the existing key in the directory (if --name is specified it must give the same name). The new key gets gets added to the directory. The existing, expiring key remains valid until it actually expires.

New keys must always have the same name, but other parameters can be different.

stashermg --clustkey { -l | --list } directory

--list produces a formatted output, listing the keys in the specified cluster key directory, and their expiration. The Key ID column contains each key's identifier.

If desired, multiple keys may be installed in a cluster directory, and used concurrently, for reasons other than expiration. All keys are interchangable with each other, any valid key can be used to create and sign individual cluster node keys.

stashermg --clustkey { -r | --remove } directory keyid

After a cluster key expires, it should be removed from the cluster key directory, but it may be removed for other reasons, as long as there are no installed node certificates that are signed by that key.

After creating a new cluster key, or after removing a key, the updated list of cluster certificates needs to be exported, or pushed, into the repository:

stashermg --clustkey { -e | --export } directory nodekeydirectory

nodekeydirectory is the directory of an existing cluster node, on the same machine. If the node is up, and the cluster is in quorum, the updated list of cluster certificates from directory gets distributed to all nodes in the cluster. If the node is not running, the updated cluster certificate list gets distributed when the node comes up and joins a cluster that's in quorum.

Do not export cluster keys to a running node that's not connected to a cluster, or if the cluster is not in quorum (the majority of nodes in the cluster are up, connected and synchronized with each other).

Repository node keys

Each node in a cluster has its own key. The key gets signed by the object repository's cluster key. A node can connect to other nodes in the cluster only if both node's keys are mutually signed by a cluster key.

stashermg --nodekey --generate { -n | --name }=name [{ -b | --bits }=strength] [{ -d | --digest }=algorithm] [{ -e | --expires }=interval] [{ -k | --signkey }=keyid] [nodekeydirectory] directory

The --name parameter gives the name of the node in the object repository cluster. This is a label. Each node in the repository must have a unique label. The label gets prepended to the signing cluster's key, and when the node starts, the resulting name gets registered with the portmapper. This allows multiple nodes in the cluster to run on the same machine, presumably for testing purposes.

The other parameters are optional: --bits specifies the bit strength of the signing key, weak, low, normal (default), high, or ultra; --digest specifies the signing algorithm, the default is sha256; and --expires specifies the certificate's duration (default is 1 year), this parameter understands n days, n months, and n years.

The new node certificate and key gets installed in the specified. nodekeydirectory, which gets created if it does not exist. The new node certificate gets signed with the newest cluster key from the cluster key directory, if there's more than one there. --signkey selects a non-default key instead, if specified.

nodekeydirectory is optional. If this command has two directory parameters, the first parameters is the new node key directory and the second parameter is the cluster key directory. If this command has a single directory parameter, it specifies a cluster key directory, and the node key directory defaults to @localstatedir@/stasher/newnodes/name, where name is the new node's name.

A node certificate must be kept secure, just like a cluster certificate. The certificate file gets created without group and world permissions, but the new node directory is world readable. This allows processes running under any userid to connect to the local object repository node, which can read the certificate.

This command also copies the current list of cluster certificates into the created new node directory. As previously described, updates to the list of cluster certificates are distributed by --export, using any existing node in the object repository cluster.

The new node key directory gets created on the same machine as the cluster key directory, since a node key must be signed by a cluster key. To install nodes on other machines, copy the created node key directory, securely, to the other machine, taking care to preserve the structure and the permissions of all the contents of the newly-created node key directory.

A node certificate expires just like cluster certificates, and a new node certificate, with the same name must be created, before the existing node certificate expires.

A renewal certificate gets created by specifying an existing nodekeydirectory. --name default's to the node's name. A renewal certificate for another node gets created by an explicit --name. In that case, both the node on this machine and the node whose certificate is getting renewed must be up and connected to the cluster. The node running on this machine forwards the certificate to the peer specified by --name, which installs it.

Creating certificates when the cluster certificates are stored separately

It's possible to securely keep the cluster certificates on a completely separate machine from any cluster node, and use it to generate node certificates. To create a new node on another machine, follow the process for creating a new node certificate, and copy the entire resulting directory to the other machine, taking care to use the right permissions and ownership of its contents. To renew a node certificate, follow the same process, and copy just the cert.pem file. To distribute a new cluster certificate, generate it, and export it to a temporary directory, then copy the rootcerts.pem file.

In either case, run stashermg --certreload directory on the node's machine, after installing a new cert.pem or a rootcerts.pem, to reload the certificate. The running node server loads the new cert.pem file, if it exists. If a new rootcerts.pem exists it gets loaded also, but straight into the object repository, and distributed to all nodes in the cluster, before removing it from the node directory, where it is no longer needed.