Skip to content

10 Administration and Operations

This chapter is your day-2 operations runbook for SSH Teams. Use it to keep service health, trust material, licensing, and notification paths reliable over time.

10.1 Administration Settings

Use /administration as your operational control center.

graph TD
    A[Admin signs in] --> B[Open administration landing page]
    B --> C[Check counts access and CA fingerprints]
    C --> D{Choose operation}

    D --> E[Users and roles]
    D --> F[SSL and certificates]
    D --> G[License]
    D --> H[Notifications]

    E --> I[Run post-change validation]
    F --> I
    G --> I
    H --> I

    I --> J[Record outcome]

10.2 Prerequisites

Requirement Lab Staging Production
Admin account with ADMIN or required management role Required Required Required
Stable hostname and TLS strategy Recommended Required Required
Backup location for config and database Optional Required Required
Mail/SMS test destination for OTP checks Recommended Required Required
Change log or ticket reference for admin actions Optional Recommended Required

Environment variables to confirm before operations:

  • SSHTEAM_SSL_CONF_DIR
  • SSHTEAM_PERSISTENCE_BACKEND
  • SSHTEAM_NITRATE_DB_FILE (Nitrate mode)
  • MONGODB_URI (Mongo mode)

10.3 Quick Start (Day-1 and Day-30 Workflow)

Day-1 operator pass after rollout:

  1. Open /administration and verify counts/fingerprints.
  2. Open /administration/ssl and confirm certificate validity.
  3. Open /administration/license and confirm active license state.
  4. Open /administration/notifications and run provider test.
  5. Run one end-to-end sign and SSH login test.

Day-30 recurring maintenance pass:

  1. Review certificate expiry and renewal path.
  2. Review license expiry window.
  3. Rotate notification credentials and re-test dispatch.
  4. Run backup and restore validation sample.
  5. Record outcomes and remediation actions.

If checks fail, use 12-troubleshooting-handbook.md#122-install-and-startup-failures and 12-troubleshooting-handbook.md#123-browser-and-authentication-failures.

Administration landing page:

SSH Teams administration landing page

Core signals shown in the current UI:

  • License edition badge (for example, Community Edition).
  • Joined server count.
  • Certificate policy count.
  • My Devices active count.
  • My Access derived from current policy matching.
  • User CA key fingerprints (RSA and ED25519) with authorized_keys download.
  • Join script commands for Linux/macOS and Windows.
  • CLI package download links by platform.

Operational checks to run at login:

  1. Verify server and policy counts look expected for your team.
  2. Verify join script output matches your external hostname/port.
  3. Verify CA fingerprint continuity after certificate/key maintenance.
  4. Confirm My Access entries are non-empty for expected operators.

Admin entry points:

  • /administration for the administration landing page.
  • /administration/users for user/role management.
  • /administration/notifications for OTP provider controls.
  • /administration/license for license status and upload.
  • /administration/ssl for TLS certificate operations (primary-team admins only).

10.4 SSL and Certificate Material Management

Why this matters

TLS trust failures break browser onboarding and CLI/API flows. Treat SSL operations as service-availability work, not just security hygiene.

SSH Teams stores TLS material in the configured SSL directory:

  • sshteam.ssl.conf-dir (env: SSHTEAM_SSL_CONF_DIR, default conf.d)
  • Certificate file: sshteam-server.crt
  • Private key file: sshteam-server.key

If certificate files are missing at startup, SSH Teams generates a self-signed certificate automatically.

SSL administration page (/administration/ssl) capabilities:

SSL certificate page:

SSH Teams SSL certificate administration page

  • View current certificate metadata (CN, validity window, serial, SHA-256 fingerprint).
  • Regenerate self-signed certificate with subject fields.
  • Generate and download a CSR for external CA signing.
  • Configure and trigger Let's Encrypt issuance.

Let's Encrypt operational prerequisites:

  • Hostname must resolve publicly to this service.
  • HTTP challenge path must be reachable (port-forward/reverse-proxy rules must allow validation traffic).
  • Contact email and hostname must be valid.

Recommended TLS maintenance practice:

  1. Capture current fingerprint and expiry.
  2. Apply regeneration/CSR/LE update.
  3. Recheck fingerprint and expiry in UI.
  4. Validate browser and CLI trust from a clean client.
  5. Verify join scripts still produce the expected base URL.

