riak admin Command Line Interface

riak admin

The riak admin command 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 riak admin 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 | stat | status | transfer-limit | reformat-indexes |
                    top [-interval N] [-sort reductions|memory|msg_q] [-lines N] |
                    downgrade-objects | security | bucket-type | repair-2i |
                    services | ensemble-status | handoff | set |
                    show | describe }

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

Documentation for the riak admin cluster command interface can be found in Cluster Administration.

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

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

riak admin backup <node> <cookie> <filename> [node|all]
  • <node> is the node from which to perform the backup.
  • <cookie> is the Erlang cookie/shared secret used to connect to the node. This is riak in the default configuration.
  • <filename> is the file where the backup will be stored. This should be the full path to the file.
  • [node|all] specifies whether the data on this node or the entire

restore

Deprecation notice

The riak admin restore command has been deprecated. It was originally 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 KV.

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

riak admin restore <node> <cookie> <filename>
  • <node> is the node which will perform the restore.
  • <cookie> is the Erlang cookie/shared secret used to connect to the node. This is riak in the default configuration.
  • <filename> is the file where the backup is stored. This should be the full path to the file.

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 Changing Cluster Information 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. Note: This command has been deprecated in KV 3.2.0 onwards and will no longer function.

riak admin js-reload

erl-reload

Reloads the Erlang .beam files used for MapReduce jobs, pre- and post-commit hooks, and other purposes.

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

riak admin erl-reload

The response to this command should appear as:

ok

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>

produces the following when the service is up:

riak_kv is up

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

Produces:

TRUE All nodes agree on the ring ['dev1@127.0.0.1','dev2@127.0.0.1',`dev3@127.0.0.1`]

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

Produces:

No transfers active

Active Transfers:


ok

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>

Running the above, targetted at node dev1@127.0.0.1 setting a transfer limit of 1 produces the following:

Set transfer limit for 'dev1@127.0.0.1' to 1

down

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

riak admin down <node>

Produces:

Success: "dev1@127.0.0.1" marked as down

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:

  • Current time and date
  • VM statistics
  • erlang:memory() summary
  • Top 50 process memory hogs
  • Registered process names
  • Registered process name via regs()
  • Non-zero mailbox sizes
  • Ports
  • Applications
  • Timer status
  • ETS summary
  • Nodes summary
  • net_kernel summary
  • inet_db summary
  • Alarm summary
  • Global summary
  • erlang:system_info() summary
  • Loaded modules
  • Riak Core config files
  • Riak Core vnode modules
  • Riak Core ring
  • Riak Core latest ring file
  • Riak Core active partitions
  • Riak KV status
  • Riak KV ringready
  • Riak KV transfers

Examples

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

riak admin cluster_info /tmp/cluster_info.txt

Produces:

HTML report is at: 'dev1@127.0.0.1':"/tmp/cluster_info.txt"
Writing report for node 'dev1@127.0.0.1'
Writing report for node 'dev2@127.0.0.2'
[ok,ok]

Output information from the current nodeL

riak admin cluster_info /tmp/cluster_info.txt local

Produces:

HTML report is at: 'dev1@127.0.0.1':"/tmp/cluster_info.txt"
Writing report for node 'dev1@127.0.0.1'
[ok]

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

Produces:

HTML report is at: 'dev1@127.0.0.1':"/tmp/cluster_info.txt"
Writing report for node 'dev1@127.0.0.1'
[ok]

member-status

Prints the current status of all cluster members.

riak admin member-status

Produces:

================================= Membership ==================================
Status     Ring    Pending    Node
-------------------------------------------------------------------------------
valid      50.0%      --      dev1@127.0.0.1
valid      50.0%      --      dev2@127.0.0.2
-------------------------------------------------------------------------------
Valid:2 / Leaving:0 / Exiting:0 / Joining:0 / Down:0
ok

ring-status

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

riak admin ring-status

Produces:

================================== Claimant ===================================
Claimant:  'dev1@127.0.0.1'
Status:     up
Ring Ready: true

============================== Ownership Handoff ==============================
No pending changes.

============================== Unreachable Nodes ==============================
All nodes are up and reachable

ok

vnode-status

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

riak admin vnode-status

This command outputs a list of stats for each vnode on the local node, a snapshot of which should appear as:

VNode: 22835963083295358096932575511191922182123945984
Backend: riak_kv_bitcask_backend
Status:
[{key_count,0},{status,[]}]
Status:
{vnodeid,<<33,100,52,76,20,78,17,78>>}
Status:
{counter,10000}
Status:
{counter_lease,20000}
Status:
{counter_lease_size,10000}
Status:
{counter_leasing,false}

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.

  • Exchanges

    • The Last column lists when the most recent exchange between a partition and one of its sibling replicas was performed.
    • The All column shows how long it has been since a partition exchanged with all of its sibling replicas.

  • Entropy Trees

    • The Built column shows when the hash trees for a given partition were created.

  • Keys Repaired

    • The Last column shows the number of keys repaired during the most recent key exchange.
    • The Mean column shows the mean number of keys repaired during all key exchanges since the last node restart.
    • The Max column shows the maximum number of keys repaired during all key exchanges since the last node restart.
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.

Note: This command has been deprecated in KV 3.2.0 onwards and will no longer function.

stat

Provides an interface for interacting with a variety of cluster-level metrics and information.

riak admin stat

Full documentation of this command can be found in Statistics and Monitoring.

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:

  • interval specifies the number of seconds between each update of the top output and defaults to 5
  • sort determines on which category riak admin top sorts and defaults to reductions
  • lines 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.

An example of the output from this command is below:

========================================================================================
 'dev1@127.0.0.1'                                                         12:39:00
 Load:  cpu         0               Memory:  total       70263    binary       7812
        procs    1221                        processes   21478    code        13714
        runq        0                        atom          767    ets          9610

Pid            Name or Initial Func    Time    Reds  Memory    MsgQ Current Function
----------------------------------------------------------------------------------------
<8533.10.0>    erl_prim_loader          '-' 3770357  142716       0 erl_prim_loader:loop
<8533.224.0>   application_master:s     '-' 2959336 4119536       0 application_master:l
<8533.260.0>   riak_core_vnode_mana     '-' 2436172   58972       0 gen_server:loop/7
<8533.145.0>   exometer_report          '-' 2358255   88620       0 gen_server:loop/7
<8533.445.0>   riak_kv_put_fsm_sj_s     '-' 1383697    5756       0 gen_server:loop/7
<8533.465.0>   riak_kv_get_fsm_sj_s     '-' 1379786    8772       0 gen_server:loop/7
<8533.382.0>   mochiweb_clock           '-' 1364333    3964       0 gen_server:loop/7
<8533.485.0>   riak_kv_stat_sj_stat     '-' 1357563    8772       0 gen_server:loop/7
<8533.261.0>   riak_core_capability     '-' 1342806   34436       0 gen_server:loop/7
<8533.383.0>   'http://172.17.0.3:8     '-' 1234115    6616       0 gen_server:loop/7
========================================================================================

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

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.

handoff

Documentation for the handoff command can be found in Handoff.

set

Enables you to change the value of one of Riak’s configuration parameters on the fly, without needing to stop and restart the node.

riak admin set <variable>=<value>

The set command can only be used for the following parameters:

  • transfer_limit
  • handoff.outbound
  • handoff.inbound

show

Whereas the riak admin status command will display all currently available statistics for your Riak cluster, the show command enables you to view only some of those statistics.

riak admin show <variable>

describe

Provides a brief description of one of Riak’s configurable parameters.

riak admin describe <variable>

If you want to know the meaning of the nodename parameter:

riak admin describe nodename

That will produce the following output:

nodename:
  Name of the Erlang node