LinuxHandbook/article/linux-ssh-tutorial.md at main · fhmio/LinuxHandbook

title

Linux Command Tutorial: ssh

date

2026-09-12 00:00:00 +0000

1. Introduction

Upstream: OpenSSH 10.5 | POSIX: De facto standard (IETF RFC 4251-4254) | Safety Tier: safe-read-only | Scope: Encrypted remote login & command execution

ssh (Secure Shell client) is the primary remote login and command execution program of the OpenSSH suite. It replaces insecure cleartext protocols such as Telnet, rlogin, and rsh, providing cryptographic confidentiality, integrity, and server authentication over untrusted IP networks.

Upstream Project & Provenance: Maintained by the OpenBSD Project and the OpenSSH Portable development team (openssh-clients).
Portability & Standards Baseline: ssh is standardized through the IETF SSHv2 Protocol specifications (RFC 4251, RFC 4252, RFC 4253, RFC 4254). It is not specified in POSIX.1-2024.
Target Research Implementation: Audited against OpenSSH 10.5 (ssh(1)).
Applicability & Lifecycle: The foundational client for interactive shell sessions, automated command dispatch, remote port tunnels, SOCKS proxies, and VPN encapsulations across modern Linux systems.

2. Syntax and Command Model

2.1 Canonical Synopsis

ssh [-46AaCfGgKkMNnqsTtVvXxYy] [-B bind_interface] [-b bind_address]
    [-c cipher_spec] [-D [bind_address:]port] [-E log_file]
    [-e escape_char] [-F configfile] [-I pkcs11] [-i identity_file]
    [-J destination] [-L address] [-l login_name] [-m mac_spec]
    [-O ctl_cmd] [-o option] [-p port] [-Q query_option] [-R address]
    [-S ctl_path] [-W host:port] [-w local_tun[:remote_tun]]
    destination [command [argument ...]]

2.2 Destination Specification

[user@]hostname

or URI format:

ssh://[user@]hostname[:port]

2.3 Execution & Process Model

When invoked without a trailing command, ssh allocates a pseudo-terminal (PTY) on the remote system and enters an interactive remote shell session.
When invoked with a command argument (e.g., ssh host uptime), ssh defaults to non-interactive raw stream mode: standard input, output, and error are connected directly to the remote process without PTY allocation.
Escape Character: Interactive sessions allocate the default escape character ~ (tilde) at the beginning of a newline for session controls (~. to disconnect, ~^Z to suspend).

3. Options

3.1 Connection and Routing Options

Flag	Description	Default	Upstream Note
`-4` / `-6`	Force IPv4 or IPv6 transport resolution.	Dual-stack	Standard
`-p port`	Remote TCP port to connect to.	`22`	Standard
`-i identity_file`	Path to public key identity file.	`~/.ssh/id_*`	Standard
`-J destination`	Jump proxy (ProxyJump connection).	Direct	OpenSSH 7.3+
`-F configfile`	Alternative user configuration file.	`~/.ssh/config`	Standard
`-v` / `-vv` / `-vvv`	Verbose debug levels 1 through 3.	Standard info	Standard
`-q`	Quiet mode: suppress warning and diagnostic output.	Verbose	Standard

3.2 Tunnels and Port Forwarding

Flag	Description	Model
`-L [bind_addr:]port:host:hostport`	Local port forwarding to remote destination.	Inbound on local socket forwarded across SSH tunnel.
`-R [bind_addr:]port:host:hostport`	Remote port forwarding to local destination.	Inbound on remote socket forwarded back to client.
`-D [bind_addr:]port`	Dynamic application-level port forwarding.	Allocates local SOCKS4/SOCKS5 proxy.
`-w local_tun[:remote_tun]`	Layer 3/2 TUN/TAP network device tunneling.	Requires root/`CAP_NET_ADMIN` on both ends.

3.3 Session Controls

Flag	Description
`-t`	Force pseudo-terminal (PTY) allocation (useful for interactive screen/tmux over SSH).
`-T`	Disable pseudo-terminal allocation (recommended for scripted data streaming).
`-N`	Do not execute a remote command; useful solely for forwarding ports.
`-f`	Requests `ssh` to go to background just before command execution.
`-C`	Request compression of all data (via zlib).

4. Basic Usage

4.1 Quick Reference & Common Invocations

