Riak KV Configuration Reference

Riak has a riak.conf configuration file located in /etc if you are using a source install or in /etc/riak or /usr/local/etc if you used a binary install.

The riak.conf file is used to set a wide variety of attributes for the node, from the storage backend that the node will use to store data to the location of SSL-related files to sibling resolution parameters and beyond.

Note on upgrades to 2.0

If your cluster is currently running a version of Riak prior to 2.0 and you’d like to upgrade to version 2.0 or later, you may continue to use your old app.config and vm.args files. You may also use the newer riak.conf alongside them, but please be aware that any settings in app.config or vm.args will override settings in riak.conf.

The advanced.config file

For most Riak installations, the riak.conf file should be sufficient for configuration management. But some installations, particularly those upgrading from an earlier version of Riak to version 2.0 or later, may need to make use of an advanced.config file to control some settings available only in versions prior to 2.0. If this applies to your installation, please see the Advanced Configuration section below.

Node Metadata

Every Riak node has a name and a cookie used to facilitate inter-node communication. The following parameters enable you to customize the name and cookie.

Config Description Default
distributed_cookie Cookie for distributed node communication within a Riak cluster. All nodes in the same cluster should use the same cookie or they will not be able to communicate. riak
nodename The name of the Riak node. riak@127.0.0.1
ring_size Number of partitions in the cluster (only valid when first creating the cluster). Must be a power of 2. The minimum is 8 and the maximum is 1024. 64

Ring

Configurable parameters for your cluster’s ring.

Config Description Default
ring.state_dir Default location of ringstate. ./data/ring
ring_size Number of partitions in the cluster (only valid when first creating the cluster). Must be a power of 2. The minimum is 8 and the maximum is 1024. 64
transfer_limit Number of concurrent node-to-node transfers allowed. 2

Storage Backend

Riak enables you to choose from the following storage backends:

Config Description Default
storage_backend Specifies the storage engine used for Riak's key-value data and secondary indexes (if supported).

The available options are bitcask (the default), leveldb, memory, leveled and multi.		 bitcask

Directories

The directories in which Riak stores data, logs, dependencies, executables, and configuration files can be configured using the parameters below.

Config Description Default
platform_bin_dir The directory in which the riak admin, riak-debugexecutables are stored. ./bin
platform_data_dir The directory in which Riak stores its storage backend data, as well as active anti-entropy data, and cluster metadata. ./data
platform_etc_dir The directory in which Riak's configuration files are stored. ./etc
platform_lib_dir The directory in which Riak's dependencies are housed. ./lib
platform_log_dir The directory in which Riak's log files are stored, e.g. console.log, erlang.log, and crash.log files. ./log

Each of these directory parameters can be used to construct values for other parameters by placing it within a $(...). Thus, platform_log_dir becomes $(platform_log_dir) and so on.

To give an example, you can select the directory used by Riak’s active anti-entropy system using the anti_entropy.data_dir parameter. When setting that parameter, you can specify an absolute directory, as below:

anti_entropy.data_dir = /path/to/anti_entropy

Or you can use the value of platform_data_dir:

anti_entropy.data_dir = $(platform_data_dir)/anti_entropy

Riak Control

Riak Control is a web-based administrative console for inspecting and manipulating Riak clusters. The configurable parameters below enable you to turn the Riak Control subsystem on and off and to configure console authorization.

Config Description Default
riak_control Set to off to disable the admin panel. off
riak_control.auth.mode Authentication mode used for access to the admin panel. Options are off (which is the default) or userlist. off
riak_control.auth.user.$username.password If Riak Control's authentication mode (riak_control.auth.mode) is set to userlist, this is the list of usernames and passwords for access to the admin panel.

Runtime Health

Configurable parameters for interaction between Riak and the underlying operating system.

