From 449b9ddedbdfb6f4a5035fee136c034c9f7e92bf Mon Sep 17 00:00:00 2001 From: Josh Black Date: Mon, 1 Feb 2021 10:03:42 -0800 Subject: [PATCH] Clarify docs around using the Vault Agent as a windows service (#10519) --- website/content/docs/agent/winsvc.mdx | 84 +++++++++++++++++++++------ 1 file changed, 67 insertions(+), 17 deletions(-) diff --git a/website/content/docs/agent/winsvc.mdx b/website/content/docs/agent/winsvc.mdx index 8430d756a..ec9a378ae 100644 --- a/website/content/docs/agent/winsvc.mdx +++ b/website/content/docs/agent/winsvc.mdx @@ -9,43 +9,85 @@ description: >- # Vault Agent Windows Service Vault Agent can be run as a Windows service. In order to do this, you need to register Vault Agent with the Windows -Service Control Manager using `sc.exe`. After Vault Agent is registered, it can be started like any other Windows +Service Control Manager. After Vault Agent is registered, it can be started like any other Windows service. **Note:** These commands should be run in a PowerShell session with Administrator capabilities. ## Register Vault Agent as a Windows service -Use the [`sc.exe`](https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/sc-create) program -to create a service called "Vault Agent". The `binPath` argument should include the fully qualified path to the Vault -executable, as well as any arguments required. +There are multiple ways to register Vault Agent as a Windows service. One way is to use +[`sc.exe`](https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/sc-create). `sc.exe` works +best if the path to your Vault binary and its associated agent config file do not contain spaces. `sc.exe` can be +pretty tricky to get working correctly if your path contains spaces, as paths containing spaces must be quoted, +and escaping quotes correctly in a way that makes `sc.exe` happy is non-trivial. If your path contains spaces, or you prefer not to use `sc.exe`, another +alternative is to use the +[`New-Service`](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.management/new-service?view=powershell-5.1) +cmdlet. `New-Service` is less picky about the method used to escape quotes, and can sometimes be easier. Examples of +both will be shown below. + +### Using sc.exe +If you use `sc.exe`, make sure you specify `sc.exe` explicitly, and not just `sc`. The command below shows the creation +of Vault Agent as a service, using "Vault Agent" as the display name, and starting automatically when Windows starts. +The `binPath` argument should include the fully qualified path to the Vault executable, as well as any arguments required. ```shell-session -PS C:\Windows\system32> sc.exe create "Vault Agent" binPath= "C:\vault\vault.exe agent -config=\"C:\vault\agent-config.hcl\"" +PS C:\Windows\system32> sc.exe create VaultAgent binPath= "C:\vault\vault.exe agent -config=C:\vault\agent-config.hcl" displayName= "Vault Agent" start= auto [SC] CreateService SUCCESS ``` -Note that the spacing after the `=` in `binPath=` is intentional. +Note that the spacing after the `=` in all of the arguments is intentional and required. If you receive a success message, your service is registered with the service manager. If you get an error, please verify the path to the binary and check the arguments, by running the contents of `binPath=` directly in a PowerShell session and observing the results. -## Start the Vault Agent service - -You have two ways to start the service. - -- Using the `sc.exe` command. -- Go to the Windows Service Manager, and look for **Vault Agent** in the service name column. Click the - `Start` button to start the service. - -### Example starting Vault Agent using sc.exe +### Using New-Service +The syntax is slightly different for `New-Service`, but the gist is the same. The invocation below is equivalent to the +`sc.exe` one above. ```shell-session -PS C:\Windows\system32> sc.exe start "Vault Agent" +PS C:\Windows\system32> New-Service -Name "VaultAgent" -BinaryPathName "C:\vault\vault.exe agent -config=C:\vault\agent-config.hcl" -DisplayName "Vault Agent" -StartupType "Automatic" -SERVICE_NAME: Vault Agent +Status Name DisplayName +------ ---- ----------- +Stopped VaultAgent Vault Agent +``` + +As mentioned previously, `New-Service` is easier to use if the path to your Vault executable and/or agent config contains spaces. +Below is an example of how to configure Vault Agent as a service using a path with spaces. + +```shell-session +PS C:\Windows\system32> New-Service -Name "VaultAgent" -BinaryPathName '"C:\my dir\vault.exe" agent -config="C:\my dir\agent-config.hcl"' -DisplayName "Vault Agent" -StartupType "Automatic" + +Status Name DisplayName +------ ---- ----------- +Stopped VaultAgent Vault Agent +``` + +Note that only the paths themselves are double quoted, and the entire `BinaryPathName` is wrapped in single quotes, in order +to escape the double quotes used for the paths. + +If anything goes wrong during this process, and you need to manually edit the path later, use the Registry Editor to find +the following key: `HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\VaultAgent`. You can edit the `ImagePath` value +at that key to the correct path. + +## Start the Vault Agent service + +There are multiple ways to start the service. + +- Using the `sc.exe` command. +- Using the `Start-Service` cmdlet. +- Go to the Windows Service Manager, and look for **VaultAgent** in the service name column. Click the + `Start` button to start the service. + +### Example starting Vault Agent using `sc.exe` + + ```shell-session +PS C:\Windows\system32> sc.exe start VaultAgent + +SERVICE_NAME: VaultAgent TYPE : 10 WIN32_OWN_PROCESS STATE : 4 RUNNING (STOPPABLE, NOT_PAUSABLE, ACCEPTS_SHUTDOWN) @@ -56,3 +98,11 @@ SERVICE_NAME: Vault Agent PID : 6548 FLAGS : ``` + +### Example starting Vault Agent using `Start-Service` + + ```shell-session +PS C:\Windows\system32> Start-Service -Name "VaultAgent" +``` + +Note that in the case where the service was started successfully, `New-Service` does not return any output.