riak-admin Command Line Interface
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 | stat | 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 | 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 theriak-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 newriak-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 isriak
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 theriak-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 isriak
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>
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.
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:
- 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
summaryinet_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
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
riak-admin vnode-status
The riak-admin vnode-status
command should not be used more frequently than every 5 minutes. Running it more often will result in handoffs being stalled.
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.
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.
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 to5
sort
determines on which categoryriak-admin top
sorts and defaults toreductions
lines
specifies the number of processes to display in the top output and defaults to10
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-2i
command 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
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.
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>
At the moment, the set
command can only be used for the following
parameters, all three of which are related to Riak’s handoff subsystem:
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 ```