Config Description Default
runtime_health.triggers.distribution_port Whether distribution ports with full input buffers will be counted as busy. Distribution ports connect Riak nodes within a single cluster. on
runtime_health.triggers.port Whether ports with full input buffers will be counted as busy. Ports can represent open files or network sockets. on
runtime_health.triggers.process.heap_size A process will become busy when its heap exceeds this size (in bytes). 160444000
runtime_health.triggers.process.garbage_collection A process will become busy when it exceeds this amount of time doing garbage collection. Set as an integer plus time unit, e.g. `50ms` for 50 milliseconds, `5s` for 5 seconds, etc.Note: Enabling this setting can cause performance problems on multi-core systems. off
runtime_health.triggers.process.long_schedule A process will become busy when it exceeds this amount of time during a single process scheduling and execution cycle. Set as an integer plus time unit, e.g. `50ms` for 50 milliseconds, `5s` for 5 seconds, etc. off
runtime_health.thresholds.busy_ports The threshold at which a warning will be triggered about the number of ports that are overly busy. Ports with full input buffers count toward this threshold. 2
runtime_health.thresholds.busy_processes The threshold at which to warn a warning will be triggered about the number of processes that are overly busy. Processes with large heaps or that take a long time to garbage collect will count toward this threshold. 30

Default Bucket Properties

When configuring buckets using bucket types, the table below lists the bucket properties that are used when no bucket type is specified.

Config Description Default
buckets.default.allow_mult Whether or not siblings are allowed

Note: See Conflict Resolution for a discussion of siblings.		 false
buckets.default.basic_quorum Whether not-founds will invoke the "basic quorum" optimization. This setting will short-circuit fetches where the majority of replicas report that the key is not found. Only used when notfound_ok is set to false. false
buckets.default.dw The number of replicas which must reply to a write request indicating that the write was committed to durable storage for the write to be deemed successful. quorum
buckets.default.last_write_wins Whether conflicting writes resolve via timestamp. false
buckets.default.merge_strategy The strategy used when merging objects that potentially have conflicts. The default is 2 in Riak 2.0 for typed buckets and 1 for non-typed buckets. This setting reduces sibling creation through additional metadata on each sibling (also known as Dotted Version Vectors). Setting this to 1 is the default for Riak 1.4 and earlier, and may duplicate siblings that originated in the same write. 1
buckets.default.n_val The number of replicas stored in **non-typed** buckets. For typed buckets, the default is 3 unless changed explicitly for that bucket type.

Note: See Replication Properties for further discussion.		 3
buckets.default.notfound_ok Whether not-founds will count toward a quorum of reads. true
buckets.default.postcommit A space-delimited list of functions that will be run after a value is stored. Only Erlang functions are allowed, using the module:function format.
buckets.default.precommit A space-delimited list of functions that will be run before a value is stored, and that can abort the write. Only Erlang functions are allowed, using the module:function format.
buckets.default.pr The number of primary, non-fallback replicas that must reply to a read request. 0
buckets.default.pw The number of primary, non-fallback replicas which must reply to a write request. 0
buckets.default.r The number of replicas which must reply to a read request. quorum
buckets.default.w The number of replicas which must reply to a write request, indicating that the write was received. quorum
buckets.default.rw The number of replicas which must reply to a delete request. quorum

Object Settings

Configurable parameters for conflict resolution and dealing with sibling explosion.

Config Description Default
object.format Controls which binary representation of a riak value is stored on disk. Options are 0, which will use the original erlang:term_to_binary format but has a higher space overhead, or 1, which will tell Riak to utilize a new format for more compact storage of small values. 1
object.siblings.maximum Writing an object with more than this number of siblings will send a failure to the client. 100
object.siblings.warning_threshold Writing an object with more than this number of siblings will generate a warning in the logs. 25
object.size.maximum Writing an object larger than this will send a failure to the client. 50MB
object.size.warning_threshold Reading or writing objects larger than this size will write a warning in the logs. 5MB

Erlang VM

In the older configuration system, the Erlang VM in which Riak runs was configured using a vm.args file. In the new, riak.conf-based system, the Erlang VM can be configured using the parameters in the table below.

