Download Riak 2.0 RC1

Configuring Riak CS

For Riak CS to operate properly it must know how to connect to Riak. A Riak CS node typically runs on the same server as its corresponding Riak node, which means that changes will only be necessary if Riak is configured using non-default settings.

The settings reside in the Riak CS app.config file, which is typically located in the /etc directory on each node. Configurable parameters related to Riak CS specifically can be found in the riak_cs section of that file. That section looks something like this:

{riak_cs, [
    {parameter1, value},
    {parameter2, value},
    %% and so on...
]},

Host and Port

To connect Riak CS to Riak, make sure that the following parameters are set to the host and port used by Riak:

Note on IP addresses

The IP address you enter here must match the IP address specified for the Protocol Buffers interface in the Riak app.config file unless Riak CS is running on a completely different network and address translation is required.

After making any changes to the app.config file in Riak CS, restart the node if it is already running.

Specifying the Stanchion Node

If you have a single node, you don't have to change the Stanchion settings because Stanchion runs on the local host. If your Riak CS system has multiple nodes, however, you must specify the IP address and port for the Stanchion node and whether or not SSL is enabled.

The Stanchion settings reside in the Riak CS app.config file, which is located in the /etc directory of each Riak CS node. The settings appear in the riak_cs config section of the file.

To set the host and port for Stanchion, do the following:

Enabling SSL

SSL is turned off by default in Stanchion, i.e. the stanchion_ssl variable is set to false. If Stanchion is configured to use SSL, change this variable to true. The following example configuration would set the host to localhost, the port to 8085 (the default), and set up Stanchion to use SSL:

{riak_cs, [
    %% Other configs

    {stanchion_ip, "127.0.0.1"},
    {stanchion_host, 8085},
    {stanchion_ssl, true},

    %% Other configs
]}

Specifying the Node Name

You can also set a more useful name for the Riak CS node, which is helpful to identify the node from which requests originate during troubleshooting. This setting resides in the Riak CS vm.args configuration file, which is also located in the /etc directory. This would set the name of the Riak CS node to riak_cs@127.0.0.1:

-name riak_cs@127.0.0.1

Change 127.0.0.1 to the IP address or hostname for the server on which Riak CS is running.

Specifying the Admin User

The admin user is authorized to perform actions such as creating users or obtaining billing statistics. An admin user account is no different from any other user account. You must create an admin user to use Riak CS.

Note on anonymous user creation

Before creating an admin user, you must first set {anonymous_user_creation, true} in the Riak CS app.config. You may disable this again once the admin user has been created.

To create an account for the admin user, use an HTTP POST request with the username you want to use for the admin account. The following is an example:

curl -H 'Content-Type: application/json' \
  -XPOST http://localhost:8080/riak-cs/user \
  --data '{"email":"foobar@example.com", "name":"admin user"}'

The JSON response will look something like this:

{
  "Email": "foobar@example.com",
  "DisplayName": "adminuser",
  "KeyId": "324ABC0713CD0B420EFC086821BFAE7ED81442C",
  "KeySecret": "5BE84D7EEA1AEEAACF070A1982DDA74DA0AA5DA7",
  "Name": "admin user",
  "Id":"8d6f05190095117120d4449484f5d87691aa03801cc4914411ab432e6ee0fd6b",
  "Buckets": []
}

You can optionally send and receive XML if you set the Content-Type to application/xml, as in this example:

Once the admin user exists, you must specify the credentials of the admin user on each node in the Riak CS system. The admin user credential settings reside in the Riak CS app.config file, which is located in the etc/riak-cs directory. The settings appear in the Riak CS config section of the file. Paste the key_id string between the quotes for the admin_key. Paste the key_secret string into the admin_secret variable, as shown here:

%% Admin user credentials
{admin_key, "LXAAII1MVLI93IN2ZMDD"},
{admin_secret, "5BE84D7EEA1AEEAACF070A1982DDA74DA0AA5DA7"},

Once the admin user exists, you must specify the credentials of the admin user in the app.config file. Those will be the same credentials that you received as a JSON object when you ran the POST request to create the user.

In the riak_cs section of app.config, add the following to establish the admin user credentials:

