basforge

Search titles, text and the “If it doesn’t work” cases.

    RU
    ConfigLinuxSSH

    ~/.ssh/config: short names, a key per server, jumping through a server

    The client’s settings file: instead of ssh -i ~/.ssh/id_ed25519 -p 22 [email protected] you type ssh web1, and scp, rsync and git understand the same name. As on the server, the first value found wins — put the shared Host * settings at the end.

    How ssh reads this file

    Sources in order: command-line options, then ~/.ssh/config, then the system-wide /etc/ssh/ssh_config. Within the file, ssh walks top to bottom through the Host blocks that match the name, and for each option takes the first value. So:

    • specific servers’ blocks go at the top;
    • Host * with shared settings goes last, or it overrides everything below;
    • one name can match several blocks: web1 matches both Host web1 and Host *.

    ssh -G shows what you get for a given name: it parses the file and prints the result without connecting anywhere.

    The file is ~/.ssh/config; on Windows, C:\Users\<name>\.ssh\config. The tilde works in paths there too.

    The file, block by block

    Server names and addresses are placeholders: web1, web2, db1, backup1, addresses from the documentation ranges.

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

    Pull in files from a directory: the work servers’ config lives in its own file, which you can keep in another repository or not show at all. Include must come before the first Host — inside a block it only applies to that block.

    default nothing included

    Host web1
        HostName 203.0.113.10
        User example-user
        IdentityFile ~/.ssh/id_ed25519
        IdentitiesOnly yes
    Key part

    A short name instead of the address, user and key. IdentitiesOnly yes offers the server only this key, not every key in the agent in turn: with five keys in the agent, a server with MaxAuthTries 3 drops the connection before it gets to the right one (sshd_config).

    default:User your local user namePort 22IdentitiesOnly no

    Host web2 db1 backup1
        HostName %h.example.org
        User example-user
        IdentityFile ~/.ssh/id_ed25519
        IdentitiesOnly yes

    Several names on one line — shared settings for a group of servers. Each has its own address, so HostName goes in separate blocks above or in config.d. %h is the name you typed in the command.

    Host github-infra
        HostName github.com
        User git
        IdentityFile ~/.ssh/github_infra
        IdentitiesOnly yes

    A GitHub alias with its own key: a deploy key opens one repository (Server configs in git, Each key and token grants one access). In git, write the URL with the alias: git@github-infra:example-user/infra-web1.git. The user on GitHub is always git.

    Host db-internal
        HostName 10.0.0.5
        User example-user
        ProxyJump web1

    A server with no public address, reached through the first one. ProxyJump connects to web1 and, through it, to 10.0.0.5; the key stays on your computer and never lands on the jump host. On the command line: ssh -J web1 [email protected].

    default direct

    Host *
        ServerAliveInterval 30
        ServerAliveCountMax 3

    Every 30 seconds the client sends the server an empty packet; three missed replies in a row and the connection closes. The home router’s NAT doesn’t forget a quiet session, and a dead one doesn’t hang for minutes.

    default:ServerAliveInterval 0 — don’t sendServerAliveCountMax 3

        AddKeysToAgent yes

    A key with a passphrase goes into the agent on first use, and the passphrase isn’t asked again until the agent session ends (ssh-agent). Needs a running agent: on Windows, the ssh-agent service.

    default no

        StrictHostKeyChecking ask

    An unknown server gets a yes/no prompt with the fingerprint; a changed key gets a refusal. accept-new silently accepts only new servers and still complains about a changed key — good for scripts that connect to fresh machines. Ubuntu’s client config also hashes names in known_hosts (HashKnownHosts yes): the file doesn’t give away your server list, but you can’t read it by eye either.

    default:StrictHostKeyChecking askHashKnownHosts no (yes on Ubuntu)

    Host web1 web2 db1 backup1
        ControlMaster auto
        ControlPath ~/.ssh/cm/%C
        ControlPersist 10m

    A shared connection: the first ssh web1 holds the channel, and later ssh, scp, git ride on it without logging in again — a second session opens instantly. Linux and macOS only. Create ~/.ssh/cm in advance, mode 700.

    default no

        ForwardAgent yes

    Don’t turn on agent forwarding, neither for Host * nor for your servers: root on the server can sign anything with your agent while the session is open. For jumping through a server there’s ProxyJump (ssh-agent).

    default no

    Tokens in values

    Token What it expands to
    %h the host name after HostName substitution; in the HostName line itself, the name from the command
    %n the name exactly as typed in the command
    %r the remote user
    %p the port
    %C a hash of %l%h%p%r — a short name for the ControlPath socket
    %d your local home directory

    If it doesn’t work

    A setting in a host block has no effect

    Cause
    Higher up in the file there’s Host * or another matching block with the same setting — and the first value wins.
    Fix
    ssh -G web1 | grep -i <setting> shows the result. Specific host blocks go up, Host * goes at the end of the file.

    Bad owner or permissions on /home/me/.ssh/config

    Cause
    The group or others can write to the file.
    Fix
    chmod 600 ~/.ssh/config.

    On Windows the connection fails with ControlMaster

    Cause
    OpenSSH for Windows can’t share a connection over a Unix socket: with any ControlPath ssh fails — getsockname failed: Not a socket, then Read from remote host …: Unknown error.
    Fix
    Keep the ControlMaster block only in the Linux and macOS config, or under a Match exec that doesn’t fire on Windows.

    git clone git@github-infra:… — Could not resolve hostname github-infra

    Cause
    Git runs an ssh that reads a different config: for example, Git for Windows with its own ssh.exe and a different HOME.
    Fix
    Tell git which ssh to use: git config --global core.sshCommand C:/Windows/System32/OpenSSH/ssh.exe, and check ssh -G github-infra.

    Through ProxyJump — channel 0: open failed: administratively prohibited

    Cause
    The jump host has AllowTcpForwarding no, and a jump works through forwarding.
    Fix
    Allow forwarding there: AllowTcpForwarding yes, or at least a Match User example-user block with that line.

    How to check

    ssh -G parses the file for a name and prints the result without connecting. For web1 from the file above:

    ssh -G web1 | grep -E '^(hostname|user|port|identityfile|identitiesonly|serveraliveinterval) '
    # user example-user
    # hostname 203.0.113.10
    # port 22
    # identitiesonly yes
    # serveraliveinterval 30
    # identityfile ~/.ssh/id_ed25519

    The jump — which path ssh will take:

    ssh -G db-internal | grep -i '^proxyjump'
    # proxyjump web1

    The git alias:

    ssh -T github-infra
    # Hi example-user/infra-web1! You've successfully authenticated, but GitHub does not provide shell access.