Config Description Default
erlang.async_threads The number of threads in the Erlang VM's asynchronous thread pool. The valid range is 0-1024. If thread support is not available, this parameter will have no impact; if thread support is available, the default value is 64. This is the equivalent of the +A flag. More information can be found here. 64 (if thread support is available)
erlang.async_threads.stack_size If thread support is available in your Erlang VM, this parameter sets the amount of memory allocated to each asynchronous thread, which you can set as KB, MB, GB, etc. The valid range is 16-8192 kilowords, which translates to 64-32768 KB on 32-bit architectures. Although there is no default, we suggest a stack size of 16 kilowords, which translates to 64 KB. This small default size has been chosen because the number of asynchronous threads, set using the erlang.async_threads parameter explained above, might be quite large. The 64 KB default is enough for drivers delivered with Erlang/OTP but might not be large enough to accommodate drivers that use the driver_async() functionality, documented here.
erlang.distribution.net_ticktime The net kernel is an Erlang system process that provides various forms of network monitoring. In a Riak cluster, one of the functions of the net kernel is to periodically check node liveness. Tick time is the frequency with which those checks happen. This parameter determines that frequency for every N. If you set this parameter to 10, for example, the tick will occur once every 10 seconds.
erlang.distribution.port_range.minimum For ease of firewall configuration, the Erlang distribution can be bound to a limited range of TCP ports. If this parameter is set, and erlang.distribution.port_range.maximum is not set, only this port will be used. If the minimum is unset, no restriction will be made on the port range. Instead, Erlang will listen on a random high-numbered port. More information here and here.
erlang.distribution.port_range.maximum See the description for erlang.distribution.port_range.minimum directly above.
erlang.schedulers.force_wakeup_interval Set the scheduler forced wakeup interval. All run queues will be scanned each time period specified (in milliseconds). While there are sleeping schedulers in the system, one scheduler will be woken for each non-empty run queue found. An interval of zero disables this feature, which is the default. This feature is a workaround for lengthy executing native code, and native code that does not properly bump reductions. More information here.
erlang.schedulers.compaction_of_load Enables or disables the Erlang scheduler's compaction of load. When enabled (which is the default), load balancing will strive to establish a load distribution that causes as many scheduler threads as possible to be fully loaded, i.e. not to run out of scheduled work. This is accomplished by migrating load, such as running processes, into a smaller set of schedulers when schedulers frequently run out of work. When disabled, the frequency at which schedulers run out of work will not be taken into account by the load balancing logic. true (enabled)
erlang.schedulers.utilization_balancing Enables or disables the Erlang scheduler's balancing of load. By default, scheduler utilization of balancing is disabled while scheduler compaction of load is enabled, i.e. erlang.schedulers.compaction_of_load is set to true. In this state, the Erlang VM will strive for a load distribution which causes as many scheduler threads as possible to be fully loaded, i.e. to not run out of work. When load balancing is enabled using this setting, the system will attempt to equally scheduler utilization between schedulers. false (disabled)
erlang.distribution_buffer_size For nodes with many busy_dist_port events, Basho recommends raising the sender-side network distribution buffer size. 32MB may not be sufficient for some workloads and is a suggested starting point. Erlangers may know this as +zdbbl. See more here . 32MB
erlang.process_limit Raises the default Erlang process limit 256000
erlang.max_ets_tables Raises the ETS table limit 256000
erlang.crash_dump Sets the location of crash dumps ./log/erl_crash.dump
erlang.fullsweep_after A non-negative integer which indicates how many times generational garbage collections can be done without forcing a fullsweep collection. In low-memory systems (especially without virtual memory), setting the value to 0 can help to conserve memory. More information here. 0
erlang.max_ports The number of concurrent ports/sockets. The valid range is 1024 to 134217727. 65536
erlang.K Enables or disables the kernel poll functionality if the emulator supports it. If the emulator does not support kernel poll, and the K flag is passed to the emulator, a warning is issued at startup. Similar information here. on
erlang.schedulers.total Sets the number of scheduler threads to create and scheduler threads to set online when erlang.smp support has been enabled. The maximum for both values is 1024. If the Erlang runtime system is able to determine the amount of logical processors configured and logical processors available, schedulers.total will default to logical processors configured, and schedulers.online will default to the number of logical processors available. Otherwise, the default values will be 1. Schedulers may be omitted if schedulers.online is not and vice versa. If schedulers.total or schedulers.online is specified as a negative number, the value is subtracted from the default number of logical processors configured or logical processors available, respectively. Specifying the value 0 for Schedulers or SchedulersOnline resets the number of scheduler threads or scheduler threads online respective to its default value. This option is ignored if the emulator doesn't have SMP support enabled (see the erlang.smp flag). More information here.
erlang.schedulers.online See the description for erlang.schedulers.total directly above.
erlang.W Sets the mapping of warning messages for error_logger. Messages sent to the error logger using one of the warning routines can be mapped either to errors, warnings (w, which is the default), or info reports (i). w
erlang.smp Starts the Erlang runtime system with SMP support enabled. This may fail if no runtime system with SMP support is available. The auto setting starts the Erlang runtime system with SMP support enabled if it is available and more than one logical processor is detected. A value of disable starts a runtime system without SMP support. Note: The runtime system with SMP support will not be available on all supported platforms. See also the erlang.schedulers settings. Some native extensions (NIFs) require use of the SMP emulator. More information here. enable
erlang.shutdown_time Limits how long the Erlang VM spends shutting down. After the specified duration elapses, all existing processes are killed. 10s

