» Serf Keys

Command: serf keys

The serf keys command performs cluster-wide encryption key operations, such as installing new keys and removing old keys. When used properly, the keys command allows you to achieve non-disruptive encryption key rotation across a Serf cluster.

By default, changes made to the encryption keys will not be written to disk, and will be lost upon agent restart. It is possible to enable persistence by using the -keyring-file option to the Serf agent. More information is available on the agent configuration options page.

Serf allows multiple encryption keys to be in use simultaneously. This is intended to provide a transition state while the cluster converges. It is the responsibility of the operator to ensure that only the required encryption keys are installed on the cluster. You can ensure that a key is not installed using the -list and -remove options.

All variations of the keys command will return 0 if all nodes reply and there are no errors. If any node fails to reply or reports failure, the exit code will be 1.

» Usage

Usage: serf keys [options]

All operations are idempotent. The list of available flags are:

  • -install - Install a new encryption key to the Serf keyring. This will broadcast the new key to the cluster.

  • -use - Change the primary encryption key. The primary key is the only key used to encrypt messages, and is the first key used while decrypting messages.

  • -remove - Remove a currently installed encryption key from the Serf keyring. Any messages transmitted using this key after this operation completes will fail verification and be rejected.

  • -list - Ask all members in the cluster for a list of the keys they have installed. After gathering keys from all members, the results will be returned in a summary showing each key and the number of members which have that key installed. This is useful to operators to ensure that a given key has been installed on or removed from all members. It is possible that there are too many keys to fit into one message. In that case the reporting member truncates the list until the message can be sent. This is done to avoid not being able to list the keys in case there are too many keys.

  • -rpc-addr - Address to the RPC server of the agent you want to contact to send this command. If this isn't specified, the command will contact "" which is the default RPC address of a Serf agent. This option can also be controlled using the SERF_RPC_ADDR environment variable.

  • -rpc-auth - Optional RPC auth token. If the agent is configured to use an auth token, then this must be provided or the agent will refuse the command. This option can also be controlled using the SERF_RPC_AUTH environment variable.