Skip to content

sshc.1.md

Latest commit

 

History

History
145 lines (95 loc) · 3.72 KB

sshc.1.md

File metadata and controls

145 lines (95 loc) · 3.72 KB

% SSHC(1) % sshc % 2026-02-16

NAME

sshc - SSH agent confirmation proxy for forwarded signing requests

SYNOPSIS

sshc [-D] [-s | -c] [-a path] [-n name]

sshc [-D] [-a path] [-n name] -- cmd [arg ...]

sshc [-D] [-a path] [-n name] [ssh-destination-and-args ...]

DESCRIPTION

sshc listens on a local UNIX socket and proxies requests to an upstream SSH agent socket from SSH_AUTH_SOCK.

For SSH2 sign requests, sshc asks for user confirmation through ssh-askpass. If approved, the request is forwarded to the upstream agent. If denied, sshc returns an agent failure reply.

sshc supports three behavior modes:

  • Environment-print mode (no command and no SSH arguments): starts as an agent-like process and prints shell commands to set SSH_AUTH_SOCK and SSH_AGENT_PID.
  • Explicit command mode (-- cmd ...): runs the command with SSH_AUTH_SOCK set to the proxy socket.
  • Implicit SSH wrap mode (remaining args without --): runs ssh -o ForwardAgent=<proxy_socket> ... while leaving child SSH_AUTH_SOCK set to the original upstream socket for initial authentication.

OPTIONS

-a path : Bind the proxy socket at path. If omitted, sshc creates a temporary socket under /tmp/sshc-XXXXXX/agent.sock.

-D : Stay in the foreground (debug mode). In environment-print mode, output is still printed, but no daemon fork is performed.

-s : Print Bourne-shell style environment lines.

-c : Print csh-style environment lines.

-n name : Override the name shown in askpass confirmation prompts.

-h : Show usage help and exit.

BEHAVIOR MODES

Environment-print mode

Triggered when no command and no trailing SSH arguments are given.

By default, sshc forks and prints environment setup lines from the parent, similar to ssh-agent. With -D, sshc stays in foreground and prints lines using its own PID.

Output format is auto-detected from SHELL unless forced by -s or -c.

Explicit command mode (-- cmd ...)

Triggered when command separator -- is present.

sshc runs cmd with SSH_AUTH_SOCK set to the proxy socket path. This mode does not add SSH options automatically.

Implicit SSH wrap mode

Triggered when positional arguments remain and no -- separator is used.

sshc executes:

ssh -o ForwardAgent=<proxy_socket> <original arguments...>

In this mode, child SSH_AUTH_SOCK remains the upstream socket from the caller environment, so initial client-side SSH authentication uses the upstream agent directly while remote forwarded-agent use goes through sshc.

ENVIRONMENT

SSH_AUTH_SOCK : Required. Path to the upstream SSH agent socket used by sshc.

SHELL : Used only in environment-print mode to auto-select sh vs csh output format when neither -s nor -c is specified.

EXAMPLES

Start proxy and evaluate exported variables in a POSIX shell:

eval "$(sshc -s)"

Wrap an SSH connection (implicit mode):

sshc user@example.com -p 2222

Run a command with proxy socket directly (explicit mode):

sshc -- ssh-add -l

Use a fixed socket path and custom prompt label:

sshc -a "$HOME/.ssh/sshc.sock" -n prod-bastion -- ssh -T git@example.com

EXIT STATUS

0 : Success.

1 : Runtime/configuration failure (for example missing SSH_AUTH_SOCK, socket setup failure, spawn failure, or proxy loop failure).

2 : Command-line usage error.

In explicit command mode and implicit SSH wrap mode, sshc exits with the child command exit code, or 128 + signal if the child exits due to a signal.

NOTES

  • The proxy socket is created with mode 0600.
  • If -a is omitted, the temporary socket directory is removed at exit.
  • Askpass confirmation is requested only for SSH2 sign requests.