keywarden/docs/admin-guide.md

Administration Guide

This guide covers administrative features available to users with the Admin or Owner role. For basic user operations, see the User Guide. For role details, see Roles & Permissions.

Server Management

Admins manage the inventory of remote SSH servers that Keywarden can deploy keys to.

Adding a Server

1. Navigate to Servers → Add Server
2. Fill in:
   • Name — Descriptive name (e.g., "Web Server 1")
   • Hostname — IP address or DNS name
   • Port — SSH port (default: 22)
   • Username — SSH admin user for connections (typically root)
   • Description — Optional description
   • Server Groups — Optionally assign the server to one or more groups
3. Click Save

Testing Server Connectivity

From the server list, you can run two types of tests:

• Connection Test — TCP connectivity check (is the port reachable?)
• Auth Test — Full SSH authentication test using the system master key

Both tests help verify that Keywarden can reach and authenticate to the server.

Editing / Deleting Servers

Use the edit and delete buttons on the server list. Deleting a server removes it from all groups and cancels related assignments.

Server Groups

Server groups allow you to organize servers and deploy keys to multiple servers at once.

Creating a Group

1. Navigate to Groups → Add Group
2. Enter a name and optional description
3. Click Create

Managing Group Members

From the group edit page:

• Add servers to the group by selecting them from the list of all servers
• Remove servers from the group

Server groups are used as targets for:

• Group deployments
• Access assignments
• Cron jobs (temporary access)

Key Deployment

Manual Deployment

1. Navigate to Deploy
2. Select an SSH key from the dropdown (shows all keys from all users)
3. Select a target server
4. Choose an authentication method (password or existing key)
5. Click Deploy

Keywarden connects to the target server and appends the selected public key to the server user's ~/.ssh/authorized_keys.

Owner only: The SSH key dropdown includes the [MASTER] System Master Key as the first option. This allows the owner to deploy the system master key directly to servers from the Deploy page — useful for initial server setup or re-deployment after master key regeneration.

Group Deployment

1. Navigate to Deploy
2. Select an SSH key
3. Select a server group
4. Click Deploy to Group

The key is deployed to all servers in the group sequentially.

Deployment History

The deploy page shows the last 50 deployment results with status (success/failed) and error messages. Master key deployments are included in the history as [MASTER] System Master Key.

After each deployment (single host or group), a flash message is displayed at the top of the page indicating success or failure.

Access Assignments

Access assignments are the core feature for managing who has access to which servers. They provide a declarative model: define the desired state, and Keywarden syncs it to the servers.

Creating an Assignment

