Riak Control

Riak Control is a web-based administrative console for inspecting and manipulating Riak clusters.

Requirements

Though Riak Control is maintained as a separate application, the necessary code for it ships with versions of Riak 1.1 and above and requires no additional installation steps.

Before getting started, you should know the address and port of the HTTP (or HTTPS) listeners for the cluster member(s) running Riak Control. You can obtain this information from the configuration files as indicated here:

listener.http.<name> = 127.0.0.1:8098

or

listener.https.<name> = 127.0.0.1:8096

## *** The default listeners in the riak.conf file are
##     named `internal`, so you would consult the value of
##     `listener.http.internal` in your configuration.

 {riak_api,
     [
        %% Other configs
        ... if HTTP is configured ...
        {http,[{"127.0.0.1",8098}]},
        ... if HTTPS is configured ...
        {https,[{"127.0.0.1",8069}]},
         %% Other configs
     ]},

%% *** This is a truncated configuration to illustrate the
%%     pertinent items -- the `http` and `https` tuples within
%%     the `riak_api` tuple's value list.

Enabling and Disabling Riak Control

Riak Control is disabled by default, meaning that you should see the following in your configuration files:

riak_control = off

{riak_control, [
                %% Other configs
                {enabled, false},
                %% Other configs
               ]}

Enabling Riak Control is simple:

riak_control = on

{riak_control, [
                %% Other configs
                {enabled, true},
                %% Other configs
               ]}

Make sure to restart the node once you have enabled Riak Control for the change to take effect.

After restarting the node, you should be able to access it by going to http://ip_address_of_listener:port/admin. In the case of a development cluster using the default configuration, you would access Riak Control at http://127.0.0.1:8098/admin

If you enabled authentication for Riak Control while performing the above configuration, you will be unable to access Riak Control until you have enabled and configured SSL and HTTPS.

Enabling SSL and HTTPS

In order to use SSL in conjunction with Riak Control, SSL must be enabled on each Riak node. For more information, see our security documentation. Once SSL is enabled, you can proceed to setting up authentication for Riak Control.

Please note that Riak Control will not work if you have enabled authentication but SSL is not set up properly.

Authentication

Riak Control provides you the option of requiring authentication (via HTTP basic auth) for users of the web interface. It is disabled by default. To enable authentication:

riak_control.auth.mode = userlist

{riak_control, [
                %% Other configs
                {auth, userlist}, %% The only other available option is "none"
                %% Other configs
               ]}

When authentication is enabled, you can specify as many username/password pairs as you wish. The default pair is the username

user and the password pass. We strongly recommend selecting different credentials. The example below would set up three user-defined pairs:

riak_control.auth.user.bob.password = bob_is_the_coolest
riak_control.auth.user.polly.password = h4x0r123
riak_control.auth.user.riakrocks.password = cap_theorem_4_life

{riak_control, [
                %% Other configs
                {userlist, [
                            {"bob", "bob_is_the_coolest"},
                            {"polly", "h4x0r123"},
                            {"riakrocks", "cap_theorem_4_life"}
                            ]}
                %% Other configs
]}

User Interface

To begin using Riak Control, navigate to https://ip_address_of_https_listener:https_port/admin For a default configuration, this will be https://localhost:8069/admin.

If your browser warns you that it cannot authenticate the page, this may be because you are using self-signed certificates. If you have authentication enabled in your configuration, you will next be asked to authenticate. Enter an appropriate username and password now.

Snapshot View

When you first navigate to Riak Control, you will land on the Snapshot view:

In this interface, the health of your cluster is made immediately obvious. In the event that something isn’t quite right (or has the potential to cause problems in the near future), the green check mark will turn into a red X. The red X is accompanied by a list of reasons for concern. Each item in the list links to a page where you can get more information about the issue.

Cluster Management View

On the top right side of the admin panel are navigation tabs. If you click the Cluster tab, you will be taken to the cluster management page.

On this page, you can see all of the nodes in your cluster, along with their status, the percentage of the ring owned by that node, and memory consumption. You can also stage and commit changes to the cluster, such as adding, removing, and marking nodes as down.

Staged changes to the cluster:

Changes committed; transfers active:

Cluster stabilizes after changes:

Node Management View

The node management view allows you to operate against the individual nodes in the cluster.

Ring View

One level deeper than the cluster view is the ring view. This is where you can see the health of each vnode.

Most of the time, your ring will be too large to effectively manage from the ring view. That said, with filters you can easily identify partition ownership, unreachable primaries, and in-progress handoffs.