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:
- Bitcask --- configuration
- LevelDB --- configuration
- Memory --- configuration
- Multi --- configuration
| 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, 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-debug, and now-deprecated search-cmd executables 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
Search
Configuration parameters for Riak KV Search. For a more detailed description of these parameters, check out Search Settings.
| Field | Default | Valid values |
|---|---|---|
search | off | on or off |
search.anti_entropy.data_dir | ./data/yz_anti_entropy | Directory |
search.anti_entropy.throttle.$tier.delay | No default | Non-negative integer |
search.anti_entropy.throttle.$tier.solrq_queue_length | No default | Non-negative integer |
search.dist_query | on | on or off |
search.index.error_threshold.failure_count | 3 | Integer |
search.index.error_threshold.failure_interval | 5000 | Milliseconds |
search.index.error_threshold.reset_interval | 30000 | Milliseconds |
search.queue.batch.flush_interval | 1000 | ms, s, m, h |
search.queue.batch.maximum | 100 | Integer |
search.queue.batch.minimum | 1 | Integer |
search.queue.high_watermark | 10000 | Integer |
search.queue.high_watermark.purge_strategy | purge_one | purge_one, purge_index, or off |
search.root_dir | ./data/yz | Directory |
search.solr.jvm_options | -d64 -Xms1g -Xmx1g -XX:+UseStringCache -XX:+UseCompressedOops | Java command-line arguments |
search.solr.jmx_port | 8985 | Integer |
search.solr.jmx_port | 8985 | Integer |
search.solr.port | 8093 | Integer |
search.solr.start_timeout | 30s | Integer with time units (eg. 2m) |
yokozuna.aae_throttle_enabled | on | on or off |
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 integerplus 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. | 8087 |
| listener.http.$name | This is the IP address and TCP port to which the Riak HTTP interface will bind. | 8098 |
| listener.https.$name | This is the IP address and TCP port to which the Riak HTTPS interface will bind. |
Logging
Configurable parameters for lager, Riak's logging system.
| Config | Description | Default |
|---|---|---|
| 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 |
| log.syslog | When set to on, enables log output to syslog | off |
| log.syslog.facility | Sets the facility level of syslog output if log.syslog is set to on. Possible values: auth authpriv clock cron daemon ftp kern lpr mail news syslog user uucpIn addition to these settings, you may also select local0 through local7. | daemon |
| log.syslog.ident | If log.syslog is set to on, this setting determines the prefix appended to each syslog message. | riak |
| log.syslog.level | If log.syslog is set to on, this setting determines the log level of syslog output. Possible values: alert critical debug emergency error info none notice warning | info |
| 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 |
| search.anti_entropy.throttle | Whether the distributed throttle for Active Anti-Entropy is enabled. | on |
| search.anti_entropy.throttle.$tier.solrq_queue_length | Sets the throttling tiers for Active Anti-Entropy. Each tier is a minimum vnode mailbox size and a time-delay that the throttle should observe at that size and above. For example, anti_entropy.throttle.tier1.mailbox_size = 0 , anti_entropy.throttle.tier1.delay = 0ms, anti_entropy.throttle.tier2.mailbox_size = 40, anti_entropy.throttle.tier2.delay = 5ms, etc. If configured, there must be a tier which includes a mailbox size of 0. Both .mailbox_size and .delay must be set for each tier. | |
| search.anti_entropy.throttle.$tier.delay | See the description for anti_entropy.throttle.$tier.mailbox_size above. | |
| 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 |
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, such as Riak Search, 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 whatlevel. When set to an integer, the parameter refers to theaggressiveness 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
Configurable parameters for the [Simple Network Management Protocol][use ref snmp] (SNMP) server built into Riak SNMP.
| Config | Description | Default |
|---|---|---|
| snmp.nodePutTime100Threshold | Maximum PUT time | off |
| snmp.nodePutTime99Threshold | 99th percentile PUT time | off |
| snmp.nodePutTime95Threshold | 95th percentile PUT time | off |
| snmp.nodePutTimeMedianThreshold | Median PUT time | off |
| snmp.nodePutTimeMeanThreshold | Mean PUT time | off |
| snmp.nodeGetTime100Threshold | Maximum GET time | off |
| snmp.nodeGetTime99Threshold | 99th percentile GET time | off |
| snmp.nodeGetTime95Threshold | 95th percentile GET time | off |
| snmp.nodeGetTimeMedianThreshold | Median GET time | off |
| snmp.nodeGetTimeMeanThreshold | The threshold for the SNMP gauge at which traps are sent. Set to off to disable traps for this gauge. When set to a positive integer in microseconds, the rising trap will be sent when the gauge crosses above the threshold, and the falling trap will be sent when thegauge crosses below the threshold. In the case of the nodeGetTimeMean gauge, the threshold is nodeGetTimeMeanThreshold, the rising trap is nodeGetTimeMeanAlarmRising, and the falling trap is nodeGetTimeMeanFalling. Other gauge thresholds follow this naming pattern. | off |
| snmp.traps.replication | Enable or disable traps for Multi-Datacenter Replication. | off |
| snmp.refresh_frequency | How often SNMP will refresh its counters out of Riak's internal stats. | 1m |
| snmp.database_dir | The directory in which SNMP will store its internal database. | ./data/snmp/agent/db |
| snmp.force_reload | Whether to force SNMP information to be repopulated on startup | on |
JMX
Configuration parameters for the [JMX Monitoring][use ref jmx] system built into Riak JMX.
| Config | Description | Default |
|---|---|---|
| jmx | Turns on Java Management Extensions for Riak | off |
| jmx.refresh_rate | How often to refresh stats | 30s |
| jmx.restart_check | Time to wait between restarts of JMX. This is only for retrying JMX | |
| if the JMX server crashes. | 10m | |
| jmx.port | The port on which JMX will listen | 41110 |
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, Riak Search, Bitcask Expiration, LevelDB Secondary Indexes, Riak Data Types and Commit Hooks. 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 |
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 Enterprise 1.3.2 and later. | 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 Enterprise 1.3.2 and later. | 15 |
| 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 Enterprise 2.0 and later. | true |
Upgrading Riak Search with advanced.config
If you are upgrading to Riak 2.x and wish to upgrade to the new [Riak Search][use ref search](codename Yokozuna), you will need to enable
legacy Search while the upgrade is underway. You can add the following
snippet to your advanced.config configuration to do so:
[
%% Other configs
{riak_search, [ {enabled, true} ]},
{merge_index, [
{data_root, "/var/lib/riak/merge_index"},
{buffer_rollover_size, 1048576},
{max_compact_segments, 20}
]},
%% Other configs
].
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. | 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.
note
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 |
cluster.job.riak_search.query | enabled | enabled or disabled |
cluster.job.yokozuna.query | enabled | enabled or disabled |