1. Navigate to Assignments → Add Assignment
2. Fill in:
   • User — The Keywarden user to grant access to
   • SSH Key — Which key to deploy (from that user's keys)
   • Target Type — Single server or server group
   • Target — Select the server or group
   • System User — The Linux username on the target server
   • Desired State — present (deploy key) or absent (remove key)
   • Sudo — Grant NOPASSWD sudo privileges to the system user
   • Create User — Create the Linux user if it doesn't exist
3. Click Save

After creation, the assignment is automatically synced — Keywarden immediately connects to the target server(s) and applies the configuration.

What Sync Does

When an assignment is synced with desired_state = "present":

1. Creates the system user (if create_user is enabled and user doesn't exist)
   • Uses useradd -m -s /bin/bash
   • Sets an initial password if one is configured (auto-generated if empty)
2. Adds sudo privileges (if sudo is enabled)
   • Creates /etc/sudoers.d/<username> with NOPASSWD:ALL
3. Deploys the SSH public key to the system user's authorized_keys

When an assignment is synced with desired_state = "absent":

• Removes the SSH key from the system user's authorized_keys

Manual Re-Sync

Click the Sync button on any assignment to re-apply it. This is useful if the server was reinstalled or if a previous sync failed.

Deleting an Assignment

When deleting an assignment, you have two options:

• Remove key only — Only removes the SSH key from the system user's authorized_keys
• Delete system user — Completely removes the system user account, their home directory, and sudo privileges from the target server(s)

The cleanup operation runs on all target servers (including all servers in a group).

Assignment Status

Status	Meaning
pending	Not yet synced
synced	Successfully applied to all targets
failed	Sync failed (see error message)

Cron Jobs (Temporary Access)

Cron jobs provide time-limited access to servers. They are essentially scheduled access assignments with an expiry.

Creating a Cron Job

1. Navigate to Temporary Access → Add Job
2. Configure:
   • Name — Descriptive job name
   • Target User — Keywarden user to grant access to
   • SSH Key — Which key to deploy
   • Target — Single server or server group
   • System User — Linux username on the target
   • Create User — Create the system user if needed
   • Sudo — Grant sudo privileges
   • Schedule — once, hourly, daily, weekly, or monthly
   • Scheduled Time — When the job should run (timezone-aware)
   • Remove After — Minutes after deployment to remove access (0 = permanent)
   • Expiry Action — What to do when access expires:
     • remove_key — Only remove the SSH key
     • disable_user — Lock the account and set shell to nologin
     • delete_user — Completely delete the system user
3. Click Save

Schedule Types

Schedule	Parameters	Behavior
once	Date + Time	Runs exactly once at the specified time
hourly	Minute of hour	Runs every hour at the specified minute
daily	Time of day	Runs every day at the specified time
weekly	Day of week + Time	Runs every week on the specified day
monthly	Day of month + Time	Runs monthly (clamped to last day if needed)

Cron Job Lifecycle

1. Active — Waiting for next run
2. Running — Currently executing
3. Done — One-time job completed
4. Paused — Manually paused by admin
5. Failed — Execution failed (recurring jobs stay active, one-time jobs remain failed)

Expiry Timer

When remove_after_min > 0, a background timer starts after successful deployment. When it fires, the configured expiry action is executed on all target servers.

User Management

Creating Users

1. Navigate to Users → Add User
2. Fill in:
   • Username — Must be unique
   • Email — Must be unique
   • Role — user, admin, or owner (see Roles & Permissions)
   • Password — Set a password, or...
   • Send Invitation — If email is configured, send an invitation email instead of setting a password
3. Click Create

When using invitations, the user receives an email with a secure link to set their own password.

Editing Users

Admins can change a user's username, email, and role. Additional actions:

• Reset password — Set a new password (the user will be prompted to change it)
• Force password change — Flag the user to change password on next login
• Unlock account — Clear a lockout from failed login attempts

Deleting Users

Deleting a user removes their SSH keys, server records, and all related data (CASCADE delete).

Protection: You cannot delete the last owner account.

System Information

Navigate to System to view runtime information:

• Application version (with update badge if a newer release is available)
• Go version, OS, architecture
• CPU count, goroutine count
• Memory allocation
• Runtime environment (Docker or native)
• Hostname and uptime

Update Notifications

Keywarden automatically checks for new releases in the background by querying the Gitea releases API. If a newer version is available, a yellow update badge is displayed in the top header for Admin and Owner users. The badge links directly to the release page on Gitea.

The update checker is only active when the application was built with a proper version tag. Development builds without a version skip the check entirely.

Admin Settings (Owner Only)

See Roles & Permissions for details on which settings are owner-only.

Navigate to Admin Settings (owner only) to configure:

Login Page Customization

• Background Image — Upload a custom background image for the login page (max 5 MB, JPEG/PNG/WebP). The image is centered and fills the screen without distortion (background-size: cover). The text color (heading, subtitle, footer) is automatically adjusted based on the image brightness — light text for dark images, dark text for bright images. The login card always uses a glass effect (transparent, blurred backdrop).

Application Settings

• App Name — Custom application name displayed in the UI
• Default Key Type — Default key type for generation (ed25519, rsa)
• Default Key Bits — Default key size
• Session Timeout — Inactivity timeout in minutes (default: 60)

Security Settings

• Password Policy — Minimum length, uppercase, lowercase, digit, special character requirements
• Account Lockout — Number of failed attempts before lockout and lockout duration
• MFA Enforcement — Require all users to enable TOTP MFA

Key Enforcement

• Enforcement Mode — Disabled (default), Monitor (log only), or Enforce (auto-remove unauthorized keys)
• Check Interval — How often the worker scans servers (1–1440 minutes, default: 15)
• Run Now — Trigger an immediate enforcement check

See Security — Key Enforcement for details.

Master Key

• View the system master key's public key and fingerprint
• Regenerate the master key (requires password confirmation)

Email Test

Send a test email to verify SMTP configuration.

Backup & Restore

See Backup & Restore for details.

CLI Commands

Keywarden provides CLI commands for administrative tasks that can be run via docker exec.

Password Reset

Reset a user's password when they are locked out or have forgotten it:

docker exec -it keywarden ./keywarden reset-password --username <name>

This generates a new random password, prints it to the terminal, and forces the user to change it on next login. The account lockout counter is also cleared.

To additionally disable MFA (e.g. when the user lost their TOTP device):

docker exec -it keywarden ./keywarden reset-password --username <name> --reset-mfa

Help

docker exec -it keywarden ./keywarden help