JavaScript MapReduce

Configurable parameters for Riak’s now-deprecated JavaScript MapReduce system.

Config Description Default
javascript.source_dir A directory containing the Javascript source files which will be loaded by Riak when it initializes Javascript VMs.
javascript.maximum_stack_size The maximum amount of thread stack memory to allocate to each JavaScript virtual machine. 16MB
javascript.maximum_heap_size The maximum amount of memory allocated to each JavaScript virtual machine. 8MB
javascript.hook_pool_size The number of JavaScript virtual machines available for executing pre-commit hook functions. 2
javascript.reduce_pool_size The number of JavaScript virtual machines available for executing reduce functions. 6
javascript.map_pool_size The number of JavaScript virtual machines available for executing map functions. 8

Security

Configurable parameters for Riak KV Security.

Config Description Default
ssl.cacertfile The default signing authority location for HTTPS. #(platform_etc_dir)/cacertfile.pem
ssl.keyfile Default key location for HTTPS. #(platform_etc_dir)/key.pem
ssl.certfile Default cert location for HTTPS. #(platform_etc_dir)/cert.pem
secure_referer_check Measures were added to Riak 1.2 to counteract cross-site scripting and request-forgery attacks. Some reverse proxies cannot remove the Referer header and make serving data directly from Riak impossible. Turning this setting to off disables this security check. on
check_crl Whether to check the certificate revocation list (CRL) of a client certificate. This defaults to on but some CAs may not maintain or define a CRL, so this can be disabled if no CRL is available. on
tls_protocols.sslv3 Determine which SSL/TLS versions are allowed. By default, only TLS 1.2 is allowed, but other versions can be enabled if clients don't support the latest TLS standard. It is strongly recommended that SSLv3 not be enabled unless absolutely necessary. More than one protocol can be enabled at once. The tls_protocols parameters below can be used to turn different versions on and off. off
tls_protocols.tlsv1.2 on
tls_protocols.tlsv1.1 off
tls_protocols.tlsv1 off
honor_cipher_order Whether to prefer the order in which the server lists its ciphers. When set to off, the client's preferred cipher order dictates which cipher is chosen. on

Client Interfaces

Configurable parameters for clients connecting to Riak either through Riak’s Protocol Buffers or HTTP API.

Config Description Default
protobuf.nagle Turns off Nagle's algorithm for Protocol Buffers connections. This is equivalent to setting the TCP_NODELAY option on the socket. off
protobuf.backlog The maximum length to which the queue of pending connections may grow. If set, it must be an integer greater than zero. If you anticipate a huge number of connections being initialized simultaneously, set this number higher. 128
listener.protobuf.$name This is the IP address and TCP port to which the Riak Protocol Buffers interface will bind. {"127.0.0.1",8087}
listener.http.$name This is the IP address and TCP port to which the Riak HTTP interface will bind. {"127.0.0.1",8098}
listener.https.$name This is the IP address and TCP port to which the Riak HTTPS interface will bind.

Logging

Riak’s logging system.

logger.file Filename to use for log files. $(platform_log_dir)/console.log
log.console Where to emit the default log messages (typically at info severity). Possible values: off, which disables console log messages; file, which specifies that log messages will be output to the file specified by log.console.file; console, which outputs messages to standard output (seen when using riak attach-direct); or both, which outputs messages both to the file specified in log.console.file and to standard out. file
log.console.file When log.console is set to file or both, this parameter determines the path of the file to which console messages will be logged. ./log/console.log
log.console.level The severity level of the console log. Possible values:
  • debug
  • info
  • warning
  • error
 info
