SSH usage guide: command-line operations

This article covers common OpenSSH client interfaces; consult the manual for the installed version for available options. User configuration is usually in ~/.ssh/.

ssh-keygen: generate and inspect keys#

# 生成 ed25519 密钥对（-t 类型 / -C 注释 / -f 输出路径）
ssh-keygen -t ed25519 -C "user@workstation" -f ~/.ssh/id_ed25519

# 查看公钥指纹（-l 指纹 / -E sha256 指定哈希 / -lf 对文件）
ssh-keygen -lf ~/.ssh/id_ed25519.pub

# 查看私钥对应的公钥（-y：读私钥输出公钥）
ssh-keygen -y -f ~/.ssh/id_ed25519

# 加 / 改 passphrase（-p；会先问旧密码，改/加用这个）
ssh-keygen -p -f ~/.ssh/id_ed25519

The passphrase prompt during generation When generating a new key, ssh-keygen asks Enter passphrase: press Enter for an unencrypted key, or enter a passphrase to encrypt it. Entering one is recommended.

ssh-add: manage keys in the agent#

ssh-add -l                        # 列出 agent 已加载的 key（含指纹）
ssh-add ~/.ssh/id_ed25519         # 把某个私钥加进 agent
ssh-add -d ~/.ssh/id_ed25519      # 移除某把
ssh-add -D                        # 清空 agent（全部移除）

First confirm that SSH_AUTH_SOCK points to a working agent, then check loaded keys with ssh-add -l. Your desktop may provide integration through gcr or a similar service; automatic loading is not guaranteed in every session.

Connecting and debugging#

# 测试 GitHub 连接（-T 禁止分配伪终端；GitHub 不提供 shell；正常返回 "Hi <用户>!"）
ssh -T git@github.com

# 试解析配置（-G：显示某个 Host 生效的配置项，验证 config 写没写对）
ssh -G github.com

# 调试连接（-v 详细 / -vv 更详细，看认证过程）
ssh -v git@github.com

# 指定私钥连接（-i）
ssh -i ~/.ssh/id_ed25519 user@server.example.com

A practical check for passphrase protection ssh-keygen -y -f ~/.ssh/id_ed25519: if it prints the public key immediately, the private key is unencrypted; if it waits for a passphrase, the key is encrypted.

Client configuration: GitHub and general-purpose development machines#

~/.ssh/config:

On Windows, config is at $HOME.ssh/config

Host github.com
    HostName github.com
    User git
    IdentityFile ~/.ssh/id_ed25519
    IdentitiesOnly yes                # 限制为配置身份，而非 agent 中所有身份

Host dev-server
    HostName server.example.com       # 替换为已核对的服务器地址
    User user                         # 替换为远端账户

Host *
    IdentityFile ~/.ssh/id_ed25519    # 默认私钥；多个 IdentityFile 会累积
    AddKeysToAgent yes                # 已有 agent 时自动添加从文件加载的密钥
    ServerAliveInterval 60            # 协议保活；不保证网络永不掉线
    StrictHostKeyChecking ask         # 新主机先核对指纹再确认

Everyday workflow:

# git push/pull（远端使用 GitHub SSH URL 时走相应 Host 配置）
git push origin main

# 通用开发机（先配置实际地址与账户并核对主机指纹）
ssh dev-server

config permissions chmod 600 ~/.ssh/config is a common conservative setting, not the only permitted value. User configuration must meet OpenSSH’s ownership and write-permission requirements; violations may cause an immediate error. For declaratively managed files, handle permissions in the configuration source.

Related articles#

• Concepts: The SSH authentication model
• agent and passphrase → ssh-agent, passphrases, and keyrings
• References: ssh-keygen man | ssh config man

Place specific Host blocks before general defaults, because most settings use the first value obtained; options that permit multiple values, such as IdentityFile, accumulate. Successful GitHub authentication produces a message saying shell access is unavailable and usually returns exit code 1, so a nonzero exit code alone does not indicate authentication failure. On the first connection, check the host fingerprint against the official fingerprint or a trusted console. If a host key changes, investigate the cause before taking action; do not simply disable verification.