Memory residency on Linux

For most production FaunaDB installations, we recommend configuring each server to be single-purpose: the FaunaDB process should be the only one using any meaningful amount of CPU, network, memory, or storage resources, to maximize cluster performance and to simplify operations.

By default, FaunaDB attempts to take advantage of memory residency on Linux. If FaunaDB is unable to take advantage of memory residency, the following message appears in the core.log:

Unable to lock JVM memory (ENOMEM). This can result in part of the JVM
being swapped out, especially with mmapped I/O enabled. Increase
RLIMIT_MEMLOCK or run as root.

To correct this issue, the lockable operating system memory must be configured correctly and the cap_ipc_lock capability must be enabled. While FaunaDB can operate without this set, the performance and efficiency of the database can be limited.

To view the current limit of lockable memory, use the command ulimit -l.

We recommend that you set the lockable memory high enough to reliably lock the memory that FaunaDB’s JVM might consume. This is generally done by modifying the file /etc/security/limits.conf to add two new entries (or modify the existing):

soft memlock *
hard memlock *

After making that change, the capability to use memory residency needs to be enabled. While there are many ways to accomplish this, the easiest is to enable the capability on the JVM. As root, run the following command:

setcap cap_ipc_lock+pie `readlink -f \`which java\``

Once setcap has been used to make the JVM capable of performing privileged operations, the JVM library must be trusted. This is very easy to accomplish. Create a new file called /etc/ld.so.cache.d/java.conf. Inside this file, insert the path to the directory that libjli.so resides in. This is usually ${JAVA_HOME}/lib/*/jli. Then, remove the file /etc/ld.so.cache and re-run ldconfig as root.

When you have this complete, and you have restarted the FaunaDB server, you should see the message JNA mlockall successful in the core.log just after startup.

Was this article helpful?

We're sorry to hear that.
Tell us how we can improve! documentation@fauna.com

Thank you for your feedback!