Vault will by default attempt to lock its virtual address space into RAM to disable swapping to disk. This requires both that the process be run with root privileges, and also requires a system that can support the mlock() capability.
If you attempt to start Vault as a non-root user and notice a message like the one shown in the following example:
$ 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.then you need to ensure that the vault binary is allowed to use the mlock() call before starting it as a non-root user.
While it is possible to specify capabilities in the Vault start up scipt such as systemd unit file for example:
[Unit]
Description=Vault service
Requires=network-online.target
After=network-online.target consul.service
[Service]
User=vault
Group=vault
Capabilities=CAP_IPC_LOCK+ep
CapabilityBoundingSet=CAP_SYSLOG CAP_IPC_LOCK
...this alone is not sufficient to allow the binary to actually call mlock(), and so you must also use setcap to allow mlock() by the vault binary with the following command in addition to any init system configuration you might also do:
$ sudo setcap cap_ipc_lock=+ep $(readlink -f $(which vault))Note that this must be done each time the Vault binary is replaced as it would be in an upgrade, for example.
It is common practice to include the setcap command as part of the Vault init script or systemd unit. To include it in the systemd unit, you’d add an
ExecStartPre line like this:
ExecStartPre=/sbin/setcap 'cap_ipc_lock=+ep' $(readlink -f $(which vault))Another option that works for modern systemd versions is to simply add this line to your [Service] block instead of the previously mentioned ExecStartPre and PermissionsStartOnly:
LimitMEMLOCK=infinityThis does not require adding the mlock() capability directly to the binary is great for when the setcap command is not available.
Disabling mlock
While it is never recommended for production usage unless using Integrated Storage, Vault does provide a means to disable its use of mlock() by setting the disable_mlock parameter value to true in your Vault server configuration.
Note that you should disable swapping at the OS level if you’re concerned about memory in a development or test instance being swapped to disk when operating Vault with disable_mlock = true. This also applies when running Vault using Integrated Storage. See Vault Performance Tuning for more information.