← Full reference

ssh

Key-based login, ssh-keygen, permissions on ~/.ssh and authorized_keys, ~/.ssh/config, tunnels, copying with scp

ssh opens a shell on a remote machine or runs a single command there. Key-based login works like this: the private key stays with you, the public key goes into the user's ~/.ssh/authorized_keys on the server. The server lets the client prove it has the private key — the key itself is never sent over the network.

Syntax

ssh [options] [user@]host [command]
scp [options] source… destination

Without a command, an interactive shell opens; with a command, it runs, the output comes back to you, and ssh's exit code equals the command's exit code. In scp, a remote path is written as user@host:path.

ssh options

OptionWhat it does
-i keywhich private key to use
-p portserver port (22 by default)
-l useruser name — same as user@host
-v, -vv, -vvvverbose connection log: which keys were offered, why it was refused
-qquiet: no warnings or banners
-o Option=valueany setting from ssh_config (see below)
-F fileanother config file instead of ~/.ssh/config
-G hostprint the effective settings for a host and exit without connecting
-J [user@]jump[:port]connect via an intermediate host (jump host, bastion)
-L port:host:portlocal tunnel: your port → an address visible from the server
-R port:host:portreverse tunnel: a port on the server → an address visible from your machine
-D portSOCKS proxy through the server
-Ndon't run a command — tunnels only
-fgo to the background after login (usually together with -N)
-t / -ttallocate a terminal (needed for sudo, top, vim in the command); -tt — even if you have no terminal yourself
-Aforward ssh-agent to the server (trusted machines only)
-Ccompress traffic
-4 / -6IPv4 only / IPv6 only

Common settings for -o and ~/.ssh/config

SettingWhat it does
HostName / User / Portreal address, user, port
IdentityFile ~/.ssh/keywhich key to offer
IdentitiesOnly yesoffer only the specified keys, not everything in the agent
ProxyJump bastiongo through an intermediate host (like -J)
StrictHostKeyChecking accept-newadd a new host to known_hosts without asking, reject a changed one
UserKnownHostsFile fileanother known_hosts file (/dev/null — don't remember)
BatchMode yesnever ask for a password or confirmation — fail immediately; for scripts
ConnectTimeout 5how many seconds to wait for the connection
ServerAliveInterval 30ping the server so the connection isn't dropped when idle
LocalForward 9000 127.0.0.1:8000a tunnel like -L
ForwardAgent yeslike -A

ssh-keygen and keys

CommandWhat it does
ssh-keygen -t ed25519 -f ~/.ssh/id_x -C 'comment'create a pair: id_x (private) and id_x.pub (public)
ssh-keygen -t rsa -b 4096an RSA key — for old systems without ed25519
-N 'phrase' / -N ''passphrase / empty — no prompts
ssh-keygen -lf key.pubfingerprint (SHA256:…); -E md5 — in the old MD5 format
ssh-keygen -y -f keyrecover the public key from the private key
ssh-keygen -p -f keychange the passphrase
ssh-keygen -c -C 'text' -f keychange the comment
ssh-keygen -F host / -R hostfind / remove a host in known_hosts; a host with a non-standard port is written as [host]:port
ssh-copy-id -i key.pub [-p port] user@hostappend the public key to authorized_keys on the server
eval "$(ssh-agent -s)", ssh-add keyagent: enter the passphrase once per session; ssh-add -l — keys in the agent

authorized_keys

One line — one key: type key comment, e.g. ssh-ed25519 AAAAC3Nz… demo key. You can put comma-separated restrictions before the key:

OptionWhat it does
from="10.0.0.0/8"allow this key only from these addresses
command="…"on login, run only this command, whatever the client asks for
restrictforbid port forwarding, agent forwarding, terminal

Permissions

sshd ignores authorized_keys if others can write to it or to the directories on its path (the StrictModes check):

PathPermissions
home directorynobody but the owner can write: 755 or stricter
~/.ssh700
~/.ssh/authorized_keys600
private key on the client600

All these files are owned by the user themselves, not by root.

scp options

OptionWhat it does
-P portport (capital!)
-i keykey
-rdirectories recursively
-ppreserve modification time and permissions
-qno progress meter
-Ccompression
-o Option=valueas in ssh; aliases from ~/.ssh/config work too

Examples

# create an ed25519 key without a passphrase
ssh-keygen -t ed25519 -f ~/.ssh/id_demo -N '' -C 'demo key'

# run one command on the server
ssh -i ~/.ssh/id_demo -p 2222 user@localhost 'uname -a'

# install the public key for a user with the right permissions
install -d -m 700 -o user -g user /home/user/.ssh
cat ~/.ssh/id_demo.pub >> /home/user/.ssh/authorized_keys
chown user:user /home/user/.ssh/authorized_keys
chmod 600 /home/user/.ssh/authorized_keys

# copy a file there and a directory back
scp -P 2222 -i ~/.ssh/id_demo notes.txt user@localhost:/tmp/
scp -r -P 2222 user@localhost:~/project ./project-copy

# send data via stdin
ssh user@localhost 'cat > /tmp/copy.txt' < notes.txt

# tunnel: port 8000, open only on the server, becomes localhost:9000 on your side
ssh -f -N -L 9000:127.0.0.1:8000 user@server

# via an intermediate host
ssh -J user@bastion user@internal

# why it won't let you in: look at the Offering and Authentications that can continue lines
ssh -v -i ~/.ssh/id_demo user@localhost

# effective settings for a host, config included
ssh -G demo | grep -E '^(hostname|port|user|identityfile) '

To avoid repeating options, describe the host in ~/.ssh/config:

cat >> ~/.ssh/config <<'EOF'
Host demo
    HostName localhost
    Port 2222
    User user
    IdentityFile ~/.ssh/id_demo
    IdentitiesOnly yes
EOF

ssh demo              # same as ssh -i ~/.ssh/id_demo -p 2222 user@localhost
scp file.txt demo:/tmp/

Pitfalls

  • Bad permissions = silent refusal. authorized_keys with mode 666 or a home directory with 777 — and the server just answers Permission denied (publickey,…). The reason shows up only in the sshd log (Authentication refused: bad ownership or modes); the client never learns it.
  • -p in ssh, -P in scp. In scp, lowercase -p means "preserve file times and permissions", not the port.
  • A private key with mode 644 will be refused by the client: WARNING: UNPROTECTED PRIVATE KEY FILE!. You need chmod 600.
  • One line per key in authorized_keys. A key broken by a line wrap while copying won't work. Append with >>, not >, so you don't wipe other keys.
  • Too many authentication failures — the client tried all the keys from the agent before the right one. IdentitiesOnly yes with an explicit IdentityFile helps.
  • REMOTE HOST IDENTIFICATION HAS CHANGED — the server key doesn't match known_hosts. If the change is expected (the server was recreated), remove the old entry with ssh-keygen -R rather than disabling the check entirely.
  • Quotes in the remote command. ssh host echo $HOME substitutes your $HOME locally. Put the command in single quotes.
  • Interactive programs need a terminal. ssh host sudo … that asks for a password without -t answers a terminal is required to read the password; full-screen vim, less, top also need -t.
  • In ~/.ssh/config the first value found wins: put the generic Host * at the end of the file.
  • After editing /etc/ssh/sshd_config, check it with sshd -t before restarting the service — otherwise you can lose access.

See also

chmod · chown · rsync · useradd · openssl · ansible