HashiConf 2025 Don't miss the live stream of HashiConf Day 2 happening now View live stream
Vault
Secrets management

Automate Linux password rotation with Vault

  • 14min
  • |
  • Enterprise
  • Vault

Enterprise Only

This feature requires a Vault Enterprise license.

Rotating passwords across dozens or hundreds of Linux servers is time-consuming and error-prone when done manually. In this tutorial, you'll learn how to use HashiCorp Vault's OS secrets engine plugin to automate password management for local Linux accounts, enforce password policies, and maintain security compliance across your infrastructure.

Challenge

Platform engineers often manage hundreds or thousands of servers across various data centers. Manually logging into each system to update local account passwords is impractical and creates security risks. When a security incident occurs, quickly rotating passwords across all affected systems becomes critical but difficult to coordinate.

Even organizations using LDAP need local account management for break-glass scenarios - emergency accounts when LDAP is down, or sudoers accounts needed to fix LDAP client issues. Without automation, password rotation policies are difficult to enforce, and tracking when passwords were last rotated becomes nearly impossible.

Solution

Vault's OS secrets engine plugin automates the management of local Linux account passwords. It allows you to:

  • Rotate passwords automatically based on defined policies
  • Enforce password complexity requirements
  • Track password rotation history and statistics
  • Quickly rotate passwords in large batches during security incidents
  • Maintain compliance with security standards through centralized management

Security engineers can set rotation schedules and password policies, while compliance officers gain visibility into password ages, rotation dates, and policy adherence for audit purposes.

Personas

The scenario described in this tutorial involves multiple roles:

  • Developer: Danielle is a developer who needs access to a Linux server for testing and development purposes. They require secure credentials that are regularly rotated to prevent unauthorized access.
  • Operator: Oliver is a platform engineer responsible for managing the infrastructure and ensuring that all systems are secure. They need to automate password rotation to maintain security without manual intervention.

Prerequisites

Scenario

Oliver is a platform engineer at HashiCups who manages dozens of servers and their passwords. The security team has implemented password complexity and rotation policies enforced across all systems. Oliver will use Vault's OS secrets engine plugin to automate this process.

Lab setup

  1. Create a plugins directory where you will download the OS secrets engine plugin.

    $ mkdir plugins

  2. Open a terminal and export an environment variable with a valid Vault Enterprise license.

    $ export VAULT_LICENSE=02MV4UU43BK5....

  1. Open a terminal and start a Vault dev server with the literal string root as the root token value, and enable TLS.

    $ vault server -dev -dev-root-token-id root -dev-plugin-dir="plugins" -dev-tls

    The dev server listens on the loopback interface at 127.0.0.1 on TCP port 8200 with TLS enabled. At runtime, the dev server also automatically unseals, and prints the unseal key and initial root token values to the standard output.

    Root tokens

    The dev mode server starts with an initial root token value set.

    Root token use should be extremely guarded in production environments because it provides full access to the Vault server.

    You can supply the root token value to start Vault in dev mode for convenience and to keep the steps here focused on the learning goals of this tutorial.

  2. In a new terminal, export the VAULT_ADDR and VAULT_CACERT environment variables using the commands suggested in your Vault dev server output.

    Copy each command (without the $) from the server output, and paste it into the new terminal session.

    Example:

    $ export VAULT_ADDR='https://127.0.0.1:8200'

    Example:

    $ export VAULT_CACERT='/var/folders/qr/zgztx0sj6n1dxy86sl36ntnw0000gn/T/vault-tls3037226588/vault-ca.pem'

    Remember to use your dev server's values, not the examples shown here.

  3. Export an environment variable for the vault CLI to authenticate with the Vault server.

    $ export VAULT_TOKEN=root

    The Vault server is ready.

  4. Clone the GitHub repository for this tutorial:

    $ git clone https://github.com/hashicorp-education/learn-vault-os-password-rotation.git

  5. Navigate to the tutorial directory:

    $ cd learn-vault-os-password-rotation

Set up the SSH server

To run the OS secrets engine plugin, you need a Linux server with SSH access. You'll use a Docker container to simulate this environment.