log.crash Whether to enable the crash log on
log.crash.file If the crash log is enabled, the file where its messages will be written ./log/crash.log
log.crash.maximum_message_size Maximum size of individual messages in the crash log 64KB
log.crash.rotation The schedule on which to rotate the crash log. More information here. $D0
log.crash.rotation.keep The number of rotated crash logs to keep. When set to current, only the current open log file is kept. Otherwise, an integer can be specified. 5
log.crash.size Maximum size of the crash log before it is rotated 10MB
log.error.file The file where error messages will be logged. ./log/error.log
log.error.messages_per_second Maximum number of error_logger messages to handle per second 100
log.error.redirect Whether to redirect error_logger messages into lager on
sasl Whether to enable sasl, Erlang's built-in error logger off

Active Anti-Entropy

Configurable parameters for Riak’s active anti-entropy subsystem.

Config Description Default
anti_entropy How Riak will repair out-of-sync keys. If set to active, out-of-sync keys will be repaired in the background; if set to passive, out-of-sync keys are only repaired on read; and if set to active-debug, verbose debugging information will be output. active
anti_entropy.bloomfilter Bloom filters are highly effective in shortcutting data queries that are destined to not find the requested key, though they tend to entail a small performance cost. on
anti_entropy.max_open_files 20
anti_entropy.write_buffer_size The LevelDB options used by Active Anti-Entropy to generate the LevelDB-backed on-disk hashtrees. 4MB
anti_entropy.data_dir The directory where AAE hash trees are stored. ./data/anti_entropy
anti_entropy.trigger_interval The tick determines how often the Active Anti-Entropy manager looks for work to do (building/expiring trees, triggering exchanges, etc). Lowering this value will speed up the rate at which all replicas are synced across the cluster. Increasing the value is not recommended. 15s
anti_entropy.concurrency_limit Limit how many Active Anti-Entropy exchanges or builds can happen concurrently. 2
anti_entropy.tree.expiry Determines how often hash trees are expired after being built. Periodically expiring a hash tree ensures that the on-disk hash tree data stays consistent with the actual K/V backend data. It also helps Riak identify silent disk failures and bit rot. However, expiration is not needed for normal active anti-entropy operations and should be infrequent for performance reasons. The time is specified in milliseconds. 1w
anti_entropy.tree.build_limit.per_timespan 1h
anti_entropy.tree.build_limit.number Restrict how fast AAE can build hash trees. Building the tree for a given partition requires a full scan over that partition's data. Once built, trees stay built until they are expired. .number is the number of builds; .per_timespan is the amount of time in which that number of builds occurs. 1
anti_entropy.use_background_manager Whether AAE is to use a background process to limit AAE tree rebuilds. If set to on, this will help to prevent system response degradation under times of heavy load from multiple background tasks that contend for the same system resources; setting this parameter to off can cut down on system resource usage. off

TicTac Active Anti-Entropy

Config Description Default
tictacaae_active Changes TicTacAAE from Passive or Active. If you want to run TicTac AAE alongside legacy AAE, set both to Active. Can be active or passive passive
tictacaae_dataroot Path under which aae datafiles will be stored (platform_data_dir)/tictac_aae
tictacaae_parallelstore When running in parallel mode, which will be the default if the backend does not support native tictac aae (i.e. is not leveled), what type of parallel key store should be kept - leveled_ko (leveled and key-ordered), or leveled_so (leveled and segment ordered). When running in native mode, this setting is ignored. Acceptable values are leveled_ko or leveled_so leveled_ko
tictacaae_rebuildwait The minimum number of hours to wait between rebuilds. 336
tictacaae_rebuilddelay The number of seconds which represents the length of the period in which the next rebuild will be scheduled. So if all vnodes are scheduled to rebuild at the same time, they will actually rebuild randomly between 0 and this value (in seconds) after the rebuild time. 345600

Intra-Cluster Handoff

Configurable parameters for intra-cluster, i.e. inter-node, handoff.

Config Description Default
handoff.max_rejects The maximum number of times that a secondary system within Riak can block handoff of primary key/value data. The approximate maximum duration that a vnode can be blocked can be determined by multiplying this setting by vnode_management_timer. If you want to prevent handoff from ever being blocked by a secondary system, set this parameter to 0. 6
handoff.inbound Whether inbound handoff is enabled on the node. Possible values are on or off. on
handoff.outbound Whether outbound handoff is enabled on the node. Possible values are on or off. on
handoff.port Specifies the TCP port that Riak uses for intra-cluster data handoff. 8099
handoff.ssl.certfile To encrypt riak_core intra-cluster data handoff traffic, uncomment this line and edit its path to an appropriate certfile and keyfile.
handoff.ssl.keyfile The keyfile paired with the certfile specified in .certfile.
handoff.use_background_manager Whether Riak will use a background manager to limit K/V handoff. This can help to prevent system response degradation during times of heavy load caused by multiple background tasks that contend for the same system resources; setting this parameter to off can cut down on system resource usage. off

