Introduction to SSH (Secure Shell)

1. What Is SSH?


• SSH (Secure Shell) is a cryptographic network protocol used to securely connect to remote computers.


• It allows you to:
  • log in to remote servers,
  • run commands,
  • transfer files,
  • tunnel network traffic,
  • and manage systems securely over an encrypted connection.


• SSH replaces older insecure protocols such as telnet and rsh, which transmitted passwords in plain text.


• SSH is one of the most essential tools for developers, system administrators, DevOps engineers, and cloud users.



2. How SSH Works: A Simple Overview


• You usually authenticate using:
  • password (less secure)
  • SSH key pair (much more secure)


• The general connection flow:

Your Machine  → (encrypted tunnel) → Remote Server



• All communication goes through port 22 by default.



3. SSH Key Pairs


• SSH keys are the most secure way to authenticate.


• A key pair consists of:
• Private key — stays on your machine and must never be shared.
• Public key — stored on the remote server in ~/.ssh/authorized_keys.


• To generate a key pair:

ssh-keygen -t ed25519 -C "your_email@example.com"

• This creates id_ed25519 the private key and id_ed25519.pub the public key.
• For older systems, -t rsa may be used, but ed25519 is recommended for better security and performance.



4. Connecting to a Remote Server


• Basic SSH command:

ssh username@hostname



• Examples:

ssh ubuntu@54.23.11.222       # AWS EC2 instance
ssh user@myserver.com         # domain
ssh root@192.168.1.10         # LAN server



• If your key is named something else:

ssh -i mykey.pem ubuntu@<public-ip>



• If the server uses a non-default port:

ssh -p 2222 user@host




5. First-Time Connection and Host Keys


• The first time you connect to a server, SSH shows a message:

The authenticity of host 'example.com (54.x.x.x)' can't be established.
Are you sure you want to continue connecting (yes/no)?

• This is SSH verifying the server’s identity.
• It stores the server’s fingerprint in ~/.ssh/known_hosts.
• Next time you connect, SSH will warn you if the fingerprint changes (which could indicate a security risk).



6. SSH Directory Layout


• Your local SSH configuration lives in ~/.ssh/:

~/.ssh/
    id_ed25519           # private key
    id_ed25519.pub       # public key
    authorized_keys      # keys allowed to log in (on server)
    known_hosts          # server fingerprints
    config               # optional config file




7. SSH Config File (Simplifies Connections)


• You can create ~/.ssh/config to store shortcuts and settings:

Host my-ec2
    HostName 54.23.11.222
    User ubuntu
    IdentityFile ~/.ssh/mykey.pem
    Port 22



• Now connect with:

ssh my-ec2



• This is extremely useful when working with many servers.



8. To Copy Files via SSH


• Use scp (Secure Copy) or rsync over SSH.


• To Upload a file:

scp file.txt user@host:/remote/path/



• To Download a file:

scp user@host:/remote/path/file.txt ./



• To Copy a folder recursively:

scp -r ./myfolder user@host:/var/www/



• rsync example (faster, syncs changes only):

rsync -avz ./site/ user@host:/var/www/site/




9. Port Forwarding (Tunneling)


• SSH can forward ports to securely tunnel traffic.


• Local port forward — access remote service through local port:

ssh -L 8080:localhost:3000 user@host

• This forwards localhost:8080 on your machine → localhost:3000 on the remote server.
• Useful for:
  • remote development,
  • databases,
  • private web dashboards.


• Reverse port forwarding:

ssh -R 9000:localhost:3000 user@host

• This allows a remote server to access a local port on your machine.



10. SSH Agent (Storing Keys Temporarily)


• The SSH agent holds private keys in memory so you don’t need to type your passphrase each time.

eval "$(ssh-agent)"
ssh-add ~/.ssh/id_ed25519

• Once added, SSH can use the keys automatically.



11. Hardening SSH Security


• SSH is secure, but you can harden it further by:
• Disabling password login (use only keys)
• Changing SSH port
• Restricting users with AllowUsers
• Using fail2ban to block repeated failures
• Enforcing firewall rules


