Download Riak 2.0 RC1

riak-admin Command Line


This script performs operations unrelated to node-liveness, including node membership, backup, and basic status reporting. The node must be running for most of these commands to work.

Usage: riak-admin { cluster | join | leave | backup | restore | test |
                    reip | js-reload | erl-reload | wait-for-service |
                    ringready | transfers | force-remove | down |
                    cluster-info | member-status | ring-status | vnode-status |
                    diag | status | transfer-limit | top }


As of version 1.2, Riak provides a multi-phased approach to cluster administration that allows changes to be staged and reviewed before being committed.

This approach to cluster administration allows multiple changes to be grouped together, such as adding multiple nodes at once, or adding some nodes while removing others.

Details about how a set of staged changes will impact the cluster, listing the future ring ownership as well as the number of transfers necessary to implement the planned changes are provided by the new interface.

The following commands stage changes to cluster membership. These commands do not take effect immediately. After staging a set of changes, the staged plan must be committed using the staging commands to take effect:

cluster join

Join this node to the cluster containing <node>.

riak-admin cluster join <node>

cluster leave

Instruct this node to hand off its data partitions, leave the cluster and shutdown.

riak-admin cluster leave

Instruct <node> to hand off its data partitions, leave the cluster and shutdown.

riak-admin cluster leave <node>

cluster force-remove

Remove <node> from the cluster without first handing off data partitions. This command is designed for crashed, unrecoverable nodes, and should be used with caution.

riak-admin cluster force-remove <node>

cluster replace

Instruct <node1> to transfer all data partitions to <node2>, then leave the cluster and shutdown.

riak-admin cluster replace <node1> <node2>

cluster force-replace

Reassign all partitions owned by <node1> to <node2> without first handing off data, and then remove <node1> from the cluster.

riak-admin cluster force-replace <node1> <node2>

Staging Commands

The following commands are used to work with staged changes:

cluster plan

Display the currently staged cluster changes.

riak-admin cluster plan

cluster clear

Clear the currently staged cluster changes.

riak-admin cluster clear

cluster commit

Commit the currently staged cluster changes. Staged cluster changes must be reviewed with riak-admin cluster plan prior to being committed.

riak-admin cluster commit


Deprecation Notice

As of Riak version 1.2, the riak-admin join command has been deprecated in favor of the riak-admin cluster join command. The command can still be used by providing a -f option, however.

Joins the running node to another running node so that they participate in the same cluster.

riak-admin join -f <node>


Deprecation Notice

As of Riak version 1.2, the riak-admin leave command has been deprecated in favor of the new riak-admin cluster leave command. The command can still be used by providing a -f option, however.

Causes the node to leave the cluster in which it participates. After this is run, the node in question will hand-off all its replicas to other nodes in the cluster before it completely exits.

riak-admin leave -f


Functionality Note

While the backup command backs up an object's siblings, the restore command (detailed below) currently does not restore the siblings of an object. If preservation of siblings during the backup and restore process is important to your use case, please see the Backing Up Riak document for more backup options.

Backs up the data from the node or entire cluster into a file.

riak-admin backup <node> <cookie> <filename> [node|all]


Restores data to the node or cluster from a previous backup.

riak-admin restore <node> <cookie> <filename>


Runs a test of a few standard Riak operations against the running node.

riak-admin test


Renames a node. This process backs up and edits the Riak ring, and MUST be run while the node is stopped. Reip should only be run in cases where riak-admin cluster force-replace cannot be used to rename the nodes of a cluster. For more information, visit the Renaming Nodes document.

riak-admin reip <old nodename> <new nodename>
Note about reip prior to Riak 2.0

Several bugs have been fixed related to reip in Riak 2.0. We recommend against using reip prior to 2.0, if possible.


Forces the embedded Javascript virtual machines to be restarted. This is useful when deploying new custom built-in MapReduce functions.

Note: This needs to be run on all nodes in the cluster.

riak-admin js-reload


Reloads the Erlang .beam files used for MapReduce jobs, pre- and post-commit hooks, and other purposes. More information on custom Erlang code can be found in the Installing Custom Code guide.

Note: This needs to be run on all nodes in the cluster.

riak-admin erl-reload


Lists available services on the node (e.g. riak_kv)

riak-admin services


Waits on a specific watchable service to be available (typically riak_kv). This is useful when (re-)starting a node while the cluster is under load. Use “services” to see what services are available on a running node.