Riak Data Types

Config Description Default
datatypes.compression_level Whether serialized Data Types will use compression and at what level. When set to an integer, the parameter refers to the aggressiveness of compression, on a scale from 0 to 9. on is equivalent to 6, whereas off is equivalent to 0. Higher values for compression tend to be more CPU intensive. 1

SNMP

Owing to lack of usage, SNMP support has been removed from Riak KV 2.9.0 and higher.

JMX

Owing to lack of usage, JMX support has also been removed from Riak KV 2.9.0 and higher.

Strong Consistency

Please Note:

Riak KV’s strong consistency is an experimental feature and may be removed from the product in the future. Strong consistency is not commercially supported or production-ready. Strong consistency is incompatible with Multi-Datacenter Replication, Bitcask Expiration, LevelDB Secondary Indexes, Riak Data Types and Commit Hooks. It suffers from known issues and we do not recommend its usage in any production environment.

Riak’s strong consistency feature has a variety of tunable parameters that allow you to enable and disable strong consistency, modify the behavior of leaders and followers, set various timeouts, and more. More detailed information from an operations perspective can be found in our documentation on managing strong consistency.

Strong consistency is disabled by default. The strong_consistency parameter enables you to turn it on. This setting is available in each node’s riak.conf file.

Config Description Default
strong_consistency Enables the consensus subsystem used for strongly consistent Riak operations if set to on. off

Unlike the strong_consistency setting, the settings listed below are available only in advanced.config, in the riak_ensemble section of that file. That section looks like this:

{riak_ensemble, [
    {parameter1, value},
    {parameter2, value},
    %% Other setting
  ]}

Further instructions on setting parameters in advanced.config can be found in the advanced configuration section below.

Using these settings properly demands a firm understanding of the basic architecture of Riak’s implementation of strong consistency. We highly recommend reading our documentation on the implementation details behind strong consistency before changing the defaults on these parameters.

Config Description Default
ensemble_tick The rate at which leaders perform their periodic duties, including refreshing the leader lease, in milliseconds. This setting must be lower than both the lease_duration and follower_timeout settings (both listed below). Lower values mean that leaders perform their duties more frequently, which can allow for faster convergence if a leader goes offline and then returns to the ensemble; higher values mean that leaders perform their duties less frequently, which can reduce network overhead. 500
lease_duration Determines how long a leader lease remains valid without being refreshed (in milliseconds). This should be set higher than the ensemble_tick setting (listed above) so that leaders have time to refresh their leases before they time out, and it must be set lower than the follower_timeout setting (listed below). ensemble_tick * 3/2
follower_timeout Determines how long a follower waits to hear from a leader before it abandons the leader (in milliseconds). This must be set greater than the lease_duration setting. lease_duration * 4
alive_tokens Determines the number of ticks the leader will wait to hear from its associated vnode before assuming that the vnode is unhealthy and stepping down as leader. If the vnode does not respond to the leader before ensemble_tick * alive_tokens milliseconds have elapsed, the leader will give up leadership. It may be necessary to raise this setting if your Riak vnodes are frequently stalling out on slow backend reads/writes. If this setting is too low, it may cause slow requests to time out earlier than the request timeout. 2
storage_delay Determines how long the consensus subsystem delays syncing to disk when performing certain metadata operations (in milliseconds). This delay allows multiple operations to be coalesced into a single disk write. We do not recommend that you change this setting. 50
storage_tick Determines how often the consensus subsystem writes data to disk that was requested to be written asynchronously (in milliseconds). We do not recommend that you change this setting. 5000
trust_lease Determines whether leader leases are used to optimize reads. When set to true, a leader with a valid lease will handle the read directly without contacting any followers; when set to false, the leader will always contact followers. For more information, see our internal documentation on leader leases. true
peer_get_timeout Determines the timeout used internally for reading consistent data, in milliseconds. This setting must be greater than the highest request timeout used by your application. 60000 (1 minute)
peer_put_timeout Determines the timeout, in milliseconds, used internally for writing consistent data. This setting must be greater than the highest request timeout used by your application. 60000 (1 minute)
peer_workers The number of concurrent workers used by the leader to service requests. Increasing this setting may boost performance depending on the workload. 1
tree_validation Determines whether Riak considers peer Merkle trees to be trusted after a node restart. When validation is enabled (the default), Riak does not trust peer trees after a restart, instead requiring the peer to sync with a trusted majority. This is the safest option, as it protects Riak against undetected corruption of the Merkle tree. However, this mode reduces Riak availability since it can sometimes require more than a simple majority of nodes to be online and reachable. true
synchronous_tree_updates Determines whether the metadata updates to follower Merkle trees are handled synchronously or not. When set to true, Riak requires two quorum round trips to occur before replying back to the client, the first quorum request to write the actual object and the second to write the Merkle tree data. When set to false, Riak will respond back to the client after the first round trip, letting the metadata update happen asynchronously.