• SSH server config file (on remote server): /etc/ssh/sshd_config.

Common SSH Command Options

1. Overview


• This chapter summarizes the most commonly used ssh client options.


• These options apply to the OpenSSH client (the one you normally use on Linux/macOS and WSL).



2. Basic Connection and Identity Options


• These options are most frequently used when connecting to a host.



Option	Description	Example
-p <port>	Connect to the remote host on the specified TCP port (default is 22).	ssh -p 2222 user@example.com
-i <identity_file>	Use this private key file for authentication (instead of the default ~/.ssh/id_*).	ssh -i ~/.ssh/mykey.pem ubuntu@host
-l <user>	Specify the remote login user (same as user@host).	ssh -l ubuntu 1.2.3.4
-F <configfile>	Use an alternative SSH config file instead of ~/.ssh/config.	ssh -F ./ssh_config my-alias
-4, -6	Force use of IPv4 (-4) or IPv6 (-6).	ssh -4 user@example.com
-C	Enable compression on the SSH connection (useful on slow links).	ssh -C user@example.com
-q	Quiet mode: suppress most warnings and diagnostic messages.	ssh -q user@example.com




3. Authentication and Key Handling


• Options related to authentication behavior and keys.



Option	Description	Example
-i <identity_file>	Use specified private key file (repeated here because it is so common).	ssh -i ~/.ssh/id_ed25519 user@host
-A	Enable SSH agent forwarding (forward your local agent to the remote host).	ssh -A user@jumphost
-a	Disable SSH agent forwarding (explicitly turn it off).	ssh -a user@host
-K	Enable GSSAPI-based authentication (Kerberos etc.), if configured.	ssh -K user@host
-o PreferredAuthentications=<methods>	Specify which authentication methods to try (e.g., publickey,password).	ssh -o PreferredAuthentications=publickey user@host
-o IdentitiesOnly=yes	Use only the explicitly specified identities (not every key from the agent).	ssh -i ~/.ssh/work_rsa -o IdentitiesOnly=yes user@host




4. Host Key Checking and Security


• Options controlling how SSH verifies the server identity.



Option	Description	Example
-o StrictHostKeyChecking=yes|no|ask	Control behavior when a host key changes or is unknown: yes = refuse; no = accept automatically; ask = prompt.	ssh -o StrictHostKeyChecking=ask user@host
-o UserKnownHostsFile=<file>	Use a particular known-hosts file instead of ~/.ssh/known_hosts.	ssh -o UserKnownHostsFile=./known_hosts user@host
-o VerifyHostKeyDNS=yes|no	Check host keys via DNS (SSHFP records), if configured.	ssh -o VerifyHostKeyDNS=yes user@host
-o HostKeyAlgorithms=<list>	Specify which host key algorithms to accept (useful when dealing with older servers).	ssh -o HostKeyAlgorithms=ssh-ed25519 user@oldhost




5. Port Forwarding and Tunneling


• These options are used to tunnel TCP traffic through an SSH connection.



Option	Description	Example
-L <local_port>:<host>:<host_port>	Local port forward: listen on local port and forward to host:host_port from the remote side.	ssh -L 8080:localhost:3000 user@server
-R <remote_port>:<host>:<host_port>	Remote port forward: listen on remote port and forward back to host:host_port on your local side.	ssh -R 9000:localhost:3000 user@server
-D <local_port>	Dynamic port forwarding (SOCKS proxy) on the given local port. Useful for tunneling arbitrary traffic through SSH.	ssh -D 1080 user@server
-N	Do not execute a remote command; only forward ports (no shell).	ssh -N -L 5432:db.internal:5432 user@bastion
-f	Run SSH in the background (after asking for passwords / passphrases).	ssh -f -N -L 8080:localhost:3000 user@server
-g	Allow remote hosts to connect to local forwarded ports (for -L / -D).	ssh -g -L 8080:localhost:3000 user@server