The plugin relies on passwd and chpasswd commands to manage local user passwords, so the container will be configured with these utilities and an SSH server.

Examine the Dockerfile in the repository which sets up an SSH server. 

# Copyright IBM Corp. 2018, 2026
# SPDX-License-Identifier: MPL-2.0

# syntax=docker/dockerfile:1

FROM redhat/ubi9

WORKDIR /

RUN dnf --assumeyes upgrade && dnf --assumeyes install openssh-server sudo

RUN mkdir -p /etc/sudoers.d

# create test users
RUN arr=("danielle" "oliver") && \
for i in "${arr[@]}"; do \
    user="$i"; \
    useradd -m -g users $user; \
    echo "$user:YnkXV/6g1+Bd7fKKjfM07g==" | chpasswd; \
    echo "$user ALL=NOPASSWD:/usr/sbin/chpasswd" > "/etc/sudoers.d/$user"; \
done

# Ensure sshd allows password logins
RUN echo "PasswordAuthentication yes" > /etc/ssh/sshd_config.d/40-local-passwords.conf

# Clear and regenerate host key for sshd
RUN rm -rvf /etc/ssh/ssh_host_*_key* \
    && ssh-keygen -A

EXPOSE 22

# Run
CMD ["/usr/sbin/sshd", "-D"]

In this Dockerfile:

  • Users are created in lines 15-21 with the useradd command and their passwords are set to "YnkXV/6g1+Bd7fKKjfM07g==" using chpasswd.
  • Vault needs the accounts to have sudo privilege for the chpasswd command to run on the remote host. This should only be granted for the chpasswd command to minimize security risks. The Dockerfile in the repository sets up this environment for you.

  1. Build the Docker image for the SSH server:

    $ docker build -t ssh-image .

  2. Start the Docker container:

    $ docker run -dit --name ssh-host -p 2222:22 ssh-image

  3. Get the SSH host key from the container. TO connect to if with ssh you'll need this to append this to your local .ssh/known_hosts file:

    $ ssh-keyscan -t ed25519 -p 2222 localhost >> ~/.ssh/known_hosts

  4. Verify you can SSH into the container using the default credentials:

    $ ssh -p 2222 danielle@localhost

    The default password is YnkXV/6g1+Bd7fKKjfM07g==. You should authenticate and see a shell prompt.

    danielle@localhost's password: 
[danielle@f874c647936c ~]$

    Use a ctrl+d to exit the SSH session.

Download and enable the plugin

  1. Determine the latest version of the plugin found in the releases page. For example, if the latest version is vault-plugin-secrets-os_0.1.0-rc1+ent, set the PLUGIN_VERSION variable to the value after vault-plugin-secrets-os_.

    Example:

    $ export PLUGIN_VERSION="0.1.0-rc1+ent"

  2. Download the plugin binary for your OS and architecture.

    $ vault plugin register \
    -download \
    -version=$PLUGIN_VERSION \
    secret vault-plugin-secrets-os

  3. Enable the plugin at the os/ path:

    $ vault secrets enable -path=os vault-plugin-secrets-os
Success! Enabled the vault-plugin-secrets-os secrets engine at: os/

  4. Verify the plugin:

    $ vault secrets list
Path               Type                       Accessor                            Description
----               ----                       --------                            -----------
cubbyhole/         cubbyhole                  cubbyhole_85c5b8e0                  per-token private secret storage
os/                vault-plugin-secrets-os    vault-plugin-secrets-os_7dd5d23c    n/a
secret/            kv                         kv_766fc4c6                         key/value secret storage

    You should see os/ in the list of enabled secrets engines.

Create a password policy

  1. Define a password policy that enforces complexity requirements. Create a policy file:

    $ cat > /tmp/password_policy.hcl <<-EOF
   length = 20
   rule "charset" {
      charset = "abcdefghijklmnopqrstuvwxyz"
      min-chars = 1
   }