Task / Scenario	Command	Key Flags / Behavior
Connect remote shell	`ssh user@192.168.1.100`	Allocates interactive pseudo-terminal (PTY)
Connect on custom port	`ssh -p 2222 user@192.168.1.100`	`-p` specifies remote TCP port
Use explicit private key	`ssh -i ~/.ssh/id_ed25519 user@192.168.1.100`	`-i` selects authentication key file
Execute remote command	`ssh -q user@192.168.1.100 "uptime"`	Runs command remotely without allocating PTY
Local port forwarding	`ssh -N -L 8080:127.0.0.1:80 user@192.168.1.100`	`-L` forwards local port to remote destination
Dynamic SOCKS5 proxy	`ssh -N -D 1080 user@192.168.1.100`	`-D` allocates local SOCKS5 tunnel proxy
Route through jump host	`ssh -J jumpuser@bastion:2222 user@10.0.0.45`	`-J` sets up end-to-end encrypted proxy hop
Force interactive PTY	`ssh -t user@192.168.1.100 "htop"`	`-t` forces terminal allocation for TUI tools

4.2 Interactive Shell Connection

ssh admin@192.168.1.100

Sample terminal output:

The authenticity of host '192.168.1.100 (192.168.1.100)' can't be established.
ED25519 key fingerprint is SHA256:abcd1234efgh5678ijkl9012mnop3456qrst7890uvw.
Are you sure you want to continue connecting (yes/no/[fingerprint])? yes
Warning: Permanently added '192.168.1.100' (ED25519) to the list of known hosts.
admin@192.168.1.100's password:
Linux web-node-01 6.6.0-amd64 #1 SMP PREEMPT x86_64
admin@web-node-01:~$

4.3 Non-Interactive Command Execution

Executing a command on a remote system and capturing the output locally:

ssh -q admin@192.168.1.100 "uname -r && uptime"

Sample terminal output:

6.6.0-amd64
 10:45:02 up 14 days,  3:12,  2 users,  load average: 0.15, 0.08, 0.02

5. Practical Operations

5.1 Local Port Forwarding to Secure an Internal Service

Forwarding local port 8080 to a remote database management console accessible only from localhost:80 on the remote server:

ssh -N -L 8080:127.0.0.1:80 admin@192.168.1.100

Technical Analysis: -N prevents remote shell spawning; -L 8080:127.0.0.1:80 opens TCP port 8080 on the client loopback interface. Any connection hitting localhost:8080 is encrypted across the SSH tunnel and routed to 127.0.0.1:80 from the perspective of the remote server.

5.2 Dynamic SOCKS5 Proxy

Creating an on-demand SOCKS5 proxy on local port 1080 for secure browsing across an untrusted network:

ssh -N -D 1080 -C admin@gateway.corp.example.com

Applications configured with SOCKS proxy localhost:1080 route all TCP traffic through gateway.corp.example.com.

5.3 Connecting Through an Intermediate Bastion (ProxyJump)

Connecting directly to an internal node (10.0.0.45) through a perimeter bastion (bastion.corp.example.com):

ssh -J deploy@bastion.corp.example.com:2222 appuser@10.0.0.45

Technical Analysis: -J establishes an end-to-end encrypted channel between your client and 10.0.0.45; the intermediate bastion acts strictly as a TCP forwarder and cannot inspect payload traffic.

5.4 Remote Interactive Session with Forced PTY Allocation

Running interactive curses programs like htop in non-login contexts:

ssh -t admin@192.168.1.100 "htop"

Without -t, ssh detects non-interactive invocation, omits PTY allocation, and curses applications fail with "Error opening terminal".

6. Advanced Usage

6.1 Multiplexing and Connection Pooling (ControlMaster)

Connection setup introduces latency due to TCP handshakes, TLS/SSH key exchanges, and authentication rounds. Multiplexing allows multiple concurrent ssh sessions to share a single established TCP connection.

Configure in ~/.ssh/config:

Host *
    ControlMaster auto
    ControlPath ~/.ssh/sockets/%r@%h-%p
    ControlPersist 10m

Testing connection reuse:

ssh -O check admin@192.168.1.100

Sample terminal output:

Master running (pid=45123)

Subsequent invocations of ssh, scp, or sftp to this host execute instantaneously without authentication delays.

6.2 Passing Direct Command Pipelines Over SSH

Transferring a compressed disk image directly into a remote raw block device without intermediate files:

dd if=/dev/nvme0n1p1 bs=4M status=progress | gzip -c | ssh admin@backup-server "gunzip -c | dd of=/dev/sdb1 bs=4M"

Data streams through stdin/stdout pipelines across the encrypted SSH pipe.

7. Exit Status, Environment, and Configuration

7.1 Exit Status Codes

Exit Code	Condition
`0`	Remote command exited with `0`, or interactive session closed cleanly.
`1`–`254`	The remote command failed and returned its specific exit code.
`255`	An internal SSH client error occurred (DNS resolution failure, authentication failed, network timeout, connection terminated by signal).

7.2 Environment Variables

