Vault SIGHUP Behavior

Problem

SIGHUP is a POSIX-compliant signal sent to a process to inform it of a terminal close. SIGHUP is often used to trigger configuration reloads in services. SIGHUP can be used to initiate reloads with Vault, and this document details such behavior.

Introduction

When the Vault process receives a SIGHUP, Vault's configuration and certain other files from the host filesystem are reloaded, facilitating maintenance processes without any interruption to service.

• Starting with Vault 1.13, the Vault Agent process will also respond to SIGHUP.

Sending a SIGHUP to Vault

Using systemd

If Vault has been started as a systemd service using the default vault.service unit file (included in Linux installation packages), the command systemctl reload vault.service will send a SIGHUP to the Vault process.

Using kill

The command kill -SIGHUP $(pidof vault) can be used to send the signal to the Vault process, though it depends on the availability of the pidof command, which may not be present in all distributions.

As an alternative, you can look up the Vault process' PID with the command ps aux | grep vault; the number in the second column of the output indicates the PID, which can be substituted for $(pidof vault) in the command above.

Operations triggered by SIGHUP

• Vault Server: Audit log files' descriptors are released and reopened. Vault will continue writing to the same audit log file even if it was moved or renamed as part of log rotation; issuing a SIGHUP to the Vault process is necessary for the file to be released. Following the SIGHUP, Vault will reopen the file at the original path specified in the audit device configuration, creating a new file if one is not already present.
  
  
• Vault Server and Agent: TLS certificates used by Vault listeners are reloaded. When the certificate files on the host are changed, the certificates previously loaded by Vault will remain in use until a SIGHUP is received, or until the Vault process is restarted.
  • Note: the location of the TLS certificates cannot be changed while Vault is running; the certificates currently at the paths specified when Vault was started will be loaded even if the path specified in the Vault configuration file has changed.
    
    
• Vault Server and Agent: The log_level applied to Vault's operational logs is updated with the current value specified in the configuration file. This is useful for increasing the logging level to collect troubleshooting information without having to restart Vault.
  • Note: If the logging level was specified as an environmental variable or CLI argument when Vault was started, it will take precedence over the value in the Vault configuration file. This can sometimes be the source of unexpected logging changes where the desired level is set at startup.  Updating the environment variable will require restarting the vault process, as environment variables are only parsed when a process is created.
    
    
• Vault Server (Enterprise only): If using the license_path parameter in the Vault configuration file in order to auto-load the Vault Enterprise license the license file is checked and if newer than previously loaded, the new license is loaded. 

Additional Information

• Vault Documentation: Vault Agent
• Vault Documentation: Vault Server Config Log Level
• Vault Tutorial: Enable and Start Vault Service