When does OpenSSH's ssh_config need a Match block instead of Host, and why must Match exec never see an attacker-chosen user or host name?
answer
- Host sees only the typed name
- host versus originalhost
- a re-parse for the last pass
- exec runs a local shell command
- tokens expanded without quoting
basics
~20 sHost matches only the typed name; Match tests other facts, such as the host after HostName substitution, the user, the local network or a command's exit status. Match exec expands tokens unquoted into a shell command, so a crafted name can inject commands.
solid answer
~50 s`Host` compares patterns with the name typed on the command line. `Match` takes criteria: `host` (the target after `HostName` or canonicalization), `originalhost` (as typed), `user`, `localuser`, `localnetwork`, `tagged` (a `Tag` or `ssh -P`), `command`, `version`, `exec`, plus `canonical`, `final` and `all`. `Match final` asks for a re-parse and matches only in that last pass, so decisions can rest on values earlier blocks set. `Match exec` runs a command under your shell on the client and matches on exit status 0; tokens such as `%h` and `%u` are expanded without quoting, so a user or host name from an untrusted source can inject shell commands. OpenSSH 9.6 banned most shell metacharacters in command-line user and host names, 10.1 rejected control characters in user names, and 10.3 fixed validation that ran too late for `%u` in `Match exec`; the project says such mitigations cannot be absolute.
go deeper
Recall that Match can test things Host cannot, such as the real host after HostName, the user or the local network.
Explain host versus originalhost, what final's re-parse is for, and why Match exec tokens are dangerous with untrusted names.
Show how you replace Match exec with static criteria, keep tokens out of shell commands, and review wrappers that build ssh command lines.
Weigh clever conditional client config against a simpler explicit file that every engineer can read and audit.
## What Host cannot express A `Host` line compares its patterns with one thing: the **hostname argument as typed** on the command line. That covers aliases and wildcards, but not questions like "is the real target in this domain once `HostName` is applied", "am I on the office network", "which remote user is this" or "is this an sftp session". **`Match`** opens a section, ending at the next `Host` or `Match`, that applies only when **all** of its criteria are satisfied; each criterion may be negated with `!`. ## The criteria | Criterion | Tests | Typical use | |---|---|---| | `host` | target name after `HostName` or canonicalization | settings for every alias that resolves into a domain | | `originalhost` | the name as typed | same as `Host`, combinable with other criteria | | `user` / `localuser` | remote login / local account running ssh | per-account keys; system-wide rules | | `localnetwork` | CIDR ranges of active local interfaces | skip the bastion when on the internal network | | `tagged` | a name set by `Tag` or `ssh -P tag` | opt-in profiles chosen per run | | `command` | the remote command or subsystem requested | different options for `sftp` sessions | | `exec` | exit status of a local shell command | anything else, at a cost | | `canonical`, `final`, `all` | the re-parse passes; always true | ordering and catch-all blocks | Two notes from the manual are worth repeating. `localnetwork` is **not a trustworthy criterion** where addresses come from DHCP, so it should not gate security-sensitive settings. And `final` requests that the configuration be **re-parsed** regardless of `CanonicalizeHostname`, matching only during that final pass, which lets a block depend on the `HostName` an earlier block chose. ```ini Match host *.prod.internal.example !localnetwork 192.0.2.0/24 ProxyJump bastion-prod ``` Every alias whose `HostName` lands in production goes through the bastion, except when the laptop already sits on 192.0.2.0/24. The first-value rule still applies, so `Match` sections also belong above general defaults. ## Match exec: power and its price `Match exec "command"` runs the command **locally, under the user's shell**, during config parsing, and the condition is true when it exits with status 0. It accepts the `%` tokens, and the manual's TOKENS section warns that tokens are **expanded without quoting or escaping of shell characters**; the user must make sure they are safe. Two costs follow: 1. **Latency.** The command runs on every ssh invocation that reaches the block, including each `scp`, `sftp` and automation call. 2. **Injection.** If `%h`, `%r` or `%u` end up in the command and a user or host name comes from somewhere you do not control, such as a wrapper that builds ssh command lines from a ticket, a repository or a web form, a name containing shell syntax can run commands as you. ## How OpenSSH narrowed the hole - **9.6** banned most shell metacharacters from user and host names supplied on the command line, after finding that `ProxyCommand`, `LocalCommand` and `Match exec` expansions of them could inject commands. - **10.1** disallowed control characters in user names from the command line or `%` expansion. - **10.3** fixed validation of metacharacters in command-line user names that was performed too late to stop some `%` expansions, such as `%u` in `Match exec`. Values written literally in `ssh_config` are not subject to these checks, on the assumption that you wrote them. The release notes still recommend **against exposing ssh command lines to untrusted input**, because no filter can cover every shell and configuration. The defensive habits are simple: prefer static criteria (`host`, `user`, `localnetwork`, `tagged`) over `exec`, keep tokens out of `exec` commands, and validate names before any wrapper passes them to ssh. ## Choosing the right tool - If a decision depends only on the typed name, a `Host` block is simpler and faster to read. - If it depends on the real target after `HostName`, use `Match host`, adding `final` when the name is settled further down the file. - If it depends on where the laptop is, `localnetwork` avoids running a command, with the trust caveat above. - If a profile should apply only when asked for, `Tag` and `ssh -P` make the choice explicit on the command line. - Reach for `exec` last, and check the outcome of any of these with `ssh -G`, which prints the configuration after evaluating Match blocks.
- `Host web1` sets `HostName web1.prod.internal.example`; later, `Host *.prod.internal.example` sets ProxyJump. Does `ssh web1` use the bastion?No. `Host` compares patterns with the typed name `web1`, which does not match the wildcard. `Match host *.prod.internal.example` would, because `host` is tested after `HostName` substitution; add `final` if `HostName` is only set further down the file.
- Why is `Match localnetwork` a poor way to decide whether to skip a bastion for security reasons?It only inspects the client's own interface addresses, which anyone on a DHCP network can be handed or can set. The manual warns it is not a trustworthy criterion for security-sensitive settings; use it for convenience, and keep the server-side controls as the real boundary.
- Host patterns are re-checked against the HostName after substitution
- Match exec runs its command on the remote server
- Match final means the block's values override earlier ones
- OpenSSH 10.3 makes untrusted names safe in Match exec
- Match localnetwork is a reliable security boundary
Assumes OpenSSH 10.5; 9.6 banned most shell metacharacters in command-line user and host names, 10.1 rejected control characters in user names, and 10.3 fixed late validation that let %u in Match exec be exploited.