6. Jump Hosts and Proxies


• Options for connecting to a host via intermediate servers.



Option	Description	Example
-J <user@jump>[,<user@jump2>...]	Use one or more jump hosts (proxy jumps). SSH will connect through these hosts to reach the final destination.	ssh -J jumphost user@target
-o ProxyCommand=<command>	Use a custom command to connect to the server (legacy way to implement jump hosts).	ssh -o ProxyCommand="ssh jumphost nc %h %p" user@target
-o ProxyJump=<host>	Same as -J, for use in config files.	ssh -o ProxyJump=jumphost user@target




7. X11 Forwarding and Terminal Behavior


• Options that affect how the terminal and graphical forwarding behave.



Option	Description	Example
-X	Enable X11 forwarding (trusted or untrusted based on server config; sometimes restricted).	ssh -X user@remote
-Y	Enable trusted X11 forwarding (less restricted, but requires caution).	ssh -Y user@remote
-t	Force pseudo-tty allocation (useful when running interactive commands like top or sudo).	ssh -t user@remote "sudo journalctl -f"
-T	Disable pseudo-tty allocation (never allocate a terminal).	ssh -T git@github.com




8. Debugging, Logging, and ControlMaster


• Options for seeing what SSH is doing and reusing connections.



Option	Description	Example
-v, -vv, -vvv	Increase verbosity of logging (more v = more detailed). Useful for debugging handshake/auth problems.	ssh -vv user@host
-E <logfile>	Append debug logs to the specified file.	ssh -vvE ssh.log user@host
-M	Place the SSH connection into "master" mode for connection sharing (ControlMaster).	ssh -M -S /tmp/ssh-sock user@host
-S <ctl_socket>	Specify the control socket path used for ControlMaster/ControlPath connections. Allows subsequent SSH calls to reuse the same TCP connection.	ssh -S /tmp/ssh-sock user@host
-O check|forward|exit	Send control commands to an existing master connection (check status, request port forwarding, or close it).	ssh -O check -S /tmp/ssh-sock user@host




9. Generic -o Option (Config Key = Value)


• -o lets you specify any SSH config directive on the command line. Common patterns:



Example -o usage	Meaning
-o ConnectTimeout=5	Fail if connection cannot be established within 5 seconds.
-o ServerAliveInterval=30	Send keepalive messages every 30 seconds to avoid idle disconnections.
-o ServerAliveCountMax=3	After 3 unanswered keepalives, SSH will terminate the connection.
-o LogLevel=ERROR	Show only error messages (less verbose than the default).
-o Compression=yes	Enable compression (same effect as -C).

Introduction to ssh-keygen

1. What Is It?


• ssh-keygen is the standard tool (from OpenSSH) for creating and managing SSH key pairs.


• It is used to:
  • generate new SSH keys,
  • change key passphrases,
  • convert keys to different formats,
  • print public keys from private keys,
  • manage host keys / known_hosts entries.


• SSH keys are the recommended way to authenticate to remote servers instead of passwords.


• On Linux/macOS, ssh-keygen is usually installed by default together with ssh.



2. Basic Usage: Generating a Key Pair


• The most common usage: generate a new key pair (private + public key):

ssh-keygen -t ed25519 -C "your_email@example.com"



• Interactive steps:
• file path – default is ~/.ssh/id_ed25519
• passphrase – optional but highly recommended


• Result:
• ~/.ssh/id_ed25519 → private key
• ~/.ssh/id_ed25519.pub → public key


• The public key is what you copy to remote servers (e.g., into ~/.ssh/authorized_keys).



3. Key Types and Algorithms


• You choose the algorithm with -t:



Type	Option	Notes
Ed25519	-t ed25519	Modern, fast, short keys, recommended default if supported.
RSA	-t rsa	Widely supported, use 3072 or 4096 bits for security.
ECDSA	-t ecdsa	Elliptic curve, okay, but ed25519 is often preferred.
DSA	-t dsa	Deprecated/insecure, do not use.



