In OpenSSH's ~/.ssh/config, how does a Host block with HostName, User, Port and IdentityFile turn a long ssh command into `ssh web1`?
answer
- an alias, not a DNS name
- pattern matched against what you typed
- HostName is the real address
- per-host user, port, key, bastion
basics
~20 sA Host block names an alias pattern; when the name typed after ssh matches it, the client applies that block's HostName (the real address), User, Port and IdentityFile, so ssh web1 expands into the full connection.
solid answer
~40 s`Host` opens a section whose directives apply only when the name you typed matches one of its patterns. `HostName` gives the real DNS name or address to connect to, `User` the remote login, `Port` the TCP port and `IdentityFile` the private key to offer, so a `Host web1` block with `HostName web1.prod.internal.example`, `User deploy`, `Port 2222` and `IdentityFile ~/.ssh/id_prod` makes `ssh web1` equal to `ssh -p 2222 -i ~/.ssh/id_prod [email protected]`. Patterns accept `*`, `?` and `!` negation, so one block can cover a whole environment, and a `ProxyJump` line in the block declares the bastion that host is reached through. `scp`, `sftp` and other programs that call ssh read the same file, so the alias works there too. Options given on the command line still win over the file.
code
ini · 10 linesHost bastion-prod
HostName bastion.prod.example.com
User alice
Host web1
HostName web1.prod.internal.example
User deploy
Port 2222
IdentityFile ~/.ssh/id_prod
ProxyJump bastion-prodgo deeper
Recall that Host is an alias pattern and HostName, User, Port and IdentityFile fill in the real connection details.
Explain that Host matches the typed name, that negated patterns carve exceptions, and that the bastion needs its own block.
Show how one wildcard block per environment with a per-environment ProxyJump keeps sixty hosts manageable without per-host sprawl.
Weigh a shared, reviewed client file distributed to the team against each engineer's hand-edited aliases drifting apart.
## What the client file is for OpenSSH's client, `ssh`, reads its settings from three places in a fixed order: **command-line options** first, then the **user file** `~/.ssh/config`, then the **system file** `/etc/ssh/ssh_config`. Each file is a list of directive-and-value lines, optionally split into sections by `Host` or `Match` lines. A section's directives apply only when its condition matches the connection being made. The everyday use of this is the **host alias**: a short name you type that stands for a full set of connection details. ## Anatomy of a Host block ```ini Host web1 HostName web1.prod.internal.example User deploy Port 2222 IdentityFile ~/.ssh/id_prod ``` With that block in `~/.ssh/config`, typing `ssh web1` produces the same connection as `ssh -p 2222 -i ~/.ssh/id_prod [email protected]`. | Directive | What it supplies | Without it | |---|---|---| | `Host` | the pattern(s) the typed name must match | no section, settings apply to every host | | `HostName` | the real DNS name or IP address to connect to | the name typed on the command line | | `User` | the account to log in as on the remote host | your local user name | | `Port` | the server's TCP port | 22 | | `IdentityFile` | a private key file to offer during public-key login | the default key files in `~/.ssh` | | `ProxyJump` | the bastion (jump host) to go through first | a direct connection | Two details trip people up: - **`Host` is matched against the name as typed**, not against the `HostName` it resolves to. `ssh web1.prod.internal.example` does not match `Host web1`. - **`HostName` replaces the name outright.** There is no fallback to DNS for the alias; if `HostName` is wrong, the connection goes to the wrong place. ## Patterns: one block for many hosts A `Host` line can carry several whitespace-separated patterns, and each pattern may use `*` (any run of characters), `?` (one character) and a leading `!` to negate. A negated pattern that matches cancels the whole block, which is how you carve exceptions out of a wildcard: ```ini Host *.prod.internal.example !bastion.prod.internal.example User deploy ProxyJump bastion-prod ``` Here every production host is reached as `deploy` through the bastion, but the bastion itself is excluded, so the client never tries to reach the bastion through itself. ## Declaring the bastion per host `ProxyJump` names one or more jump hosts as `[user@]host[:port]` (or an ssh URI), comma-separated if there are several. The value can be another alias, which keeps the bastion's own details in one place. The manual page notes that the destination's configuration is **not generally applied to the jump host**, so the bastion needs its own block: 1. Write a `Host bastion-prod` block with its `HostName`, `User` and `IdentityFile`. 2. In the block for the hosts behind it, set `ProxyJump bastion-prod`. 3. Where one host inside a wildcard must connect directly, give it `ProxyJump none` in a block placed earlier in the file. How the jump actually carries the connection is a forwarding mechanism covered with port forwarding and tunneling; the client file only declares which hosts use which bastion. ## Why this matters on a fleet On sixty hosts in three environments behind two bastions, aliases turn every engineer's command line into `ssh web1` or `ssh db3.stage`, and the per-environment user, port, key and bastion live in one reviewed file instead of in shell history. Because `scp`, `sftp` and anything else that invokes `ssh` read the same file, the alias works for file copies and automation as well. Anything given on the command line (`-p`, `-l`, `-i`, `-J`, `-o`) is read first and therefore wins over the file, which is the intended escape hatch for one-off overrides. ## Mistakes that show up in review - **Putting `Host *` first.** The client keeps the first value it obtains for each directive, so a catch-all block at the top silently pins `User` or `Port` for every host; general defaults belong at the end of the file. - **Expecting the alias to match its own HostName.** Typing the full name skips the alias block unless that name is listed as a pattern too. - **Forgetting the bastion's own block.** The jump host is connected to with only the settings that match its name. - **Wildcards that include the bastion.** A wildcard `ProxyJump` that also matches the bastion's name makes the client try to reach the bastion through itself; exclude it with `!` or give it `ProxyJump none` earlier in the file.
- Does `ssh web1.prod.internal.example` pick up the settings in a `Host web1` block whose HostName is that same name?No. A `Host` pattern is compared with the name typed on the command line, not with any `HostName` it maps to. To cover both spellings, list both patterns on the `Host` line (`Host web1 web1.prod.internal.example`) or use a wildcard such as `*.prod.internal.example`.
- Why does the bastion need its own Host block when the target block already says `ProxyJump bastion-prod`?The target's settings are not generally applied to the jump host, so the client connects to the bastion using only what matches the bastion's own name. A `Host bastion-prod` block gives it its real `HostName`, `User` and key; without one, ssh would try to resolve a host literally called `bastion-prod` with whatever defaults happen to match.
- Host patterns match the resolved HostName or the IP address
- HostName is only a label and DNS still resolves the alias
- The config file overrides options typed on the command line
- Aliases work for ssh but scp and sftp need full names
- The target's User and key are reused for the jump host automatically