User FAQ

Questions from the person using ssoossh to connect. Host administrators and server operators have their own FAQs, at Host admin FAQ and Operator FAQ; how ssoossh sits beside existing keys and PAM stacks is in the Adoption FAQ. If your question is of the form “why does it not just…”, check Decisions first – that page exists for exactly those.

Do I have to replace ssh?

No. Your existing ssh invokes the ssoossh client through a line or two of ssh_config, and from there everything is standard OpenSSH certificate authentication. ssoossh ssh config prints those lines and needs no server, so it answers before anything is set up. See ssh_config integration, or the illustrated walkthrough for what a login looks like.

Do I get a browser prompt every time I ssh?

Not if your certificate is still valid: it is reused until it expires, so you approve again only when a new one is needed. How often that is depends on the lifetime your administrator sets; the shipped default is 30 seconds, and a deployment that sets eight hours asks about once a working day. The certificate is checked once at session start; an established SSH session does not drop when the certificate expires.

ssoossh ssh login --force replaces a loaded certificate when you want a new one anyway.

Do I need an ssh-agent?

Only for ProxyCommand mode. ssh reads key files once at startup, so a certificate refreshed on disk after that goes unseen. With the recommended Match exec mode, key files on disk work fine without an agent – see ssh_config integration and use_agent.

Can I approve from a different device than the one running ssh?

Yes. The approval URL can be opened in any browser; the client just waits for the outcome on its own stream. The browser’s address does not affect the certificate: the lifetime policy is judged on the address the client’s request came from. See Options and lifetime resolution.

Does it work on Windows and macOS?

Yes: macOS, Linux, and Windows, including Pageant and the WSL relay. The macOS binary is signed and notarized, so Gatekeeper does not block it. Getting started has the install steps.

On WSL, what decides which build you need is not the operating system but which ssh-agent your ssh reads. With an agent on each side, ssh inside a distro needs the Linux build installed in that distro and ssh.exe needs the Windows build. With one agent bridged across the boundary, a single installation covers both.

It is not working. What do I send you?

Re-run with -v and attach the stderr. That is the flag to reach for first; -vv adds requests and file operations, -vvv adds bodies.

ssoossh -vv ssh login 2> ssoossh.log

If ssh is the one invoking the client, its command line is not yours to edit, so use the environment variable instead:

SSOOSSH_VERBOSE=2 ssh bastion.example.com 2> ssoossh.log

When the problem looks like the wrong configuration rather than the wrong behavior – the wrong server, a config file you expected to be picked up and was not, a key file it cannot find – add --debug (or SSOOSSH_DEBUG=1). Both write to stderr only, so neither disturbs a ProxyCommand relay or a certificate on stdout. Full detail: Diagnostics.

Read the log before sending it: at -vvv it contains request bodies, and it always names your server, username, and file paths.

Does the server ever see my private key?

No. The client generates the keypair locally and sends only the public key; the private key goes nowhere except your local ssh-agent or a local file. This is one of the project’s hard invariants – see Security model.

How is the private key protected when it is written to a file?

On macOS and Linux it is written 0600, readable only by you and root.

Windows has no file mode, so the client sets an access list on the file instead: the account that generated the key, LocalSystem, and Administrators, with inherited entries from the containing folder switched off. That is the same set OpenSSH for Windows requires before it will use a key, and it is the closest equivalent to 0600.

One consequence worth knowing for service accounts: the account that runs ssoossh service enroll is the account named on the key. If a service then runs as a different, non-administrator user, grant that user access to the key file explicitly, exactly as you would with chown on Linux. See Service accounts.

Which of my accounts does the certificate name?

The ones you pick on the approval page, from the accounts you hold. The page starts at the accounts you last approved a request of the same type with, in this browser. With nothing remembered, a PAM or console request starts at the local account being acted as, when you hold it, because that is what the host matches against, and a user request starts at your username. Which of your names may assume which local account is the host’s decision, not the server’s – see The principals map.

ssoossh ssh inspect prints the principals on the certificate you are actually holding.

Can I stop the client asking for forwarding I never use?

Yes. The client asks for the full interactive extension set by default, and you can opt out per extension in config or with a flag:

ssoossh ssh login --no-x11-forwarding --no-agent-forwarding

The equivalent config keys are under certificate_extensions. The server narrows whatever is requested against its own configuration anyway, and the approval page shows what survived, so asking for the full set is always safe.

How do I get rid of the certificate on this machine?

ssoossh ssh logout

It removes the certificates ssoossh put in your ssh-agent – those signed by the configured CA – and nothing else. Your own keys are left alone. When key files are used instead of an agent, the files ssoossh wrote are deleted.

Where does my certificate history live?

In the web UI: the dashboard shows your recent certificates, and History shows all of them, each opening into a detail view. Service certificates link back to the code they were redeemed from. See Approving in the browser.

Why did I get an email about a certificate?

Because you turned that kind on. The three “was this you?” notifications – user, PAM, and console certificate issued – are off by default; the four about service enrollments are on. Choose at /preferences in the web UI: Email notifications.

Can my administrator lock my client settings?

Yes: an enforce file on Linux, Group Policy on Windows, or managed preferences on macOS. --debug marks those tiers in the source chain so you can see which settings your administrator has locked. They are guardrails rather than a security boundary – the client runs as you. See Client configuration and Client settings enforcement.