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
andvm.args
files. You may also use the newerriak.conf
alongside them, but please be aware that any settings inapp.config
orvm.args
will override settings inriak.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 , 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 ring state data, 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.
Config | Description | Default |
---|---|---|
search |
To enable Search, set this to on . |
off |
search.anti_entropy.data_dir |
The directory in which Search's Active Anti-Entropy data files are stored | ./data/yz_anti_entropy |
search.root_dir |
The root directory for Riak Search, under which index data and configuration is stored. | ./data/yz |
search.solr.jmx_port |
The port to which Solr JMX binds.
Note: Binds on every interface. |
8985 |
search.solr.jvm_options |
The options to pass to the Solr JVM. Non-standard options, i.e.
-XX , may not be portable across JVM implementations.
Example: XX:+UseCompressedStrings |
-d64 -Xms1g -Xmx1g -XX:+UseStringCache
-XX:+UseCompressedOops |
search.solr.port |
The port to which Solr binds.
Note: Binds on every interface. |
8093 |
search.solr.start_timeout |
How long Riak will wait for Solr to start. The start sequence will
be tried twice. If both attempts time out, the Riak node will be shut
down. This may need to be increased as more data is indexed and Solr
takes longer to start. Values lower than 1s will be rounded
up to the minimum 1s . |
30s |
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.
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, Riak
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
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:
|
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:
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:
none |
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 |
anti_entropy.throttle |
Whether the distributed throttle for Active Anti-Entropy is enabled. | on |
anti_entropy.throttle.$tier.mailbox_size |
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.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. |
|
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 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
Configurable parameters for the [Simple Network Management Protocol][use ref snmp](SNMP) server built into Riak Enterprise.
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 the
gauge 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 Enterprise.
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. | {"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 |