Skip to content

Troubleshooting Handbook

This handbook helps you find and fix SSH Teams problems quickly by starting with symptoms and narrowing down the cause.

Fast Triage Flow

graph TD
    A[Issue reported] --> B{Where does it fail}
    B -->|Service start| C[Check container or app logs]
    B -->|Browser login| D[Check URL TLS session and redirects]
    B -->|Device init| E[Check device flow and token polling]
    B -->|Certificate issue| F[Check policy match DPoP and host fingerprint]
    C --> G[Apply fix and retest]
    D --> G
    E --> G
    F --> G
    G --> H{Resolved}
    H -->|Yes| I[Close incident and record root cause]
    H -->|No| J[Collect diagnostics bundle and escalate]

Before you dig in, check these basics:

  1. Capture the failing command or URL and the exact time it happened.
  2. Note the environment and hostname (lab, staging, or production).
  3. Find out if the issue affects one person or everyone.
  4. Ask whether the problem started right after a change.

Install and Startup Failures

Common signs:

  • The web interface does not load after deployment.
  • The container keeps restarting.
  • /login returns a 5xx error.

What to check:

  1. Make sure ports are mapped and the process is running.
  2. Make sure persistence paths are mounted and writable.
  3. Confirm the backend settings make sense (nitrate vs mongo).
  4. Confirm the TLS files and configuration directory are accessible.

Helpful commands:

docker ps --filter name=sshteam
docker logs --tail=200 sshteam
curl -k -I https://<hostname>:8443/login
curl -I http://<hostname>:8080/login

Common causes:

  • Port mapping mismatch. The examples use 8080:8080 and 8443:8443.
  • Wrong or unreachable MONGODB_URI when using Mongo mode.
  • Missing or permission-blocked conf.d or data path.

Browser and Authentication Failures

Common signs:

  • Redirect loops between /login and protected pages.
  • 403 or 401 errors after entering credentials.
  • The setup page is not available when you expect it.

What to check:

  1. Confirm the URL and scheme are correct.
  2. Confirm the browser is accepting cookies for the host.
  3. Confirm the user has the right role and team assignment.
  4. Confirm whether first-run setup has already been completed.

What to try:

  • Retry in private browsing mode to rule out stale cookies.
  • Log in again and watch where the redirect lands.
  • Confirm admin permissions for administration routes.

Expected behavior:

  • Unauthenticated requests to protected pages are redirected to /login.
  • Newly installed environments route the root page to /setup until team creation is complete.

Device Flow Failures

Common signs:

  • authorization_pending keeps appearing until the request times out.
  • access_denied appears while polling for a token.
  • expired_token appears for the device code.
  • invalid_dpop_proof appears on a token or signing request.

What to check:

  1. Use the exact verify URL and user_code shown by the CLI.
  2. Make sure the approval matches the pending request.
  3. Check that the device clock is not way off.
  4. Confirm the device was not revoked.

How to recover:

  • Run sshteam init https://<hostname> again.
  • Approve the request in the browser promptly.
  • If DPoP errors persist, re-initialize the device to generate fresh key material.

Useful commands:

sshteam init https://<hostname>
sshteam devices list

Policy Mismatch and Access Denials

Common signs:

  • A signing request is denied even though login and device look fine.
  • Some users can sign for a host while others cannot.

What to check:

  1. Confirm the server's fingerprint or tags match the policy scope.
  2. Confirm the requested Unix account is listed in the policy principals.
  3. Confirm the current time falls inside the active window and timezone.
  4. Confirm source IP limits if the policy has any.
  5. Confirm the policy priority and enabled state.

How to fix it:

  1. Test one connection that should be allowed.
  2. Test one connection that should be denied.
  3. Change one policy setting at a time.
  4. Re-test and write down why the final rule works.

Certificate Issuance Failures

Common signs:

  • sshteam sign or sshteam issue returns policy or auth errors.
  • SSH still fails even after a certificate is issued.

What to check:

  1. Confirm the CLI is using the right server context (--server when needed).
  2. Confirm the target host key fingerprint resolves correctly.
  3. Confirm the certificate algorithm and key type match what the server accepts.
  4. Confirm the joined server still trusts the team CA in TrustedUserCAKeys.
  5. Confirm the certificate has not expired.

Useful commands:

sshteam sign <user@host> -k ~/.ssh/id_ed25519.pub
sshteam issue <user@host>
sshteam agent <user@host>
ssh -vvv <user@host>

On the server side:

  • Verify the joined host still has the expected CA public keys.
  • Verify sshd was reloaded after any trust-file updates.

Known Gotchas and Diagnostic Commands

Things that often trip people up:

  • Revoked devices cannot refresh or sign. That is expected.
  • Switching default servers across multiple CAs can lead to wrong-target requests.
  • Self-signed TLS in labs can show up as auth failures when trust is broken.

If you need to escalate, collect this information first:

  1. The failing command or URL and the full error message.
  2. The timestamp and timezone.
  3. Relevant app or container logs from around the failure.
  4. The policy target details: user, principal, host, tags, and time.
  5. Whether the device was recently re-initialized or revoked.

Quick command pack:

docker logs --tail=300 sshteam
curl -k -I https://<hostname>:8443/login
sshteam devices list
ssh -vvv <user@host>

Most incidents fall into one of four areas: auth/session, device/token, policy matching, or host trust. Identifying the bucket usually points you straight to the fix.

Prevention Checklist

A little regular checking reduces repeat incidents.

Weekly:

  • Validate one known-good login and one certificate issuance.
  • Review newly revoked devices and confirm they were expected.
  • Check policy edits for accidentally broad grants.

Monthly:

  • Check TLS certificate expiry and renewal readiness.
  • Test backup restore in a non-production environment.
  • Re-test notification provider delivery and failover.

After every high-impact change:

  • Re-run one allowed and one denied policy test.
  • Re-run one sshteam init and one sshteam sign flow.
  • Record the results in your operations log.