Download Riak 2.0

riak-admin Command Line

riak-admin

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. Running the riak-admin command by itself will output a list of available commands:

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 |
                    aae-status | diag | status | transfer-limit | reformat-indexes |
                    top [-interval N] [-sort reductions|memory|msg_q] [-lines N] |
                    downgrade-objects | security | bucket-type | repair-2i |
                    search | services | ensemble-status }

Node Naming

An important thing to bear in mind is that all Riak nodes have unique names within the cluster that are used for a wide variety of operations. The name for each node can be set and changed in each node's configuration files. The examples below set the name of a node to riak_node_1@199.99.99.01 in the riak.conf file if you are using the newer configuration system and in vm.args if you are using the older system:

nodename = riak_node_1@199.99.99.01
-name riak_node_1@199.99.99.01

The name prior to the @ symbol can be whatever you'd like, e.g. riak1, dev, cluster1_node1, or spaghetti. After the @ you must use a resolvable IP address or hostname. In general, we recommend using hostnames over IP addresses when possible because this enables the node to potentially live on different machines over the course of its existence.

cluster

Riak provides a multi-phased approach to cluster administration that allows changes to be staged and reviewed before being committed. This allows multiple cluster 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 this interface.

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

Please note that you can stage multiple cluster-level changes prior to planning and committing those changes.

cluster join

Join this node to the cluster containing <node>:

riak-admin cluster join <node>

You can replace <node> with any node that is currently in the cluster. Once a node joins, all of the operations necessary to establish communication with all other nodes proceeds automatically.

Note: As with all cluster-level actions, the changes made when you run the cluster join command will take effect only after you have both planned the changes by running riak-admin cluster plan and committed the changes by running riak-admin cluster commit. You can stage multiple cluster joins before planning/committing.

cluster leave

Instruct this node to hand off its data partitions, leave the cluster, and shut down:

riak-admin cluster leave

Instruct the node named <node> to hand off its data partitions, leave the cluster, and shut down:

riak-admin cluster leave <node>

Note: As with all cluster-level actions, the changes made when you run the cluster leave command will take effect only after you have both planned the changes by running riak-admin cluster plan and committed the changes by running riak-admin cluster commit. You can stage multiple cluster leave operations before planning/committing.

cluster force-remove

Remove the node named <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>

Note: As with all cluster-level actions, the changes made when you run the cluster force-remove command will take effect only after you have both planned the changes by running riak-admin cluster plan and committed the changes by running riak-admin cluster commit. You can stage multiple force remove operations before planning/committing.

cluster replace

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

riak-admin cluster replace <node1> <node2>

Note: As with all cluster-level actions, the changes made when you run the cluster replace command will take effect only after you have both planned the changes by running riak-admin cluster plan and committed the changes by running riak-admin cluster commit. You can stage multiple replace operations before planning/committing.

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>

Note: As with all cluster-level actions, the changes made when you run the cluster force-replace command will take effect only after you have both planned the changes by running riak-admin cluster plan and committed the changes by running riak-admin cluster commit. You can stage multiple replace operations before planning/committing.

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

join

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. However, this command can still be used by providing a -f option (which forces the command).

Joins the running node to another running node so that they participate in the same cluster. <node> is the other node to connect to.

riak-admin join -f <node>

leave

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. However, this command can still be used by providing a -f option (which forces the command).

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

backup

Deprecation notice

The riak-admin backup command has been deprecated. We recommend using backend-specific backup procedures instead. Documentation can be found in Backing up Riak.

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

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

restore

Deprecation notice

The riak-admin restore command has been deprecated. It was orignally intended to be used in conjunction with backups performed using the riak-admin backup command, which is also deprecated. We recommend using the backup and restore methods described in Backing up Riak.

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

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

test

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

riak-admin test

If the test is successful, you should see output like the following:

Successfully completed 1 read/write cycle to 'dev1@127.0.0.1'

reip

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.

js-reload

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

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

riak-admin js-reload

erl-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

wait-for-service

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 riak-admin services to see which services are available on a running node.

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

ringready

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 the ring state has settled.

riak-admin ringready

transfers

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

transfer-limit

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 in the transfer_limit setting in the riak.conf configuration file.

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

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

down

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

riak-admin down <node>

cluster-info

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.

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

The following information is collected:

Examples

Output information from all nodes to /tmp/cluster_info.txt:

riak-admin cluster_info /tmp/cluster_info.txt

Output information from the current nodeL

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@192.168.1.10
riak@192.168.1.11

