Redis Settings in the Boxfile

Last Updated October 2014

The Boxfile is a yaml config file that allows you to custom-configure your app's environment. Settings typically set in the redis.conf are handled here. The following configuration options available in the Boxfile allow you to tailor-fit the build of your Redis service specific to your needs. After reading this, you should understand how to:

  • How to customize your Redis build
  • Bask in the awesomeness of Redis and Pagoda Box

Overview of Redis Boxfile Settings YAML

  cache1:
    type: redis
    version: 2.8
    stability: production
    topology: single
    redis_tcp_keepalive: 60
    redis_databases: 16
    redis_stop_writes_on_bgsave_error: 'yes'
    redis_slave_serve_stale_data: 'yes'
    redis_slave_read_only: 'yes'
    redis_repl_ping_slave_period: 10
    redis_repl_timeout: 60
    redis_repl_disable_tcp_nodelay: 'no'
    redis_max_clients: 1024
    redis_maxmemory_policy: 'volatile-lru'
    redis_maxmemory_samples: 3
    redis_appendonly: 'no'
    redis_appendfsync: 'everysec'
    redis_no_appendfsync_on_rewrite: 'no'
    redis_auto_aof_rewrite_percentage: 100
    redis_auto_aof_rewrite_min_size: '64m'
    redis_lua_time_limit: 5000
    redis_slowlog_log_slower_than: 0
    redis_slowlog_max_len: 128
    # Advanced Configs
    redis_hash_max_ziplist_entries: 512
    redis_hash_max_ziplist_value: 64
    redis_list_max_ziplist_entries: 512
    redis_list_max_ziplist_value: 64
    redis_set_max_intset_entries: 512
    redis_zset_max_ziplist_entries: 12
    redis_zset_max_ziplist_value: 64
    redis_activerehashing: 'yes'
    redis_hz: 10
    redis_aof_rewrite_incremental_fsync: 'yes'
/Boxfile

Redis Configuration Options

Redis Type & Version

When configuring a Redis service in your Boxfile, you must define the type of the service as redis. You can also specify the version of Redis to load into your cache service. The following version(s) are available:

  • 2.8

  • 3.0

The specific patch level is determined by the "stability" config.

Redis Version Defined on Create

Due to version compatibility constraints, Redis versions cannot be changed after the service is created. To use a different version, you'll have to create a new Redis service.

redis type & version YAML

  # default setting
  cache1:
    type: redis
    version: 3.0
/Boxfile
Topology

Topology defines the service's architecture and in what ways it can scale. Redis supports the following topologies:

  • Single

  • Redundant

More information can be found in the Service Topologies doc.

topology YAML

  # default setting
  cache1:
    type: redis
    topology: single
/Boxfile
TCP Keepalive

If non-zero, use SO_KEEPALIVE to send TCP ACKs to clients in absence of communication. This is useful for two reasons:

  1. Detect dead peers.

  2. Take the connection alive from the point of view of network equipment in the middle.

redis_tcp_keepalive YAML

  # default setting
  cache1:
    redis_tcp_keepalive: 60
/Boxfile
Databases

Sets the number of databases.

redis_databases YAML

  # default setting
  cache1:
    redis_databases: 16
/Boxfile
Stop Writes on BGSave Error

By default Redis will stop accepting writes if RDB snapshots are enabled (at least one save point) and the latest background save failed. This will make the user aware (in an hard way) that data is not persisting on disk properly, otherwise chances are that no one will notice and some distater will happen.

If the background saving process will start working again Redis will automatically allow writes again.

However if you have setup your proper monitoring of the Redis server and persistence, you may want to disable this feature so that Redis will continue to work as usually even if there are problems with disk, permissions, and so forth.

redis_stop_writes_on_bgsave_error YAML

  # default setting
  cache1:
    redis_stop_writes_on_bgsave_error: 'yes'
/Boxfile
Slave Serve Stale Data

When a slave loses its connection with the master, or when the replication is still in progress, the slave can act in two different ways:

  1. If slave-serve-stale-data is set to 'yes' the slave will still reply to client requests, possibly with out of date data, or the data set may just be empty if this is the first synchronization.

  2. If slave-serve-stale-data is set to 'no' the slave will reply with an error "SYNC with master in progress" to all the kind of commands but to INFO and SLAVEOF.

