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
| Option | What it does |
|---|---|
-i key | which private key to use |
-p port | server port (22 by default) |
-l user | user name — same as user@host |
-v, -vv, -vvv | verbose connection log: which keys were offered, why it was refused |
-q | quiet: no warnings or banners |
-o Option=value | any setting from ssh_config (see below) |
-F file | another config file instead of ~/.ssh/config |
-G host | print 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:port | local tunnel: your port → an address visible from the server |
-R port:host:port | reverse tunnel: a port on the server → an address visible from your machine |
-D port | SOCKS proxy through the server |
-N | don't run a command — tunnels only |
-f | go to the background after login (usually together with -N) |
-t / -tt | allocate a terminal (needed for sudo, top, vim in the command); -tt — even if you have no terminal yourself |
-A | forward ssh-agent to the server (trusted machines only) |
-C | compress traffic |
-4 / -6 | IPv4 only / IPv6 only |
Common settings for -o and ~/.ssh/config
| Setting | What it does |
|---|---|
HostName / User / Port | real address, user, port |
IdentityFile ~/.ssh/key | which key to offer |
IdentitiesOnly yes | offer only the specified keys, not everything in the agent |
ProxyJump bastion | go through an intermediate host (like -J) |
StrictHostKeyChecking accept-new | add a new host to known_hosts without asking, reject a changed one |
UserKnownHostsFile file | another known_hosts file (/dev/null — don't remember) |
BatchMode yes | never ask for a password or confirmation — fail immediately; for scripts |
ConnectTimeout 5 | how many seconds to wait for the connection |
ServerAliveInterval 30 | ping the server so the connection isn't dropped when idle |
LocalForward 9000 127.0.0.1:8000 | a tunnel like -L |
ForwardAgent yes | like -A |
ssh-keygen and keys
| Command | What 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 4096 | an RSA key — for old systems without ed25519 |
-N 'phrase' / -N '' | passphrase / empty — no prompts |
ssh-keygen -lf key.pub | fingerprint (SHA256:…); -E md5 — in the old MD5 format |
ssh-keygen -y -f key | recover the public key from the private key |
ssh-keygen -p -f key | change the passphrase |
ssh-keygen -c -C 'text' -f key | change the comment |
ssh-keygen -F host / -R host | find / 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@host | append the public key to authorized_keys on the server |
eval "$(ssh-agent -s)", ssh-add key | agent: 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:
| Option | What 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 |
restrict | forbid 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):
| Path | Permissions |
|---|---|
| home directory | nobody but the owner can write: 755 or stricter |
~/.ssh | 700 |
~/.ssh/authorized_keys | 600 |
| private key on the client | 600 |
All these files are owned by the user themselves, not by root.
scp options
| Option | What it does |
|---|---|
-P port | port (capital!) |
-i key | key |
-r | directories recursively |
-p | preserve modification time and permissions |
-q | no progress meter |
-C | compression |
-o Option=value | as 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_keyswith mode666or a home directory with777— and the server just answersPermission denied (publickey,…). The reason shows up only in thesshdlog (Authentication refused: bad ownership or modes); the client never learns it. -pin ssh,-Pin scp. Inscp, lowercase-pmeans "preserve file times and permissions", not the port.- A private key with mode
644will be refused by the client:WARNING: UNPROTECTED PRIVATE KEY FILE!. You needchmod 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 yeswith an explicitIdentityFilehelps.REMOTE HOST IDENTIFICATION HAS CHANGED— the server key doesn't matchknown_hosts. If the change is expected (the server was recreated), remove the old entry withssh-keygen -Rrather than disabling the check entirely.- Quotes in the remote command.
ssh host echo $HOMEsubstitutes your$HOMElocally. Put the command in single quotes. - Interactive programs need a terminal.
ssh host sudo …that asks for a password without-tanswersa terminal is required to read the password; full-screenvim,less,topalso need-t. - In
~/.ssh/configthe first value found wins: put the genericHost *at the end of the file. - After editing
/etc/ssh/sshd_config, check it withsshd -tbefore restarting the service — otherwise you can lose access.