basforge

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

    RU
    ManualLinuxSSH

    SSH keys: from ssh-keygen to passwordless login

    Create an ed25519 key with a passphrase on your computer, put the public half into authorized_keys on the server, and check that the server lets you in with the key. Don’t turn off password login yet — that’s the next step, sshd_config.

    What you end up with

    computer                                  server
    ~/.ssh/id_ed25519        private key      ~example-user/.ssh/authorized_keys
                             600, passphrase    ssh-ed25519 AAAA…key… laptop-2026
    ~/.ssh/id_ed25519.pub    public key ─────── the same line, one per device
    ~/.ssh/known_hosts       server keys

    The private half never leaves your computer. Only the .pub goes to the server, to GitHub, to the provider’s panel.

    Which key to create

    Type When to use it
    ed25519 almost always. Short (the .pub line is about 100 characters), fast; the ssh-keygen default since OpenSSH 9.5
    ed25519-sk you have a FIDO2 hardware key (YubiKey and the like): the private part lives in it, and you log in with a touch. Needs OpenSSH 8.2+ on both sides
    rsa -b 4096 the server or device doesn’t know ed25519: an old router, network gear, OpenSSH older than 6.5
    ecdsa a policy requires it and doesn’t allow ed25519; no reason to pick it otherwise
    dsa never: OpenSSH 10.0 removed it entirely, and Ubuntu 26.04 won’t accept such a key

    Setup

    1. Check for an existing key

      ls -l ~/.ssh/
      # id_ed25519  id_ed25519.pub  known_hosts

      In PowerShell: ls $env:USERPROFILE\.ssh. If a key is already there, skip the next step. Creating a new one on top of the old one cuts you off from everywhere the old one opens: ssh-keygen asks Overwrite (y/n)?.

    2. Create the key

      ssh-keygen -t ed25519 -C "laptop-2026"
      # Generating public/private ed25519 key pair.
      # … path — Enter, passphrase — twice …
      # Your identification has been saved in /home/me/.ssh/id_ed25519
      # Your public key has been saved in /home/me/.ssh/id_ed25519.pub
      # The key fingerprint is:
      # SHA256:u7WTRQvHCGalFd0cVdGQ7Wm7cULmdHtHUpyj6Q0uXcA laptop-2026
      • -C is the comment at the end of the .pub line. Put the device and the year: two years from now it tells you which line in authorized_keys to delete. The default is user@hostname.
      • A passphrase — yes. It encrypts the file on disk: a stolen id_ed25519 is useless without it. You won’t type it every time — the agent asks once per session (ssh-agent).
      • The default file name is id_ed25519: ssh finds such a key and offers it to servers with no setup. A key for a separate job gets its own name (-f ~/.ssh/github_infra), and then you point to it explicitly — -i or IdentityFile in ~/.ssh/config (~/.ssh/config).
    3. Put the public key on the server

      While password login is still open, ssh-copy-id does everything: creates ~/.ssh, appends the line and sets permissions.

      ssh-copy-id -i ~/.ssh/id_ed25519.pub [email protected]
      # Number of key(s) added: 1

      Windows has no ssh-copy-id, but one PowerShell command does the same:

      type $env:USERPROFILE\.ssh\id_ed25519.pub | ssh example-[email protected] "mkdir -p ~/.ssh && chmod 700 ~/.ssh && cat >> ~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keys"

      >> appends instead of overwriting: keys already in the file stay.

      If the server was created with a key from the provider’s panel, cloud-init has already put it in place — usually for root or ubuntu, depending on the provider. Your own user and its key — First login to a server.

    4. Check permissions on the server

      sshd checks permissions before it reads the key (StrictModes yes by default). If anyone else can change the directory or the file, the key is silently rejected.

      ls -ld ~ ~/.ssh ~/.ssh/authorized_keys
      # drwxr-x--- 4 example-user example-user 4096 … /home/example-user
      # drwx------ 2 example-user example-user 4096 … /home/example-user/.ssh
      # -rw------- 1 example-user example-user   93 … /home/example-user/.ssh/authorized_keys

      The home directory, ~/.ssh and authorized_keys must not be writable by others. Ubuntu lets group write through if the group is private — only the user is in it, as for example-user after adduser; anyone else in the group and the key is refused. The log then says Authentication refused: bad ownership or modes for directory /home/example-user. If the files were created with sudo, root owns them — give them back: sudo chown -R example-user:example-user /home/example-user/.ssh.

    5. Log in with the key

      ssh -v [email protected] 2>&1 | grep -E 'Offering|Server accepts|Authenticated'
      # debug1: Offering public key: /home/me/.ssh/id_ed25519 ED25519 SHA256:u7WT… agent
      # debug1: Server accepts key: /home/me/.ssh/id_ed25519 ED25519 SHA256:u7WT… agent
      # Authenticated to 203.0.113.10 ([203.0.113.10]:22) using "publickey".

      A prompt for the key’s passphrase is normal: that’s how the client decrypts the file. A prompt for [email protected]'s password: means the key didn’t match — see “If it doesn’t work”.

    6. Add a second key

      Before you turn off password login, the server should have two keys from different devices: say, a laptop and a desktop, or a key written to a USB stick and put in a drawer. Losing one device then doesn’t lock you out.

      cat ~/.ssh/authorized_keys
      # ssh-ed25519 AAAAC3Nza… laptop-2026
      # ssh-ed25519 AAAAC3Nza… desktop-2026

      Next, close password and root logins: sshd_config.

    A line in authorized_keys

    Comma-separated restrictions can go before the key. That’s how an automation key is limited to one job:

    from="198.51.100.7",command="rrsync -ro /srv/backup",restrict ssh-ed25519 AAAAC3Nza… backup1-pull
    Option What it does
    from="198.51.100.7" the key is accepted only from this address; lists and masks work: from="10.0.0.0/8,!10.0.0.13"
    command="…" whatever the client asks for, this command runs; the original is in $SSH_ORIGINAL_COMMAND
    restrict turns everything off at once: shell, port and agent forwarding, X11. Give back what’s needed: restrict,pty
    expiry-time="20261231" the key stops working after the date (OpenSSH 7.7+)

    A key that rsync uses for backups, with such a line, won’t open a shell even if it leaks along with the server it lives on.

    If it doesn’t work

    Permission denied (publickey) even though the key was added

    Cause
    The key belongs to the wrong user (added to /root/.ssh while you log in as example-user), the line in authorized_keys is broken by a line wrap, or ~ or ~/.ssh has permissions that are too open: with StrictModes yes (the default) sshd won’t read such a file.
    Fix
    On the server: ls -ld ~ ~/.ssh ~/.ssh/authorized_keys — you need drwx------ on .ssh and -rw------- on the file; journalctl -u ssh -n 20 names the reason, for example Authentication refused: bad ownership or modes.

    WARNING: UNPROTECTED PRIVATE KEY FILE! and the key isn’t used

    Cause
    Other users of the computer can read the private key. On Linux and macOS, permissions are wider than 600; on Windows, the file’s ACL has someone besides the owner.
    Fix
    Linux, macOS: chmod 600 ~/.ssh/id_ed25519. Windows: icacls $env:USERPROFILE\.ssh\id_ed25519 /inheritance:r /grant:r "$($env:USERNAME):F".

    Load key "…": invalid format

    Cause
    The key file got damaged in copying (CRLF line endings, a missing final newline), or it’s a PuTTY key in .ppk format.
    Fix
    Convert .ppk to OpenSSH format: PuTTYgen, Conversions — Export OpenSSH key. Take a damaged copy again from the original computer.

    No ssh-copy-id: ssh-copy-id: command not found

    Cause
    OpenSSH for Windows doesn’t include it.
    Fix
    The PowerShell command in step 3 does the same thing.

    The server still asks for the user’s password

    Cause
    The key didn’t match, and the server fell back to a password. Most often the client offered the wrong key.
    Fix
    ssh -v [email protected] 2>&1 | grep -E 'Offering|Server accepts|Authenticated' shows which keys went out and which was accepted. Point to the right key with -i or in ~/.ssh/config (~/.ssh/config).

    Forgot the key’s passphrase

    Cause
    There’s no way to recover it: the key is encrypted with that passphrase.
    Fix
    Create a new key, log in with your spare key or through the provider console (Provider console), and replace the line in authorized_keys.

    How to check

    To be sure you log in with the key and not the user’s password, tell the client not to try passwords at all:

    ssh -o PasswordAuthentication=no -o KbdInteractiveAuthentication=no [email protected] 'echo ok'
    # ok

    The fingerprint of your key matches the line on the server:

    ssh-keygen -lf ~/.ssh/id_ed25519.pub
    # 256 SHA256:u7WTRQvHCGalFd0cVdGQ7Wm7cULmdHtHUpyj6Q0uXcA laptop-2026 (ED25519)
    ssh [email protected] 'ssh-keygen -lf ~/.ssh/authorized_keys'
    # 256 SHA256:u7WTRQvHCGalFd0cVdGQ7Wm7cULmdHtHUpyj6Q0uXcA laptop-2026 (ED25519)
    # 256 SHA256:Qm4x… desktop-2026 (ED25519)