diff --git a/website/content/docs/install.mdx b/website/content/docs/install.mdx deleted file mode 100644 index fea6ea4bc71f..000000000000 --- a/website/content/docs/install.mdx +++ /dev/null @@ -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 diff --git a/website/content/docs/install/build-from-code.mdx b/website/content/docs/install/build-from-code.mdx new file mode 100644 index 000000000000..4843539ecd3d --- /dev/null +++ b/website/content/docs/install/build-from-code.mdx @@ -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. + + + +- You have [Go](https://golang.org) installed and the `GOPATH` environment + variable configured. +- You have [`git`](https://www.git-scm.com/) installed. + + + + + + + +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/`. + + + + + +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/`. + + + + \ No newline at end of file diff --git a/website/content/docs/install/index.mdx b/website/content/docs/install/index.mdx new file mode 100644 index 000000000000..c6a538548170 --- /dev/null +++ b/website/content/docs/install/index.mdx @@ -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 + + + + If you plan to run Vault on Kubernetes, we recommend + [installing with Helm](/vault/docs/platform/k8s/helm). + + + +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 \ No newline at end of file diff --git a/website/content/docs/install/install-binary.mdx b/website/content/docs/install/install-binary.mdx new file mode 100644 index 000000000000..e3ab10820782 --- /dev/null +++ b/website/content/docs/install/install-binary.mdx @@ -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 + + + + + +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} + ``` + + + We recommend storing Vault data and Vault logs on different volumes than the + operating system. + + + + + + +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 ` + -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) + + + + + + +## Step 2: Configure user permissions + + + + + +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} + ``` + + + + + +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" + ) + ``` + + + + 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. + + + +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 + ``` + + + + + +## Step 3: Create a basic configuration file + +Create a basic Vault configuration file for testing and development. + + + + 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. + + + + + + + +1. Create a file called `vault.hcl` under your configuration directory: + ```shell-session + $ sudo tee ${VAULT_CONFIG}/vault.hcl < + + + +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 +``` + + + + 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. + + + + + + + +## 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. + + + + + +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 + ``` + + + + + +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 + ``` + + + + + + +## 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) \ No newline at end of file diff --git a/website/content/docs/run-as-service.mdx b/website/content/docs/run-as-service.mdx new file mode 100644 index 000000000000..e2f2d599135b --- /dev/null +++ b/website/content/docs/run-as-service.mdx @@ -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 + + + + + + + + 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) + + + +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 < + + + +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 ',''} + ``` + + + + + +## Step 2: Start the new service + + + + + +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 + ``` + + + + + + + + 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`. + + + +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 + ``` + + + + + +## 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) diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index d7a97dcd8ea6..1e2a16b6f0a5 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -34,8 +34,25 @@ }, { - "title": "Installing Vault", - "path": "install" + "title": "Install Vault", + "routes": [ + { + "title": "Overview", + "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", diff --git a/website/public/img/install/windows-system-path.png b/website/public/img/install/windows-system-path.png new file mode 100644 index 000000000000..18204689fa14 Binary files /dev/null and b/website/public/img/install/windows-system-path.png differ