Linux VMs

Secret Management for Linux VMs

This guide will show you how to provision an application running on a Linux virtual machine with the secrets it needs.

If your VMs run in the cloud, check out the cloud-specific guides instead that cover how to authenticate to SecretHub using cloud-native services, so you don’t have to deal with service credentials:

  • AWS EC2
  • GCP Compute Engine (coming soon)
  • Azure Virtual Machines (coming soon)

Before you begin

Before you start using SecretHub with Linux VMs, make sure you have completed the following steps:

  1. Install the SecretHub CLI for your OS.
  2. Sign up for a SecretHub account.
  3. Set up SSH access to a Linux test VM.
  4. Open a port on the test VM, so you can see the result.

Step 1: Check out the demo application

To see the mechanism in action, the SecretHub CLI comes packed with a demo application. This application serves a web page and tries to connect to using credentials provided in the environment (DEMO_USERNAME and DEMO_PASSWORD).

First, try to run the app locally without setting the username and password:

secrethub demo serve

A web page will now be served at http://localhost:8080, but if you visit it, you’ll see that it shows an error because it’s missing the username and password.

Step 2: Provide secrets to the application

To get the demo application to work correctly, you’ll need to provide a username and password. You wouldn’t want to have those scattered around in plaintext, so let’s store those on SecretHub instead and use secrethub run to inject them at runtime.

Here’s a nice shortcut to auto-generate the values for you at your-username/demo:

secrethub demo init

Next, create a secrethub.env file, and instead of hardcoding secret values, reference them by path:

DEMO_USERNAME = {{ your-username/demo/username }}
DEMO_PASSWORD = {{ your-username/demo/password }}

Then, wrap the app start command in secrethub run:

secrethub run -- secrethub demo serve

The secrets will now automatically get fetched, decrypted and injected as environment variables to the app.

If you visit http://localhost:8080 again, you’ll see that the red cross got replaced by a green checkmark. The wisdom that was hidden in the Demo API has now been revealed!

Step 3: Create a service account for the demo app

Next, let’s deploy the app to a Linux test VM in your datacenter.

The first step here is to create a service account for the demo app, using the service init command. It generates a new credential for the app to fetch and decrypt the secrets, which you can deploy to the VM using SSH:

secrethub service init your-username/demo \
  --description demo-app \
  --permission read \
  | ssh user@host \
  "mkdir .secrethub && cat > .secrethub/credential"

The SecretHub CLI will look for the credential at $HOME/.secrethub/credential.

Any usage of this credential gets recorded on the audit log, and you can revoke the account at any time.

Step 4: Install the CLI on the VM

With the service credential in place, the next step is to install the SecretHub CLI on the VM.

There are various installation methods available, so pick one that suits you best.

SSH into the VM and run your preferred install command. If you’re on CentOS for example, you can use yum:

yum install -y

Step 5: Run the app

Create or move the secrethub.env file we used earlier and wrap the demo app start command in secrethub run, setting the --port flag to an open port on the machine:

secrethub run -- secrethub demo serve --host --port 1234

Visit the webpage and see it in action!

There you have it, an app running on a Linux VM, provisioned with the secrets it needs. Check out the audit log, and you’ll see reads done by this service account being logged. If you want to rotate the secret, just write a new version to SecretHub and restart the apps that consume it. No config updates needed.