Variable	Influence on Execution
`SSH_AUTH_SOCK`	Specifies path to UNIX domain socket for `ssh-agent`.
`SSH_CONNECTION`	Automatically set on the remote environment: `<client_ip> <client_port> <server_ip> <server_port>`.
`SSH_CLIENT`	Legacy variable indicating client connection parameters.
`SSH_TTY`	Set on the remote environment to the path of the allocated PTY device (e.g., `/dev/pts/2`).

7.3 Configuration Hierarchy

Client configuration is parsed top-down in ~/.ssh/config, followed by /etc/ssh/ssh_config. First-match-wins applies for configuration directives:

Host internal-cluster-*
    User devops
    IdentityFile ~/.ssh/id_ed25519
    Port 2222
    StrictHostKeyChecking ask

8. Safety, Security, and Portability

8.1 Key Hygiene & Algorithm Deprecations

Warning

Host Key Verification: Disabling StrictHostKeyChecking=no or redirecting UserKnownHostsFile=/dev/null strips cryptographic trust verification, exposing connection credentials to active Man-in-the-Middle (MITM) attacks.

Note

Deprecated Cryptosystems: OpenSSH upstream has disabled DSA keys and deprecated SHA-1 signatures (ssh-rsa). Ed25519 (id_ed25519) or ECDSA (id_ecdsa) should be used exclusively.

8.2 Agent Forwarding Risks

Caution

Agent Hijacking Risk: The -A flag enables agent forwarding, allowing the remote host to request signatures from your local ssh-agent. If the remote server is compromised, root users on that system can hijack your forwarded agent socket to authenticate across your network. Never use agent forwarding (-A) across untrusted hosts; use ProxyJump (-J) instead.

9. Best Practices

Adopt Ed25519 as Default Public Key Cryptosystem:

[!TIP] Guidance: Generate client keys using ssh-keygen -t ed25519. Authoritative Justification: OpenSSH security documentation identifies Ed25519 as providing compact 256-bit keys with superior resistance to side-channel attacks compared to RSA.
Employ ProxyJump (-J) for Bastion Access:

[!IMPORTANT] Guidance: Route traffic via -J bastion instead of opening intermediate interactive shells or forwarding agents. Authoritative Justification: Upstream documentation explains that -J creates an end-to-end encrypted TCP forward, isolating keys and credentials from intermediate nodes.
Use ControlMaster for Automated CI/CD Pipelines:

[!TIP] Guidance: Enable ControlPersist in automation environments that issue frequent successive commands to identical targets. Authoritative Justification: Eliminates repetitive public key cryptographic handshakes, reducing server CPU utilization and latency.
Enforce Strict Permissions on Configuration Files:

[!IMPORTANT] Guidance: Enforce chmod 700 ~/.ssh and chmod 600 ~/.ssh/*. Authoritative Justification: OpenSSH strictly aborts if private keys or configuration files are accessible by group or world users.
Disable Pseudo-Terminal for Non-Interactive Pipelines:

[!TIP] Guidance: Use ssh -T when piping raw binary data or streaming backups. Authoritative Justification: Prevents newline translation (CR/LF munging) and carriage-return artifacts introduced by terminal drivers.

References

OpenSSH ssh(1) Manual: OpenBSD Manual Pages. https://man.openbsd.org/ssh
RFC 4251: The Secure Shell (SSH) Protocol Architecture. https://datatracker.ietf.org/doc/html/rfc4251
OpenSSH 10.5 Release Notes: Official OpenSSH Project Portal. https://www.openssh.com/releasenotes.html
OpenSSH Security Advisories: Legacy algorithm deprecation and socket security policies. https://www.openssh.com/security.html

FilesExpand file tree

linux-ssh-tutorial.md

Latest commit

History

linux-ssh-tutorial.md

File metadata and controls

1. Introduction

2. Syntax and Command Model

2.1 Canonical Synopsis

2.2 Destination Specification

2.3 Execution & Process Model

3. Options

3.1 Connection and Routing Options

3.2 Tunnels and Port Forwarding

3.3 Session Controls

4. Basic Usage

4.1 Quick Reference & Common Invocations

4.2 Interactive Shell Connection

4.3 Non-Interactive Command Execution

5. Practical Operations

5.1 Local Port Forwarding to Secure an Internal Service

5.2 Dynamic SOCKS5 Proxy

5.3 Connecting Through an Intermediate Bastion (ProxyJump)

5.4 Remote Interactive Session with Forced PTY Allocation

6. Advanced Usage

6.1 Multiplexing and Connection Pooling (ControlMaster)

6.2 Passing Direct Command Pipelines Over SSH

7. Exit Status, Environment, and Configuration

7.1 Exit Status Codes

7.2 Environment Variables

7.3 Configuration Hierarchy

8. Safety, Security, and Portability

8.1 Key Hygiene & Algorithm Deprecations

8.2 Agent Forwarding Risks

9. Best Practices

References