~/.ssh/config

Save repeatable connection options in the client configuration file.

Before you run

The first block is file content, not a shell command: edit ~/.ssh/config locally. Keep specific Host blocks before broad Host * defaults because the first obtained value normally wins. Protect the file (typically chmod 600 ~/.ssh/config). Keep passwords and private-key contents out of it. ServerAlive settings detect an unresponsive SSH peer, not every application failure. ssh -G prints effective configuration without connecting and may expose private addresses or paths.

Examples

Add a lab alias with port, identity and SSH keepalive settings.

Host lab
    HostName server.example.com
    User alice
    Port 2222
    IdentityFile ~/.ssh/id_ed25519
    IdentitiesOnly yes
    ServerAliveInterval 30
    ServerAliveCountMax 3

Connect using the alias, or inspect its effective configuration.

ssh lab
ssh -G lab

Options and examples

Host patternCommon

Start a block matching an SSH alias or host pattern. Put specific blocks before general ones: the first obtained value is used.

Example

Host lab
    HostName server.example.com

HostName / User / PortCommon

Set the actual server address, login name, and SSH port for the matching host.

Example

Host lab
    HostName server.example.com
    User alice
    Port 2222

IdentityFile / IdentitiesOnlyCommon

Select a private key and, when set to yes, limit offered identities to configured ones.

Example

Host lab
    IdentityFile ~/.ssh/id_ed25519
    IdentitiesOnly yes

ProxyJumpCommon

Connect through one or more SSH jump hosts.

Example

Host lab
    ProxyJump alice@bastion.example.com

LocalForward

Configure a local listener forwarded to a destination reached from the SSH server.

Example

Host lab
    LocalForward 127.0.0.1:15432 db.internal.example.com:5432

RemoteForward

Configure a remote listener forwarded to a destination reached from the local computer; server policy applies.

Example

Host lab
    RemoteForward 127.0.0.1:18080 127.0.0.1:8080

DynamicForward

Configure a local SOCKS listener. Clients must be configured separately.

Example

Host lab
    DynamicForward 127.0.0.1:1080

ExitOnForwardFailure

Fail the SSH connection if requested initial forwarding listeners cannot be established.

Example

Host lab
    ExitOnForwardFailure yes

ServerAliveInterval / ServerAliveCountMaxCommon

Configure SSH-level peer checks and the number of unanswered checks before disconnecting.

Example

Host lab
    ServerAliveInterval 30
    ServerAliveCountMax 3

ConnectTimeout

Set the connection timeout in seconds.

Example

Host lab
    ConnectTimeout 10

ForwardAgent

Control agent forwarding. A compromised remote host can request signatures; enable only for trusted hosts.

Example

Host lab
    ForwardAgent no

Include

Include additional SSH configuration files; order affects which values are selected.

Example

Include ~/.ssh/config.d/*.conf

Authoritative references

Reviewed October 27, 2026