Introduction
The Vault Agent can be run as a Windows service. In order to do this, you must first register the Vault Agent with the Windows Service Control Manager. After the Vault Agent is registered, it can be started like any other Windows service. For registration of the service, please refer to the documentation found here: https://www.vaultproject.io/docs/agent/winsvc.
Scenario
Once the service has been created there can still be issues with starting the service, such as:
- Error 2: The system cannot find the file specified
- Error 1053: The service did not respond to the start or control request in a timely fashion
- Error 1067: The process terminated unexpectedly
Troubleshooting
1. Verify the service configuration by using
sc.exe
. This can be done with the command sc.exe qc VaultAgent
. From the output, confirm items such as the binary path and the agent config path.C:\> sc.exe qc VaultAgent
[SC] QueryServiceConfig SUCCESS
SERVICE_NAME: VaultAgent
TYPE : 10 WIN32_OWN_PROCESS
START_TYPE : 2 AUTO_START
ERROR_CONTROL : 1 NORMAL
BINARY_PATH_NAME : C:\vaultAgent\vault_oss.exe agent -config=C:\vaultAgent\vault-agent.hcl
LOAD_ORDER_GROUP :
TAG : 0
DISPLAY_NAME : VaultAgent
DEPENDENCIES :
SERVICE_START_NAME : LocalSystem
2. Run the agent manually from the command prompt by running the same entry under
BINARY_PATH_NAME
. Below is an example for a successful start to the Vault agent. If command returns an error, this can provide further information why the Windows service itself could be failing. C:\> C:\vaultAgent\vault.exe agent -config=C:\vaultAgent\vault-agent.hcl
==> Vault agent started! Log data will stream in below:
==> Vault agent configuration:
Api Address 1: http://169.254.233.99:8100
Cgo: disabled
Log Level: info
Version: Vault v1.10.1
Version Sha: e452e9b30a9c2c8adfa1611c26eb472090adc767
2022-06-23T12:56:19.310-0700 [INFO] sink.file: creating file sink
2022-06-23T12:56:19.318-0700 [INFO] sink.file: file sink configured: path=C:/vaultAgent/agent-token mode=-rw-r-----
2022-06-23T12:56:19.325-0700 [INFO] template.server: starting template server
2022-06-23T12:56:19.326-0700 [INFO] template.server: no templates found
2022-06-23T12:56:19.325-0700 [INFO] auth.handler: starting auth handler
2022-06-23T12:56:19.327-0700 [INFO] auth.handler: authenticating
2022-06-23T12:56:19.325-0700 [INFO] sink.server: starting sink server
3. Inspecting the vault-agent.hcl
configuration file and verifying expected paths:
pid_file = "V:/vaultAgent/agent.pid"
vault {
address = "http://192.168.0.18:8200"
}
auto_auth {
method "approle" {
config = {
role_id_file_path = "V:/vaultAgent/agent-role-id"
secret_id_file_path = "V:/vaultAgent/agent-secret-id"
remove_secret_id_file_after_reading = false
}
}
sink "file" {
config = {
path = "V:/vaultAgent/agent-token"
}
}
}
cache {
use_auto_auth_token = true
}
listener "tcp" {
address = "10.10.10.115:8100"
tls_disable = true
}
Solutions
Error 2: The system cannot find the file specified.
: Verify the path used for the Vault binary along with the path to the Vault agent configuration file. Note: if placed on a different drive, this must be specified.
Error 1053: The service did not respond to the start or control request in a timely fashion.
: This error does not necessarily indicate that there is an issue with the service itself, but that the services snap-in has timed out. Troubleshooting at the server level could be helpful. Possible solutions could be to increase the timeout period for ServicePipeTimeout
. Also possible corrupt system settings, outdated Windows, or network configurations. Error 1067: The process terminated unexpectedly
: Verify all paths within the vault-agent.hcl
configuration file are as expected, including the full drive paths. Items can include paths for pid_file
, role_id_file_path
, secret_id_file_path
, and sink file path
.Related Links:
Vault Agent Overview: https://www.vaultproject.io/docs/agent
Vault Agent Windows Service: https://www.vaultproject.io/docs/agent/winsvc
Vault Agent Windows Service Learn Guide: https://learn.hashicorp.com/tutorials/vault/agent-windows-service