redis_slave_serve_stale_data YAML

  # default setting
  cache1:
    redis_slave_serve_stale_data: 'yes'
/Boxfile
Slave Read-Only

You can configure a slave instance to accept writes or not. Writing against a slave instance may be useful to store some ephemeral data (because data written on a slave will be easily deleted after resync with the master) but may also cause problems if clients are writing to it because of a misconfiguration.

redis_slave_read_only YAML

  # default setting
  cache1:
    redis_slave_read_only: 'yes'
/Boxfile
Repl Ping Slave Period

Slaves send PINGs to server in a predefined interval. It's possible to change this interval.

redis_repl_ping_slave_period YAML

  # default setting
  cache1:
    redis_repl_ping_slave_period: 10
/Boxfile
Repl Timeout

The following option sets a timeout for both Bulk transfer I/O timeout and master data or ping response timeout. The default value is 60 seconds. It is important to make sure that this value is greater than the value specified for redis_repl_ping_slave_period otherwise a timeout will be detected every time there is low traffic between the master and the slave.

redis_repl_timeout YAML

  # default setting
  cache1:
    redis_repl_timeout: 60
/Boxfile
Repl Disable TCP NoDelay

Toggles TCP_NODELAY on the slave socket after SYNC. If you select "yes" Redis will use a smaller number of TCP packets and less bandwidth to send data to slaves. But this can add a delay for the data to appear on the slave side. If you select "no" the delay for data to appear on the slave side will be reduced but more bandwidth will be used for replication.

redis_repl_disable_tcp_nodelay YAML

  # default setting
  cache1:
    redis_repl_disable_tcp_nodelay: 'no'
/Boxfile
Max Clients

Set the max number of clients connected at the same time. Once the limit is reached Redis will close all the new connections sending an error 'max number of clients reached'.

redis_max_clients YAML

  # default setting
  cache1:
    redis_max_clients: 1024
/Boxfile
MaxMemory Policy

Defines how Redis will select what to remove when maxmemory is reached. You can select among five behaviors:

  • volatile-lru - remove the key with an expire set using an LRU algorithm

  • allkeys-lru - remove any key accordingly to the LRU algorithm

  • volatile-random - remove a random key with an expire set

  • allkeys-random - remove a random key, any key

  • volatile-ttl - remove the key with the nearest expire time (minor TTL)

  • noeviction - don't expire at all, just return an error on write operations

redis_maxmemory_policy YAML

  # default setting
  cache1:
    redis_maxmemory_policy: 'volatile-lru'
/Boxfile
MaxMemory Samples

LRU and minimal TTL algorithms are not precise algorithms but approximated algorithms (in order to save memory), so you can select as well the sample size to check. For instance for default Redis will check three keys and pick the one that was used less recently, you can change the sample size using the following configuration directive.

redis_maxmemory_samples YAML

  # default setting
  cache1:
    redis_maxmemory_samples: 3
/Boxfile
AppendOnly

By default Redis asynchronously dumps the dataset on disk. This mode is good enough in many applications, but an issue with the Redis process or a power outage may result into a few minutes of writes lost (depending on the configured save points).

The Append Only File is an alternative persistence mode that provides much better durability. For instance, using the default data fsync policy, Redis can lose just one second of writes in a dramatic event like a server power outage, or a single write if something wrong with the Redis process itself happens, but the operating system is still running correctly.

AOF and RDB persistence can be enabled at the same time without problems. If the AOF is enabled on startup Redis will load the AOF, that is the file with the better durability guarantees. Please check Redis Persistence Documentation for more information.

redis_appendonly YAML

  # default setting
  cache1:
    redis_appendonly: 'no'
/Boxfile
AppendFSync

The fsync() call tells the Operating System to actually write data on disk instead to wait for more data in the output buffer. Redis supports three different modes:

  • no - don't fsync, just let the OS flush the data when it wants. Faster.

  • always - fsync after every write to the append only log . Slow, Safest.

  • everysec - fsync only one time every second. Compromise.

