From d1ec264eff1ec85aeec72e47331efa58bc9b74c4 Mon Sep 17 00:00:00 2001 From: Sheldon Hearn Date: Thu, 28 May 2015 12:40:56 +0200 Subject: [PATCH 1/2] Clarify the disable_mlock option --- website/source/docs/config/index.html.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/website/source/docs/config/index.html.md b/website/source/docs/config/index.html.md index 77c93c16c8..9e334eab56 100644 --- a/website/source/docs/config/index.html.md +++ b/website/source/docs/config/index.html.md @@ -39,7 +39,7 @@ to specify where the configuration is. * `disable_mlock` (optional) - A boolean. If true, this will disable the server from executing the `mlock` syscall to prevent memory from being - swapped to disk. This is not recommended. + swapped to disk. This is not recommended in production (see below). * `statsite_addr` (optional) - An address to a [Statsite](https://github.com/armon/statsite) instances for metrics. This is highly recommended for production usage. @@ -47,6 +47,16 @@ to specify where the configuration is. * `statsd_addr` (optional) - This is the same as `statsite_addr` but for StatsD. +In production, you should only consider setting the `disable_mlock` option +on Linux systems that only use encrypted swap or do not use swap at all. +Vault does not currently support memory locking on Mac OS X and Windows +and so the feature is automatically disabled on those platforms. To give +the Vault executable access to the `mlock` syscall on Linux systems: + +```shell +sudo setcap cap_ipc_lock=+ep $(readlink -f $(which vault)) +``` + ## Backend Reference For the `backend` section, the supported backends are shown below. From 233a862b608f6d3eaba5447adb3ef1bbdb523e7f Mon Sep 17 00:00:00 2001 From: Sheldon Hearn Date: Thu, 28 May 2015 13:24:28 +0200 Subject: [PATCH 2/2] Mention `disable_mlock` in deploy walkthrough --- .../intro/getting-started/deploy.html.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/website/source/intro/getting-started/deploy.html.md b/website/source/intro/getting-started/deploy.html.md index 3af3ff590e..1b9830825c 100644 --- a/website/source/intro/getting-started/deploy.html.md +++ b/website/source/intro/getting-started/deploy.html.md @@ -79,6 +79,24 @@ You'll notice that you can't execute any commands. We don't have any auth information! When you first setup a Vault server, you have to start by _initializing_ it. +On Linux, Vault may fail to start with the following error: + +```shell +$ vault server -config=example.hcl +Error initializing core: Failed to lock memory: cannot allocate memory + +This usually means that the mlock syscall is not available. +Vault uses mlock to prevent memory from being swapped to +disk. This requires root privileges as well as a machine +that supports mlock. Please enable mlock on your system or +disable Vault from using it. To disable Vault from using it, +set the `disable_mlock` configuration option in your configuration +file. +``` + +For guidance on dealing with this issue, see the discussion of +`disable_mlock` in [Server Configuration](/docs/config/index.html). + ## Initializing the Vault Initialization is the process of first configuring the Vault. This