riak-admin wait-for-service <service> <nodename>


Checks whether all nodes in the cluster agree on the ring state. Prints “FALSE” if the nodes do not agree. This is useful after changing cluster membership to make sure that ring state has settled.

riak-admin ringready


Identifies nodes that are awaiting transfer of one or more partitions. This usually occurs when partition ownership has changed (after adding or removing a node) or after node recovery.

riak-admin transfers


Change the handoff_concurrency limit. The value set by running this command will only persist while the node is running. If the node is restarted, the transfer-limit will return to the default of 2 or the value specified by the handoff_concurrency setting in the riak_core section of the app.config file.

Running this command with no node argument will set the transfer-limit for every node in the cluster. Running this command with no arguments will display the current transfer-limit for each node in the cluster.

Hinted vs. Ownership handoff

riak-admin transfer-limit allows setting a value greater than 8, which will apply when hinted handoff is occurring. Ownership handoff concurrency has a hard limit of 8 partitions at a time.

riak-admin transfer-limit <node> <limit>


Deprecation Notice

As of Riak version 1.2, the riak-admin force-remove command has been deprecated in favor of the new riak-admin cluster force-remove command. The command can still be used by providing a -f option, however.

Immediately removes a node from the cluster without ensuring handoff of its replicas. This is a dangerous command, and is designed to only be used in cases were the normal, safe leave behavior cannot be used – e.g. when the node you are removing had a major hardware failure and is unrecoverable. Using this command will result in a loss of all replicas living on the removed node which will then need to be recovered through other means such as read repair. It's recommended that you use the riak-admin leave command whenever possible.

riak-admin force-remove -f <node>


Marks a node as down so that ring transitions can be performed before the node is brought back online.

riak-admin down <node>


Output system information from a Riak cluster. This command will collect information from all nodes or a subset of nodes and output the data to a single text file.

The following information is collected:

riak-admin cluster_info <output file> [<node list>]


# Output information from all nodes to /tmp/cluster_info.txt
riak-admin cluster_info /tmp/cluster_info.txt
# Output information from the current node
riak-admin cluster_info /tmp/cluster_info.txt local
# Output information from a subset of nodes
riak-admin cluster_info /tmp/cluster_info.txt riak@


Prints the current status of all cluster members.

riak-admin member-status


Outputs the current claimant, its status, ringready, pending ownership handoffs and a list of unreachable nodes.

riak-admin ring-status


Outputs the status of all vnodes the are running on the local node.

riak-admin vnode-status


This command provides insight into operation of Riak's Active Anti Entropy (AAE) feature.

riak-admin aae-status

The output contains information on AAE key/value partition exchanges, entropy tree building, and key repairs which were triggered by AAE.

All AAE status information is in-memory and is reset across a node restart. Only tree build times are persistent (since trees themselves are persistent).

More details on the aae-status command are available in the Riak version 1.3 release notes.


Run diagnostic checks against <node>.

riak-admin diag <check>


Prints status information, including performance statistics, system health information, and version numbers. The statistics-aggregator must be enabled in the configuration for this to work. Further information about the output is available here.

riak-admin status


This command reformats integer indexes in Secondary Index data for versions of Riak prior to 1.3.1 so that range queries over the indexes will return correct results.

riak-admin reformat-indexes [<concurrency>] [<batch size>] --downgrade

The concurrency option defaults to 2 and controls how many partitions are concurrently reformatted.

The batch size option controls the number of simultaneous key operations and defaults to 100.

The command can be executed while the node is serving requests, and default values are recommended for most cases. You should only change the default values after testing impact on cluster performance.

Information is written to console.log upon completion of the process.

A --downgrade switch can be specified when downgrading a node to a version of Riak prior to version 1.3.1.

Additional details are available in the Riak 1.3.1 release notes.


Top uses Erlang's etop to provide information about what the Erlang processes inside of Riak are doing. Top reports process reductions (an indicator of CPU utilization), memory used, and message queue sizes.

riak-admin top [-interval N] [-sort reductions|memory|msg_q] [-lines N]

The interval option specifies the number of seconds between each update of the top output and defaults to 5.
The sort option determines what category riak-admin top sorts on and defaults to reductions.
The lines option specifies the number of processes to display in the top output and defaults to 10.

More information about Erlang's etop can be found in the etop documentation.