It's important to note that the leader always updates its local Merkle tree before responding to the client. This setting only affects the metadata writes sent to followers.

In principle, asynchronous updates are unsafe. If the leader crashes before sending the metadata updates and all followers that had acknowledged the object write somehow revert to the object value immediately prior to a write request, a future read could return the immediately preceding value without realizing that it was incorrect. Given that this scenario is unlikely, this setting defaults to false in the name of improved performance.		 false

Miscellaneous

Config Description Default
metadata_cache_size This setting controls the size of the metadata cache for each vnode. The cache can be disabled by setting it to off (this is the default). Enabling the cache should not be necessary in disk-based backends (i.e. LevelDB and Bitcask) but it can help performance in the Memory backend. Note that this setting adjusts the size of the ETS table rather than the actual data. Thus, more space may be used than the simple size * number-of-vnodes calculation would imply.

Caution: This setting should not be changed without extensive benchmarking.		 off
max_concurrent_requests The maximum number of concurrent requests of each type (GET or PUT) that is allowed. Setting this value to infinite disables overload protection. The erlang.process_limit should be at least 3 times this setting. 50000
dtrace Whether DTrace is enabled. Do not enable unless your Erlang/OTP runtime is compiled to support DTrace, which is available in R15B01 (supported by the official source package) and in R14B04 via a custom repository and branch. off
vnode_management_timer Sets the frequency with which vnodes attempt to trigger handoff between this node and other nodes in the cluster. 10s (10 seconds)
retry_put_coordinator_failure When a PUT (i.e. write) request fails, Riak will retry the operation if this setting is set to on, which is the default. Setting it to off will speed response times on PUT requests in general, but at the risk of potentially increasing the likelihood of write failure. on
background_manager Riak's background manager is a subsystem that coordinates access to shared resources from other Riak subsystems. The background manager can help to prevent system response degradation under times of heavy load caused by multiple background tasks. on
worker_pool_size This is a pool of workers per-vnode, to be used for general queries, in %% particular secondary index queries. This now defaults to 5 workers, prior %% to release 3.2.0 it was set to a default of 10. 5

Advanced Configuration

The advanced.config file takes the same format as the app.config file familiar to users of versions of Riak prior to 2.0. Here is an example:

[
  {riak_core,
    [
      {cluster_mgr, {"127.0.0.1", 8098 } },
      %% more riak_core configs
    ]},

  {riak_repl,
    [
      {data_root, "/var/db/riak/riak_repl/"},
      %% more riak_repl configs
    ]
  }
].

The following settings are available in the advanced.config file:

riak_repl settings

Most settings that are configurable through advanced.config are related to Riak’s riak_repl subsystem.

