Redis Settings in the Boxfile
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'
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:
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
Topology defines the service's architecture and in what ways it can scale. Redis supports the following topologies:
More information can be found in the Service Topologies doc.
# default setting cache1: type: redis topology: single
If non-zero, use SO_KEEPALIVE to send TCP ACKs to clients in absence of communication. This is useful for two reasons:
Detect dead peers.
Take the connection alive from the point of view of network equipment in the middle.
# default setting cache1: redis_tcp_keepalive: 60
Sets the number of databases.
# default setting cache1: redis_databases: 16
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.
# default setting cache1: redis_stop_writes_on_bgsave_error: 'yes'
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:
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.
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.
# default setting cache1: redis_slave_serve_stale_data: 'yes'
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.
# default setting cache1: redis_slave_read_only: 'yes'
Repl Ping Slave Period
Slaves send PINGs to server in a predefined interval. It's possible to change this interval.
# default setting cache1: redis_repl_ping_slave_period: 10
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.
# default setting cache1: redis_repl_timeout: 60
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.
# default setting cache1: redis_repl_disable_tcp_nodelay: 'no'
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'.
# default setting cache1: redis_max_clients: 1024
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
# default setting cache1: redis_maxmemory_policy: 'volatile-lru'
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.
# default setting cache1: redis_maxmemory_samples: 3
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.
# default setting cache1: redis_appendonly: 'no'
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".
# default setting cache1: redis_appendfsync: 'everysec'
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.
# default setting cache1: redis_no_appendfsync_on_rewrite: 'no'
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.
# default setting cache1: redis_auto_aof_rewrite_percentage: 100
Auto AOF Rewrite Min Size
Specifies the minimal size for the AOF file to be rewritten.
# default setting cache1: redis_auto_aof_rewrite_min_size: '64m'
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.
# default setting cache1: redis_lua_time_limit: 5000
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.
# default setting cache1: redis_slowlog_log_slower_than:
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.
# default setting cache1: redis_slowlog_max_len: 128
Advanced Redis Config
Hash Max Ziplist Entries
Sets the max number of hash entries before they are encrypted to save space.
# default setting cache1: redis_hash_max_ziplist_entries: 512
Hash Max Ziplist Value
Sets the max value of hash entries before they are encrypted to save space.
# default setting cache1: redis_hash_max_ziplist_value: 64
List Max Ziplist Entries
Sets the max number of list entries before they are encrypted to save space.
# default setting cache1: redis_list_max_ziplist_entries: 512
List Max Ziplist Value
Sets the max value of list entries before they are encrypted to save space.
# default settings cache1: redis_list_max_ziplist_value: 64
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.
# default setting cache1: redis_set_max_intset_entries: 512
ZSet Max Ziplist Entries
Sets the maximum number of entries before a sorted set is encoded to save space.
# default setting cache1: redis_zset_max_ziplist_entries: 12
ZSet Max Ziplist Values
Sets the maximum value of entries before a sorted set is encoded to save space.
# default setting cache1: redis_zset_max_ziplist_value: 64
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.
redis_activerehashing: 'yes' if you don't have such hard requirements but want to free memory asap when possible.
# default setting cache1: redis_activerehashing: 'yes'
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.
# default setting cache1: redis_hz: 10
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.
# default setting cache1: redis_aof_rewrite_incremental_fsync: 'yes'
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.
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.
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.
Table of Contents
- Redis Type & Version
- TCP Keepalive
- Stop Writes on BGSave Error
- Slave Serve Stale Data
- Slave Read-Only
- Repl Ping Slave Period
- Repl Timeout
- Repl Disable TCP NoDelay
- Max Clients
- MaxMemory Policy
- MaxMemory Samples
- No AppendFSync on Rewrite
- Auto AOF Rewrite Percentage
- Auto AOF Rewrite Min Size
- Lua Time Limit
- SlowLog Log Slower Than
- SlowLog Max Length
- Hash Max Ziplist Entries
- Hash Max Ziplist Value
- List Max Ziplist Entries
- List Max Ziplist Value
- Set Max IntSet Entries
- ZSet Max Ziplist Entries
- ZSet Max Ziplist Values
- Redis "hz"
- AOF Rewrite Incremental FSync
If you have any questions, suggestions, or corrections, let us know.