From a4b25bca07165c4c230856b74fefe00b56c797b7 Mon Sep 17 00:00:00 2001 From: Adam Overa Date: Thu, 17 Apr 2025 16:42:11 -0400 Subject: [PATCH 1/5] Deploying OpenBao on a Linode Compute Instance --- .../index.md | 331 ++++++++++++++++++ 1 file changed, 331 insertions(+) create mode 100644 docs/guides/security/secrets-management/deploying-openbao-on-a-linode-compute-instance/index.md diff --git a/docs/guides/security/secrets-management/deploying-openbao-on-a-linode-compute-instance/index.md b/docs/guides/security/secrets-management/deploying-openbao-on-a-linode-compute-instance/index.md new file mode 100644 index 00000000000..1d44df715b6 --- /dev/null +++ b/docs/guides/security/secrets-management/deploying-openbao-on-a-linode-compute-instance/index.md @@ -0,0 +1,331 @@ +--- +slug: deploying-openbao-on-a-linode-compute-instance +title: "Deploying Openbao on a Linode Compute Instance" +description: "Two to three sentences describing your guide." +og_description: "Optional two to three sentences describing your guide when shared on social media. If omitted, the `description` parameter is used within social links." +authors: ["Linode"] +contributors: ["Linode"] +published: 2025-04-17 +keywords: ['list','of','keywords','and key phrases'] +license: '[CC BY-ND 4.0](https://creativecommons.org/licenses/by-nd/4.0)' +external_resources: +- '[Link Title 1](http://www.example.com)' +- '[Link Title 2](http://www.example.net)' +--- + +# Deploying OpenBao on a Linode Compute Instance + +This guide walks through how to deploy OpenBao on a single Linode Compute Instance using the [Linode CLI](https://github.com/linode/linode-cli). + +## Prerequisites + +To follow along in this walkthrough, you’ll need the following: + +* A [Linode account](https://www.linode.com/cfe) +* A [Linode API token (personal access token)](https://www.linode.com/docs/products/platform/accounts/guides/manage-api-tokens/) +* The [Linode CLI](https://www.linode.com/docs/products/tools/cli/guides/install/) installed and configured +* An [SSH key pair](https://www.linode.com/content/ssh-key-authentication-how-to-create-ssh-key-pairs/) + +## Step 1: Initialize a Compute Instance + +This guide uses the Linode CLI to provision resources. The Linode Marketplace offers a one-click [OpenBao Marketplace app](https://www.linode.com/docs/marketplace-docs/guides/openbao/), whereas this tutorial walks through a manual installation. + +### Determine instance configuration + +In order to provision a Linode instance, you must specify the desired operating system, geographical region, and Linode plan size. The options available for each of these can be obtained using the Linode CLI. + +#### Operating system + +Run this command to obtain a formatted list of available operating systems: + +| $ linode-cli images list \--type=manual | +| :---- | + +This guide will use Ubuntu 22.04, which has the ID linode/ubuntu22.04. + +#### Geographical region + +| $ linode-cli regions list | +| :---- | + +This guide will use the us-sea region (Seattle, WA). + +#### Compute Instance size + +| $ linode-cli linodes types | +| :---- | + +The OpenBao documentation does not explicitly state hardware resource requirements for deploying OpenBao. However, as a fork of HashiCorp Vault, the [hardware size guide](https://developer.hashicorp.com/vault/tutorials/day-one-raft/raft-reference-architecture#hardware-sizing-for-vault-servers) for Vault can serve as a reference. For an initial, small cluster deployment of HashiCorp Vault (and thus, OpenBao), the documentation recommends: + +* 2-4 CPU cores +* 8-16 GB RAM +* 100+ GB disk capacity +* 75+ Mbps transfer rate + +This guide will use the g6-standard-4 Linode, which has 4 cores, 160 GB disk, and 8 GB RAM with a 5000 Mbps transfer rate. These capabilities are comparable to the hardware sizing recommendations. + +### Create the Compute Instance + +The following command creates a Linode Compute Instance based on the specified operating system, geographical region, and size as noted above. + +| $ linode-cli linodes create \\ \--image linode/ubuntu22.04 \\ \--region us-sea \\ \--type g6-standard-4 \\ \--root\_pass \ \\ \--authorized\_keys "$(cat \~/.ssh/id\_rsa.pub)" \\ \--label openbao-linode | +| :---- | + +Note the following key points: + +* Replace **``** with a secure alternative. +* This command assumes that an SSH public/private key pair exists, with the public key stored as id\_rsa.pub in the user’s $HOME/.ssh/ folder. +* The \--label argument specifies the name of the new server (openbao-linode). + +Within a few minutes of executing this command, the instance will be visible with status running in the Linode Cloud Manager or via the following CLI command: + +| $ linode-cli linodes list \--label openbao-linode ┌-----------------┬--------┬---------------┬---------┬-----------------┐ │ label │ region │ type │ status │ ipv4 │ ├-----------------┼--------┼---------------┼---------┼-----------------┤ │ openbao-linode │ us-sea │ g6-standard-1 │ running │ 172.233.157.190 │ └-----------------┴--------┴---------------┴---------┴-----------------┘ | +| :---- | + +Depending on notification settings, emails detailing the progress of the provisioning process may also be sent to the Linode user’s address. + +## Step 2: Install OpenBao on the Linode Compute Instance + +To install OpenBao, you will need to SSH into the newly provisioned Linode. The IP address of the new instance can be found in the Linode Cloud Manager dashboard or via the following command: + +| $ linode-cli linodes list | +| :---- | + +Once the IP address is found, run the following command: + +| $ ssh \-l root \ | +| :---- | + +| Note that this method of connecting uses the root user, which is initially the only accessible user on the system. For production systems, it is strongly recommended that you disable the ability to access the instance as the root user, instead creating a limited user account with sudo privileges for access. See [this guide](https://techdocs.akamai.com/cloud-computing/docs/set-up-and-secure-a-compute-instance#add-a-limited-user-account) for more details. This guide will assume that all remaining commands are run with sudo as a newly created user on the Linode instance. | +| :---- | + +### Update system packages + +Ensure that the new system is up to date with the latest Ubuntu packages. The Ubuntu package manager (apt) needs to be updated to pull the latest package manifests, followed by upgrading any that are outdated. + +| $ apt update && apt upgrade \-y | +| :---- | + +### Download and install the OpenBao package + +Find the desired version of OpenBao from the [downloads page](https://openbao.org/downloads/). In this case, the AMD 64-bit debian package works with the Linode Compute Instance that has been provisioned. + +| $ wget https://github.com/openbao/openbao/releases/download/v2.0.3/bao\_2.0.3\_linux\_amd64.deb | +| :---- | + +Install the package. + +| $ dpkg \-i bao\_2.0.3\_linux\_amd64.deb Selecting previously unselected package bao. (Reading database ... 219929 files and directories currently installed.) Preparing to unpack bao\_2.0.3\_linux\_amd64.deb ... Unpacking bao (2.0.3) ... Setting up bao (2.0.3) ... Generating OpenBao TLS key and self-signed certificate... ... OpenBao TLS key and self-signed certificate have been generated in '/opt/openbao/tls'. | +| :---- | + +Verify the install was successful. + +| $ bao \-h | +| :---- | + +### Verify swap memory limits + +For Linux distributions, ensure that the OpenBao service settings do not impose a soft limit on Swap memory. To check this with a systemd-based Linux distro, use the following command: + +| $ systemctl cat openbao \# /usr/lib/systemd/system/openbao.service \[Unit\] Description="OpenBao \- A tool for managing secrets" … \[Service\] … TimeoutStopSec=30 LimitNOFILE=65536 MemorySwapMax=0 \[Install\] WantedBy=multi-user.target | +| :---- | + +Verify that MemorySwapMax=0 appears in the results under the Service heading. + +## Step 3: Test the OpenBao Development Server + +OpenBao provides a development server that runs completely in memory. Use this to verify settings and explore OpenBao features. + +### Start the development server + +To start the server in development mode and set a primary key run this command: + +| $ bao server \-dev \\ \-dev-root-token-id="this-is-my-test-dev-token" | +| :---- | + +The OpenBao server configuration will print to the screen along with a tail of the logs. + +| \==\> OpenBao server configuration: Administrative Namespace: Api Address: http://127.0.0.1:8200 Cgo: disabled Cluster Address: https://127.0.0.1:8201 Environment Variables: HOME, LANG, LESSCLOSE, LESSOPEN, LOGNAME, LS\_COLORS, MAIL, PATH, PWD, SHELL, SHLVL, SUDO\_COMMAND, SUDO\_GID, SUDO\_UID, SUDO\_USER, TERM, USER, \_ Go Version: go1.22.9 Listener 1: tcp (addr: "127.0.0.1:8200", cluster address: "127.0.0.1:8201", max\_request\_duration: "1m30s", max\_request\_size: "33554432", tls: "disabled") Log Level: Recovery Mode: false Storage: inmem Version: OpenBao v2.0.3, built 2024-11-15T16:54:47Z Version Sha: a2522eb71d1854f83c7e2e02fdbfc01ae74c3a78 \==\> OpenBao server started\! Log data will stream in below: ... 2024-11-25T10:07:57.493-0700 \[INFO\] core: vault is unsealed 2024-11-25T10:07:57.495-0700 \[INFO\] expiration: revoked lease: lease\_id=auth/token/root/hf0285ed983c6c93bd02f9422f179d20f12508b046d39228a7b2e13c245293de6 2024-11-25T10:07:57.498-0700 \[INFO\] core: successful mount: namespace="" path=secret/ type=kv version="" 2024-11-25T10:07:57.499-0700 \[INFO\] secrets.kv.kv\_cd63d9f9: collecting keys to upgrade 2024-11-25T10:07:57.499-0700 \[INFO\] secrets.kv.kv\_cd63d9f9: done collecting keys: num\_keys=1 2024-11-25T10:07:57.499-0700 \[INFO\] secrets.kv.kv\_cd63d9f9: upgrading keys finished … | +| :---- | + +Leave this server process running in the background. In a separate terminal window, connect to the Linode instance with another shell session. + +### Setting and getting a test secret + +Use curl requests to test setting and getting a test secret. OpenBao expects certain variables to be set for every request. Instead of setting these variables repeatedly with each command, set the following environment variables in the shell: + +| $ export VAULT\_TOKEN="this-is-my-test-dev-token" $ export OPENBAO\_IP="127.0.0.1" $ export OPENBAO\_PORT="8200" | +| :---- | + +Send a request with curl to set a secret as a key-value pair. + +| $ curl \-X POST \\ \--header "X-Vault-Token: $VAULT\_TOKEN" \\ \--header "Content-Type: application/json" \\ \--data '{"data": {"password": "OpenBao123"}}' \\ http://$OPENBAO\_IP:$OPENBAO\_PORT/v1/secret/data/test-password-1 \\ | json\_pp { "auth" : null, "data" : { "created\_time" : "2024-11-25T17:25:05.234896488Z", "custom\_metadata" : null, "deletion\_time" : "", "destroyed" : false, "version" : 1 }, "lease\_duration" : 0, "lease\_id" : "", "renewable" : false, "request\_id" : "0ad32a55-51cd-086c-0eba-5b1f6349bb3b", "warnings" : null, "wrap\_info" : null } | +| :---- | + +The development server is only exposed on localhost. Therefore, this command must be run on the server itself. Authentication is handled by supplying the X-Vault-Token header. The structure of the URI follows the pattern /v1/secret/data/\. This POST request stores the key-value pair at location /data/\. + +The response provides metadata regarding the secret stored in the data object, including versioning (how many times this secret has been updated). + +To retrieve the secret, send the following request: + +| $ curl \\ \--header "X-Vault-Token: $VAULT\_TOKEN" \\ http://$OPENBAO\_IP:$OPENBAO\_PORT/v1/secret/data/test-password-1 \\ | json\_pp { "auth" : null, "data" : { "data" : { "password" : "OpenBao123" }, "metadata" : { "created\_time" : "2024-11-25T17:25:05.234896488Z", "custom\_metadata" : null, "deletion\_time" : "", "destroyed" : false, "version" : 1 } }, "lease\_duration" : 0, "lease\_id" : "", "renewable" : false, "request\_id" : "0471a6c0-b9ad-d6d4-1e81-c0ade5d057ce", "warnings" : null, "wrap\_info" : null } | +| :---- | + +The original secret is found within the data object as a key-value pair. + +## Step 4: Run OpenBao as a Service + +In a real-world use case, it would be expected that OpenBao runs as a service, managed by a tool such as systemd. Run the following command: + +| $ systemctl status openbao ○ openbao.service \- "OpenBao \- A tool for managing secrets" Loaded: loaded (/usr/lib/systemd/system/openbao.service; disabled; preset: enabled) Active: inactive (dead) Docs: https://github.com/openbao/openbao/tree/main/website/content/docs | +| :---- | + +This shows that systemd is aware of the OpenBao service but it has not been started. + +The default location of the OpenBao configuration file on the Linode Compute Instance is /etc/openbao/openbao.hcl. Edit this file and set it up for a publicly available service with the following contents: + +| ui \= false storage "file" { path \= "/opt/openbao/data" } api\_addr \= "http://0.0.0.0:8200" listener "tcp" { address \= "0.0.0.0:8200" tls\_disable \= 1 } | +| :---- | + +**Note:** The configuration above is insecure and not suitable for production use. It is only for demonstration purposes of this tutorial. For a production-grade deployment, reference the [configuration](#configuration) near the end of this guide. + +Start the service, then check its status. + +| $ systemctl start openbao $ systemctl status openbao ● openbao.service \- "OpenBao \- A tool for managing secrets" Loaded: loaded (/usr/lib/systemd/system/openbao.service; disabled; preset: enabled) Active: active (running) since Mon 2024-11-25 10:38:04 MST; 7s ago Docs: https://github.com/openbao/openbao/tree/main/website/content/docs Main PID: 642487 (bao) Tasks: 6 (limit: 1124\) Memory: 12.2M (swap max: 0B peak: 12.5M) CPU: 66ms CGroup: /system.slice/openbao.service └─642487 /usr/bin/bao server \-config=/etc/openbao/openbao.hcl | +| :---- | + +To start the service automatically whenever the Linode server boots, run the following command: + +| $ systemctl enable openbao | +| :---- | + +## Step 5: Configure OpenBao for External Access + +Although OpenBao is now running as a service on the Linode Compute Instance, it is still not ready for use. Use the [OpenBao CLI](https://openbao.org/docs/commands/) to interact with the running server, retrieving its current status: + +| $ bao status \--address=http://0.0.0.0:8200 Key Value \--- \----- Seal Type shamir Initialized false Sealed true Total Shares 0 Threshold 0 Unseal Progress 0/0 Unseal Nonce n/a Version 2.0.3 Build Date 2024-11-15T16:54:47Z Storage Type file HA Enabled false | +| :---- | + +The status shows that the server has not been initialized, and it is sealed. Both of these issues must be resolved before the server can be interacted with. + +### Initialize the server + +Set the BAO\_ADDR environment variable, which will be used in several subsequent commands. + +| $ export BAO\_ADDR=http://0.0.0.0:8200 | +| :---- | + +Run the following command to initialize the server. + +| $ bao operator init Unseal Key 1: lmeBuSpXWfmpGocWBrpD08nK7OOws691bygB2ipS2KUE Unseal Key 2: CXi4hCiD4H922RtyTAU8sR77svDfsCkyXaVuZYY2VkFa Unseal Key 3: oCKeZ0JxPS6G8+losHgKWDPV5Qc01XU4e4g2//sp3lje Unseal Key 4: cD1yVzWt0dh71BI7vtiIImoj5e12OhEWw7lmAGsnZjb/ Unseal Key 5: uSNLC9hISYKz0fbyNF3sX7gjF/HZ5U7mR6EfGYKdHbuF Initial Root Token: s.eZTodpa8pErpfQGDyPPUqVME Vault initialized with 5 key shares and a key threshold of 3\. Please securely distribute the key shares printed above. When the Vault is re-sealed, restarted, or stopped, you must supply at least 3 of these keys to unseal it before it can start servicing requests. Vault does not store the generated root key. Without at least 3 keys to reconstruct the root key, Vault will remain permanently sealed\! It is possible to generate new unseal keys, provided you have a quorum of existing unseal keys shares. See "vault operator rekey" for more information. | +| :---- | + +Store the unseal keys and initial root token in a secure location. + +### Unseal the vault (three times for quorum) + +Unseal the vault using one of the unseal keys provided. + +| $ bao operator unseal Unseal Key (will be hidden): lmeBuSpXWfmpGocWBrpD08nK7OOws691bygB2ipS2KUE Key Value \--- \----- Seal Type shamir Initialized true Sealed true Total Shares 5 Threshold 3 Unseal Progress 1/3 Unseal Nonce f0724cb7-324e-ef04-34fb-3fb6f0f0806e Version 2.0.3 Build Date 2024-11-15T16:54:47Z Storage Type file HA Enabled false | +| :---- | + +After this first execution, the unseal progress shows 1/3. Unsealing must be done a total of three times, as this is the default quorum for OpenBao unsealing. + +| $ bao operator unseal Unseal Key (will be hidden): CXi4hCiD4H922RtyTAU8sR77svDfsCkyXaVuZYY2VkFa $ bao operator unseal Unseal Key (will be hidden): oCKeZ0JxPS6G8+losHgKWDPV5Qc01XU4e4g2//sp3lje | +| :---- | + +After unsealing has been executed three times (with three different unseal keys), the OpenBao status will show the following: + +| Key Value \--- \----- Seal Type shamir Initialized true Sealed false Total Shares 5 Threshold 3 Version 2.0.3 Build Date 2024-11-15T16:54:47Z Storage Type file Cluster Name vault-cluster-5e4b590f Cluster ID d7b79512-d2d0-13d1-92a3-e636384c10af HA Enabled false | +| :---- | + +Now, the vault has been initialized and unsealed. + +### Authenticate the CLI + +To authenticate the CLI with the server, use the bao login command with the root token provided upon vault initialization. + +| $ bao login \-method=token s.eZTodpa8pErpfQGDyPPUqVME Success\! You are now authenticated. The token information displayed below is already stored in the token helper. You do NOT need to run "bao login" again. Future OpenBao requests will automatically use this token. Key Value \--- \----- token s.eZTodpa8pErpfQGDyPPUqVME token\_accessor otHrg1OUERHfyEGgy2DOXbEB token\_duration ∞ token\_renewable false token\_policies \["root"\] identity\_policies \[\] policies \["root"\] | +| :---- | + +### Enable key-value storage + +Lastly, to enable a key-value store in OpenBao for stashing and retrieving secrets via the API. To do this, run the following command: + +| $ bao secrets enable kv Success\! Enabled the kv secrets engine at: kv/ | +| :---- | + +### Setting and getting a secret remotely over HTTP + +OpenBao can now be accessed externally via the API. Ensure that any firewall on the Linode Compute Instance allows traffic on port 8200. From a remote machine, set a new secret, providing the root token for authentication. + +| $ curl \-X POST \\ \--header "X-Vault-Token: s.eZTodpa8pErpfQGDyPPUqVME" \\ \--header "Content-Type: application/json" \\ \--data '{"data": {"hello": "world"}}' \\ http://\:8200/v1/kv/test-secret | +| :---- | + +Get the newly created secret to verify it was stored properly. + +| $ curl \-X GET \\ \--header "X-Vault-Token: s.eZTodpa8pErpfQGDyPPUqVME" \\ http://\:8200/v1/kv/test-secret { "auth" : null, "data" : { "hello" : "world" }, "lease\_duration" : 2764800, "lease\_id" : "", "renewable" : false, "request\_id" : "3bbd69a5-b77a-62b0-686d-a8a3103d6d6b", "warnings" : null, "wrap\_info" : null } | +| :---- | + +## Considerations for Production Deployments + +To harden an OpenBao server for production use, several additional steps are recommended. + +### Auto Unseal + +OpenBao starts with its vault in a sealed state, meaning all data is encrypted. For more information on the seal/unseal concept in OpenBao, see their [documentation](https://openbao.org/docs/concepts/seal/). + +In production, [auto-unseal](https://openbao.org/docs/concepts/seal/#auto-unseal) is recommended to minimize manual operations that could lead to mistakes or exposure. Auto-unseal is configured using cloud-based key management systems to ensure the unsealing key is never exposed directly. + +### Authentication + +Enable and configure secure authentication methods such as: + +* AppRole +* JSON Web Tokens (JWT) +* TLS certificates +* LDAP +* OpenID Connect (OIDC) + +TLS certificate authentication provides secure, mutual TLS verification for sensitive environments, while AppRole allows service accounts and applications to securely authenticate without human interaction. + +For LDAP or OIDC deployments, enforce Multi Factor Authentication (MFA) for human operators to enhance security if supported. + +### Configuration {#configuration} + +OpenBao supports two configuration formats: + +1. HashiCorp Configuration Language (HCL) +2. JSON + +Properly configuring the OpenBao server is essential to ensure a secure production environment. The main configuration aspects include the UI, TLS certificate, and address/port settings. + +A default production configuration HCL file may look like this: + +| ui \= false storage "file" { path \= "/opt/openbao/data" } api\_addr \= "https://0.0.0.0:8200" listener "tcp" { address \= "0.0.0.0:8200" tls\_cert\_file \= "/opt/openbao/tls/tls.crt" tls\_key\_file \= "/opt/openbao/tls/tls.key" } | +| :---- | + +In production, disabling or securing the UI is crucial, as it exposes OpenBao's management interface—which could be exploited if left unprotected. If the UI is required, limit its exposure by restricting access to trusted IP ranges or VPN users only. Implement strong authentication methods like OIDC for access control. + +If the UI is not required, set ui \= false. + +TLS certificates encrypt traffic to and from the OpenBao server, ensuring data confidentiality and integrity. Using a valid, trusted TLS certificate prevents man-in-the-middle attacks and validates the server's identity to clients. Obtain a certificate from a trusted Certificate Authority (CA) and configure OpenBao to use it as shown in the example configuration above. + +For environments using an internal CA, ensure that all clients trust the CA, and renew the certificates periodically to avoid downtime. + +Controlling the address and ports on which OpenBao listens reduces exposure and minimizes the risk of unauthorized access. Limit OpenBao's exposure by binding it to an internal IP address (such as 127.0.0.1 or a specific internal network IP). Ensure that OpenBao only listens on the necessary port (default is 8200). Use firewall rules to restrict access to this port to authorized networks or users only. + +These hardening measures reduce the attack surface of the OpenBao server, enhance security controls, and ensure that only authorized entities have access. + +--- + +The resources below are provided to help you become familiar with OpenBao when deployed to Linode. + +## OpenBao Resources + +* [Package downloads](https://openbao.org/downloads/) +* [Installation instructions](https://openbao.org/docs/install/) +* [CLI documentation](https://openbao.org/docs/commands/) +* [Plugins](https://openbao.org/docs/plugins/) +* [Authentication](https://openbao.org/docs/auth/) +* [OpenBao Linode Marketplace App](https://www.linode.com/docs/marketplace-docs/guides/openbao/) \ No newline at end of file From 4e6672979ed6b7b8d7874b141c73b271bc901b07 Mon Sep 17 00:00:00 2001 From: Adam Overa Date: Fri, 18 Apr 2025 14:41:34 -0400 Subject: [PATCH 2/5] Edit 1 --- .../index.md | 728 +++++++++++++----- 1 file changed, 545 insertions(+), 183 deletions(-) diff --git a/docs/guides/security/secrets-management/deploying-openbao-on-a-linode-compute-instance/index.md b/docs/guides/security/secrets-management/deploying-openbao-on-a-linode-compute-instance/index.md index 1d44df715b6..030ffbbdc12 100644 --- a/docs/guides/security/secrets-management/deploying-openbao-on-a-linode-compute-instance/index.md +++ b/docs/guides/security/secrets-management/deploying-openbao-on-a-linode-compute-instance/index.md @@ -1,271 +1,634 @@ --- slug: deploying-openbao-on-a-linode-compute-instance -title: "Deploying Openbao on a Linode Compute Instance" -description: "Two to three sentences describing your guide." -og_description: "Optional two to three sentences describing your guide when shared on social media. If omitted, the `description` parameter is used within social links." -authors: ["Linode"] -contributors: ["Linode"] +title: "Deploying OpenBao on a Linode Compute Instance" +description: "Deploy OpenBao on a Linode Compute Instance using Ubuntu 24.04 LTS and the Linode CLI. Learn how to install, configure, unseal, and securely manage secrets." +authors: ["Akamai"] +contributors: ["Akamai"] published: 2025-04-17 -keywords: ['list','of','keywords','and key phrases'] +keywords: ['openbao','openbao linode','openbao ubuntu install','secrets management linode','how to install openbao','secure secrets storage linux','openbao ubuntu 24.04','deploy openbao cli','install vault alternative','hashicorp vault fork','openbao setup tutorial','linux secrets manager','initialize openbao server','openbao unseal process','openbao vs vault','openbao config hcl','how to deploy openbao on a linode instance','secure secrets management with openbao','install and configure openbao on ubuntu','openbao systemd service setup','openbao cli secret storage example','openbao firewall and api access configuration','openbao key value store example','setting up openbao secrets engine'] license: '[CC BY-ND 4.0](https://creativecommons.org/licenses/by-nd/4.0)' -external_resources: -- '[Link Title 1](http://www.example.com)' -- '[Link Title 2](http://www.example.net)' --- -# Deploying OpenBao on a Linode Compute Instance - This guide walks through how to deploy OpenBao on a single Linode Compute Instance using the [Linode CLI](https://github.com/linode/linode-cli). ## Prerequisites To follow along in this walkthrough, you’ll need the following: -* A [Linode account](https://www.linode.com/cfe) -* A [Linode API token (personal access token)](https://www.linode.com/docs/products/platform/accounts/guides/manage-api-tokens/) -* The [Linode CLI](https://www.linode.com/docs/products/tools/cli/guides/install/) installed and configured -* An [SSH key pair](https://www.linode.com/content/ssh-key-authentication-how-to-create-ssh-key-pairs/) +- A [Linode account](https://www.linode.com/cfe) +- A [Linode API token (personal access token)](/docs/products/platform/accounts/guides/manage-api-tokens/) +- The [Linode CLI](/docs/products/tools/cli/guides/install/) installed and configured +- An [SSH key pair](https://www.linode.com/content/ssh-key-authentication-how-to-create-ssh-key-pairs/) + +## Before You Begin + +1. If you do not already have a virtual machine to use, create a Compute Instance with at least 4 GB of memory. See our [Getting Started with Linode](/docs/products/platform/get-started/) and [Creating a Compute Instance](/docs/products/compute/compute-instances/guides/create/) guides. + +1. Follow our [Setting Up and Securing a Compute Instance](/docs/products/compute/compute-instances/guides/set-up-and-secure/) guide to update your system. You may also wish to set the timezone, configure your hostname, create a limited user account, and harden SSH access. + +{{< note >}} +The steps in this guide require root privileges. Be sure to run the steps below as `root` or with the `sudo` prefix. For more information on privileges, see our [Users and Groups](/docs/guides/linux-users-and-groups/) guide. +{{< /note >}} ## Step 1: Initialize a Compute Instance -This guide uses the Linode CLI to provision resources. The Linode Marketplace offers a one-click [OpenBao Marketplace app](https://www.linode.com/docs/marketplace-docs/guides/openbao/), whereas this tutorial walks through a manual installation. +This guide uses the Linode CLI to provision resources. The Linode Marketplace offers a one-click [OpenBao Marketplace app](/docs/marketplace-docs/guides/openbao/), whereas this tutorial walks through a manual installation. -### Determine instance configuration +### Determine Instance Configuration In order to provision a Linode instance, you must specify the desired operating system, geographical region, and Linode plan size. The options available for each of these can be obtained using the Linode CLI. -#### Operating system +#### Operating System Run this command to obtain a formatted list of available operating systems: -| $ linode-cli images list \--type=manual | -| :---- | +```command +linode-cli images list --type=manual +``` -This guide will use Ubuntu 22.04, which has the ID linode/ubuntu22.04. +This guide uses Ubuntu 24.04 LTS, which has the ID `linode/ubuntu24.04`. -#### Geographical region +#### Geographical Region -| $ linode-cli regions list | -| :---- | +```command +linode-cli regions list +``` -This guide will use the us-sea region (Seattle, WA). +This guide uses the `us-mia` region (Miami, FL). -#### Compute Instance size +#### Compute Instance Size -| $ linode-cli linodes types | -| :---- | +```command +linode-cli linodes types +``` The OpenBao documentation does not explicitly state hardware resource requirements for deploying OpenBao. However, as a fork of HashiCorp Vault, the [hardware size guide](https://developer.hashicorp.com/vault/tutorials/day-one-raft/raft-reference-architecture#hardware-sizing-for-vault-servers) for Vault can serve as a reference. For an initial, small cluster deployment of HashiCorp Vault (and thus, OpenBao), the documentation recommends: -* 2-4 CPU cores -* 8-16 GB RAM -* 100+ GB disk capacity -* 75+ Mbps transfer rate +- 2-4 CPU cores +- 8-16 GB RAM +- 100+ GB disk capacity +- 75+ Mbps transfer rate -This guide will use the g6-standard-4 Linode, which has 4 cores, 160 GB disk, and 8 GB RAM with a 5000 Mbps transfer rate. These capabilities are comparable to the hardware sizing recommendations. +This guide uses the `g6-standard-4` Linode, which has 4 cores, 160 GB disk, and 8 GB RAM with a 5000 Mbps transfer rate. These capabilities are comparable to the hardware sizing recommendations. ### Create the Compute Instance -The following command creates a Linode Compute Instance based on the specified operating system, geographical region, and size as noted above. +1. The following command creates a Linode Compute Instance based on the specified operating system, geographical region, and size as noted above. + + ```command + linode-cli linodes create \ + --image linode/ubuntu24.04 \ + --region us-mia \ + --type g6-standard-4 \ + --root_pass {{< placeholder "PASSWORD" >}} \ + --authorized_keys "$(cat ~/.ssh/id_ed25519.pub)" \ + --label openbao-linode + ``` + + Note the following key points: + + - Replace {{< placeholder "PASSWORD" >}} with a secure alternative. + - This command assumes that an SSH public/private key pair exists, with the public key stored as `id_ed25519.pub` in the user’s `$HOME/.ssh` folder. + - The `--label` argument specifies the name of the new server (e.g. `openbao-linode`). + + ```output + Using default values: {'authorized_users': ['{{< placeholder "USERNAME" >}}']}; use the --no-defaults flag to disable defaults + ┌────┬────────────────┬────────┬───────────────┬────────────────────┬──────────────┬──────────────┬─────────────────┬───────────────────────┐ + │ id │ label │ region │ type │ image │ status │ ipv4 │ disk_encryption │ placement_group.label │ + ├────┼────────────────┼────────┼───────────────┼────────────────────┼──────────────┼──────────────┼─────────────────┼───────────────────────┤ + │ {{< placeholder "ID" >}} │ openbao-linode │ us-mia │ g6-standard-4 │ linode/ubuntu24.04 │ provisioning │ {{< placeholder "IPV4_ADDRESS" >}} │ enabled │ │ + └────┴────────────────┴────────┴───────────────┴────────────────────┴──────────────┴──────────────┴─────────────────┴───────────────────────┘ + ``` + +1. Within a few minutes of executing this command, the instance should be visible with status `running` in the Akamai Cloud Manager or via the following Linode CLI command: + + ```command + linode-cli linodes list --label openbao-linode + ``` + + ```output + ┌────┬────────────────┬────────┬───────────────┬────────────────────┬─────────┬──────────────┬─────────────────┬───────────────────────┐ + │ id │ label │ region │ type │ image │ status │ ipv4 │ disk_encryption │ placement_group.label │ + ├────┼────────────────┼────────┼───────────────┼────────────────────┼─────────┼──────────────┼─────────────────┼───────────────────────┤ + │ {{< placeholder "ID" >}} │ openbao-linode │ us-mia │ g6-standard-4 │ linode/ubuntu24.04 │ running │ {{< placeholder "IPV4_ADDRESS" >}} │ enabled │ │ + └────┴────────────────┴────────┴───────────────┴────────────────────┴─────────┴──────────────┴─────────────────┴───────────────────────┘ + ``` -| $ linode-cli linodes create \\ \--image linode/ubuntu22.04 \\ \--region us-sea \\ \--type g6-standard-4 \\ \--root\_pass \ \\ \--authorized\_keys "$(cat \~/.ssh/id\_rsa.pub)" \\ \--label openbao-linode | -| :---- | +Depending on notification settings, emails detailing the progress of the provisioning process may also be sent to the Linode user’s address. -Note the following key points: +## Step 2: Install OpenBao on the Linode Compute Instance -* Replace **``** with a secure alternative. -* This command assumes that an SSH public/private key pair exists, with the public key stored as id\_rsa.pub in the user’s $HOME/.ssh/ folder. -* The \--label argument specifies the name of the new server (openbao-linode). +To install OpenBao, you need to SSH into the newly provisioned Linode: -Within a few minutes of executing this command, the instance will be visible with status running in the Linode Cloud Manager or via the following CLI command: +1. The IP address of the new instance can be found in the Linode Cloud Manager dashboard or via the following command: -| $ linode-cli linodes list \--label openbao-linode ┌-----------------┬--------┬---------------┬---------┬-----------------┐ │ label │ region │ type │ status │ ipv4 │ ├-----------------┼--------┼---------------┼---------┼-----------------┤ │ openbao-linode │ us-sea │ g6-standard-1 │ running │ 172.233.157.190 │ └-----------------┴--------┴---------------┴---------┴-----------------┘ | -| :---- | + ```command + linode-cli linodes list + ``` -Depending on notification settings, emails detailing the progress of the provisioning process may also be sent to the Linode user’s address. - -## Step 2: Install OpenBao on the Linode Compute Instance +1. Once the IP address is found, run the following command: -To install OpenBao, you will need to SSH into the newly provisioned Linode. The IP address of the new instance can be found in the Linode Cloud Manager dashboard or via the following command: + ```command + ssh -l root {{< placeholder "IP_ADDRESS" >}} + ``` -| $ linode-cli linodes list | -| :---- | +{{< note >}} +This method of connecting uses the `root` user, which is initially the only accessible user on the system. For production systems, it is strongly recommended that you disable the ability to access the instance as the `root` user, instead creating a limited user account with sudo privileges for access. See [this guide](https://techdocs.akamai.com/cloud-computing/docs/set-up-and-secure-a-compute-instance#add-a-limited-user-account) for more details. -Once the IP address is found, run the following command: +This guide assumes that all remaining commands are run with `sudo` as a newly created user on the Linode instance. +{{< /note >}} -| $ ssh \-l root \ | -| :---- | +### Update System Packages -| Note that this method of connecting uses the root user, which is initially the only accessible user on the system. For production systems, it is strongly recommended that you disable the ability to access the instance as the root user, instead creating a limited user account with sudo privileges for access. See [this guide](https://techdocs.akamai.com/cloud-computing/docs/set-up-and-secure-a-compute-instance#add-a-limited-user-account) for more details. This guide will assume that all remaining commands are run with sudo as a newly created user on the Linode instance. | -| :---- | +Ensure that the new system is up to date with the latest Ubuntu packages. The Ubuntu package manager (`apt`) needs to be updated to pull the latest package manifests, followed by upgrading any that are outdated. -### Update system packages +```command +sudo apt update && apt upgrade -y +``` -Ensure that the new system is up to date with the latest Ubuntu packages. The Ubuntu package manager (apt) needs to be updated to pull the latest package manifests, followed by upgrading any that are outdated. +### Download and Install the OpenBao Package -| $ apt update && apt upgrade \-y | -| :---- | +Find the desired version of OpenBao from the [downloads page](https://openbao.org/downloads/). -### Download and install the OpenBao package +1. In this case, the AMD 64-bit Debian package works with the provisioned Linode Compute Instance. -Find the desired version of OpenBao from the [downloads page](https://openbao.org/downloads/). In this case, the AMD 64-bit debian package works with the Linode Compute Instance that has been provisioned. + ```command + wget https://github.com/openbao/openbao/releases/download/v2.2.0/bao_2.2.0_linux_amd64.deb + ``` -| $ wget https://github.com/openbao/openbao/releases/download/v2.0.3/bao\_2.0.3\_linux\_amd64.deb | -| :---- | +1. Install the package: -Install the package. + ```command + sudo dpkg -i bao_2.2.0_linux_amd64.deb + ``` -| $ dpkg \-i bao\_2.0.3\_linux\_amd64.deb Selecting previously unselected package bao. (Reading database ... 219929 files and directories currently installed.) Preparing to unpack bao\_2.0.3\_linux\_amd64.deb ... Unpacking bao (2.0.3) ... Setting up bao (2.0.3) ... Generating OpenBao TLS key and self-signed certificate... ... OpenBao TLS key and self-signed certificate have been generated in '/opt/openbao/tls'. | -| :---- | + ```output + Selecting previously unselected package bao. + (Reading database ... 124865 files and directories currently installed.) + Preparing to unpack bao_2.2.0_linux_amd64.deb ... + Unpacking bao (2.2.0) ... + Setting up bao (2.2.0) ... + Generating OpenBao TLS key and self-signed certificate... + ... + OpenBao TLS key and self-signed certificate have been generated in '/opt/openbao/tls'. + ``` -Verify the install was successful. +1. Verify the install was successful: -| $ bao \-h | -| :---- | + ```command + bao -h + ``` -### Verify swap memory limits +### Verify Swap Memory Limits For Linux distributions, ensure that the OpenBao service settings do not impose a soft limit on Swap memory. To check this with a systemd-based Linux distro, use the following command: -| $ systemctl cat openbao \# /usr/lib/systemd/system/openbao.service \[Unit\] Description="OpenBao \- A tool for managing secrets" … \[Service\] … TimeoutStopSec=30 LimitNOFILE=65536 MemorySwapMax=0 \[Install\] WantedBy=multi-user.target | -| :---- | +```command +systemctl cat openbao +``` -Verify that MemorySwapMax=0 appears in the results under the Service heading. +```output +# /usr/lib/systemd/system/openbao.service +[Unit] +Description="OpenBao - A tool for managing secrets" +... -## Step 3: Test the OpenBao Development Server +[Service] +... +TimeoutStopSec=30 +LimitNOFILE=65536 +MemorySwapMax=0 -OpenBao provides a development server that runs completely in memory. Use this to verify settings and explore OpenBao features. +[Install] +WantedBy=multi-user.target +``` -### Start the development server +Verify that `MemorySwapMax=0` appears in the results under the `Service` heading. -To start the server in development mode and set a primary key run this command: +## Step 3: Test the OpenBao Development Server -| $ bao server \-dev \\ \-dev-root-token-id="this-is-my-test-dev-token" | -| :---- | +OpenBao provides a development server that runs completely in memory. Use this to verify settings and explore OpenBao features. -The OpenBao server configuration will print to the screen along with a tail of the logs. +### Start the Development Server -| \==\> OpenBao server configuration: Administrative Namespace: Api Address: http://127.0.0.1:8200 Cgo: disabled Cluster Address: https://127.0.0.1:8201 Environment Variables: HOME, LANG, LESSCLOSE, LESSOPEN, LOGNAME, LS\_COLORS, MAIL, PATH, PWD, SHELL, SHLVL, SUDO\_COMMAND, SUDO\_GID, SUDO\_UID, SUDO\_USER, TERM, USER, \_ Go Version: go1.22.9 Listener 1: tcp (addr: "127.0.0.1:8200", cluster address: "127.0.0.1:8201", max\_request\_duration: "1m30s", max\_request\_size: "33554432", tls: "disabled") Log Level: Recovery Mode: false Storage: inmem Version: OpenBao v2.0.3, built 2024-11-15T16:54:47Z Version Sha: a2522eb71d1854f83c7e2e02fdbfc01ae74c3a78 \==\> OpenBao server started\! Log data will stream in below: ... 2024-11-25T10:07:57.493-0700 \[INFO\] core: vault is unsealed 2024-11-25T10:07:57.495-0700 \[INFO\] expiration: revoked lease: lease\_id=auth/token/root/hf0285ed983c6c93bd02f9422f179d20f12508b046d39228a7b2e13c245293de6 2024-11-25T10:07:57.498-0700 \[INFO\] core: successful mount: namespace="" path=secret/ type=kv version="" 2024-11-25T10:07:57.499-0700 \[INFO\] secrets.kv.kv\_cd63d9f9: collecting keys to upgrade 2024-11-25T10:07:57.499-0700 \[INFO\] secrets.kv.kv\_cd63d9f9: done collecting keys: num\_keys=1 2024-11-25T10:07:57.499-0700 \[INFO\] secrets.kv.kv\_cd63d9f9: upgrading keys finished … | -| :---- | +To start the server in development mode and set a primary key run this command: -Leave this server process running in the background. In a separate terminal window, connect to the Linode instance with another shell session. +```command +bao server -dev \ + -dev-root-token-id="this-is-my-test-dev-token" +``` + +The OpenBao server configuration should print to the screen along with a tail of the logs: + +```output +==> OpenBao server configuration: + +Administrative Namespace: + Api Address: http://127.0.0.1:8200 + Cgo: disabled + Cluster Address: https://127.0.0.1:8201 + Environment Variables: HOME, LANG, LESSCLOSE, LESSOPEN, LOGNAME, LS_COLORS, MAIL, PATH, PWD, SHELL, SHLVL, SUDO_COMMAND, SUDO_GID, SUDO_UID, SUDO_USER, TERM, USER, _ + Go Version: go1.22.9 + Listener 1: tcp (addr: "127.0.0.1:8200", cluster address: "127.0.0.1:8201", max_request_duration: "1m30s", max_request_size: "33554432", tls: "disabled") + Log Level: + Recovery Mode: false + Storage: inmem + Version: OpenBao v2.0.3, built 2024-11-15T16:54:47Z + Version Sha: a2522eb71d1854f83c7e2e02fdbfc01ae74c3a78 + + ==> OpenBao server started! Log data will stream in below: + + ... + 2024-11-25T10:07:57.493-0700 [INFO] core: vault is unsealed + 2024-11-25T10:07:57.495-0700 [INFO] expiration: revoked lease: lease_id=auth/token/root/hf0285ed983c6c93bd02f9422f179d20f12508b046d39228a7b2e13c245293de6 + 2024-11-25T10:07:57.498-0700 [INFO] core: successful mount: namespace="" path=secret/ type=kv version="" + 2024-11-25T10:07:57.499-0700 [INFO] secrets.kv.kv_cd63d9f9: collecting keys to upgrade + 2024-11-25T10:07:57.499-0700 [INFO] secrets.kv.kv_cd63d9f9: done collecting keys: num_keys=1 + 2024-11-25T10:07:57.499-0700 [INFO] secrets.kv.kv_cd63d9f9: upgrading keys finished +... +``` -### Setting and getting a test secret +Leave this server process running in the background. In a separate terminal window, connect to the Linode instance with another shell session. -Use curl requests to test setting and getting a test secret. OpenBao expects certain variables to be set for every request. Instead of setting these variables repeatedly with each command, set the following environment variables in the shell: +### Setting and Retrieving a Test Secret + +Use `curl` requests to test setting and retrieving a test secret. OpenBao expects certain variables to be set for every request. + +1. Instead of setting these variables repeatedly with each command, set the following environment variables in the shell: + + ```command + export VAULT_TOKEN="this-is-my-test-dev-token" + export OPENBAO_IP="127.0.0.1" + export OPENBAO_PORT="8200" + ``` + +1. Send a request with `curl` to set a secret as a key-value pair. + + ```command + curl -X POST \ + --header "X-Vault-Token: $VAULT_TOKEN" \ + --header "Content-Type: application/json" \ + --data '{"data": {"password": "OpenBao123"}}' \ + http://$OPENBAO_IP:$OPENBAO_PORT/v1/secret/data/test-password-1 \ + | json_pp + ``` + + ```output + { + "auth" : null, + "data" : { + "created_time" : "2025-04-17T16:53:43.538885271Z", + "custom_metadata" : null, + "deletion_time" : "", + "destroyed" : false, + "version" : 1 + }, + "lease_duration" : 0, + "lease_id" : "", + "renewable" : false, + "request_id" : "8b6538d0-e52c-7a7a-27a4-6d4c58d9fc02", + "warnings" : null, + "wrap_info" : null + } + ``` + + The development server is only exposed on `localhost`. Therefore, this command must be run on the server itself. Authentication is handled by supplying the `X-Vault-Token` header. The structure of the URI follows the pattern `/v1/secret/data/{{< placeholder "SECRET_NAME" >}}`. This `POST` request stores the key-value pair at location `/data/{{< placeholder "SECRET_NAME" >}}`. + + The response provides metadata regarding the secret stored in the `data` object, including versioning (how many times this secret has been updated). + +1. To retrieve the secret, send the following request: + + ```command + curl \ + --header "X-Vault-Token: $VAULT_TOKEN" \ + http://$OPENBAO_IP:$OPENBAO_PORT/v1/secret/data/test-password-1 \ + | json_pp + ``` + + The original secret is found within the data object as a key-value pair. + + ```output + { + "auth" : null, + "data" : { + "data" : { + "password" : "OpenBao123" + }, + "metadata" : { + "created_time" : "2025-04-17T16:53:43.538885271Z", + "custom_metadata" : null, + "deletion_time" : "", + "destroyed" : false, + "version" : 1 + } + }, + "lease_duration" : 0, + "lease_id" : "", + "renewable" : false, + "request_id" : "7ec0baa1-126d-1bd8-56a3-4ea4555821ff", + "warnings" : null, + "wrap_info" : null + } + ``` + +1. When done, you can close the second terminal session. + +1. Return to the original terminal session with OpenBao running and press Ctrl+C to stop OpenBao. -| $ export VAULT\_TOKEN="this-is-my-test-dev-token" $ export OPENBAO\_IP="127.0.0.1" $ export OPENBAO\_PORT="8200" | -| :---- | +## Step 4: Run OpenBao as a Service -Send a request with curl to set a secret as a key-value pair. +In a real-world use case, OpenBao should run as a service managed by a tool such as `systemd`. -| $ curl \-X POST \\ \--header "X-Vault-Token: $VAULT\_TOKEN" \\ \--header "Content-Type: application/json" \\ \--data '{"data": {"password": "OpenBao123"}}' \\ http://$OPENBAO\_IP:$OPENBAO\_PORT/v1/secret/data/test-password-1 \\ | json\_pp { "auth" : null, "data" : { "created\_time" : "2024-11-25T17:25:05.234896488Z", "custom\_metadata" : null, "deletion\_time" : "", "destroyed" : false, "version" : 1 }, "lease\_duration" : 0, "lease\_id" : "", "renewable" : false, "request\_id" : "0ad32a55-51cd-086c-0eba-5b1f6349bb3b", "warnings" : null, "wrap\_info" : null } | -| :---- | +1. Run the following `systemctl` command to check the status of the OpenBao service: -The development server is only exposed on localhost. Therefore, this command must be run on the server itself. Authentication is handled by supplying the X-Vault-Token header. The structure of the URI follows the pattern /v1/secret/data/\. This POST request stores the key-value pair at location /data/\. + ```command + systemctl status openbao + ``` -The response provides metadata regarding the secret stored in the data object, including versioning (how many times this secret has been updated). + This shows that `systemd` is aware of the OpenBao service but it has not been started: -To retrieve the secret, send the following request: + ```output + ○ openbao.service - "OpenBao - A tool for managing secrets" + Loaded: loaded (/usr/lib/systemd/system/openbao.service; disabled; preset: enabled) + Active: inactive (dead) + Docs: https://github.com/openbao/openbao/tree/main/website/content/docs + ``` -| $ curl \\ \--header "X-Vault-Token: $VAULT\_TOKEN" \\ http://$OPENBAO\_IP:$OPENBAO\_PORT/v1/secret/data/test-password-1 \\ | json\_pp { "auth" : null, "data" : { "data" : { "password" : "OpenBao123" }, "metadata" : { "created\_time" : "2024-11-25T17:25:05.234896488Z", "custom\_metadata" : null, "deletion\_time" : "", "destroyed" : false, "version" : 1 } }, "lease\_duration" : 0, "lease\_id" : "", "renewable" : false, "request\_id" : "0471a6c0-b9ad-d6d4-1e81-c0ade5d057ce", "warnings" : null, "wrap\_info" : null } | -| :---- | +1. Edit the OpenBao configuration file, located at `/etc/openbao/openbao.hcl`, in a command line text editor such as `nano`: -The original secret is found within the data object as a key-value pair. + ```command + sudo nano /etc/openbao/openbao.hcl + ``` -## Step 4: Run OpenBao as a Service + Edit the file to create a publicly available service with the following contents: -In a real-world use case, it would be expected that OpenBao runs as a service, managed by a tool such as systemd. Run the following command: + ```file {title="/etc/openbao/openbao.hcl"} + ui = false -| $ systemctl status openbao ○ openbao.service \- "OpenBao \- A tool for managing secrets" Loaded: loaded (/usr/lib/systemd/system/openbao.service; disabled; preset: enabled) Active: inactive (dead) Docs: https://github.com/openbao/openbao/tree/main/website/content/docs | -| :---- | + storage "file" { + path = "/opt/openbao/data" + } + api_addr = "http://127.0.0.1:8200" -This shows that systemd is aware of the OpenBao service but it has not been started. + listener "tcp" { + address = "0.0.0.0:8200" + tls_disable = 1 + } + ``` -The default location of the OpenBao configuration file on the Linode Compute Instance is /etc/openbao/openbao.hcl. Edit this file and set it up for a publicly available service with the following contents: + {{< note >}} + The configuration above is insecure and not suitable for production use. It is only for demonstration purposes of this tutorial. For a production-grade deployment, reference the [configuration](#configuration) near the end of this guide. + {{< /note >}} -| ui \= false storage "file" { path \= "/opt/openbao/data" } api\_addr \= "http://0.0.0.0:8200" listener "tcp" { address \= "0.0.0.0:8200" tls\_disable \= 1 } | -| :---- | + When done, press CTRL+X, followed by Y then Enter to save the file and exit `nano`. -**Note:** The configuration above is insecure and not suitable for production use. It is only for demonstration purposes of this tutorial. For a production-grade deployment, reference the [configuration](#configuration) near the end of this guide. +1. Start the OpenBao service, then check its status. -Start the service, then check its status. + ```command + systemctl start openbao + systemctl status openbao + ``` -| $ systemctl start openbao $ systemctl status openbao ● openbao.service \- "OpenBao \- A tool for managing secrets" Loaded: loaded (/usr/lib/systemd/system/openbao.service; disabled; preset: enabled) Active: active (running) since Mon 2024-11-25 10:38:04 MST; 7s ago Docs: https://github.com/openbao/openbao/tree/main/website/content/docs Main PID: 642487 (bao) Tasks: 6 (limit: 1124\) Memory: 12.2M (swap max: 0B peak: 12.5M) CPU: 66ms CGroup: /system.slice/openbao.service └─642487 /usr/bin/bao server \-config=/etc/openbao/openbao.hcl | -| :---- | + ```output + ● openbao.service - "OpenBao - A tool for managing secrets" + Loaded: loaded (/usr/lib/systemd/system/openbao.service; disabled; preset: enabled) + Active: active (running) since Mon 2024-11-25 10:38:04 MST; 7s ago + Docs: https://github.com/openbao/openbao/tree/main/website/content/docs + Main PID: 642487 (bao) + Tasks: 6 (limit: 1124) + Memory: 12.2M (swap max: 0B peak: 12.5M) + CPU: 66ms + CGroup: /system.slice/openbao.service + └─642487 /usr/bin/bao server -config=/etc/openbao/openbao.hcl + ``` -To start the service automatically whenever the Linode server boots, run the following command: +1. Run the following command to start the service automatically whenever the Linode server boots: -| $ systemctl enable openbao | -| :---- | + ```command + systemctl enable openbao + ``` ## Step 5: Configure OpenBao for External Access Although OpenBao is now running as a service on the Linode Compute Instance, it is still not ready for use. Use the [OpenBao CLI](https://openbao.org/docs/commands/) to interact with the running server, retrieving its current status: -| $ bao status \--address=http://0.0.0.0:8200 Key Value \--- \----- Seal Type shamir Initialized false Sealed true Total Shares 0 Threshold 0 Unseal Progress 0/0 Unseal Nonce n/a Version 2.0.3 Build Date 2024-11-15T16:54:47Z Storage Type file HA Enabled false | -| :---- | +```command +bao status --address=http://0.0.0.0:8200 +``` + +```output +Key Value +--- ----- +Seal Type shamir +Initialized false +Sealed true +Total Shares 0 +Threshold 0 +Unseal Progress 0/0 +Unseal Nonce n/a +Version 2.2.0 +Build Date 2025-03-05T13:07:08Z +Storage Type file +HA Enabled false +``` The status shows that the server has not been initialized, and it is sealed. Both of these issues must be resolved before the server can be interacted with. -### Initialize the server - -Set the BAO\_ADDR environment variable, which will be used in several subsequent commands. +### Initialize the Server -| $ export BAO\_ADDR=http://0.0.0.0:8200 | -| :---- | +1. Set the `BAO_ADDR` environment variable, which is used in several subsequent commands: -Run the following command to initialize the server. + ```command + export BAO_ADDR=http://0.0.0.0:8200 + ``` -| $ bao operator init Unseal Key 1: lmeBuSpXWfmpGocWBrpD08nK7OOws691bygB2ipS2KUE Unseal Key 2: CXi4hCiD4H922RtyTAU8sR77svDfsCkyXaVuZYY2VkFa Unseal Key 3: oCKeZ0JxPS6G8+losHgKWDPV5Qc01XU4e4g2//sp3lje Unseal Key 4: cD1yVzWt0dh71BI7vtiIImoj5e12OhEWw7lmAGsnZjb/ Unseal Key 5: uSNLC9hISYKz0fbyNF3sX7gjF/HZ5U7mR6EfGYKdHbuF Initial Root Token: s.eZTodpa8pErpfQGDyPPUqVME Vault initialized with 5 key shares and a key threshold of 3\. Please securely distribute the key shares printed above. When the Vault is re-sealed, restarted, or stopped, you must supply at least 3 of these keys to unseal it before it can start servicing requests. Vault does not store the generated root key. Without at least 3 keys to reconstruct the root key, Vault will remain permanently sealed\! It is possible to generate new unseal keys, provided you have a quorum of existing unseal keys shares. See "vault operator rekey" for more information. | -| :---- | +1. Initialize the server: -Store the unseal keys and initial root token in a secure location. - -### Unseal the vault (three times for quorum) + ```command + bao operator init + ``` -Unseal the vault using one of the unseal keys provided. + ```output + Unseal Key 1: SNP+diKq1L2MYYre8pn+PIqSEn/nK76n7C6coUoVby4g + Unseal Key 2: 9Bm3d5ZHsWBT/LghfVYbGrVn0Lcmr5CvNu6H8UYVx+R/ + Unseal Key 3: IrPLoIFrl2ol7dF4mA9C+kTaE44qogwT/pZ+kTrS7M4j + Unseal Key 4: O7fs+9492lVGdI5295n4AKis5c3cFZ8VEtkBmLg3lYAJ + Unseal Key 5: 0gnwUnHfkeFTaE6xIkVWy/5s4Hfwh5WxVWOrCrApGHig -| $ bao operator unseal Unseal Key (will be hidden): lmeBuSpXWfmpGocWBrpD08nK7OOws691bygB2ipS2KUE Key Value \--- \----- Seal Type shamir Initialized true Sealed true Total Shares 5 Threshold 3 Unseal Progress 1/3 Unseal Nonce f0724cb7-324e-ef04-34fb-3fb6f0f0806e Version 2.0.3 Build Date 2024-11-15T16:54:47Z Storage Type file HA Enabled false | -| :---- | + Initial Root Token: s.V82B9tynwZkQtDyOne7PJ1IS -After this first execution, the unseal progress shows 1/3. Unsealing must be done a total of three times, as this is the default quorum for OpenBao unsealing. + Vault initialized with 5 key shares and a key threshold of 3. Please securely + distribute the key shares printed above. When the Vault is re-sealed, + restarted, or stopped, you must supply at least 3 of these keys to unseal it + before it can start servicing requests. -| $ bao operator unseal Unseal Key (will be hidden): CXi4hCiD4H922RtyTAU8sR77svDfsCkyXaVuZYY2VkFa $ bao operator unseal Unseal Key (will be hidden): oCKeZ0JxPS6G8+losHgKWDPV5Qc01XU4e4g2//sp3lje | -| :---- | + Vault does not store the generated root key. Without at least 3 keys to + reconstruct the root key, Vault will remain permanently sealed! -After unsealing has been executed three times (with three different unseal keys), the OpenBao status will show the following: + It is possible to generate new unseal keys, provided you have a quorum of + existing unseal keys shares. See "bao operator rekey" for more information. + ``` -| Key Value \--- \----- Seal Type shamir Initialized true Sealed false Total Shares 5 Threshold 3 Version 2.0.3 Build Date 2024-11-15T16:54:47Z Storage Type file Cluster Name vault-cluster-5e4b590f Cluster ID d7b79512-d2d0-13d1-92a3-e636384c10af HA Enabled false | -| :---- | +Store the unseal keys and initial root token in a secure location. -Now, the vault has been initialized and unsealed. +### Unseal the Vault (Three Times for Quorum) + +1. Use the following command to begin unsealing the vault: + + ```command + bao operator unseal + ``` + + When prompted, enter one of the unseal keys provided in the previous section: + + ```output + Unseal Key (will be hidden): SNP+diKq1L2MYYre8pn+PIqSEn/nK76n7C6coUoVby4g + ``` + + After this first execution, the unseal progress shows `1/3`: + + ```output + Key Value + --- ----- + Seal Type shamir + Initialized true + Sealed true + Total Shares 5 + Threshold 3 + Unseal Progress 1/3 + Unseal Nonce e88d59f4-db7f-a074-c9e5-6476e55d77c4 + Version 2.2.0 + Build Date 2025-03-05T13:07:08Z + Storage Type file + HA Enabled false + ``` + + Unsealing must be done a total of three times, as this is the default quorum for OpenBao unsealing. + +1. Unseal the vault again, but enter a different unseal key when prompted: + + ```command + bao operator unseal + ``` + + ```output + Unseal Key (will be hidden): 9Bm3d5ZHsWBT/LghfVYbGrVn0Lcmr5CvNu6H8UYVx+R/ + Key Value + --- ----- + Seal Type shamir + Initialized true + Sealed true + Total Shares 5 + Threshold 3 + Unseal Progress 2/3 + Unseal Nonce e88d59f4-db7f-a074-c9e5-6476e55d77c4 + Version 2.2.0 + Build Date 2025-03-05T13:07:08Z + Storage Type file + HA Enabled false + ``` + +1. Unseal the vault for the third and final time, using another unsealing key when prompted: + + ```command + bao operator unseal + ``` + + After unsealing has been executed three times (with three different unseal keys), the OpenBao status shows the following: + + ```output + Unseal Key (will be hidden): IrPLoIFrl2ol7dF4mA9C+kTaE44qogwT/pZ+kTrS7M4j + Key Value + --- ----- + Seal Type shamir + Initialized true + Sealed false + Total Shares 5 + Threshold 3 + Version 2.2.0 + Build Date 2025-03-05T13:07:08Z + Storage Type file + Cluster Name vault-cluster-bf06dcdc + Cluster ID e241640b-4e62-5063-04fb-e71562706b8c + HA Enabled false + ``` + +The vault has now been initialized and unsealed. ### Authenticate the CLI -To authenticate the CLI with the server, use the bao login command with the root token provided upon vault initialization. - -| $ bao login \-method=token s.eZTodpa8pErpfQGDyPPUqVME Success\! You are now authenticated. The token information displayed below is already stored in the token helper. You do NOT need to run "bao login" again. Future OpenBao requests will automatically use this token. Key Value \--- \----- token s.eZTodpa8pErpfQGDyPPUqVME token\_accessor otHrg1OUERHfyEGgy2DOXbEB token\_duration ∞ token\_renewable false token\_policies \["root"\] identity\_policies \[\] policies \["root"\] | -| :---- | - -### Enable key-value storage - -Lastly, to enable a key-value store in OpenBao for stashing and retrieving secrets via the API. To do this, run the following command: - -| $ bao secrets enable kv Success\! Enabled the kv secrets engine at: kv/ | -| :---- | - -### Setting and getting a secret remotely over HTTP - -OpenBao can now be accessed externally via the API. Ensure that any firewall on the Linode Compute Instance allows traffic on port 8200. From a remote machine, set a new secret, providing the root token for authentication. - -| $ curl \-X POST \\ \--header "X-Vault-Token: s.eZTodpa8pErpfQGDyPPUqVME" \\ \--header "Content-Type: application/json" \\ \--data '{"data": {"hello": "world"}}' \\ http://\:8200/v1/kv/test-secret | -| :---- | - -Get the newly created secret to verify it was stored properly. - -| $ curl \-X GET \\ \--header "X-Vault-Token: s.eZTodpa8pErpfQGDyPPUqVME" \\ http://\:8200/v1/kv/test-secret { "auth" : null, "data" : { "hello" : "world" }, "lease\_duration" : 2764800, "lease\_id" : "", "renewable" : false, "request\_id" : "3bbd69a5-b77a-62b0-686d-a8a3103d6d6b", "warnings" : null, "wrap\_info" : null } | -| :---- | +To authenticate the CLI with the server, use the `bao login` command with the root token provided upon vault initialization. + +```command +bao login -method=token s.V82B9tynwZkQtDyOne7PJ1IS +``` + +```output +Success! You are now authenticated. The token information displayed below is +already stored in the token helper. You do NOT need to run "bao login" again. +Future OpenBao requests will automatically use this token. + +Key Value +--- ----- +token s.V82B9tynwZkQtDyOne7PJ1IS +token_accessor 4IjIYjvf9TLIPPXgMVFFJYzG +token_duration ∞ +token_renewable false +token_policies ["root"] +identity_policies [] +policies ["root"] +``` + +### Enable Key-Value Storage + +Lastly, enable a key-value store in OpenBao for stashing and retrieving secrets via the API. + +To do this, run the following command: + +```command +bao secrets enable kv +``` + +```output +Success! Enabled the kv secrets engine at: kv/ +``` + +### Setting and Retrieving a Secret Remotely Over HTTP + +OpenBao can now be accessed externally via the API. Ensure that any firewall on the Linode Compute Instance allows traffic on port `8200`. + +1. From a remote machine, set a new secret, providing the root token for authentication. + + ```command + curl -X POST \ + --header "X-Vault-Token: s.eZTodpa8pErpfQGDyPPUqVME" \ + --header "Content-Type: application/json" \ + --data '{"data": {"hello": "world"}}' \ + http://{{< placeholder "LINODE_IP" >}}:8200/v1/kv/test-secret + ``` + +1. Get the newly created secret to verify it was stored properly. + + ```command + curl -X GET \ + --header "X-Vault-Token: s.eZTodpa8pErpfQGDyPPUqVME" \ + http://{{< placeholder "LINODE_IP" >}}:8200/v1/kv/test-secret + ``` + + ```output + { + "auth" : null, + "data" : { + "hello" : "world" + }, + "lease_duration" : 2764800, + "lease_id" : "", + "renewable" : false, + "request_id" : "3bbd69a5-b77a-62b0-686d-a8a3103d6d6b", + "warnings" : null, + "wrap_info" : null + } + ``` ## Considerations for Production Deployments @@ -281,51 +644,50 @@ In production, [auto-unseal](https://openbao.org/docs/concepts/seal/#auto-unseal Enable and configure secure authentication methods such as: -* AppRole -* JSON Web Tokens (JWT) -* TLS certificates -* LDAP -* OpenID Connect (OIDC) +- AppRole +- JSON Web Tokens (JWT) +- TLS certificates +- LDAP +- OpenID Connect (OIDC) TLS certificate authentication provides secure, mutual TLS verification for sensitive environments, while AppRole allows service accounts and applications to securely authenticate without human interaction. -For LDAP or OIDC deployments, enforce Multi Factor Authentication (MFA) for human operators to enhance security if supported. +For LDAP or OIDC deployments, enforce Multi Factor Authentication (MFA) for human operators to enhance security if supported. -### Configuration {#configuration} +### Configuration OpenBao supports two configuration formats: -1. HashiCorp Configuration Language (HCL) -2. JSON +1. HashiCorp Configuration Language (HCL) +2. JSON Properly configuring the OpenBao server is essential to ensure a secure production environment. The main configuration aspects include the UI, TLS certificate, and address/port settings. A default production configuration HCL file may look like this: -| ui \= false storage "file" { path \= "/opt/openbao/data" } api\_addr \= "https://0.0.0.0:8200" listener "tcp" { address \= "0.0.0.0:8200" tls\_cert\_file \= "/opt/openbao/tls/tls.crt" tls\_key\_file \= "/opt/openbao/tls/tls.key" } | -| :---- | +```file +ui = false + +storage "file" { + path = "/opt/openbao/data" +} +api_addr = "https://0.0.0.0:8200" + +listener "tcp" { + address = "0.0.0.0:8200" + tls_cert_file = "/opt/openbao/tls/tls.crt" + tls_key_file = "/opt/openbao/tls/tls.key" +} +``` In production, disabling or securing the UI is crucial, as it exposes OpenBao's management interface—which could be exploited if left unprotected. If the UI is required, limit its exposure by restricting access to trusted IP ranges or VPN users only. Implement strong authentication methods like OIDC for access control. -If the UI is not required, set ui \= false. +If the UI is not required, set `ui = false`. TLS certificates encrypt traffic to and from the OpenBao server, ensuring data confidentiality and integrity. Using a valid, trusted TLS certificate prevents man-in-the-middle attacks and validates the server's identity to clients. Obtain a certificate from a trusted Certificate Authority (CA) and configure OpenBao to use it as shown in the example configuration above. For environments using an internal CA, ensure that all clients trust the CA, and renew the certificates periodically to avoid downtime. -Controlling the address and ports on which OpenBao listens reduces exposure and minimizes the risk of unauthorized access. Limit OpenBao's exposure by binding it to an internal IP address (such as 127.0.0.1 or a specific internal network IP). Ensure that OpenBao only listens on the necessary port (default is 8200). Use firewall rules to restrict access to this port to authorized networks or users only. - -These hardening measures reduce the attack surface of the OpenBao server, enhance security controls, and ensure that only authorized entities have access. - ---- - -The resources below are provided to help you become familiar with OpenBao when deployed to Linode. - -## OpenBao Resources +Controlling the address and ports on which OpenBao listens reduces exposure and minimizes the risk of unauthorized access. Limit OpenBao's exposure by binding it to an internal IP address (such as `127.0.0.1` or a specific internal network IP). Ensure that OpenBao only listens on the necessary port (default is `8200`). Use firewall rules to restrict access to this port to authorized networks or users only. -* [Package downloads](https://openbao.org/downloads/) -* [Installation instructions](https://openbao.org/docs/install/) -* [CLI documentation](https://openbao.org/docs/commands/) -* [Plugins](https://openbao.org/docs/plugins/) -* [Authentication](https://openbao.org/docs/auth/) -* [OpenBao Linode Marketplace App](https://www.linode.com/docs/marketplace-docs/guides/openbao/) \ No newline at end of file +These hardening measures reduce the attack surface of the OpenBao server, enhance security controls, and ensure that only authorized entities have access. \ No newline at end of file From bc687f08868dfc4522beb9f9abdb80c3b0416253 Mon Sep 17 00:00:00 2001 From: Adam Overa Date: Wed, 23 Apr 2025 11:58:59 -0400 Subject: [PATCH 3/5] Edit 2 --- .../index.md | 232 ++++++------------ 1 file changed, 75 insertions(+), 157 deletions(-) diff --git a/docs/guides/security/secrets-management/deploying-openbao-on-a-linode-compute-instance/index.md b/docs/guides/security/secrets-management/deploying-openbao-on-a-linode-compute-instance/index.md index 030ffbbdc12..7d486a66cb9 100644 --- a/docs/guides/security/secrets-management/deploying-openbao-on-a-linode-compute-instance/index.md +++ b/docs/guides/security/secrets-management/deploying-openbao-on-a-linode-compute-instance/index.md @@ -9,148 +9,61 @@ keywords: ['openbao','openbao linode','openbao ubuntu install','secrets manageme license: '[CC BY-ND 4.0](https://creativecommons.org/licenses/by-nd/4.0)' --- -This guide walks through how to deploy OpenBao on a single Linode Compute Instance using the [Linode CLI](https://github.com/linode/linode-cli). - -## Prerequisites - -To follow along in this walkthrough, you’ll need the following: - -- A [Linode account](https://www.linode.com/cfe) -- A [Linode API token (personal access token)](/docs/products/platform/accounts/guides/manage-api-tokens/) -- The [Linode CLI](/docs/products/tools/cli/guides/install/) installed and configured -- An [SSH key pair](https://www.linode.com/content/ssh-key-authentication-how-to-create-ssh-key-pairs/) +[OpenBao](https://openbao.org/) is an open source secrets management solution and fork of HashiCorp Vault. While our [OpenBao Marketplace app](/docs/marketplace-docs/guides/openbao/) offers one-click deployment, this guide walks through a manual installation on a single Ubuntu 24.04 LTS compute instance. ## Before You Begin -1. If you do not already have a virtual machine to use, create a Compute Instance with at least 4 GB of memory. See our [Getting Started with Linode](/docs/products/platform/get-started/) and [Creating a Compute Instance](/docs/products/compute/compute-instances/guides/create/) guides. - -1. Follow our [Setting Up and Securing a Compute Instance](/docs/products/compute/compute-instances/guides/set-up-and-secure/) guide to update your system. You may also wish to set the timezone, configure your hostname, create a limited user account, and harden SSH access. - -{{< note >}} -The steps in this guide require root privileges. Be sure to run the steps below as `root` or with the `sudo` prefix. For more information on privileges, see our [Users and Groups](/docs/guides/linux-users-and-groups/) guide. -{{< /note >}} - -## Step 1: Initialize a Compute Instance - -This guide uses the Linode CLI to provision resources. The Linode Marketplace offers a one-click [OpenBao Marketplace app](/docs/marketplace-docs/guides/openbao/), whereas this tutorial walks through a manual installation. +1. If you do not already have a virtual machine to use, see our [Getting Started with Linode](/docs/products/platform/get-started/) and [Creating a Compute Instance](/docs/products/compute/compute-instances/guides/create/) guides. While OpenBao does not provide explicit hardware recommendations, its architecture closely mirrors that of Vault. As such, this guide uses a `g6-standard-4` Linode (8 GB RAM, 4 vCPUs, 160 GB storage), which aligns with Vault’s recommended specs for a small cluster: -### Determine Instance Configuration + - 2–4 CPU cores + - 8–16 GB RAM + - 100+ GB disk + - 75+ Mbps network bandwidth -In order to provision a Linode instance, you must specify the desired operating system, geographical region, and Linode plan size. The options available for each of these can be obtained using the Linode CLI. + {{< note title="Provisioning Compute Instances with the Linode CLI" type="secondary" isCollapsible="yes" >}} + Use these steps if you prefer to use the [Linode CLI](https://github.com/linode/linode-cli) to provision resources. -#### Operating System - -Run this command to obtain a formatted list of available operating systems: - -```command -linode-cli images list --type=manual -``` - -This guide uses Ubuntu 24.04 LTS, which has the ID `linode/ubuntu24.04`. - -#### Geographical Region - -```command -linode-cli regions list -``` - -This guide uses the `us-mia` region (Miami, FL). - -#### Compute Instance Size - -```command -linode-cli linodes types -``` - -The OpenBao documentation does not explicitly state hardware resource requirements for deploying OpenBao. However, as a fork of HashiCorp Vault, the [hardware size guide](https://developer.hashicorp.com/vault/tutorials/day-one-raft/raft-reference-architecture#hardware-sizing-for-vault-servers) for Vault can serve as a reference. For an initial, small cluster deployment of HashiCorp Vault (and thus, OpenBao), the documentation recommends: - -- 2-4 CPU cores -- 8-16 GB RAM -- 100+ GB disk capacity -- 75+ Mbps transfer rate - -This guide uses the `g6-standard-4` Linode, which has 4 cores, 160 GB disk, and 8 GB RAM with a 5000 Mbps transfer rate. These capabilities are comparable to the hardware sizing recommendations. - -### Create the Compute Instance - -1. The following command creates a Linode Compute Instance based on the specified operating system, geographical region, and size as noted above. + The following command creates a Linode 8 GB compute instance (`g6-standard-4`) running Ubuntu 24.04 LTS (`linode/ubuntu24.04`) in the Miami datacenter (`us-mia`): ```command linode-cli linodes create \ --image linode/ubuntu24.04 \ --region us-mia \ --type g6-standard-4 \ - --root_pass {{< placeholder "PASSWORD" >}} \ + --root_pass {{< placeholder "ROOT_PASSWORD" >}} \ --authorized_keys "$(cat ~/.ssh/id_ed25519.pub)" \ --label openbao-linode ``` Note the following key points: - - Replace {{< placeholder "PASSWORD" >}} with a secure alternative. - - This command assumes that an SSH public/private key pair exists, with the public key stored as `id_ed25519.pub` in the user’s `$HOME/.ssh` folder. + - Replace `us-mia` with your preferred data center region. Run `linode-cli regions list` to view options. + - Replace {{< placeholder "ROOT_PASSWORD" >}} with a secure alternative for your root password. + - This command assumes that an SSH public/private key pair exists, with the public key stored as `id_ed25519.pub` in the user’s `$HOME/.ssh/` folder. - The `--label` argument specifies the name of the new server (e.g. `openbao-linode`). + {{< /note >}} - ```output - Using default values: {'authorized_users': ['{{< placeholder "USERNAME" >}}']}; use the --no-defaults flag to disable defaults - ┌────┬────────────────┬────────┬───────────────┬────────────────────┬──────────────┬──────────────┬─────────────────┬───────────────────────┐ - │ id │ label │ region │ type │ image │ status │ ipv4 │ disk_encryption │ placement_group.label │ - ├────┼────────────────┼────────┼───────────────┼────────────────────┼──────────────┼──────────────┼─────────────────┼───────────────────────┤ - │ {{< placeholder "ID" >}} │ openbao-linode │ us-mia │ g6-standard-4 │ linode/ubuntu24.04 │ provisioning │ {{< placeholder "IPV4_ADDRESS" >}} │ enabled │ │ - └────┴────────────────┴────────┴───────────────┴────────────────────┴──────────────┴──────────────┴─────────────────┴───────────────────────┘ - ``` - -1. Within a few minutes of executing this command, the instance should be visible with status `running` in the Akamai Cloud Manager or via the following Linode CLI command: - - ```command - linode-cli linodes list --label openbao-linode - ``` - - ```output - ┌────┬────────────────┬────────┬───────────────┬────────────────────┬─────────┬──────────────┬─────────────────┬───────────────────────┐ - │ id │ label │ region │ type │ image │ status │ ipv4 │ disk_encryption │ placement_group.label │ - ├────┼────────────────┼────────┼───────────────┼────────────────────┼─────────┼──────────────┼─────────────────┼───────────────────────┤ - │ {{< placeholder "ID" >}} │ openbao-linode │ us-mia │ g6-standard-4 │ linode/ubuntu24.04 │ running │ {{< placeholder "IPV4_ADDRESS" >}} │ enabled │ │ - └────┴────────────────┴────────┴───────────────┴────────────────────┴─────────┴──────────────┴─────────────────┴───────────────────────┘ - ``` - -Depending on notification settings, emails detailing the progress of the provisioning process may also be sent to the Linode user’s address. - -## Step 2: Install OpenBao on the Linode Compute Instance +1. Follow our [Setting Up and Securing a Compute Instance](/docs/products/compute/compute-instances/guides/set-up-and-secure/) guide to update your system and create a limited user account. You may also wish to set the timezone, configure your hostname, and harden SSH access. -To install OpenBao, you need to SSH into the newly provisioned Linode: +1. Follow our [Use SSH Public Key Authentication on Linux, macOS, and Windows](https://www.linode.com/docs/guides/use-public-key-authentication-with-ssh/#generate-an-ssh-key-pair) guide to generate an SSH key pair. -1. The IP address of the new instance can be found in the Linode Cloud Manager dashboard or via the following command: +1. Create a personal access token using the instructions in our [Manage personal access tokens](https://techdocs.akamai.com/cloud-computing/docs/manage-personal-access-tokens) guide. - ```command - linode-cli linodes list - ``` - -1. Once the IP address is found, run the following command: - - ```command - ssh -l root {{< placeholder "IP_ADDRESS" >}} - ``` +1. Install the Linode CLI using the instructions in our [Install and configure the CLI](https://techdocs.akamai.com/cloud-computing/docs/install-and-configure-the-cli) guide. {{< note >}} -This method of connecting uses the `root` user, which is initially the only accessible user on the system. For production systems, it is strongly recommended that you disable the ability to access the instance as the `root` user, instead creating a limited user account with sudo privileges for access. See [this guide](https://techdocs.akamai.com/cloud-computing/docs/set-up-and-secure-a-compute-instance#add-a-limited-user-account) for more details. - -This guide assumes that all remaining commands are run with `sudo` as a newly created user on the Linode instance. +This guide is written for a non-root user. Commands that require elevated privileges are prefixed with `sudo`. If you’re not familiar with the `sudo` command, see the [Users and Groups](/docs/guides/linux-users-and-groups/) guide. {{< /note >}} -### Update System Packages - -Ensure that the new system is up to date with the latest Ubuntu packages. The Ubuntu package manager (`apt`) needs to be updated to pull the latest package manifests, followed by upgrading any that are outdated. +## Install OpenBao -```command -sudo apt update && apt upgrade -y -``` +1. SSH into the newly provisioned Linode as a user with `sudo` privileges: -### Download and Install the OpenBao Package - -Find the desired version of OpenBao from the [downloads page](https://openbao.org/downloads/). + ```command + ssh -l {{< placeholder "USERNAME" >}} {{< placeholder "IP_ADDRESS" >}} + ``` -1. In this case, the AMD 64-bit Debian package works with the provisioned Linode Compute Instance. +1. Download the latest appropriate version of OpenBao from the [downloads page](https://openbao.org/downloads/). In this case, `v2.2.0` of the AMD 64-bit Debian package: ```command wget https://github.com/openbao/openbao/releases/download/v2.2.0/bao_2.2.0_linux_amd64.deb @@ -173,13 +86,13 @@ Find the desired version of OpenBao from the [downloads page](https://openbao.or OpenBao TLS key and self-signed certificate have been generated in '/opt/openbao/tls'. ``` -1. Verify the install was successful: +1. Verify if the install is successful: ```command bao -h ``` -### Verify Swap Memory Limits +{{< note title="Verify Swap Memory Limits" >}} For Linux distributions, ensure that the OpenBao service settings do not impose a soft limit on Swap memory. To check this with a systemd-based Linux distro, use the following command: @@ -204,57 +117,62 @@ WantedBy=multi-user.target ``` Verify that `MemorySwapMax=0` appears in the results under the `Service` heading. +{{< /note >}} -## Step 3: Test the OpenBao Development Server +## Test the OpenBao Development Server -OpenBao provides a development server that runs completely in memory. Use this to verify settings and explore OpenBao features. +OpenBao provides a development server that you can use to verify settings and explore OpenBao features. -### Start the Development Server +{{< caution >}} +The development server runs entirely in memory and is not suitable for production use. Data is not persisted between restarts, and TLS is disabled. +{{< /caution >}} -To start the server in development mode and set a primary key run this command: +1. Run this command to start the server in development mode and set a primary key: -```command -bao server -dev \ - -dev-root-token-id="this-is-my-test-dev-token" -``` + ```command + bao server -dev \ + -dev-root-token-id="this-is-my-test-dev-token" + ``` -The OpenBao server configuration should print to the screen along with a tail of the logs: + The OpenBao server configuration should print to the screen along with a tail of the logs: -```output -==> OpenBao server configuration: - -Administrative Namespace: - Api Address: http://127.0.0.1:8200 - Cgo: disabled - Cluster Address: https://127.0.0.1:8201 - Environment Variables: HOME, LANG, LESSCLOSE, LESSOPEN, LOGNAME, LS_COLORS, MAIL, PATH, PWD, SHELL, SHLVL, SUDO_COMMAND, SUDO_GID, SUDO_UID, SUDO_USER, TERM, USER, _ - Go Version: go1.22.9 - Listener 1: tcp (addr: "127.0.0.1:8200", cluster address: "127.0.0.1:8201", max_request_duration: "1m30s", max_request_size: "33554432", tls: "disabled") - Log Level: - Recovery Mode: false - Storage: inmem - Version: OpenBao v2.0.3, built 2024-11-15T16:54:47Z - Version Sha: a2522eb71d1854f83c7e2e02fdbfc01ae74c3a78 - - ==> OpenBao server started! Log data will stream in below: - - ... - 2024-11-25T10:07:57.493-0700 [INFO] core: vault is unsealed - 2024-11-25T10:07:57.495-0700 [INFO] expiration: revoked lease: lease_id=auth/token/root/hf0285ed983c6c93bd02f9422f179d20f12508b046d39228a7b2e13c245293de6 - 2024-11-25T10:07:57.498-0700 [INFO] core: successful mount: namespace="" path=secret/ type=kv version="" - 2024-11-25T10:07:57.499-0700 [INFO] secrets.kv.kv_cd63d9f9: collecting keys to upgrade - 2024-11-25T10:07:57.499-0700 [INFO] secrets.kv.kv_cd63d9f9: done collecting keys: num_keys=1 - 2024-11-25T10:07:57.499-0700 [INFO] secrets.kv.kv_cd63d9f9: upgrading keys finished -... -``` + ```output + ==> OpenBao server configuration: + + Administrative Namespace: + Api Address: http://127.0.0.1:8200 + Cgo: disabled + Cluster Address: https://127.0.0.1:8201 + Environment Variables: HOME, LANG, LESSCLOSE, LESSOPEN, LOGNAME, LS_COLORS, MAIL, PATH, PWD, SHELL, SHLVL, SUDO_COMMAND, SUDO_GID, SUDO_UID, SUDO_USER, TERM, USER, _ + Go Version: go1.22.9 + Listener 1: tcp (addr: "127.0.0.1:8200", cluster address: "127.0.0.1:8201", max_request_duration: "1m30s", max_request_size: "33554432", tls: "disabled") + Log Level: + Recovery Mode: false + Storage: inmem + Version: OpenBao v2.0.3, built 2024-11-15T16:54:47Z + Version Sha: a2522eb71d1854f83c7e2e02fdbfc01ae74c3a78 + + ==> OpenBao server started! Log data will stream in below: + + ... + 2024-11-25T10:07:57.493-0700 [INFO] core: vault is unsealed + 2024-11-25T10:07:57.495-0700 [INFO] expiration: revoked lease: lease_id=auth/token/root/hf0285ed983c6c93bd02f9422f179d20f12508b046d39228a7b2e13c245293de6 + 2024-11-25T10:07:57.498-0700 [INFO] core: successful mount: namespace="" path=secret/ type=kv version="" + 2024-11-25T10:07:57.499-0700 [INFO] secrets.kv.kv_cd63d9f9: collecting keys to upgrade + 2024-11-25T10:07:57.499-0700 [INFO] secrets.kv.kv_cd63d9f9: done collecting keys: num_keys=1 + 2024-11-25T10:07:57.499-0700 [INFO] secrets.kv.kv_cd63d9f9: upgrading keys finished + ... + ``` -Leave this server process running in the background. In a separate terminal window, connect to the Linode instance with another shell session. + Leave this server process running in the background. -### Setting and Retrieving a Test Secret +1. Open a separate terminal window and connect to the Linode instance with another shell session: -Use `curl` requests to test setting and retrieving a test secret. OpenBao expects certain variables to be set for every request. + ```command + ssh -l {{< placeholder "USERNAME" >}} {{< placeholder "IP_ADDRESS" >}} + ``` -1. Instead of setting these variables repeatedly with each command, set the following environment variables in the shell: +1. OpenBao expects certain variables to be set for every request. Instead of setting these variables repeatedly with each command, set the following environment variables in the shell: ```command export VAULT_TOKEN="this-is-my-test-dev-token" @@ -335,7 +253,7 @@ Use `curl` requests to test setting and retrieving a test secret. OpenBao expect 1. Return to the original terminal session with OpenBao running and press Ctrl+C to stop OpenBao. -## Step 4: Run OpenBao as a Service +## Run OpenBao as a Service In a real-world use case, OpenBao should run as a service managed by a tool such as `systemd`. @@ -408,7 +326,7 @@ In a real-world use case, OpenBao should run as a service managed by a tool such systemctl enable openbao ``` -## Step 5: Configure OpenBao for External Access +## Configure OpenBao for External Access Although OpenBao is now running as a service on the Linode Compute Instance, it is still not ready for use. Use the [OpenBao CLI](https://openbao.org/docs/commands/) to interact with the running server, retrieving its current status: @@ -650,7 +568,7 @@ Enable and configure secure authentication methods such as: - LDAP - OpenID Connect (OIDC) -TLS certificate authentication provides secure, mutual TLS verification for sensitive environments, while AppRole allows service accounts and applications to securely authenticate without human interaction. +TLS certificate authentication provides secure, mutual TLS verification for sensitive environments. Meanwhile, AppRole allows service accounts and applications to securely authenticate without human interaction. For LDAP or OIDC deployments, enforce Multi Factor Authentication (MFA) for human operators to enhance security if supported. From 9bfd6b21f3b0103b42915deadca5a2ef42dc578e Mon Sep 17 00:00:00 2001 From: Adam Overa Date: Fri, 25 Apr 2025 11:18:08 -0400 Subject: [PATCH 4/5] Edit 3 --- .../index.md | 112 +++++++++--------- 1 file changed, 55 insertions(+), 57 deletions(-) diff --git a/docs/guides/security/secrets-management/deploying-openbao-on-a-linode-compute-instance/index.md b/docs/guides/security/secrets-management/deploying-openbao-on-a-linode-compute-instance/index.md index 7d486a66cb9..119b0f333c3 100644 --- a/docs/guides/security/secrets-management/deploying-openbao-on-a-linode-compute-instance/index.md +++ b/docs/guides/security/secrets-management/deploying-openbao-on-a-linode-compute-instance/index.md @@ -4,26 +4,21 @@ title: "Deploying OpenBao on a Linode Compute Instance" description: "Deploy OpenBao on a Linode Compute Instance using Ubuntu 24.04 LTS and the Linode CLI. Learn how to install, configure, unseal, and securely manage secrets." authors: ["Akamai"] contributors: ["Akamai"] -published: 2025-04-17 +published: 2025-04-25 keywords: ['openbao','openbao linode','openbao ubuntu install','secrets management linode','how to install openbao','secure secrets storage linux','openbao ubuntu 24.04','deploy openbao cli','install vault alternative','hashicorp vault fork','openbao setup tutorial','linux secrets manager','initialize openbao server','openbao unseal process','openbao vs vault','openbao config hcl','how to deploy openbao on a linode instance','secure secrets management with openbao','install and configure openbao on ubuntu','openbao systemd service setup','openbao cli secret storage example','openbao firewall and api access configuration','openbao key value store example','setting up openbao secrets engine'] license: '[CC BY-ND 4.0](https://creativecommons.org/licenses/by-nd/4.0)' --- -[OpenBao](https://openbao.org/) is an open source secrets management solution and fork of HashiCorp Vault. While our [OpenBao Marketplace app](/docs/marketplace-docs/guides/openbao/) offers one-click deployment, this guide walks through a manual installation on a single Ubuntu 24.04 LTS compute instance. +[OpenBao](https://openbao.org/) is an open source secrets management solution and fork of HashiCorp Vault. While our [OpenBao Marketplace app](/docs/marketplace-docs/guides/openbao/) offers one-click deployment, this guide walks through a manual installation on a single Ubuntu 24.04 LTS Compute Instance. ## Before You Begin -1. If you do not already have a virtual machine to use, see our [Getting Started with Linode](/docs/products/platform/get-started/) and [Creating a Compute Instance](/docs/products/compute/compute-instances/guides/create/) guides. While OpenBao does not provide explicit hardware recommendations, its architecture closely mirrors that of Vault. As such, this guide uses a `g6-standard-4` Linode (8 GB RAM, 4 vCPUs, 160 GB storage), which aligns with Vault’s recommended specs for a small cluster: - - - 2–4 CPU cores - - 8–16 GB RAM - - 100+ GB disk - - 75+ Mbps network bandwidth +1. If you do not already have a virtual machine to use, see our [Getting Started with Linode](/docs/products/platform/get-started/) and [Creating a Compute Instance](/docs/products/compute/compute-instances/guides/create/) guides. While OpenBao does not provide explicit hardware recommendations, its architecture closely mirrors that of Vault. Based on [Vault’s recommended specifications](https://developer.hashicorp.com/vault/tutorials/day-one-raft/raft-reference-architecture#hardware-sizing-for-vault-servers), this guide uses a Shared CPU **Linode 8 GB** plan (`g6-standard-4`) with 4 vCPUs and 160 GB of storage. {{< note title="Provisioning Compute Instances with the Linode CLI" type="secondary" isCollapsible="yes" >}} - Use these steps if you prefer to use the [Linode CLI](https://github.com/linode/linode-cli) to provision resources. + Use these steps if you prefer to use the [Linode CLI](https://techdocs.akamai.com/cloud-computing/docs/install-and-configure-the-cli) to provision resources. - The following command creates a Linode 8 GB compute instance (`g6-standard-4`) running Ubuntu 24.04 LTS (`linode/ubuntu24.04`) in the Miami datacenter (`us-mia`): + The following command creates a Linode 8 GB Compute Instance (`g6-standard-4`) running Ubuntu 24.04 LTS (`linode/ubuntu24.04`) in the Miami datacenter (`us-mia`): ```command linode-cli linodes create \ @@ -45,12 +40,6 @@ license: '[CC BY-ND 4.0](https://creativecommons.org/licenses/by-nd/4.0)' 1. Follow our [Setting Up and Securing a Compute Instance](/docs/products/compute/compute-instances/guides/set-up-and-secure/) guide to update your system and create a limited user account. You may also wish to set the timezone, configure your hostname, and harden SSH access. -1. Follow our [Use SSH Public Key Authentication on Linux, macOS, and Windows](https://www.linode.com/docs/guides/use-public-key-authentication-with-ssh/#generate-an-ssh-key-pair) guide to generate an SSH key pair. - -1. Create a personal access token using the instructions in our [Manage personal access tokens](https://techdocs.akamai.com/cloud-computing/docs/manage-personal-access-tokens) guide. - -1. Install the Linode CLI using the instructions in our [Install and configure the CLI](https://techdocs.akamai.com/cloud-computing/docs/install-and-configure-the-cli) guide. - {{< note >}} This guide is written for a non-root user. Commands that require elevated privileges are prefixed with `sudo`. If you’re not familiar with the `sudo` command, see the [Users and Groups](/docs/guides/linux-users-and-groups/) guide. {{< /note >}} @@ -60,7 +49,7 @@ This guide is written for a non-root user. Commands that require elevated privil 1. SSH into the newly provisioned Linode as a user with `sudo` privileges: ```command - ssh -l {{< placeholder "USERNAME" >}} {{< placeholder "IP_ADDRESS" >}} + ssh {{< placeholder "USERNAME" >}}@{{< placeholder "IP_ADDRESS" >}} ``` 1. Download the latest appropriate version of OpenBao from the [downloads page](https://openbao.org/downloads/). In this case, `v2.2.0` of the AMD 64-bit Debian package: @@ -89,7 +78,11 @@ This guide is written for a non-root user. Commands that require elevated privil 1. Verify if the install is successful: ```command - bao -h + bao -v + ``` + + ```output + OpenBao v2.2.0 (a2bf51c891680240888f7363322ac5b2d080bb23), built 2025-03-05T13:07:08Z ``` {{< note title="Verify Swap Memory Limits" >}} @@ -123,9 +116,9 @@ Verify that `MemorySwapMax=0` appears in the results under the `Service` heading OpenBao provides a development server that you can use to verify settings and explore OpenBao features. -{{< caution >}} +{{< note type="warning" >}} The development server runs entirely in memory and is not suitable for production use. Data is not persisted between restarts, and TLS is disabled. -{{< /caution >}} +{{< /note >}} 1. Run this command to start the server in development mode and set a primary key: @@ -169,7 +162,7 @@ The development server runs entirely in memory and is not suitable for productio 1. Open a separate terminal window and connect to the Linode instance with another shell session: ```command - ssh -l {{< placeholder "USERNAME" >}} {{< placeholder "IP_ADDRESS" >}} + ssh {{< placeholder "USERNAME" >}}@{{< placeholder "IP_ADDRESS" >}} ``` 1. OpenBao expects certain variables to be set for every request. Instead of setting these variables repeatedly with each command, set the following environment variables in the shell: @@ -180,7 +173,7 @@ The development server runs entirely in memory and is not suitable for productio export OPENBAO_PORT="8200" ``` -1. Send a request with `curl` to set a secret as a key-value pair. +1. Send a request with `curl` to store a secret as a key-value pair. ```command curl -X POST \ @@ -278,15 +271,15 @@ In a real-world use case, OpenBao should run as a service managed by a tool such sudo nano /etc/openbao/openbao.hcl ``` - Edit the file to create a publicly available service with the following contents: + Replace the contents of the file with the following minimal configuration to run OpenBao as a publicly available service without TLS: - ```file {title="/etc/openbao/openbao.hcl"} + ```file {title="/etc/openbao/openbao.hcl" lang="hcl"} ui = false storage "file" { path = "/opt/openbao/data" } - api_addr = "http://127.0.0.1:8200" + api_addr = "http://0.0.0.0:8200" listener "tcp" { address = "0.0.0.0:8200" @@ -294,19 +287,26 @@ In a real-world use case, OpenBao should run as a service managed by a tool such } ``` - {{< note >}} + {{< note type="warning">}} The configuration above is insecure and not suitable for production use. It is only for demonstration purposes of this tutorial. For a production-grade deployment, reference the [configuration](#configuration) near the end of this guide. {{< /note >}} When done, press CTRL+X, followed by Y then Enter to save the file and exit `nano`. -1. Start the OpenBao service, then check its status. +1. Start the OpenBao service: ```command systemctl start openbao + ``` + +1. Recheck its status: + + ```command systemctl status openbao ``` + The output should now show `active (running)`: + ```output ● openbao.service - "OpenBao - A tool for managing secrets" Loaded: loaded (/usr/lib/systemd/system/openbao.service; disabled; preset: enabled) @@ -320,7 +320,9 @@ In a real-world use case, OpenBao should run as a service managed by a tool such └─642487 /usr/bin/bao server -config=/etc/openbao/openbao.hcl ``` -1. Run the following command to start the service automatically whenever the Linode server boots: + Press the Q key to exit the status output and return to the terminal prompt. + +1. Enable the service to start automatically on boot: ```command systemctl enable openbao @@ -328,7 +330,7 @@ In a real-world use case, OpenBao should run as a service managed by a tool such ## Configure OpenBao for External Access -Although OpenBao is now running as a service on the Linode Compute Instance, it is still not ready for use. Use the [OpenBao CLI](https://openbao.org/docs/commands/) to interact with the running server, retrieving its current status: +Although OpenBao is now running as a service on the Linode Compute Instance, additional configuration is required before it can be used. Use the [OpenBao CLI](https://openbao.org/docs/commands/) to interact with the running server, retrieving its current status: ```command bao status --address=http://0.0.0.0:8200 @@ -350,7 +352,7 @@ Storage Type file HA Enabled false ``` -The status shows that the server has not been initialized, and it is sealed. Both of these issues must be resolved before the server can be interacted with. +This shows that the server has not been initialized, and is sealed. Both of these issues must be resolved before you can interact with the server. ### Initialize the Server @@ -360,6 +362,10 @@ The status shows that the server has not been initialized, and it is sealed. Bot export BAO_ADDR=http://0.0.0.0:8200 ``` + {{< note type="warning">}} + For simplicity, this tutorial sets `BAO_ADDR` to `http://0.0.0.0:8200`. In production deployments, it should match the public IP address or domain name used to connect to the server. + {{< /note >}} + 1. Initialize the server: ```command @@ -446,13 +452,13 @@ Store the unseal keys and initial root token in a secure location. HA Enabled false ``` -1. Unseal the vault for the third and final time, using another unsealing key when prompted: +1. Unseal the vault for the third and final time, using yet another unsealing key when prompted: ```command bao operator unseal ``` - After unsealing has been executed three times (with three different unseal keys), the OpenBao status shows the following: + After unsealing the vault with three different unseal keys, OpenBao should report the following status: ```output Unseal Key (will be hidden): IrPLoIFrl2ol7dF4mA9C+kTaE44qogwT/pZ+kTrS7M4j @@ -475,10 +481,10 @@ The vault has now been initialized and unsealed. ### Authenticate the CLI -To authenticate the CLI with the server, use the `bao login` command with the root token provided upon vault initialization. +To authenticate the CLI with the server, use the `bao login` command with the initial root token provided upon vault initialization. ```command -bao login -method=token s.V82B9tynwZkQtDyOne7PJ1IS +bao login -method=token {{< placeholder "INITIAL_ROOT_TOKEN" >}} ``` ```output @@ -499,7 +505,7 @@ policies ["root"] ### Enable Key-Value Storage -Lastly, enable a key-value store in OpenBao for stashing and retrieving secrets via the API. +Lastly, enable a key-value store in OpenBao for storing and retrieving secrets via the API. To do this, run the following command: @@ -511,26 +517,27 @@ bao secrets enable kv Success! Enabled the kv secrets engine at: kv/ ``` -### Setting and Retrieving a Secret Remotely Over HTTP +### Storing and Retrieving a Secret Remotely Over HTTP OpenBao can now be accessed externally via the API. Ensure that any firewall on the Linode Compute Instance allows traffic on port `8200`. -1. From a remote machine, set a new secret, providing the root token for authentication. +1. From a remote machine, store a new secret, providing the initial root token for authentication. ```command curl -X POST \ - --header "X-Vault-Token: s.eZTodpa8pErpfQGDyPPUqVME" \ + --header "X-Vault-Token: {{< placeholder "INITIAL_ROOT_TOKEN" >}}" \ --header "Content-Type: application/json" \ --data '{"data": {"hello": "world"}}' \ - http://{{< placeholder "LINODE_IP" >}}:8200/v1/kv/test-secret + http://{{< placeholder "OPENBAO_LINODE_IP" >}}:8200/v1/kv/test-secret ``` 1. Get the newly created secret to verify it was stored properly. ```command curl -X GET \ - --header "X-Vault-Token: s.eZTodpa8pErpfQGDyPPUqVME" \ - http://{{< placeholder "LINODE_IP" >}}:8200/v1/kv/test-secret + --header "X-Vault-Token: {{< placeholder "INITIAL_ROOT_TOKEN" >}}" \ + http://{{< placeholder "OPENBAO_LINODE_IP" >}}:8200/v1/kv/test-secret \ + | json_pp ``` ```output @@ -550,11 +557,11 @@ OpenBao can now be accessed externally via the API. Ensure that any firewall on ## Considerations for Production Deployments -To harden an OpenBao server for production use, several additional steps are recommended. +Several additional steps are recommended to harden an OpenBao server for production use. ### Auto Unseal -OpenBao starts with its vault in a sealed state, meaning all data is encrypted. For more information on the seal/unseal concept in OpenBao, see their [documentation](https://openbao.org/docs/concepts/seal/). +OpenBao starts with its vault in a sealed state, meaning all data is encrypted. See the [OpenBao documentation](https://openbao.org/docs/concepts/seal/) for more information on the seal/unseal concept. In production, [auto-unseal](https://openbao.org/docs/concepts/seal/#auto-unseal) is recommended to minimize manual operations that could lead to mistakes or exposure. Auto-unseal is configured using cloud-based key management systems to ensure the unsealing key is never exposed directly. @@ -568,22 +575,13 @@ Enable and configure secure authentication methods such as: - LDAP - OpenID Connect (OIDC) -TLS certificate authentication provides secure, mutual TLS verification for sensitive environments. Meanwhile, AppRole allows service accounts and applications to securely authenticate without human interaction. - -For LDAP or OIDC deployments, enforce Multi Factor Authentication (MFA) for human operators to enhance security if supported. +TLS certificate authentication provides secure, mutual TLS verification for sensitive environments. Meanwhile, AppRole allows service accounts and applications to securely authenticate without human interaction. For LDAP or OIDC deployments, enforce Multi Factor Authentication (MFA) for human operators to enhance security, if supported. ### Configuration -OpenBao supports two configuration formats: - -1. HashiCorp Configuration Language (HCL) -2. JSON - -Properly configuring the OpenBao server is essential to ensure a secure production environment. The main configuration aspects include the UI, TLS certificate, and address/port settings. - -A default production configuration HCL file may look like this: +OpenBao supports two configuration formats: HashiCorp Configuration Language (HCL) and JSON. Properly configuring the OpenBao server is essential to ensure a secure production environment. The main configuration aspects include the UI, TLS certificate, and address/port settings. A default production configuration HCL file may look like this: -```file +```file {title="/etc/openbao/openbao.hcl" lang="hcl"} ui = false storage "file" { @@ -598,13 +596,13 @@ listener "tcp" { } ``` -In production, disabling or securing the UI is crucial, as it exposes OpenBao's management interface—which could be exploited if left unprotected. If the UI is required, limit its exposure by restricting access to trusted IP ranges or VPN users only. Implement strong authentication methods like OIDC for access control. +In production, disabling or securing the UI is crucial, as it exposes OpenBao's management interface, which could be exploited if left unprotected. If the UI is required, limit its exposure by restricting access to trusted IP ranges or VPN users only. Implement strong authentication methods like OIDC for access control. If the UI is not required, set `ui = false`. TLS certificates encrypt traffic to and from the OpenBao server, ensuring data confidentiality and integrity. Using a valid, trusted TLS certificate prevents man-in-the-middle attacks and validates the server's identity to clients. Obtain a certificate from a trusted Certificate Authority (CA) and configure OpenBao to use it as shown in the example configuration above. -For environments using an internal CA, ensure that all clients trust the CA, and renew the certificates periodically to avoid downtime. +For environments using an internal CA, ensure that all clients trust it, and renew the certificates periodically to avoid downtime. Controlling the address and ports on which OpenBao listens reduces exposure and minimizes the risk of unauthorized access. Limit OpenBao's exposure by binding it to an internal IP address (such as `127.0.0.1` or a specific internal network IP). Ensure that OpenBao only listens on the necessary port (default is `8200`). Use firewall rules to restrict access to this port to authorized networks or users only. From d3de38d0f2466eba42ceaf11d035ed783baef71d Mon Sep 17 00:00:00 2001 From: jddocs Date: Tue, 6 May 2025 15:02:09 -0400 Subject: [PATCH 5/5] update title and slug, copy edit --- .../index.md | 106 +++++++++--------- 1 file changed, 55 insertions(+), 51 deletions(-) rename docs/guides/security/secrets-management/{deploying-openbao-on-a-linode-compute-instance => deploying-openbao-on-a-linode-instance}/index.md (73%) diff --git a/docs/guides/security/secrets-management/deploying-openbao-on-a-linode-compute-instance/index.md b/docs/guides/security/secrets-management/deploying-openbao-on-a-linode-instance/index.md similarity index 73% rename from docs/guides/security/secrets-management/deploying-openbao-on-a-linode-compute-instance/index.md rename to docs/guides/security/secrets-management/deploying-openbao-on-a-linode-instance/index.md index 119b0f333c3..266f2ae3bb5 100644 --- a/docs/guides/security/secrets-management/deploying-openbao-on-a-linode-compute-instance/index.md +++ b/docs/guides/security/secrets-management/deploying-openbao-on-a-linode-instance/index.md @@ -1,19 +1,23 @@ --- -slug: deploying-openbao-on-a-linode-compute-instance -title: "Deploying OpenBao on a Linode Compute Instance" -description: "Deploy OpenBao on a Linode Compute Instance using Ubuntu 24.04 LTS and the Linode CLI. Learn how to install, configure, unseal, and securely manage secrets." +slug: deploying-openbao-on-a-linode-instance +title: "Deploying OpenBao on a Linode Instance" +description: "Deploy OpenBao on a Linode instance using Ubuntu 24.04 LTS and the Linode CLI. Learn how to install, configure, unseal, and securely manage secrets." authors: ["Akamai"] contributors: ["Akamai"] -published: 2025-04-25 +published: 2025-05-06 keywords: ['openbao','openbao linode','openbao ubuntu install','secrets management linode','how to install openbao','secure secrets storage linux','openbao ubuntu 24.04','deploy openbao cli','install vault alternative','hashicorp vault fork','openbao setup tutorial','linux secrets manager','initialize openbao server','openbao unseal process','openbao vs vault','openbao config hcl','how to deploy openbao on a linode instance','secure secrets management with openbao','install and configure openbao on ubuntu','openbao systemd service setup','openbao cli secret storage example','openbao firewall and api access configuration','openbao key value store example','setting up openbao secrets engine'] license: '[CC BY-ND 4.0](https://creativecommons.org/licenses/by-nd/4.0)' --- -[OpenBao](https://openbao.org/) is an open source secrets management solution and fork of HashiCorp Vault. While our [OpenBao Marketplace app](/docs/marketplace-docs/guides/openbao/) offers one-click deployment, this guide walks through a manual installation on a single Ubuntu 24.04 LTS Compute Instance. +[OpenBao](https://openbao.org/) is an open source secrets management solution and fork of HashiCorp Vault. This guide walks through a manual installation of OpenBao on a Linode instance with an Ubuntu 24.04 distribution. + +If you prefer an automated one-click deployment, see our [OpenBao Marketplace app](/docs/marketplace-docs/guides/openbao/). ## Before You Begin -1. If you do not already have a virtual machine to use, see our [Getting Started with Linode](/docs/products/platform/get-started/) and [Creating a Compute Instance](/docs/products/compute/compute-instances/guides/create/) guides. While OpenBao does not provide explicit hardware recommendations, its architecture closely mirrors that of Vault. Based on [Vault’s recommended specifications](https://developer.hashicorp.com/vault/tutorials/day-one-raft/raft-reference-architecture#hardware-sizing-for-vault-servers), this guide uses a Shared CPU **Linode 8 GB** plan (`g6-standard-4`) with 4 vCPUs and 160 GB of storage. +1. If you do not already have an account or virtual machine to use, see our [Get Started](https://techdocs.akamai.com/cloud-computing/docs/getting-started) and [Create a Compute Instance](https://techdocs.akamai.com/cloud-computing/docs/create-a-compute-instance) guides to create an Akamai Cloud account, familiarize yourself with Cloud Manager, and provision a new Compute Instance. + + While OpenBao does not provide explicit hardware recommendations, its architecture closely mirrors that of HashiCorp Vault. Based on [Vault’s recommended specifications](https://developer.hashicorp.com/vault/tutorials/day-one-raft/raft-reference-architecture#hardware-sizing-for-vault-servers), this guide uses a Shared CPU **Linode 8 GB** plan (`g6-standard-4`) with 4 vCPUs and 160 GB of storage. Deployment time may vary. {{< note title="Provisioning Compute Instances with the Linode CLI" type="secondary" isCollapsible="yes" >}} Use these steps if you prefer to use the [Linode CLI](https://techdocs.akamai.com/cloud-computing/docs/install-and-configure-the-cli) to provision resources. @@ -38,21 +42,23 @@ license: '[CC BY-ND 4.0](https://creativecommons.org/licenses/by-nd/4.0)' - The `--label` argument specifies the name of the new server (e.g. `openbao-linode`). {{< /note >}} -1. Follow our [Setting Up and Securing a Compute Instance](/docs/products/compute/compute-instances/guides/set-up-and-secure/) guide to update your system and create a limited user account. You may also wish to set the timezone, configure your hostname, and harden SSH access. +1. Follow our [Set Up and Secure a Compute Instance](https://techdocs.akamai.com/cloud-computing/docs/set-up-and-secure-a-compute-instance) guide to update your system and create a limited user account. You may also wish to set the timezone, configure your hostname, and harden SSH access. -{{< note >}} -This guide is written for a non-root user. Commands that require elevated privileges are prefixed with `sudo`. If you’re not familiar with the `sudo` command, see the [Users and Groups](/docs/guides/linux-users-and-groups/) guide. -{{< /note >}} + {{< note >}} + This guide is written for a non-root user. Commands that require elevated privileges are prefixed with `sudo`. If you’re not familiar with the `sudo` command, see the [Users and Groups](/docs/guides/linux-users-and-groups/) guide. + {{< /note >}} ## Install OpenBao -1. SSH into the newly provisioned Linode as a user with `sudo` privileges: +Log into your Linode instance, and install the OpenBao package. + +1. SSH into the newly provisioned Linode as a user with `sudo` privileges, replacing {{< placeholder "USERNAME" >}} with your username and {{< placeholder "IP_ADDRESS" >}} with the IP address of your Linode: ```command ssh {{< placeholder "USERNAME" >}}@{{< placeholder "IP_ADDRESS" >}} ``` -1. Download the latest appropriate version of OpenBao from the [downloads page](https://openbao.org/downloads/). In this case, `v2.2.0` of the AMD 64-bit Debian package: +1. Download the latest appropriate version of OpenBao from the [downloads page](https://openbao.org/downloads/). This tutorial uses `v2.2.0` of the AMD 64-bit Debian package: ```command wget https://github.com/openbao/openbao/releases/download/v2.2.0/bao_2.2.0_linux_amd64.deb @@ -75,7 +81,7 @@ This guide is written for a non-root user. Commands that require elevated privil OpenBao TLS key and self-signed certificate have been generated in '/opt/openbao/tls'. ``` -1. Verify if the install is successful: +1. Verify successful installation by checking the OpenBao version: ```command bao -v @@ -84,8 +90,7 @@ This guide is written for a non-root user. Commands that require elevated privil ```output OpenBao v2.2.0 (a2bf51c891680240888f7363322ac5b2d080bb23), built 2025-03-05T13:07:08Z ``` - -{{< note title="Verify Swap Memory Limits" >}} +### Verify Swap Memory Limits For Linux distributions, ensure that the OpenBao service settings do not impose a soft limit on Swap memory. To check this with a systemd-based Linux distro, use the following command: @@ -110,7 +115,6 @@ WantedBy=multi-user.target ``` Verify that `MemorySwapMax=0` appears in the results under the `Service` heading. -{{< /note >}} ## Test the OpenBao Development Server @@ -120,11 +124,11 @@ OpenBao provides a development server that you can use to verify settings and ex The development server runs entirely in memory and is not suitable for production use. Data is not persisted between restarts, and TLS is disabled. {{< /note >}} -1. Run this command to start the server in development mode and set a primary key: +1. Run this command to start the server in development mode and set a primary key. Replace {{< placeholder "MY_DEV_TOKEN" >}} with a secure key that you have created: ```command bao server -dev \ - -dev-root-token-id="this-is-my-test-dev-token" + -dev-root-token-id="{{< placeholder "MY_DEV_TOKEN" >}}" ``` The OpenBao server configuration should print to the screen along with a tail of the logs: @@ -159,27 +163,27 @@ The development server runs entirely in memory and is not suitable for productio Leave this server process running in the background. -1. Open a separate terminal window and connect to the Linode instance with another shell session: +1. Open a separate terminal window and connect to the Linode instance using another shell session: ```command ssh {{< placeholder "USERNAME" >}}@{{< placeholder "IP_ADDRESS" >}} ``` -1. OpenBao expects certain variables to be set for every request. Instead of setting these variables repeatedly with each command, set the following environment variables in the shell: +1. OpenBao expects certain variables to be set for every request. Rather than setting these variables repeatedly with each command, set the following environment variables in the shell: ```command - export VAULT_TOKEN="this-is-my-test-dev-token" + export VAULT_TOKEN="{{< placeholder "MY_DEV_TOKEN" >}}" export OPENBAO_IP="127.0.0.1" export OPENBAO_PORT="8200" ``` -1. Send a request with `curl` to store a secret as a key-value pair. +1. Send a request with `curl` to store a secret as a key-value pair. Replace {{< placeholder "VAULT_PASSWORD" >}} with a secure password. ```command curl -X POST \ --header "X-Vault-Token: $VAULT_TOKEN" \ --header "Content-Type: application/json" \ - --data '{"data": {"password": "OpenBao123"}}' \ + --data '{"data": {"password": "{{< placeholder "VAULT_PASSWORD" >}}"}}' \ http://$OPENBAO_IP:$OPENBAO_PORT/v1/secret/data/test-password-1 \ | json_pp ``` @@ -205,7 +209,7 @@ The development server runs entirely in memory and is not suitable for productio The development server is only exposed on `localhost`. Therefore, this command must be run on the server itself. Authentication is handled by supplying the `X-Vault-Token` header. The structure of the URI follows the pattern `/v1/secret/data/{{< placeholder "SECRET_NAME" >}}`. This `POST` request stores the key-value pair at location `/data/{{< placeholder "SECRET_NAME" >}}`. - The response provides metadata regarding the secret stored in the `data` object, including versioning (how many times this secret has been updated). + The response provides metadata regarding the secret stored in the `data` object, including versioning when the secret gets updated. 1. To retrieve the secret, send the following request: @@ -244,11 +248,11 @@ The development server runs entirely in memory and is not suitable for productio 1. When done, you can close the second terminal session. -1. Return to the original terminal session with OpenBao running and press Ctrl+C to stop OpenBao. +1. Return to the original terminal session with OpenBao running, and press Ctrl+C to stop OpenBao. ## Run OpenBao as a Service -In a real-world use case, OpenBao should run as a service managed by a tool such as `systemd`. +In a real-world use case, OpenBao is ideally run as a service managed by a tool like `systemd`. 1. Run the following `systemctl` command to check the status of the OpenBao service: @@ -256,7 +260,7 @@ In a real-world use case, OpenBao should run as a service managed by a tool such systemctl status openbao ``` - This shows that `systemd` is aware of the OpenBao service but it has not been started: + This shows that `systemd` is aware of the OpenBao service, but it has not been started: ```output ○ openbao.service - "OpenBao - A tool for managing secrets" @@ -265,7 +269,7 @@ In a real-world use case, OpenBao should run as a service managed by a tool such Docs: https://github.com/openbao/openbao/tree/main/website/content/docs ``` -1. Edit the OpenBao configuration file, located at `/etc/openbao/openbao.hcl`, in a command line text editor such as `nano`: +1. Edit the OpenBao configuration file located at `/etc/openbao/openbao.hcl` in a command line text editor such as `nano`: ```command sudo nano /etc/openbao/openbao.hcl @@ -288,7 +292,7 @@ In a real-world use case, OpenBao should run as a service managed by a tool such ``` {{< note type="warning">}} - The configuration above is insecure and not suitable for production use. It is only for demonstration purposes of this tutorial. For a production-grade deployment, reference the [configuration](#configuration) near the end of this guide. + The configuration above is insecure and not suitable for production use. It is only for demonstration purposes of this tutorial. For a production-grade deployment, reference the [**Configuration**](#configuration) section at the end of this guide. {{< /note >}} When done, press CTRL+X, followed by Y then Enter to save the file and exit `nano`. @@ -322,7 +326,7 @@ In a real-world use case, OpenBao should run as a service managed by a tool such Press the Q key to exit the status output and return to the terminal prompt. -1. Enable the service to start automatically on boot: +1. Run the following command to enable the service to start automatically on boot: ```command systemctl enable openbao @@ -330,7 +334,7 @@ In a real-world use case, OpenBao should run as a service managed by a tool such ## Configure OpenBao for External Access -Although OpenBao is now running as a service on the Linode Compute Instance, additional configuration is required before it can be used. Use the [OpenBao CLI](https://openbao.org/docs/commands/) to interact with the running server, retrieving its current status: +Although OpenBao is now running as a service on the Linode instance, additional configuration is required before it can be used. Use the [OpenBao CLI](https://openbao.org/docs/commands/) (`bao`) to interact with the running server, retrieving its current status: ```command bao status --address=http://0.0.0.0:8200 @@ -352,7 +356,7 @@ Storage Type file HA Enabled false ``` -This shows that the server has not been initialized, and is sealed. Both of these issues must be resolved before you can interact with the server. +This shows that the server has not been initialized and is sealed. Both of these issues must be resolved before you can interact with the server. ### Initialize the Server @@ -363,7 +367,7 @@ This shows that the server has not been initialized, and is sealed. Both of thes ``` {{< note type="warning">}} - For simplicity, this tutorial sets `BAO_ADDR` to `http://0.0.0.0:8200`. In production deployments, it should match the public IP address or domain name used to connect to the server. + This tutorial sets `BAO_ADDR` to `http://0.0.0.0:8200` for demonstration purposes. In production deployments, it should match the public IP address or domain name used to connect to the server. {{< /note >}} 1. Initialize the server: @@ -393,10 +397,12 @@ This shows that the server has not been initialized, and is sealed. Both of thes existing unseal keys shares. See "bao operator rekey" for more information. ``` -Store the unseal keys and initial root token in a secure location. + Store the values for each `Unseal Key` and `Initial Root Token` in a secure location. ### Unseal the Vault (Three Times for Quorum) +When unsealing a vault, the `bao operator unseal` command must be performed a total of three times using different `Unseal Key` values each time. This is the default quorum for OpenBao's unsealing process. + 1. Use the following command to begin unsealing the vault: ```command @@ -409,7 +415,7 @@ Store the unseal keys and initial root token in a secure location. Unseal Key (will be hidden): SNP+diKq1L2MYYre8pn+PIqSEn/nK76n7C6coUoVby4g ``` - After this first execution, the unseal progress shows `1/3`: + After this first execution, the `Unseal Progress` output value shows `1/3`: ```output Key Value @@ -427,8 +433,6 @@ Store the unseal keys and initial root token in a secure location. HA Enabled false ``` - Unsealing must be done a total of three times, as this is the default quorum for OpenBao unsealing. - 1. Unseal the vault again, but enter a different unseal key when prompted: ```command @@ -477,11 +481,11 @@ Store the unseal keys and initial root token in a secure location. HA Enabled false ``` -The vault has now been initialized and unsealed. + The vault has now been initialized and unsealed. ### Authenticate the CLI -To authenticate the CLI with the server, use the `bao login` command with the initial root token provided upon vault initialization. +To authenticate the CLI with the server, use the `bao login` command with the `Initial Root Token` output value provided upon vault initialization. ```command bao login -method=token {{< placeholder "INITIAL_ROOT_TOKEN" >}} @@ -505,9 +509,7 @@ policies ["root"] ### Enable Key-Value Storage -Lastly, enable a key-value store in OpenBao for storing and retrieving secrets via the API. - -To do this, run the following command: +Lastly, run the following command to enable a key-value store in OpenBao for storing and retrieving secrets via the API: ```command bao secrets enable kv @@ -519,9 +521,9 @@ Success! Enabled the kv secrets engine at: kv/ ### Storing and Retrieving a Secret Remotely Over HTTP -OpenBao can now be accessed externally via the API. Ensure that any firewall on the Linode Compute Instance allows traffic on port `8200`. +OpenBao can now be accessed externally via the API. Ensure that any firewall on the Linode instance allows traffic on port `8200`. -1. From a remote machine, store a new secret, providing the initial root token for authentication. +1. From a remote machine, store a new secret, providing the `Initial Root Token` for authentication. ```command curl -X POST \ @@ -561,7 +563,7 @@ Several additional steps are recommended to harden an OpenBao server for product ### Auto Unseal -OpenBao starts with its vault in a sealed state, meaning all data is encrypted. See the [OpenBao documentation](https://openbao.org/docs/concepts/seal/) for more information on the seal/unseal concept. +OpenBao starts with its vault in a sealed state, meaning all data is encrypted. For more information on the seal and unseal concepts, see the [OpenBao documentation](https://openbao.org/docs/concepts/seal/). In production, [auto-unseal](https://openbao.org/docs/concepts/seal/#auto-unseal) is recommended to minimize manual operations that could lead to mistakes or exposure. Auto-unseal is configured using cloud-based key management systems to ensure the unsealing key is never exposed directly. @@ -572,14 +574,16 @@ Enable and configure secure authentication methods such as: - AppRole - JSON Web Tokens (JWT) - TLS certificates -- LDAP +- Lightweight directory access protocol (LDAP) - OpenID Connect (OIDC) -TLS certificate authentication provides secure, mutual TLS verification for sensitive environments. Meanwhile, AppRole allows service accounts and applications to securely authenticate without human interaction. For LDAP or OIDC deployments, enforce Multi Factor Authentication (MFA) for human operators to enhance security, if supported. +TLS certificate authentication provides secure, mutual TLS verification for sensitive environments. Meanwhile, AppRole allows service accounts and applications to securely authenticate without human interaction. For LDAP or OIDC deployments, enforce multi-factor authentication (MFA) for human operators to enhance security, if supported. ### Configuration -OpenBao supports two configuration formats: HashiCorp Configuration Language (HCL) and JSON. Properly configuring the OpenBao server is essential to ensure a secure production environment. The main configuration aspects include the UI, TLS certificate, and address/port settings. A default production configuration HCL file may look like this: +OpenBao supports two configuration formats: [HashiCorp Configuration Language](https://developer.hashicorp.com/terraform/language/syntax/configuration) (HCL) and JSON. + +Properly configuring your OpenBao server is essential to ensuring a secure production environment. The main configuration aspects include the UI, TLS certificate, and address/port settings. A default production configuration HCL file may look like this: ```file {title="/etc/openbao/openbao.hcl" lang="hcl"} ui = false @@ -600,10 +604,10 @@ In production, disabling or securing the UI is crucial, as it exposes OpenBao's If the UI is not required, set `ui = false`. -TLS certificates encrypt traffic to and from the OpenBao server, ensuring data confidentiality and integrity. Using a valid, trusted TLS certificate prevents man-in-the-middle attacks and validates the server's identity to clients. Obtain a certificate from a trusted Certificate Authority (CA) and configure OpenBao to use it as shown in the example configuration above. +TLS or SSL certificates encrypt traffic to and from the OpenBao server, ensuring data confidentiality and integrity. Using a valid, trusted TLS certificate prevents man-in-the-middle attacks and validates the server's identity to clients. Obtain a certificate from a trusted Certificate Authority (CA) and configure OpenBao to use it as shown in the example configuration above. For environments using an internal CA, ensure that all clients trust it, and renew the certificates periodically to avoid downtime. -Controlling the address and ports on which OpenBao listens reduces exposure and minimizes the risk of unauthorized access. Limit OpenBao's exposure by binding it to an internal IP address (such as `127.0.0.1` or a specific internal network IP). Ensure that OpenBao only listens on the necessary port (default is `8200`). Use firewall rules to restrict access to this port to authorized networks or users only. +Controlling the address and ports on which OpenBao listens reduces exposure and minimizes the risk of unauthorized access. Limit OpenBao's exposure by binding it to an internal IP address such as `127.0.0.1` or a specific internal network IP. Ensure that OpenBao only listens on the necessary port, where the default port is `8200`. Use firewall rules to restrict access to this port to authorized networks or users only. -These hardening measures reduce the attack surface of the OpenBao server, enhance security controls, and ensure that only authorized entities have access. \ No newline at end of file +These hardening measures can reduce the attack surface of the OpenBao server, enhance security controls, and ensure that only authorized entities have access. \ No newline at end of file