Config Description Default
data_root Path (relative or absolute) to the working directory for the replication process. /var/db/riak/riak_repl/
max_fssource_cluster The hard limit of fullsync workers that will be running on the source side of a cluster across all nodes on that cluster for a fullsync to a sink cluster. This means that if you have configured fullsync for two different clusters, both with a max_fssource_cluster of 5, 10 fullsync workers can be in progress. This only affects nodes on the source cluster on which this parameter is defined, either via the configuration file or command line. 5
max_fssource_node This setting limits the number of fullsync workers that will be running on each individual node in a source cluster. This is a hard limit for all fullsyncs enabled; additional fullsync configurations will not increase the number of fullsync workers allowed to run on any node. This only affects nodes on the source cluster on which this parameter is defined, either via the configuration file or command line. 1
max_fssink_node This setting limits the number of fullsync workers allowed to run on each individual node in a sink cluster. This is a hard limit for all fullsyncs enabled; additional fullsync configurations will not increase the number of fullsync workers allowed to run on any node. This only affects nodes on the source cluster on which this parameter is defined, either via the configuration file or command line. 1
fullsync_on_connect Whether to initiate a fullsync on initial connection from the sink cluster. true
fullsync_interval A single-integer value representing the duration to wait, in minutes, between fullsyncs, or a list of {clustername, time_in_minutes} pairs for each sink participating in fullsync replication. 30
rtq_max_bytes The maximum size, in bytes, to which the realtime replication queue can grow before new objects are dropped. Dropped objects will need to be replicated with a fullsync. 104857600
proxy_get Whether to enable Riak CS proxy_get and block filter. disabled
rt_heartbeat_interval A heartbeat message is sent from the source to the sink every rt_heartbeat_interval seconds. Setting rt_heartbeat_interval to undefined disables the realtime heartbeat. This feature is available only in Riak KV Enterprise Edition 1.3.2 - 2.2.3 and then from Riak KV 2.2.6 onwards. 15
rt_heartbeat_timeout If a heartbeat response is not received within the time period specified by this setting (in seconds), the source connection exits and will be re-established. This feature is available only in Riak KV Enterprise Edition 1.3.2 - 2.2.3 and then from Riak KV 2.2.6 onwards. 15
realtime_connection_rebalance_max_delay_secs Should a server on the source cluster be restarted, this is the amount of time (in seconds), before the realtime connections are rebalanced by a change in the number of source nodes. 300
fullsync_use_background_manager By default, fullsync replication will attempt to coordinate with other Riak subsystems that may be contending for the same resources. This will help to prevent system response degradations during times of heavy load from multiple background tasks. To disable background coordination, set this parameter to `false`. This feature is available only in Riak KV Enterprise Edition 2.0 and later as well as Riak KV 2.2.6 onwards. true

Other settings

There are three non-riak_repl settings available in advanced.config.

Config Section Description Default
add_paths riak_kv If you are installing custom code for Riak, e.g. for the purpose of running MapReduce jobs or commit hooks, this setting specifies the paths to any compiled .beam files that you wish to use. This is expressed as a list of absolute paths on the node's filesystem, e.g. [ "/tmp", "/other" ].
cluster_mgr riak_core The cluster manager listens for connections from remote clusters on the specified IP and port. Every node runs one cluster manager, but only the cluster manager running on the cluster leader will service requests. This can change as nodes enter and leave the cluster. {"127.0.0.1", 9080}
delete_mode riak_kv Specifies how Riak behaves after objects are marked for deletion with a tombstone. There are three possible settings: keep disables tombstone removal altogether; immediate removes objects' tombstones as soon as the delete request is received; and setting delete_mode to an integer value specifies the number of milliseconds to wait before removing tombstones. More information can be found in Object Deletion. 3000 (3 seconds)
target_n_val riak_core The highest n_val that you generally intend to use. This setting affects how partitions are distributed within the cluster, helping to ensure that "hot spots" don't occur, i.e. that data is never stored more than once on the same physical node. You will need to change this setting only in rare circumstances. Assuming that ring_size is a power of 2, the ideal value for this setting is both (a) greater than or equal to the largest n_val for any bucket type and (b) an even divisor of the number of partitions in the ring, i.e. ring_size. The default is 4, and the number of physical nodes in your cluster must be greater than target_n_val for this setting to be effective at preventing hot spots. 4

Cluster Job Controls

Warning

Before changing cluster.job controls in a production environment, test your application to ensure it does not have any hidden dependencies on them.

The cluster.job switches control whether classes of jobs are enabled or disabled through the HTTP(S) and Protobuf interfaces. All jobs are enabled by default.

Field Default Valid values
cluster.job.riak_kv.list_buckets enabled enabled or disabled
cluster.job.riak_kv.stream_list_buckets enabled enabled or disabled
cluster.job.riak_kv.list_keys enabled enabled or disabled
cluster.job.riak_kv.stream_list_keys enabled enabled or disabled
cluster.job.riak_kv.map_reduce enabled enabled or disabled
cluster.job.riak_kv.map_reduce_js enabled enabled or disabled
cluster.job.riak_kv.secondary_index enabled enabled or disabled