From 0565e285928b98f9ab44a569e0ffba696fa2d40d Mon Sep 17 00:00:00 2001 From: Calvin Leung Huang Date: Fri, 5 Jun 2020 15:02:55 -0700 Subject: [PATCH] docs: document raft and mlock interaction (#9093) * docs: document raft and mlock interaction * docs: expand on mlock issue when raft is used * Update website/pages/docs/configuration/index.mdx Co-authored-by: Brian Kassouf Co-authored-by: Brian Kassouf --- website/pages/docs/configuration/index.mdx | 15 ++++++++++++++- website/pages/docs/configuration/storage/raft.mdx | 3 +++ 2 files changed, 17 insertions(+), 1 deletion(-) diff --git a/website/pages/docs/configuration/index.mdx b/website/pages/docs/configuration/index.mdx index 05b7a4cd9..299d3a1d4 100644 --- a/website/pages/docs/configuration/index.mdx +++ b/website/pages/docs/configuration/index.mdx @@ -81,6 +81,17 @@ to specify where the configuration is. process's entire memory address space from spilling to disk and is therefore automatically disabled on unsupported platforms. + Disabling `mlock` is strongly recommended if using [integrated + storage](/docs/internals/integrated-storage) due to + the fact that `mlock` does not interact well with memory mapped files such as + those created by BoltDB, which is used by Raft to track state. When using + `mlock`, memory-mapped files get loaded into resident memory which causes + Vault's entire dataset to be loaded in-memory and cause out-of-memory + issues if Vault's data becomes larger than the available RAM. In this case, + even though the data within BoltDB remains encrypted at rest, swap should be + disabled to prevent Vault's other in-memory sensitive data from being dumped + into disk. + On Linux, to give the Vault executable the ability to use the `mlock` syscall without running the process as root, run: @@ -88,7 +99,9 @@ to specify where the configuration is. sudo setcap cap_ipc_lock=+ep $(readlink -f $(which vault)) ``` - Note: Since each plugin runs as a separate process, you need to do the same for each plugin in your [plugins directory](/docs/internals/plugins#plugin-directory). + Note: Since each plugin runs as a separate process, you need to do the same + for each plugin in your [plugins + directory](/docs/internals/plugins#plugin-directory). If you use a Linux distribution with a modern version of systemd, you can add the following directive to the "[Service]" configuration section: diff --git a/website/pages/docs/configuration/storage/raft.mdx b/website/pages/docs/configuration/storage/raft.mdx index b16b130c6..f0e0450cd 100644 --- a/website/pages/docs/configuration/storage/raft.mdx +++ b/website/pages/docs/configuration/storage/raft.mdx @@ -42,6 +42,9 @@ backend cannot be declared. ~> **Note:** Raft cannot be used as the configured `ha_storage` backend at this time. To use Raft for HA coordination users must also use Raft for storage. +~> **Note:** When using the Raft storage backend, it is strongly recommended to +set `disable_mlock` to `true`, and to disable memory swapping on the system. + ## `raft` Parameters - `path` `(string: "")` – The file system path where all the Vault data gets