member-status

Prints the current status of all cluster members.

riak-admin member-status

ring-status

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

riak-admin ring-status

vnode-status

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

riak-admin vnode-status

aae-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.

Note in AAE status information

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.

diag

The diag command invokes the Riaknostic diagnostic system.

riak-admin diag

This command allows you to specify which diagnostic checks you would like to run, which types of diagnostic messages you wish to see, and so on. More comprehensive information can be found in the documentation on inspecting a node.

status

Prints status information, including performance statistics, system health information, and version numbers. Further information about the output is available in the documentation on inspecting a node.

riak-admin status

reformat-indexes

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.

This 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

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]

Options:

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

downgrade-objects

This command is used when changing the format of Riak objects, usually as part of a version downgrade.

riak-admin downgrade-objects <kill-handoffs> [<concurrency>]

More detailed information can be found in Rolling Downgrades.

security

This command enables you to manage to manage Riak users, choose sources of authentication, assign and revoke permissions to/from users and groups, enable and disable Riak Security, and more.

riak-admin security <command>

More comprehensive information on user management and can be found in the Authentication and Authorization guide. Detailed information on authentication sources can be found in Managing Security Sources.

bucket-type

Bucket types are a means of managing bucket properties introduced in Riak 2.0, as well as an additional namespace in Riak in addition to buckets and keys. This command enables you to create and modify bucket types, provide the status of currently available bucket types, and activate created bucket types.

riak-admin bucket-type <command>

More on bucket types can be found in Using Bucket Types.

repair-2i

This command repairs secondary indexes in a specific partition or on a cluster-wide basis. Implementation details can be found in Repairing Indexes.

To repair secondary indexes throughout the entire cluster, run the repair-2icommand by itself, without a subcommand:

riak-admin repair-2i

This will initiate the repair process. When you run this command, you should see something like the following (where <ring_size> is the number of partitions in your Riak cluster):

Will repair 2i data on <ring_size> partitions
Watch the logs for 2i repair progress reports

To repair secondary indexes in a specific partition, provide the ID of the partition along with the repair-2i command:

riak-admin repair-2i 593735040165679310520246963290989976735222595584

You can check on the status of the repair process at any time:

riak-admin repair-2i status

If the repair is already finished, the console will return 2i repair is not running. If the repair is still in progress, the console will return a series of statistics like this:

2i repair status is running:
        Total partitions: 64
        Finished partitions: 44
        Speed: 100
        Total 2i items scanned: 0
        Total tree objects: 0
        Total objects fixed: 0

If you're concerned about the computational resources required to repair secondary indexes, you can set the speed of the process to an integer between 1 and 100 (with 100 being the fastest). This command would set the speed to 90:

riak-admin repair-2i --speed 90

The repair process can be stopped at any moment using the kill command:

riak-admin repair-2i kill

search

The search command provides sub-commands for various administrative work related to the new Riak Search.

riak-admin search <command>

aae-status

riak-admin search aae-status

Output active anti-entropy (AAE) statistics for search. There are three sections. Each section contains statistics for a specific aspect of AAE for every partition owned by the local node.

The first section provides information on exchanges. Exchange is the process of comparing hash trees to determine divergences between KV data and search indexes. The Index column contains the partition number. The Last (ago) column is the amount of time that has passed since the last exchange. The All (ago) column is the amount of time that has passed since all preflists for that partition have been exchanged.

The second section lists how much time has passed since the hashtree for that partition has been built from scratch. By default trees expire after 1 week and are rebuilt from scratch.

The third section presents statistics on repair operations that have occurred. Repair is performed when AAE notices that the KV and search hashtree don't match for a particular key. The Last column is the number of keys repaired during the last exchange. The Mean column is the average number of keys repaired for all exchange rounds since the node has started. The Max column is the maximum number of keys repaired for a given exchange round since the node has started.

switch-to-new-search

Only For Legacy Migration

This is only needed when migrating from legacy riak search to the new Search (Yokozuna).

riak-admin search switch-to-new-search

Switch handling of the HTTP /solr/<index>/select resource and protocol buffer query messages from legacy Riak Search to new Search (Yokozuna).

services

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

riak-admin services

ensemble-status

This command is used to provide insight into the current status of the consensus subsystem undergirding Riak's strong consistency feature.

riak-admin ensemble-status

This command can also be used to check on the status of a specific consensus group in your cluster:

riak-admin ensemble-status <group id>

Complete documentation of this command can be found in Managing Strong Consistency.