10.5 License Management

Why this matters

License state controls feature availability and operator experience. Validate license updates before change windows close.

License administration is managed at /administration/license.

License management page:

SSH Teams license administration page

Displayed runtime fields:

  • Active/inactive status.
  • Edition.
  • Customer name.
  • Expiry date.

License file behavior:

  • Upload endpoint stores an active license only.
  • Invalid/inactive license files are rejected.
  • Stored file path resolves to <ssl-conf-dir>/license.jwt.

Common lifecycle actions:

  1. Upload new/renewed license (.jwt).
  2. Confirm status flips to Active.
  3. Confirm edition/customer/expiry values match contract.
  4. Revisit /dashboard and /administration to confirm expected feature posture.

Operational note:

  • In forced-inactive testing mode, the UI may show unlicensed behavior for validation, but a valid active license still overrides inactive state.

10.6 Notification Settings

Why this matters

OTP delivery is part of login reliability. If notifications break, operators are blocked even when infrastructure is healthy.

Notification provider administration lives at /administration/notifications.

Notification settings page:

SSH Teams notification settings page

Current provider options:

  • SendGrid email.
  • SMTP email.
  • Twilio SMS.

Runtime behavior:

  • All provider settings can be stored.
  • Exactly one provider is marked active at a time.
  • Test dispatch is available per provider before final save/activation.

Recommended change workflow:

  1. Enter provider credentials and sender defaults.
  2. Send a test OTP to a controlled destination.
  3. Mark provider active.
  4. Save settings.
  5. Perform a real login OTP challenge and verify delivery timing/content.

Security handling guidance:

  • Treat provider credentials (API keys, SMTP passwords, Twilio tokens) as secrets.
  • Restrict access to users with policy/admin privileges.
  • Rotate credentials periodically and re-run provider test after rotation.

10.7 Backup and Restore Guidance

Why this matters

Your CA trust, license state, and operational metadata are all recoverability-critical. Backups that are never restore-tested are not usable controls.

Backup strategy depends on persistence backend and shared config paths.

10.7.1 What to back up

Always include:

  • SSL/config directory (SSHTEAM_SSL_CONF_DIR, default conf.d) containing:
    • TLS cert/key files.
    • license.jwt.
    • HSM keystore material if configured there.

Include one persistence store path:

  • Nitrate backend (default):
    • SSHTEAM_NITRATE_DB_FILE (default ./nitrate/data/sshteam.nitrite.db).
  • Mongo backend:
    • MongoDB database used by MONGODB_URI.

10.7.2 Backup procedure (Nitrate)

  1. Stop SSH Teams service.
  2. Copy Nitrate DB file and SSL/config directory atomically.
  3. Restart service.

Example:

# Example paths; adjust for your deployment
cp ./nitrate/data/sshteam.nitrite.db /backup/sshteam/sshteam.nitrite.db
tar -czf /backup/sshteam/conf.d.tgz conf.d

10.7.3 Backup procedure (Mongo)

  1. Backup Mongo database using standard Mongo tooling.
  2. Backup SSH Teams SSL/config directory in the same window.

Docker deployment note:

  • Default compose setup persists app config via ./conf.d:/app/conf.d and Mongo data via the mongo-data volume.

10.7.4 Restore procedure

  1. Stop SSH Teams service.
  2. Restore SSL/config directory.
  3. Restore persistence data (Nitrate file or Mongo database).
  4. Start service.
  5. Validate:
    • Login works.
    • Dashboard counts are intact.
    • Device issuance/signing works.
    • License status and notification configuration are present.

10.7.5 Recovery validation checklist

  1. Admin login succeeds.
  2. At least one user can complete OTP flow.
  3. sshteam sign succeeds for an allowed policy target.
  4. CA key fingerprints match expected pre-backup values.
  5. License state (edition/expiry) matches pre-backup records.

10.8 Pro Tip and Common Gotcha

Pro tip:

  • Treat every admin change as a mini-change set: perform the action, run one validation command, and capture evidence in your ticket.

Common gotcha:

  • Teams rotate TLS certificates but skip join-script verification. Always confirm the advertised hostname/port still matches your public endpoint after certificate or proxy updates.