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
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
This does not require adding the
mlock() capability directly to the binary is great for when the
setcap command is not available.
While is is never recommended for production usage, Vault does provide a means to disable its use of
mlock() with the
disable_mlock parameter value to
true in your Vault server configuration to do so.
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 opeating Vault with
disable_mlock = true.