EOF

    This policy requires passwords to be 20 characters long and include lowercase letters.

  2. Write the policy to Vault:

    $ vault write sys/policies/password/rhel-policy policy=@/tmp/password_policy.hcl

  3. Verify creation of the policy:

    $ vault read sys/policies/password/rhel-policy
Key       Value
---       -----
policy    length = 20
   rule "charset" {
   charset = "abcdefghijklmnopqrstuvwxyz"
   min-chars = 1
}

  4. Configure the secrets engine.

    $ vault write "os/config" \
   ssh_host_key_trust_on_first_use=true

    The ssh_host_key_trust_on_first_use option allows Vault to trust the SSH host key on the first connection. In production, you would typically provide the host key directly in the host configuration for better security.

Configure the host

The next step is to configure a host in Vault that represents the Linux server you want to manage. This configuration includes the server's IP address and SSH port.

  1. Create a host configuration in Vault that represents your Linux server. Use the address 127.0.0.1 and port 2222 where the SSH server is running:

    $ vault write "os/hosts/ssh-host1" \
   address=127.0.0.1 \
   port=2222

  2. List all configured hosts:

    $ vault list os/hosts
Keys
----
ssh-host1

Configure managed accounts

In order for Vault to manage Linux passwords, you need to configure each host and user in Vault. This includes setting the rotation period, username, and initial password.

  1. Create an account configuration for the danielle account. You'll name this configuration "danielle":

    $ vault write os/hosts/ssh-host1/accounts/danielle \
   rotation_period="1m" \
   username="danielle" \
   password_policy="rhel-policy" \
   password="YnkXV/6g1+Bd7fKKjfM07g=="

    The rotation_period of 1 minute is for demonstration purposes. In production, you would typically use longer periods like 30d for 30 days.

    The parameters are:

  2. List all accounts configured for host ssh-host1:

    $ vault list os/hosts/ssh-host1/accounts
Keys
----
danielle

  3. Check the account configuration details:

    $ vault read os/hosts/ssh-host1/accounts/danielle
Key                           Value
---                           -----
current_version               1
custom_metadata               <nil>
disable_automated_rotation    false
last_vault_rotation           2026-04-06T14:28:41Z
next_vault_rotation           2026-04-06T14:29:41Z
password_policy               rhel-policy
rotation_period               1m
rotation_policy               n/a
rotation_schedule             n/a
rotation_window               0
ttl                           4s
username                      danielle

    In this example, the last_vault_rotation and next_vault_rotation timestamps show when the password was last rotated and when it will be automatically rotated next based on the 1-minute rotation period. The ttl shows the time remaining until the next rotation.

Rotate credentials manually

  1. Read the current credentials for the account:

    $ vault read os/hosts/ssh-host1/accounts/danielle/creds
Key                    Value
---                    -----
created_time           2026-04-06T14:31:03Z
last_vault_rotation    <nil>
next_vault_rotation    2026-04-06T14:32:03Z
password               YnkXV/6g1+Bd7fKKjfM07g==
ttl                    44s
username               danielle
version                1

    Note the password is initially set to "YnkXV/6g1+Bd7fKKjfM07g==" and there is no last_vault_rotation timestamp as there is no earlier rotation. The next_vault_rotation shows when Vault will automatically rotate the password based on the 1-minute rotation period.

    The response includes:

  2. Manually trigger a password rotation:

    $ vault write -f os/hosts/ssh-host1/accounts/danielle/rotate
Success! Data written to: os/hosts/ssh-host1/accounts/danielle/rotate

  3. Read the credentials again to see the updated password:

    $ vault read os/hosts/ssh-host1/accounts/danielle/creds
Key                    Value
---                    -----
created_time           2026-04-06T14:31:03Z
last_vault_rotation    2026-04-06T14:31:45Z
next_vault_rotation    2026-04-06T14:32:45Z
password               zxrrrnyazkqrydpyrcqa
ttl                    25s
username               danielle
version                2

Notice that the password has changed and the updated last_vault_rotation timestamp. The next_vault_rotation shows when Vault will automatically rotate the password again based on the 1-minute rotation period.

You can ssh into the server using the new password to verify it works, or wait for the next step.

Verify automatic rotation