{riak_cs, [
    %% Other configs

* `riak_ip` --- Replace `127.0.0.1` with the IP address of the Riak node you want Riak CS to connect to

If you configured Riak to use a different port for Protocol Buffers, you must change the following port setting:

* `riak_pb_port` --- Replace `8087` with the port number set in the variable `pb_port` in the Riak `app.config` file

<div class="note"><div class="title">Note</div>The IP address you enter here must match the IP address specified for the Protocol Buffers interface in the Riak <tt>app.config</tt> file. If a server has more than one network interface card (NIC), you can use the IP address for a specific NIC. If you want Riak CS to listen on all of them, set <tt>riak_ip</tt> to <tt>0.0.0.0</tt>.</div>

After modifying the port numbers, restart Riak if is already running.

## Connection Pools

Riak CS uses two distinct connection pools for communication with
Riak: a **primary** and a **secondary** pool.

The primary connection pool is used to service the majority of API
requests related to the upload or retrieval of objects. It is identified
in the configuration file as `request_pool`. The default size of this
pool is 128.

The secondary connection pool is used strictly for requests to list the
contents of buckets. The separate connnection pool is maintained in
order to improve performance. This secondary connection pool is
identified in the configuration file as `bucket_list_pool`. The default
size of this pool is 5.

The following shows the `connection_pools` default configuration entry
that can be found in the `app.config` file:

```appconfig
{riak_cs, [
    %% Other configs

    {connection_pools,
    [
     {request_pool, {128, 0} },
     {bucket_list_pool, {5, 0} }
    ]},

    %% Other configs
]}

The value for each pool is represented as a pair with the first element representing the normal size of the pool. This is representative of the number of concurrent requests of a particular type that a Riak CS node may service. The second element represents the number of allowed overflow pool requests that are allowed. It is not recommended that you use any value other than 0 for the overflow amount unless careful analysis and testing has shown it to be beneficial for a particular use case.

Tuning

We strongly recommend you that you increase the value of the _pb_backlog_ setting in Riak. When a Riak CS node is started, each connection pool begins to establish connections to Riak. This can result in a thundering herd problem in which connections in the pool believe they are connected to Riak, but in reality some of the connections have been reset. Due to TCP RST packet rate limiting (controlled by net.inet.icmp.icmplim) some of the connections may not receive notification until they are used to service a user's request. This manifests as an {error, disconnected} message in the Riak CS logs and an error to returned to the user.

Specifying the Stanchion Node

If you have a single node, you don't have to change the Stanchion settings because Stanchion runs on the local host. If your Riak CS system has multiple nodes, you must set the IP address and port for the Stanchion node and whether or not SSL is enabled.

The Stanchion settings reside in the Riak CS app.config file, which is located in the /etc/Riak-CS directory. The settings appear in the Riak CS config section of the file.

If you configured Stanchion to use a different port, you must change the following port setting:

The stanchion_ssl variable is set to false by default. If you want to use SSL, change this variable to true.

Specifying the Node IP Address

You can also set the IP address for the Riak CS node, which is helpful if you must debug code or identify the node from which requests originate. The Riak CS IP address setting resides in the Riak CS vm.args configuration file, which is located in the /etc/riak-cs directory.

Initially, the line that specifies the Riak CS node IP address is set to localhost, as follows:

## Name of the riak node
-name riak_cs@127.0.0.1

Enabling SSL in Riak CS

%%{ssl, [
%%    {certfile, "./etc/cert.pem"},
%%    {keyfile, "./etc/key.pem"}
%%   ]},

Then replace the text in quotes with the path and filename for your SSL encryption files. By default, there's a cert.pem and a key.pem in each node's /etc directory. You're free to use those or to supply your own.

Proxy vs. Direct Configuration

Riak CS can interact with S3 clients in one of two ways:

Proxy

To establish a proxy configuration, configure your client's proxy settings to point to Riak CS cluster's address. Then configure your client with Riak CS credentials.

When Riak CS receives the request to be proxied, it services the request itself and responds back to the client as if the request went to S3.

On the server side, the cs_root_host in the riak_cs section of the app.config configuration file must be set to s3.amazonaws.com because all of the bucket URLs request by the client will be destined for s3.amazonaws.com. This is the default.

Note: One issue with proxy configurations is that many GUI clients only allow for one proxy to be configured for all connections. For customers trying to connect to both S3 and Riak CS, this can prove problematic.

Direct

The establish a direct configuration, the cs_root_host in the riak_cs section of app.config must be set to the FQDN of your Riak CS endpoint, as all of the bucket URLs will be destined for the FQDN endpoint.

You will also need wildcard DNS entries for any child of the endpoint to resolve to the endpoint itself. Here's an example:

data.riakcs.net
*.data.riakcs.net

Garbage Collection Settings

The following options are available to make adjustments to the Riak CS garbage collection system. More details about garbage collection in Riak CS are available here.

Other Riak CS Settings

There are two configuration options designed to provide improved performance for Riak CS when using Riak 1.4.0 or later. These options take advantage of additions to Riak that are not present prior to version 1.4.0.

The app.config file includes other settings, such as whether to create log files and where to store them. These settings have default values that work in most cases.