• Example: strong RSA key:

ssh-keygen -t rsa -b 4096 -C "your_email@example.com"




4. Common Options (Quick Table)


• Most frequently used command-line flags:



Option	Meaning	Example
-t <type>	Key type (rsa, ed25519, ecdsa, ...).	ssh-keygen -t ed25519
-b <bits>	Key size (mainly for RSA).	ssh-keygen -t rsa -b 4096
-C <comment>	Add a comment (often an email or label).	ssh-keygen -C "laptop key"
-f <filename>	Specify output file (private key path).	ssh-keygen -f ~/.ssh/myserver_ed25519
-N <passphrase>	Set passphrase non-interactively (be careful with shell history).	ssh-keygen -N "mySecret" ...
-p	Change the passphrase of an existing key.	ssh-keygen -p -f ~/.ssh/id_ed25519
-y	Read a private key and print the corresponding public key.	ssh-keygen -y -f ~/.ssh/id_ed25519 > id_ed25519.pub
-l	Show fingerprint of a key.	ssh-keygen -l -f ~/.ssh/id_ed25519.pub
-E <hash>	Specify hash for fingerprints (e.g., md5, sha256).	ssh-keygen -l -E sha256 -f id_ed25519.pub




5. Default Locations and File Names


• By default, keys live under ~/.ssh/:

~/.ssh/
    id_ed25519        ← default ed25519 private key
    id_ed25519.pub    ← its public key
    id_rsa            ← default RSA private key
    id_rsa.pub        ← its public key



• You can have multiple keys for different purposes:
• ~/.ssh/id_github
• ~/.ssh/id_company
• ~/.ssh/id_personal_server


• Use -f when generating to pick a non-default name:

ssh-keygen -t ed25519 -f ~/.ssh/id_github -C "github key"




6. Changing or Adding a Passphrase


• To add or change a passphrase on an existing key:

ssh-keygen -p -f ~/.ssh/id_ed25519

• Interactive steps:
• Enter old passphrase (if any).
• Enter new passphrase (or press Enter for empty, which is not recommended).
• This does not change the key itself, only how it is encrypted on disk.



7. Printing the Public Key from a Private Key (-y)


• If you lost your .pub file but still have the private key, you can regenerate the public key:

ssh-keygen -y -f ~/.ssh/id_ed25519 > ~/.ssh/id_ed25519.pub

• -y reads the private key, extracts the matching public key, and prints it to stdout.



8. Checking Key Fingerprints (-l, -E)


• Fingerprints help you verify that a key (or host) is the one you expect.
• Example:

ssh-keygen -l -f ~/.ssh/id_ed25519.pub

• Add -E sha256 or -E md5 to specify hash algorithm:

ssh-keygen -l -E sha256 -f ~/.ssh/id_ed25519.pub




9. Managing known_hosts Entries


• ssh-keygen can also manipulate the ~/.ssh/known_hosts file (where host keys are stored).



Command	Meaning
ssh-keygen -F hostname	Find and print host keys for hostname in known_hosts.
ssh-keygen -R hostname	Remove all keys for hostname from known_hosts (useful if the remote host changed its key).



• Example: remove a stale known-host entry:

ssh-keygen -R example.com




10. Typical Real-World Workflows


• Generate a key and use it for GitHub:

# 1) Generate key
ssh-keygen -t ed25519 -f ~/.ssh/id_github -C "github-email@example.com"

# 2) Print the public key
cat ~/.ssh/id_github.pub

# 3) Copy the printed key into GitHub > Settings > SSH and GPG keys

# 4) Use in SSH config
cat >> ~/.ssh/config <<EOF
Host github.com
    HostName github.com
    User git
    IdentityFile ~/.ssh/id_github
EOF



• Generate a key for a specific server:

ssh-keygen -t ed25519 -f ~/.ssh/id_server -C "server key"

# copy public key to server (if ssh-copy-id is available)
ssh-copy-id -i ~/.ssh/id_server.pub user@server

