Installation

Keymaster requires Go 1.20 or later. Install it using go install:

The binary will be available at $GOPATH/bin/keymaster. Make sure this directory is in your $PATH.

Verify the installation:

Quick Start

Getting up and running with Keymaster is straightforward:

1. Initialize the Database

Run Keymaster for the first time to create the database and configuration:

Keymaster will create a SQLite database and configuration file in your user's standard config directory:

• Linux: ~/.config/keymaster/
• macOS: ~/Library/Application Support/keymaster/
• Windows: %APPDATA%\keymaster\

2. Generate Your System Key

In the TUI, navigate to Rotate System Keys and generate a new key. This is the master key Keymaster uses to manage all your hosts.

3. Add Your First Host

To bring a host under Keymaster management:

1. In the TUI: Manage Accounts → Add Account
2. Enter the account details (e.g., root@192.168.1.100)
3. Copy the bootstrap command and run it on the remote host
4. Confirm in Keymaster to complete the deployment

Configuration

Keymaster uses YAML for configuration. The default config location is:

• Linux: ~/.config/keymaster/keymaster.yaml
• macOS: ~/Library/Application Support/keymaster/keymaster.yaml
• Windows: %APPDATA%\keymaster\keymaster.yaml

Configuration Options

The configuration file includes settings for:

• Database: Connection details (SQLite, PostgreSQL, MySQL)
• SSH: Connection timeouts, retry logic
• Logging: Log level and output format
• Audit: Audit log settings

Bootstrap Hosts

Bootstrapping is the process of bringing a new host under Keymaster management. It's a two-step process:

Step 1: Generate Bootstrap Command

In the TUI, select Manage Accounts → Add Account. Keymaster will generate a one-line shell command that installs a temporary SSH key.

Step 2: Run Bootstrap on Remote Host

SSH into the remote host and paste the bootstrap command. This command:

• Creates a temporary key file
• Appends it to authorized_keys
• Outputs confirmation text

Step 3: Confirm in Keymaster

Return to Keymaster and confirm the account. Keymaster will:

1. Connect using the temporary key
2. Deploy the hardened system key
3. Clean up the temporary key

Manage Keys

Managing SSH keys is at the heart of Keymaster's functionality.

Add Public Keys

Import SSH public keys into Keymaster:

Assign Keys to Accounts

In the TUI, navigate to Assign Keys to Accounts to associate users with specific hosts.

Create Tags

Organize accounts using tags (e.g., env:production, team:backend) for bulk operations.

Deploy Updates

Deploy key changes to your entire fleet or specific hosts.

Deploy All Hosts

Deploy with Filters

Deploy to specific tags or accounts for targeted updates:

Verbose Output

Enable verbose logging to see deployment details:

Audit Fleet

Audit your infrastructure to detect configuration drift and verify that Keymaster-managed keys are properly deployed.

Full Fleet Audit

What Audit Checks

• Verifies all Keymaster-managed keys are present
• Detects unauthorized key additions
• Identifies missing or stale keys
• Reports on offline hosts

Database Migration

Start with SQLite for simplicity, migrate to PostgreSQL or MySQL as your fleet grows.

Supported Backends

• SQLite: Zero-config, perfect for small to medium deployments
• PostgreSQL: Enterprise-grade, highly scalable
• MySQL: Alternative relational database option

Migrate to PostgreSQL

Backup & Restore

Keymaster provides portable backups that can be restored on any machine or migrated between backends.

Create a Backup

This creates a compressed JSON file (keymaster-backup-*.json.zst) containing your entire database.

Restore from Backup

By default, restore is non-destructive (it merges data). Use --force to overwrite.

Security

System Key Storage

Keymaster stores the system private key in the database. This is intentional—it allows Keymaster to manage access from any machine without requiring SSH agent setup.

However, this means your database is a sensitive asset:

• Use file permissions chmod 600 on the database file
• Store the database in a secure location
• Encrypt backups before transferring them
• Use database authentication and encryption for PostgreSQL/MySQL backends

Automatic Key Hardening

Every time Keymaster deploys, it automatically applies strict restrictions to the system key:

These restrictions mean:

• command="internal-sftp": Only SFTP is allowed, no shell access
• no-port-forwarding: Prevents SSH tunneling attacks
• no-x11-forwarding: Disables X11 forwarding
• no-agent-forwarding: Prevents agent hijacking
• no-pty: No interactive terminal allocation

User Private Keys

Keymaster never handles user private keys. Only public keys are imported and deployed.

Troubleshooting

Enable Verbose Logging

For debugging, use the -v or --verbose flag:

Common Issues

Connection Timeouts

If bootstrap or deployment times out:

• Verify SSH connectivity from your machine to the target
• Check firewall rules allowing SSH (port 22)
• Verify the account credentials are correct

Permission Denied

If you see "Permission denied" errors:

• Ensure the bootstrap command was run with correct privileges (usually root)
• Check that the account can access authorized_keys file
• Verify file permissions on authorized_keys (~/.ssh/authorized_keys should be 600)

Database Errors

If you see database-related errors, check the configuration and ensure the database is accessible.