The default is "everysec", as that's usually the right compromise between speed and data safety. It's up to you to understand if you can relax this to "no" that will let the operating system flush the output buffer when it wants, for better performances (but if you can live with the idea of some data loss consider the default persistence mode that's snapshotting), or on the contrary, use "always" that's very slow but a bit safer than everysec.

More details in Redis Persistence Demistified.

If unsure, use "everysec".

redis_appendfsync YAML

  # default setting
  cache1:
    redis_appendfsync: 'everysec'
/Boxfile
No AppendFSync on Rewrite

When the AOF fsync policy is set to always or everysec, and a background saving process (a background save or AOF log background rewriting) is performing a lot of I/O against the disk, Redis may block too long on the fsync() call. Note that there is no fix for this currently, as even performing fsync in a different thread will block the synchronous write(2) call.

In order to mitigate this problem it's possible to use the following option that will prevent fsync() from being called in the main process while a BGSAVE or BGREWRITEAOF is in progress.

This means that while another child is saving, the durability of Redis is the same as redis_appendfsync: 'none'. In practical terms, this means that it is possible to lose up to 30 seconds of log in the worst scenario.

If you have latency problems turn this to "yes". Otherwise leave it as "no" that is the safest pick from the point of view of durability.

redis_no_appendfsync_on_rewrite YAML

  # default setting
  cache1:
    redis_no_appendfsync_on_rewrite: 'no'
/Boxfile
Auto AOF Rewrite Percentage

Redis is able to automatically rewrite the log file implicitly calling BGREWRITEAOF when the AOF log size grows by the specified percentage. Redis remembers the size of the AOF file after the latest rewrite. This base size is compared to the current size. If the current size is bigger than the specified percentage, the rewrite is triggered. Also you need to specify a minimal size for the AOF file to be rewritten, this is useful to avoid rewriting the AOF file even if the percentage increase is reached but it is still pretty small.

Specify a percentage of zero in order to disable the automatic AOF rewrite feature.

redis_auto_aof_rewrite_percentage YAML

  # default setting
  cache1:
    redis_auto_aof_rewrite_percentage: 100
/Boxfile
Auto AOF Rewrite Min Size

Specifies the minimal size for the AOF file to be rewritten.

redis_auto_aof_rewrite_min_size YAML

  # default setting
  cache1:
    redis_auto_aof_rewrite_min_size: '64m'
/Boxfile
Lua Time Limit

Set the Max execution time of a Lua script in milliseconds.

If the maximum execution time is reached Redis will log that a script is still in execution after the maximum allowed time and will start to reply to queries with an error.

When a long running script exceed the maximum execution time only the SCRIPT KILL and SHUTDOWN NOSAVE commands are available. The first can be used to stop a script that did not yet called write commands. The second is the only way to shut down the server in the case a write commands was already issue by the script but the user don't want to wait for the natural termination of the script.

Set it to 0 or a negative value for unlimited execution without warnings.

redis_lua_time_limit YAML

# default setting
cache1:
  redis_lua_time_limit: 5000
/Boxfile
SlowLog Log Slower Than

This tells Redis what is the execution time, in microseconds, to exceed in order for the command to get logged to the Redis Slow Log.

redis_slowlog_log_slower_than YAML

  # default setting
  cache1:
    redis_slowlog_log_slower_than:
/Boxfile
SlowLog Max Length

This parameter sets the length of the slow log. When a new command is logged the oldest one is removed from the queue of logged commands.

redis_slowlog_max_len YAML

  # default setting
  cache1:
    redis_slowlog_max_len: 128
/Boxfile

Advanced Redis Config

Hash Max Ziplist Entries

Sets the max number of hash entries before they are encrypted to save space.

redis_hash_max_ziplist_entries YAML

  # default setting
  cache1:
    redis_hash_max_ziplist_entries: 512
/Boxfile
Hash Max Ziplist Value

Sets the max value of hash entries before they are encrypted to save space.

redis_hash_max_ziplist_value YAML

  # default setting
  cache1:
    redis_hash_max_ziplist_value: 64
/Boxfile
List Max Ziplist Entries

Sets the max number of list entries before they are encrypted to save space.

redis_list_max_ziplist_entrie YAML

  # default setting
  cache1:
    redis_list_max_ziplist_entries: 512
/Boxfile
List Max Ziplist Value

Sets the max value of list entries before they are encrypted to save space.

redis_list_max_ziplist_value YAML

  # default settings
  cache1:
    redis_list_max_ziplist_value: 64
/Boxfile
Set Max IntSet Entries

Sets have a special encoding in just one case: when a set is composed of just strings that happens to be integers in radix 10 in the range of 64 bit signed integers. The following configuration setting sets the limit in the size of the set in order to use this special memory saving encoding.

redis_set_max_intset_entries YAML

  # default setting
  cache1:
    redis_set_max_intset_entries: 512
/Boxfile
ZSet Max Ziplist Entries

Sets the maximum number of entries before a sorted set is encoded to save space.

redis_zset_max_ziplist_entries YAML

  # default setting
  cache1:
    redis_zset_max_ziplist_entries: 12    
/Boxfile
ZSet Max Ziplist Values

Sets the maximum value of entries before a sorted set is encoded to save space.

redis_zset_max_ziplist_value YAML

  # default setting
  cache1:
    redis_zset_max_ziplist_value: 64
/Boxfile
ActiveRehashing

Active rehashing uses 1 millisecond every 100 milliseconds of CPU time in order to help rehashing the main Redis hash table (the one mapping top-level keys to values). The hash table implementation Redis uses (see dict.c) performs a lazy rehashing: the more operation you run into an hash table that is rehashing, the more rehashing "steps" are performed, so if the server is idle the rehashing is never complete and some more memory is used by the hash table.

The default is to use this millisecond 10 times every second in order to active rehashing the main dictionaries, freeing memory when possible.

If unsure: use redis_activerehashing: 'no' if you have hard latency requirements and it is not a good thing in your environment that Redis can reply form time to time to queries with 2 milliseconds delay.

Use redis_activerehashing: 'yes' if you don't have such hard requirements but want to free memory asap when possible.

redis_activerehashing YAML

  # default setting
  cache1:
    redis_activerehashing: 'yes'
/Boxfile
Redis "hz"

Redis calls an internal function to perform many background tasks, like closing connections of clients in timeot, purging expired keys that are never requested, and so forth. Not all tasks are perforemd with the same frequency, but Redis checks for tasks to perform accordingly to the specified "hz" value.

By default "hz" is set to 10. Raising the value will use more CPU when Redis is idle, but at the same time will make Redis more responsive when there are many keys expiring at the same time, and timeouts may be handled with more precision.

The range is between 1 and 500, however a value over 100 is usually not a good idea. Most users should use the default of 10 and raise this up to 100 only in environments where very low latency is required.

redis_hz YAML

  # default setting
  cache1:
    redis_hz: 10
/Boxfile
AOF Rewrite Incremental FSync

When a child rewrites the AOF file, if the following option is enabled the file will be fsync-ed every 32 MB of data generated. This is useful in order to commit the file to the disk more incrementally and avoid big latency spikes.

redis_aof_rewrite_incremental_fsync YAML

  # default setting
  cache1:
    redis_aof_rewrite_incremental_fsync: 'yes'
/Boxfile

Boxfile Modifications Only Take Affect After a New Build

Whenever changes are made to a Redis service's configuration in the Boxfile, those changes will not apply until the service is rebuilt. By default, Redis services are not rebuilt on deploy. However, there are three options for rebuilding your service:

Enable Rebuild on Deploy

In your app dashboard, under Dev Config > Code Deployment, you can enable the option to have data services rebuild on deploy whenever changes to the service's Boxfile config are detected.

Rebuilding data services on deploy will increase deploy times, but only when changes to the service's config are detected.

Scale

Any time you scale a Redis Service, a new instance or instances are provisioned, data is migrated, requests are routed to the new instance(s) and old instances decommissioned. The new instances are built using the modified settings in your Boxfile.

Repair

In your dashboard, click on your Redis service to expand it's options. Each data service has a "Repair" option.

"Repairing" your service will provision a new instance (or instances) based on the settings in your Boxfile, migrate data to the new instance, then reroute requests away from the old instance to the new.

New Builds Require Data Migrations

Data migrations are required during a rebuild. Your service will temporarily go offline during the migration process. More details in the Data Migrations During Scaling & Repairs doc.

If you have any questions, suggestions, or corrections, let us know.