# or manually:
cat ~/.ssh/id_server.pub  # copy this line
# then paste it into server's ~/.ssh/authorized_keys




11. Security Tips


• Always protect your private key with correct file permissions (should be readable only by you):

chmod 600 ~/.ssh/id_ed25519

• Use a passphrase for keys on laptops or shared devices.
• Consider using an SSH agent (ssh-agent + ssh-add) to avoid entering the passphrase every time.
• Use modern key types (ed25519 or RSA 3072+/4096) rather than old ones (DSA).

SSH authorized_keys and Multiple Public Keys

1. What Is ~/.ssh/authorized_keys?


• On the server, each user can have a file ~/.ssh/authorized_keys.


• This file tells the SSH daemon: “These public keys are allowed to log in as this user.”


• When you connect using a private key from your client:
  • The server checks whether the matching public key exists in authorized_keys for the target user.
  • If there is a match and the signature is valid, login is allowed (subject to restrictions).


• So, authorized_keys is basically the allow list of public keys for that Unix account.



2. Can It Contain Multiple Public Keys?


• Yes. ~/.ssh/authorized_keys can contain many public keys.


• The usual convention is:
  • one public key per line,
  • optionally followed by a comment (e.g. which machine or person it belongs to).


• Example structure (conceptually):

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIMyKeyForLaptop    laptop
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIAnotherKeyForPC   desktop
ssh-rsa     AAAAB3NzaC1yc2EAAAADAQABAAABAQDemoKey...   old-server

• Each line is an independent authorized key. Any matching private key from these lines can log in as this user.



3. Format of a Single Line in authorized_keys


• A typical line has this basic shape:

<key-type> <base64-key-data> [<comment>]

• Examples:

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIBlaBlaBla... my-laptop
ssh-rsa     AAAAB3NzaC1yc2EAAAADAQABAAABAQDemo... old-key

• <key-type> could be:
  • ssh-ed25519
  • ssh-rsa (legacy)
  • ecdsa-sha2-nistp256
  • etc., depending on what your SSH version supports.


• <base64-key-data> is a long base64 string representing the public key.


• <comment> is free text, commonly:
  • an email address,
  • a hostname,
  • or “who/what this key belongs to”.


• For multiple keys, you just add another line with this format.



4. Adding Multiple Keys Manually


• Suppose you have two public key files on your client:
  • id_ed25519.pub (laptop)
  • work_ed25519.pub (work machine)


• On the server, you can append both to authorized_keys:

cat id_ed25519.pub >> ~/.ssh/authorized_keys
cat work_ed25519.pub >> ~/.ssh/authorized_keys

• After that, your authorized_keys might look like:

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAALaptopKeyBase64... laptop
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAASomeWorkKeyBase64... work

• Either corresponding private key can now log in as this user.



5. Using ssh-copy-id to Add Keys


• On many systems, there is a convenience tool ssh-copy-id, which:
  • copies a local public key to the server,
  • appends it to ~/.ssh/authorized_keys,
  • and fixes permissions if needed.


• Basic usage:

ssh-copy-id -i ~/.ssh/id_ed25519.pub user@server

• If you run this multiple times with different keys, they will all be added as extra lines to authorized_keys.
• This is a safe and simple way to maintain multiple authorized keys.



6. Per-Key Restrictions and Options


• Lines in authorized_keys can optionally start with options that restrict what the key is allowed to do.


• General shape:

<options> <key-type> <base64-key> <comment>

• Example: a key that can only run one specific command:

command="/usr/local/bin/backup-script.sh" ssh-ed25519 AAAAC3Nz... backup-key

• Other common options:
  • from="1.2.3.4" – allow only from certain IPs.
  • no-port-forwarding
  • no-X11-forwarding
  • no-agent-forwarding
  • permitopen="host:port"


• Each line can have its own options, so some keys may be highly restricted while others are full-login keys.



7. How the Server Uses Multiple Keys


