scottk/vault
1
0
Fork 0
mirror of https://github.com/optim-enterprises-bv/vault.git synced 2025-11-01 02:57:59 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add set up vault service doc (#28272)

Browse Source 
* Add set up vault service doc
* Suggestions/edits (#28394)
---------

Co-authored-by: Sarah Chavis <62406755+schavis@users.noreply.github.com>
This commit is contained in:
Jonathan Frappier
2024-09-18 14:12:06 -04:00
committed by GitHub
parent 3df04b8aae
commit 66fa7606ac
7 changed files with 724 additions and 94 deletions
Download Patch File Download Diff File Expand all files Collapse all files

92
website/content/docs/install.mdx
View File

@@ -1,92 +0,0 @@
---
layout: docs
page_title: Install Vault
description: |-
Download a precompiled binary, compile from source, or use a package.
---
# Installing Vault
There are several options to install Vault:
1. Install from a [Package Manager](#package-manager).
1. Use a [precompiled binary](#precompiled-binaries).
1. Install [from source](#compiling-from-source).
1. [Helm for Kubernetes](/vault/docs/platform/k8s/helm)
@include 'versions.mdx'
## Package manager
HashiCorp manages packages for Ubuntu, Debian, Fedora, RHEL, Amazon
Linux, and other distributions. Follow the instructions at [HashiCorp
Tutorials][learn-vault-install] to add our PGP key, add a repository, and
install.
## Precompiled binaries
To install the precompiled binary, [download](/vault/downloads) the applicable
package for your system. Vault is packaged as a zip file.
Once the zip is downloaded, unzip the file into your designated directory. The `vault` binary
inside is all that is necessary to run Vault (or `vault.exe` for Windows). No
additional files are required to run Vault.
Copy the binary to your system. If you intend to access it from the
command-line, ensure that you place the binary somewhere on your `PATH`.
Refer to the [HashiCorp Tutorials][learn-vault-dev-server] to start a server, `put`
your first secret, and use other features of Vault.
## Compiling from source
To compile from source, you will need [Go](https://golang.org) installed and
properly configured (including a `GOPATH` environment variable set), as well as
a copy of [`git`](https://www.git-scm.com/) in your `PATH`.
Clone the Vault repository from GitHub into your `GOPATH`:
```shell-session
$ mkdir -p $GOPATH/src/github.com/hashicorp && cd $_
$ git clone https://github.com/hashicorp/vault.git
$ cd vault
```
Bootstrap the project. This will download and compile libraries and tools needed
to compile Vault:
```shell-session
$ make bootstrap
```
Build Vault for your current system and put the binary in `./bin/` (relative to
the git checkout). The `make dev` target is just a shortcut that builds `vault`
for only your local build environment (no cross-compiled targets).
```shell-session
$ make dev
```
## Verifying the installation
To verify Vault is installed, run `vault -h` on your system. You should
see the help output. If you are executing it from the command line, ensure it is
on your `PATH` to avoid receiving an error that Vault is not found.
```shell-session
$ vault -h
```
## Tutorial
Following tutorials provide some guidance on production cluster deployment:
- [Day One Preparation](/vault/tutorials/day-one-raft)
- [Recommended Patterns](/vault/tutorials/recommended-patterns)
[learn-vault-install]: /vault/tutorials/getting-started/getting-started-install
[learn-vault-dev-server]: /vault/tutorials/getting-started/getting-started-dev-server

95
website/content/docs/install/build-from-code.mdx Normal file
View File

@@ -0,0 +1,95 @@
---
layout: docs
page_title: Build Vault from code
description: >-
Build Vault locally from source code.
---
# Build Vault from code
Clone the official Vault repo and build a Vault binary from source code for your
system.
<Tip title="Assumptions">
- You have [Go](https://golang.org) installed and the `GOPATH` environment
variable configured.
- You have [`git`](https://www.git-scm.com/) installed.
</Tip>
<Tabs>
<Tab heading="Linux shell" group="nix">
1. Create a `hashicorp` source directory under your `GOPATH` and change to the
new directory:
```shell-session
$ mkdir -p ${GOPATH}/src/hashicorp && cd $_
```
1. Clone the Vault repository from GitHub:
```shell-session
$ git clone https://github.com/hashicorp/vault.git
```
1. Change to the cloned Vault directory:
```shell-session
$ cd vault
```
1. Bootstrap the Go project to download and compile the libraries and tools
needed to compile Vault:
```shell-session
$ make bootstrap
```
1. Use `make` to build Vault for your current system:
```shell-session
$ make dev
```
You can copy the compiled binary from `${GOPATH}/src/hashicorp/vault/bin/`.
</Tab>
<Tab heading="Powershell" group="ps">
1. Create a `hashicorp` source directory under your `GOPATH` and change to the
new directory:
```powershell
New-Item -ItemType Directory -Force -Path "${env:GOPATH}/src/hashicorp" | Set-Location
```
1. Clone the Vault repository from GitHub:
```powershell
git clone https://github.com/hashicorp/vault.git
```
1. Change to the cloned Vault directory:
```powershell
Set-Location vault
```
1. Use the included `make` tool to bootstrap the Go project to download and
compile the libraries and tools needed to compile Vault:
```powershell
.\make bootstrap
```
1. Use the included `make` tool to build Vault for your current system:
```powershell
.\make dev
```
You can copy the compiled binary from `${env:GOPATH}/src/hashicorp/vault/bin/`.
</Tab>
</Tabs>

35
website/content/docs/install/index.mdx Normal file
View File

@@ -0,0 +1,35 @@
---
layout: docs
page_title: Install Vault
description: |-
Download a precompiled binary, compile from source, or use a package manager.
---
# Install Vault
## Install options
<Tip title="Use Helm for Kubernetes">
If you plan to run Vault on Kubernetes, we recommend
[installing with Helm](/vault/docs/platform/k8s/helm).
</Tip>
1. [Install official Vault packages](/vault/install) with supported package
managers for macOS, Ubuntu/Debian, CentIS/RHEL, Amazon Linux, and Homebrew.
1. [Download a precompiled binary](/vault/install) or
[build Vault from code](/vault/docs/install/build-from-code) and
[install the binary manually](/vault/docs/install/install-binary).
@include 'versions.mdx'
## Related tutorials
The following tutorials provide additional guidance for installing Vault and
production cluster deployment:
- [Get started: Install Vault](/vault/tutorials/getting-started/getting-started-install)
- [Day One Preparation](/vault/tutorials/day-one-raft)
- [Recommended Patterns](/vault/tutorials/recommended-patterns)
- [Start the server in dev mode]: /vault/tutorials/getting-started/getting-started-dev-server

340
website/content/docs/install/install-binary.mdx Normal file
View File

@@ -0,0 +1,340 @@
---
layout: docs
page_title: Install Vault manually
description: >-
Manually install a Vault binary.
---
# Manually install a Vault binary
Install Vault using a compiled binary.
## Before you start
- **You must have a valid Vault binary**. You can
[download and unzip a precompiled binary](/vault/install) or
[build a local instance of Vault from source code](/vault/docs/install/build-from-code).
## Step 1: Configure the environment
<Tabs>
<Tab heading="Linux shell" group="nix">
1. Set the `VAULT_DATA` environment variable to your preferred Vault data
directory. For example, `/opt/vault/data`:
```shell-session
export VAULT_DATA=/opt/vault/data
```
1. Set the `VAULT_CONFIG` environment variable to your preferred Vault
configuration directory. For example, `/etc/vault.d`:
```shell-session
export VAULT_CONFIG=/etc/vault.d
```
1. Move the Vault binary to `/usr/bin`:
```shell-session
$ sudo mv PATH/TO/VAULT/BINARY /usr/bin/
```
1. Ensure the Vault binary can use `mlock()` to run as a non-root user:
```shell-session
$ sudo setcap cap_ipc_lock=+ep $(readlink -f $(which vault))
```
See the support article
[Vault and mlock()](https://support.hashicorp.com/hc/en-us/articles/115012787688-Vault-and-mlock)
for more information.
1. Create your Vault data directory:
```shell-session
$ sudo mkdir -p ${VAULT_DATA}
```
1. Create your Vault configuration directory:
```shell-session
$ sudo mkdir -p ${VAULT_CONFIG}
```
<Highlight title="Best practice">
We recommend storing Vault data and Vault logs on different volumes than the
operating system.
</Highlight>
</Tab>
<Tab heading="Powershell" group="ps">
1. Run Powershell as Administrator.
1. Set a `VAULT_HOME` environment variable to your preferred Vault home
directory. For example, `c:\Program Files\Vault`:
```powershell
$env:VAULT_HOME = "${env:ProgramFiles}\Vault"
```
1. Create the Vault home directory:
```powershell
New-Item -ItemType Directory -Path "${env:VAULT_HOME}"
```
1. Create the Vault data directory. For example, `c:\Program Files\Vault\Data`:
```powershell
New-Item -ItemType Directory -Path "${env:VAULT_HOME}/Data"
```
1. Create the Vault configuration directory. For example,
`c:\Program Files\Vault\Config`:
```powershell
New-Item -ItemType Directory -Path "${env:VAULT_HOME}/Config"
```
1. Create the Vault logs directory. For example, `c:\Program Files\Vault\Logs`:
```powershell
New-Item -ItemType Directory -Path "${env:VAULT_HOME}/Logs"
```
1. Move the Vault binary to your Vault directory:
```powershell
Move-Item `
-Path <PATH/TO/VAULT/BINARY> `
-Destination ${env:VAULT_HOME}\vault.exe
```
1. Add the Vault home directory to the system `Path` variable.
[![System PATH editor in Windows OS GUI](/img/install/windows-system-path.png)](/img/install/windows-system-path.png)
</Tab>
</Tabs>
## Step 2: Configure user permissions
<Tabs>
<Tab heading="Linux shell" group="nix">
1. Create a system user called `vault` to run Vault when your Vault data
directory as `home` and `nologin` as the shell:
```shell-session
$ sudo useradd --system --home ${VAULT_DATA} --shell /sbin/nologin vault
```
1. Change directory ownership of your data directory to the `vault` user:
```shell-session
$ sudo chown vault:vault ${VAULT_DATA}
```
1. Grant the `vault` user full permission on the data directory, search
permission for the group, and deny access to others:
```shell-session
$ sudo chmod -R 750 ${VAULT_DATA}
```
</Tab>
<Tab heading="Powershell" group="ps">
1. Create an access rule to grant the `Local System` user access to the Vault
directory and related files:
```powershell
$SystemAccessRule =
New-Object System.Security.AccessControl.FileSystemAccessRule(
"SYSTEM",
"FullControl",
"ContainerInherit,Objectinherit",
"none",
"Allow"
)
```
1. Create an access rule to grant yourself access to the Vault directory and
related files so you can test your Vault installation:
```powershell
$myUsername = Get-CimInstance -Class Win32_Computersystem | `
Select-Object UserName | foreach {$_.UserName} ; `
$AdminAccessRule =
New-Object System.Security.AccessControl.FileSystemAccessRule(
"$myUsername",
"FullControl",
"ContainerInherit,Objectinherit",
"none",
"Allow"
)
```
<Highlight title="Create additional access rules for human users if needed">
If you expect other accounts to start and run the Vault server, you must
create and apply access rules for those users as well. While users can run
the Vault CLI without explicit access, if they try to start the Vault
server, the process will fail with a permission denied error.
</Highlight>
1. Update permissions on the `env:VAULT_HOME` directory:
```powershell
$ACLObject = Get-ACL ${env:VAULT_HOME} ; `
$ACLObject.AddAccessRule($AdminAccessRule) ; `
$ACLObject.AddAccessRule($SystemAccessRule) ; `
Set-Acl ${env:VAULT_HOME} $ACLObject
```
</Tab>
</Tabs>
## Step 3: Create a basic configuration file
Create a basic Vault configuration file for testing and development.
<Warning title="Always enable TLS for production">
The sample configuration below disables TLS for simplicity and is not
appropriate for production use. Refer to the
[configuration documentation](/vault/docs/configuration) for a full list of
supported parameters.
</Warning>
<Tabs>
<Tab heading="Linux shell" group="nix">
1. Create a file called `vault.hcl` under your configuration directory:
```shell-session
$ sudo tee ${VAULT_CONFIG}/vault.hcl <<EOF
ui = true
cluster_addr = "http://127.0.0.1:8201"
api_addr = "https://127.0.0.1:8200"
disable_mlock = true
storage "raft" {
path = "${VAULT_DATA}"
node_id = "127.0.0.1"
}
listener "tcp" {
address = "0.0.0.0:8200"
cluster_address = "0.0.0.0:8201"
tls_disable = 1
}
EOF
```
1. Change ownership and permissions on the Vault configuration file.
```shell-session
$ sudo chown vault:vault "${VAULT_CONFIG}/vault.hcl" && \
sudo chmod 640 "${VAULT_CONFIG}/vault.hcl"
```
</Tab>
<Tab heading="Powershell" group="ps">
Create a file called `vault.hcl` under your configuration directory:
```powershell
@"
ui = true
cluster_addr = "http://127.0.0.1:8201"
api_addr = "https://127.0.0.1:8200"
disable_mlock = true
storage "raft" {
path = "$(${env:VAULT_HOME}.Replace('\','\\'))\\Data"
node_id = "127.0.0.1"
}
listener "tcp" {
address = "0.0.0.0:8200"
cluster_address = "0.0.0.0:8201"
tls_disable = 1
}
"@ | Out-File -FilePath ${env:VAULT_HOME}/Config/vault.hcl -Encoding ascii
```
<Note title="The double backslashes (\\) are not an error">
You **must** escape the Windows path character in your Vault configuration
file or the Vault server will fail with an error claiming the file contains
invalid characters.
</Note>
</Tab>
</Tabs>
## Step 4: Verify your installation
To confirm your Vault installation, use the help option with the Vault CLI to
confirm the CLI is accessible and bring up the server in development mode to
confirm you can run the binary.
<Tabs>
<Tab heading="Linux shell" group="nix">
1. Bring up the help menu in the Vault CLI:
```shell-session
$ vault -h
```
1. Use the Vault CLI to bring up a Vault server in development mode:
```shell-session
$ vault server -dev -config ${VAULT_CONFIG}/vault.hcl
```
</Tab>
<Tab heading="Powershell" group="ps">
1. Start a new Powershell session without Administrator permission.
1. Bring up the help menu in the Vault CLI:
```powershell
vault -h
```
1. Use the Vault CLI to bring up a Vault server in development mode:
```powershell
vault server -dev -config ${env:VAULT_HOME}\Config\vault.hcl
```
</Tab>
</Tabs>
## Related tutorials
The following tutorials provide additional guidance for installing Vault and
production cluster deployment:
- [Get started: Install Vault](/vault/tutorials/getting-started/getting-started-install)
- [Day One Preparation](/vault/tutorials/day-one-raft)
- [Recommended Patterns](/vault/tutorials/recommended-patterns)
- [Start the server in dev mode](/vault/tutorials/getting-started/getting-started-dev-server)

235
website/content/docs/run-as-service.mdx Normal file
View File

@@ -0,0 +1,235 @@
---
layout: docs
page_title: Run Vault as a service
description: >-
Configure and deploy Vault as a service for Linux or Windows.
---
# Run Vault as a service
Instead of starting your Vault server manually from the command line, you can
configure a service to start Vault automatically.
## Before you start
- **You must install Vault**. You can [use a package manager](/vault/install)
or [install a binary manually](/vault/docs/install/install-binary).
## Step 1: Create a new service
<Tabs>
<Tab heading="Linux shell" group="nix">
<Highlight title="Example tested on Ubuntu 22.04">
The following service definition is a simpler version of the `vault.service`
example in the Vault GitHub repo: [vault/.release/linux/package/usr/lib/systemd/system/vault.service](https://github.com/hashicorp/vault/blob/main/.release/linux/package/usr/lib/systemd/system/vault.service)
</Highlight>
1. Set the `VAULT_CONFIG` environment variable to your Vault configuration
directory. The default configuration directory is `/etc/vault.d`:
```shell-session
$ VAULT_CONFIG=/etc/vault.d
```
1. Confirm the path to your Vault binary:
```
$ VAULT_BINARY=$(which vault)
```
1. Create a `systemd` service called `vault.service` that uses the Vault
binary:
```shell-session
$ sudo tee /lib/systemd/system/vault.service <<EOF
[Unit]
Description="HashiCorp Vault"
Documentation="https://developer.hashicorp.com/vault/docs"
ConditionFileNotEmpty="${VAULT_CONFIG}/vault.hcl"
[Service]
User=vault
Group=vault
SecureBits=keep-caps
AmbientCapabilities=CAP_IPC_LOCK
CapabilityBoundingSet=CAP_SYSLOG CAP_IPC_LOCK
NoNewPrivileges=yes
ExecStart=${VAULT_BINARY} server -config=${VAULT_CONFIG}/vault.hcl
ExecReload=/bin/kill --signal HUP
KillMode=process
KillSignal=SIGINT
[Install]
WantedBy=multi-user.target
EOF
```
1. Change the permissions on `/lib/systemd/system/vault.service` to `644`:
```shell-session
$ sudo chmod 644 /lib/systemd/system/vault.service
```
</Tab>
<Tab heading="Powershell" group="ps">
The Windows binary for Vault does not support the Windows Service Application
API. To run Vault as a service, you must use a Windows service wrapper. You can
use whatever wrapper is appropriate for your environment, but the easiest we
have found is `nssm`.
1. Download and install [`nssm`](https://nssm.cc/) manually or install the
package with [Chocolatey](https://chocolatey.org/):
```powershell
choco install nssm
```
1. Set a `VAULT_HOME` environment variable to your preferred Vault home
directory. For example, `c:\Program Files\Vault`:
```powershell
$env:VAULT_HOME = "${env:ProgramFiles}\Vault"
```
1. Use `nssm` to create a new Windows service:
```powershell
nssm install MS_VAULT "${env:VAULT_HOME}\vault.exe"
```
1. Set the working directory for your Vault installation:
```powershell
nssm set MS_VAULT AppDirectory "${env:VAULT_HOME}" ; `
nssm set MS_VAULT AppParameters "server -config Config\vault.hcl"
```
1. Define the runtime parameters for Vault, including the
`-config` flag with the relative path to your Vault configuration file, for
example `Config\vault.hcl`:
```powershell
nssm set MS_VAULT AppDirectory "${env:VAULT_HOME}" ; `
nssm set MS_VAULT AppParameters "server -config Config\vault.hcl"
```
1. Set the display name and description for the "Services"
management console:
```powershell
nssm set MS_VAULT DisplayName "Vault Service" ; `
nssm set MS_VAULT Description "Vault server running as a service"
```
1. Set the startup type for your service. We recommend setting startup to
"Manual" until you confirm the service is working as expected:
```powershell
nssm set MS_VAULT Start SERVICE_DEMAND_START
```
1. Configure the service to pipe information from `stdout` and `stderr` to files
under your logging directory, for example `${env:VAULT_HOME}\Logs`:
```powershell
nssm set MS_VAULT AppStdout "${env:VAULT_HOME}\Logs\vault-stdout.log" ; `
nssm set MS_VAULT AppStderr "${env:VAULT_HOME}\Logs\vault-error.log"
```
1. Optionally, you can use the `AppEnvironmentExtra` parameter to set relevant
variables for the service environment. For example, to set the `VAULT_ADDR`
environment variable:
```powershell
nssm set MS_VAULT AppEnvironmentExtra `$env:VAULT_ADDR=https://localhost:8200
```
1. Confirm your Vault service settings with `nssm`:
```powershell
nssm dump MS_VAULT | Foreach {$_ -replace '.+nssm\.exe ',''}
```
</Tab>
</Tabs>
## Step 2: Start the new service
<Tabs>
<Tab heading="Linux shell" group="nix">
1. Reload the `systemd` configuration:
```shell-session
$ sudo systemctl daemon-reload
```
1. Start the Vault service:
```shell-session
$ sudo systemctl start vault.service
```
1. Verify the service status:
```shell-session
$ systemctl status vault.service
vault.service - "HashiCorp Vault"
Loaded: loaded (/lib/systemd/system/vault.service; disabled; vendor preset: enabled)
Active: active (running) since Thu 2024-09-05 13:58:45 UTC; 4s ago
Docs: https://developer.hashicorp.com/vault/docs
Main PID: 3145 (vault)
Tasks: 8 (limit: 2241)
Memory: 23.6M
CPU: 200ms
CGroup: /system.slice/vault.service
└─3145 /usr/bin/vault server -config=/etc/vault.d/vault.hcl
```
</Tab>
<Tab heading="Powershell" group="ps">
<Highlight title="Use Powershell commands or wrapper commands to manage your service">
Once you create the service, you can control it using standard `*-Service`
cmdlets **or** the relevant commands for the associated wrapper. For example,
to control the service with `nssm` use `nssm start MS_VAULT`.
</Highlight>
1. Start the Vault service::
```powershell
Start-Service -Name MS_VAULT
```
1. Confirm service status:
```powershell
Get-Service -Name MS_VAULT
Status Name DisplayName
------ ---- -----------
Running MS_VAULT Vault Service
```
</Tab>
</Tabs>
## Step 3: Verify the service is running
To confirm the service is running and your Vault service is available, open the
Vault GUI in a browser at the default address:
[http://localhost:8200](http://localhost:8200)
## Related tutorials
The following tutorials provide additional guidance for installing Vault and
production cluster deployment:
- [Day One Preparation](/vault/tutorials/day-one-raft)
- [Recommended Patterns](/vault/tutorials/recommended-patterns)

19
website/data/docs-nav-data.json
View File

@@ -34,9 +34,26 @@
}, },
{ {
"title": "Installing Vault", "title": "Install Vault",
"routes": [
{
"title": "Overview",
"path": "install" "path": "install"
}, },
{
"title": "Install manually",
"path": "install/install-binary"
},
{
"title": "Build from code",
"path": "install/build-from-code"
}
]
},
{
"title": "Run Vault as a service",
"path": "run-as-service"
},
{ {
"title": "Internals", "title": "Internals",
"routes": [ "routes": [

BIN
website/public/img/install/windows-system-path.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 73 KiB