Wait for a minute for the rotation period to elapse (1 minute in this example), then read the credentials again:

$ vault read os/hosts/ssh-host1/accounts/danielle/creds
Key                    Value
---                    -----
created_time           2026-04-06T14:37:50Z
last_vault_rotation    2026-04-06T14:32:35Z
next_vault_rotation    2026-04-06T14:33:35Z
password               mfjmcwoihgufquqbzkqh
ttl                    22s
username               danielle
version                3

The password will have changed automatically, demonstrating Vault's automated rotation capability. In production environments, you would set rotation periods appropriate for your security policies, such as 30 or 90 days.

Note this password down, you will use it to verify you can still SSH into the server with the new credentials.

Test the rotated password

Verify that the new password works by attempting to SSH into the container:

$ ssh -p 2222 danielle@localhost

When prompted, use the password from the most recent credentials read. You should authenticate with the rotated password.

danielle@localhost's password: 
[danielle@f874c647936c ~]$

Use a ctrl+d to exit the SSH session.

Challenge

Create a second container with a unique host configuration and manage both containers with Vault. Both containers should be running simultaneously, and you will need to be able to run Vault commands to rotate the passwords. In addition to a new host in Vault you also need to configure Danielle's account for the second host and verify that the automatic rotation is working.

You will need to create the following for the second host:

  • A new Docker container with SSH access on a different port (e.g. 2223)
  • A new host configuration in Vault with the correct address and port
  • An account configuration for the danielle user on the second host

The GitHub repository provides resources to help with this in the challenge folder. You can use it as a starting point or create your own configuration from scratch.

You can also experiment with different password policies and rotation periods to see how they affect the credentials.

Knowledge check

  1. What is the primary purpose of configuring a host in Vault's OS secrets engine plugin?

    🔘 To install the Vault plugin on the remote Linux server

    🔘 To define the Linux server's IP address, SSH port, and host key for password management

    🔘 To create user accounts on the Linux server

    🔘 To set the password complexity requirements for all accounts

    ❌ To install the Vault plugin on the remote Linux server

    ✅ To define the Linux server's IP address, SSH port, and host key for password management

    ❌ To create user accounts on the Linux server

    ❌ To set the password complexity requirements for all accounts

    Explanation: The host configuration represents the Linux server you want to manage and includes the server's connection details (address and port), which Vault needs to connect and rotate passwords.

  2. What are the two ways to rotate passwords in Vault?

    🔘 Manually by running vault write os/hosts/[host]/accounts/[account]/rotate

    🔘 Automatically based on the rotation period

    🔘 Both manually on-demand and automatically based on the rotation period

    🔘 When the user logs into the system

    ❌ Manually by running vault write os/hosts/[host]/accounts/[account]/rotate

    ❌ Automatically based on the rotation period

    ✅ Both manually on-demand and automatically based on the rotation period

    ❌ When the user logs into the system

    Explanation: The tutorial demonstrates both manual rotation using the rotate command and automatic rotation after the configured time elapses.

    Vault supports both approaches to give flexibility for scheduled maintenance and emergency situations.

Clean up

  1. Stop the Vault server.

    $ pkill vault

  2. Stop and remove the Docker container:

    $ docker stop ssh-host && docker rm ssh-host

  3. Delete the git repository if you no longer need it:

    $ cd .. && rm -rf learn-vault-os-password-rotation

Summary

In this tutorial, you learned how to:

  • Configure Vault's OS secrets engine plugin
  • Create and enforce password complexity policies
  • Set up host and account configurations
  • Manually rotate passwords on demand
  • Enable automatic password rotation based on time periods

This automation provides platform engineers with a scalable way to manage passwords across numerous servers, gives security engineers the tools to enforce compliance, and provides compliance officers with visibility into password management practices.

Additional resources

Previous

Use KMIP secrets engine with IBM Db2

 Next Collection

Associate prep

This tutorial also appears in:

  • 1 tutorial
    Vault 2.0 release highlights
    The listed tutorials were updated to showcase the new enhancements introduced in Vault 2.0.
    • Vault