• When you connect with SSH:
  • Your client offers one or more public keys (based on your local config, agent, etc.).
  • The server checks whether any of these appear in authorized_keys of the target user.
  • If it finds a match, it challenges the client to prove it has the corresponding private key.
  • If the cryptographic check succeeds and any per-key options are satisfied, you are logged in.


• So with multiple keys:
  • You can log in from different machines with different private keys.
  • You can gradually add new keys and later remove old ones by editing the file.



8. File Permissions (Important!)


• SSH is strict about permissions. If they are too open, the server may ignore authorized_keys.


• Typical safe settings on the server:

chmod 700 ~/.ssh
chmod 600 ~/.ssh/authorized_keys

• If authentication suddenly stops working after you edit the file, check these permissions first.

How to Write a SSH Config File

1. What Is ~/.ssh/config?


• The SSH client can read settings from a configuration file, usually ~/.ssh/config (user-level) or /etc/ssh/ssh_config (system-wide).


• With this file you can:
  • define short aliases for hosts (e.g. ssh my-server),
  • set a default user, port, identity file, etc.,
  • configure jump hosts (bastions),
  • configure port forwarding, keep-alives, timeouts,
  • apply options conditionally (with Match).



2. File Location and Basic Structure


• User config file path:

~/.ssh/config



• Permissions should be restrictive (otherwise OpenSSH may ignore it):

chmod 600 ~/.ssh/config



• Basic structure is a series of Host blocks:

Host ALIAS_OR_PATTERN
    Option1 value
    Option2 value
    ...



• Indentation is not required but strongly recommended for readability.
• Options inside a Host block apply only to matching hosts.



3. Minimal Working Example


• Example: define a simple shortcut to an SSH server:

Host my-server
    HostName 203.0.113.42
    User ubuntu
    IdentityFile ~/.ssh/id_myserver



• Now you can connect with just:

ssh my-server



• Instead of:

ssh -i ~/.ssh/id_myserver ubuntu@203.0.113.42




4. Common SSH Config Directives


• Some of the most frequently used keywords in ssh_config:



Directive	Meaning	Example
Host	Start a block of settings for a host alias or pattern.	Host my-server
HostName	Real DNS name or IP to connect to.	HostName 203.0.113.42
User	Remote login user (same as ssh user@host).	User ubuntu
Port	Port number (default 22).	Port 2222
IdentityFile	Path to the private key to use.	IdentityFile ~/.ssh/id_myserver
IdentitiesOnly	If yes, use only the keys listed here, not all from ssh-agent.	IdentitiesOnly yes
ForwardAgent	Forward your local ssh-agent to the remote host (yes/no).	ForwardAgent yes
ProxyJump	Jump host (bastion) for connecting to another host.	ProxyJump bastion.example.com
LocalForward	Set up local port forwarding (local_port host:host_port).	LocalForward 8080 localhost:3000
RemoteForward	Set up remote port forwarding.	RemoteForward 9000 localhost:3000
ServerAliveInterval	Send keepalive every N seconds.	ServerAliveInterval 30
ServerAliveCountMax	Number of unanswered keepalives allowed before disconnect.	ServerAliveCountMax 3
StrictHostKeyChecking	How to handle unknown/changed host keys (yes/no/ask).	StrictHostKeyChecking ask




5. Multiple Hosts and Wildcards


• You can use patterns in Host:
  • * matches any string
  • ? matches any single character
• Examples:

Host github.com
    User git
    IdentityFile ~/.ssh/id_github

Host *.example.com
    User deploy
    IdentityFile ~/.ssh/id_company

Host *
    ServerAliveInterval 60
    ServerAliveCountMax 3

• Order matters: the first matching Host block wins for each option.
• So you typically put more specific Host entries before generic ones like Host *.



6. Practical Examples: GitHub, Personal Server, Jump Host


• Example config for some common real-world cases:

# 1) GitHub SSH
Host github.com
    HostName github.com
    User git
    IdentityFile ~/.ssh/id_github
    IdentitiesOnly yes

# 2) Personal VPS
Host vps
    HostName 198.51.100.10
    User root
    Port 22
    IdentityFile ~/.ssh/id_vps
    IdentitiesOnly yes
    ServerAliveInterval 30
    ServerAliveCountMax 3

# 3) Internal server via jump host (bastion)
Host bastion
    HostName bastion.mycompany.com
    User ubuntu
    IdentityFile ~/.ssh/id_company

Host internal-app
    HostName internal.app.local
    User ubuntu
    ProxyJump bastion
    IdentityFile ~/.ssh/id_company



• Now you can simply run:

ssh github.com
ssh vps
ssh internal-app




7. Using Include to Split Configs


• If your config becomes large, you can split it into multiple files and include them.
• Directive: Include path_or_pattern
• Example structure:

~/.ssh/
    config
    config.d/
        github.conf
        work.conf
        personal.conf



• Main ~/.ssh/config:

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

Host *
    ServerAliveInterval 60
    ServerAliveCountMax 3

• Each *.conf file can hold host blocks grouped by purpose (e.g., work vs personal).



8. Conditional Config with Match Blocks


• Match allows conditional config based on:
  • user,
  • host,
  • address,
  • originalhost,
  • localaddress, etc.
• Syntax:

Match CONDITION1 CONDITION2 ...
    Option value
    ...
Match all
    # reset conditions



• Example: special options only when connecting from a specific local IP:

Match host my-server localaddress 192.168.1.100
    Compression yes
    ServerAliveInterval 15

Match all



• Example: different identity for a specific user:

Match user deploy
    IdentitiesOnly yes
    IdentityFile ~/.ssh/id_deploy




9. Testing and Debugging Your Config


• If something doesn't behave as expected, you can print the fully resolved config:

ssh -G my-server



• Use verbose output to see which options are in effect and how SSH connects:

ssh -vvv my-server



• Common debugging tips:
  • Check file permissions on ~/.ssh and its contents.
  • Ensure you didn't accidentally put spaces instead of tabs in critical places (spaces are fine; just avoid weird characters).
  • Remember: first matching Host entry for each setting wins.



10. Security Considerations


• Keep your private keys safe:
  • Permissions: chmod 600 ~/.ssh/id_*
  • Use passphrases for important keys.


• Be careful with:
  • ForwardAgent yes (only enable when you trust the remote host).
  • StrictHostKeyChecking no (can open you to MITM attacks).


• Use separate keys/config entries for different services (e.g., work vs personal) to limit damage if one key is compromised.

Using rsync (Local & over SSH)

1. What Is rsync?


• rsync is a fast, incremental file-copying tool.


• It preserves permissions, ownership, timestamps, symlinks (with correct options).


• Works both:
  • locally (disk to disk / directory to directory)
  • remotely over SSH (typical for backups & deployments)


• Basic pattern:

  rsync [OPTIONS] SOURCE DEST




2. Key Options You Will Use All the Time



Option	Description	Details
-a	Archive mode (recommended default)	Preserves:   • permissions   • timestamps   • symlinks   • device files   • recursive directories Equivalent to: -rlptgoD
-v	Verbose output	Prints names of files being transferred.
-z	Compress data during transfer	Improves transfer speed on slow networks.
--delete	Mirror deletions	Removes files on destination that no longer exist in source. Useful for exact mirroring. Always test with --dry-run first.
--dry-run -n	Simulation mode	Shows what would change without making modifications.
--progress	Show per-file transfer progress	Useful for large files, shows speed and ETA.
-e ssh	Use SSH as the remote shell	Usually optional, but needed for customizing SSH options (port, key file, etc.).




3. Local Usage (Directory to Directory)


• Basic local sync:

  rsync -av source_dir/ backup_dir/

• Important: the meaning of the trailing slash:
  • source_dir/ → copy contents of source_dir into backup_dir.
  • source_dir (without slash) → copy the directory itself as a subdirectory.


• Examples:


• Copy contents:

  rsync -av project/ /mnt/backup/project/

• Copy directory itself:

  rsync -av project /mnt/backup/

  Destination tree becomes: /mnt/backup/project/...


• Dry run to inspect:

  rsync -av --dry-run project/ /mnt/backup/project/




4. Basic Remote Usage over SSH


• General pattern (source local, dest remote):

  rsync -avz SOURCE/ user@remote.host:/path/to/dest/

• General pattern (source remote, dest local):

  rsync -avz user@remote.host:/path/to/src/ DEST/



• Example: upload local project to server:

  rsync -avz ./app/ user@example.com:/var/www/app/



• Example: download remote logs:

  rsync -avz user@example.com:/var/log/myapp/ ./logs/



• Using explicit SSH:

  rsync -avz -e ssh ./app/ user@example.com:/var/www/app/

• Customize SSH (port, identity file, etc.):


• Different port:

  rsync -avz -e "ssh -p 2222" ./app/ user@example.com:/var/www/app/

• Specific SSH key:

  rsync -avz -e "ssh -i ~/.ssh/deploy_key" ./app/ user@example.com:/var/www/app/




5. Using rsync with SSH Config Aliases


• Configure ~/.ssh/config:

Host myserver
    HostName example.com
    User deploy
    Port 2222
    IdentityFile ~/.ssh/deploy_key

• Then use simply:

rsync -avz ./app/ myserver:/var/www/app/

• No need for -e then, because SSH picks up config for myserver.



6. Common Patterns: Mirroring & Backups


• Mirror local directory to remote (delete extras on remote):

rsync -avz --delete ./app/ myserver:/var/www/app/

• This makes /var/www/app an exact mirror of ./app.
• Files deleted locally will be deleted on remote.


• Safe first step: always start with a dry-run:

rsync -avz --delete --dry-run ./app/ myserver:/var/www/app/



• Incremental backup to local external disk:

rsync -av --delete ~/Documents/ /mnt/backup/Documents/



• Backup to remote server over SSH:

rsync -avz --delete ~/Documents/ backup@backup.example.com:/data/backup/junzhe-docs/




7. Excluding Files and Directories


• Use --exclude to skip certain paths:

rsync -avz \
  --exclude ".git/" \
  --exclude "node_modules/" \
  ./app/ myserver:/var/www/app/



• Exclude patterns are matched against relative paths.
• You can store them in a file:

# exclude.txt
.git/
node_modules/
dist/
*.log

• Then:

rsync -avz --exclude-from=exclude.txt ./app/ myserver:/var/www/app/




8. Permissions, Ownership, and Timestamps


• -a (archive) already includes:
  • -p → preserve permissions
  • -o → preserve owner (needs root to work fully)
  • -g → preserve group
  • -t → preserve modification times


• Extra options:
• -H → preserve hard links
• -A → preserve ACLs
• -X → preserve extended attributes


• Example (for full system backup):

sudo rsync -aHAX --delete / /mnt/backup/rootfs/




9. Speed Tuning and Large Transfers


• Compression: -z helps on slow networks, but may be useless or harmful on fast LANs.


• Bandwidth limiting:


• To avoid saturating your connection:

rsync -avz --bwlimit=2000 ./app/ myserver:/var/www/app/

(limit ~2000 KB/s)


• Partial transfers / resume:
• --partial keeps partially transferred files.
• --partial --progress is common for large files.



10. Typical Real-World Workflows


• 1. Deploying a web app:

# from local dev machine:
rsync -avz --delete                     \
    --exclude ".git/"         \
    --exclude "node_modules/" \
    ./app/ myserver:/var/www/app/



• 2. Home directory backup to a remote server:

rsync -avz --delete                     \
    --exclude ".cache/"       \
    --exclude "Downloads/"    \
    ~/ mybackup:/data/backups/junzhe-home/



• 3. Synchronize large data between two servers (run from your local machine):

rsync -avz              \
  user1@server1:/data/  \
  user2@server2:/mirror/data/



• 4. One-time huge file transfer with resume support:

rsync -avz --partial --progress \
  largefile.iso myserver:/data/