An OpenSSH SFTP account fails immediately after login once a colleague added a greeting to the account's shell startup file; why, and what is the fix?
answer
- stdout is the protocol
- the first four bytes
- no magic cookie
- interactive shells only
basics
~20 sWith an external sftp-server, sshd starts the server through the user's shell, so the greeting enters the SFTP channel first. The client reads those bytes as a packet length and aborts. Print only in interactive shells, or use internal-sftp.
solid answer
~40 sWhen `Subsystem sftp` names the external `sftp-server`, sshd runs it through the user's login shell, and whatever that shell's startup prints on standard output travels down the same SSH channel as the SFTP packets. The client expects its first bytes to be the length of an `SSH_FXP_VERSION` packet; instead it reads the first four characters of the greeting (`Welc` is 1,466,264,675 as a big-endian uint32) and gives up on an impossible packet. RFC 4254 warns about exactly this: subsystems started through a shell can be preceded by spurious output. Fix it by printing the greeting only in interactive shells or to stderr, which SSH carries separately; by switching to `internal-sftp`, which starts no shell; or by moving the notice to sshd's pre-authentication `Banner`.
code
bash · 5 lines# Transfer account's shell startup file
# Print the greeting only when the shell is interactive
case $- in
*i*) echo "Welcome to the transfer host" ;;
esacgo deeper
Remember that a login greeting printed by the shell can break SFTP, and that interactive ssh still working does not prove the account is healthy.
Explain why: the external sftp-server is started through the login shell, and its standard output is the SFTP stream, length-prefixed with no start marker.
Diagnose with a byte count of a trivial remote command, then pick the fix that fits: a guard, stderr, internal-sftp or a pre-authentication Banner.
Argue for transfer-only accounts served in-process, so shell customisation on shared hosts can never take partner integrations down.
## What the greeting actually did The symptom is distinctive: `sftp` authenticates and then fails at once, usually complaining about an impossibly long message or a closed connection, while interactive `ssh` to the same account still works and shows the new greeting. Keys, ports and the server's SFTP code are all fine. The cause is the account's **shell startup**. OpenSSH's sshd runs every command for a user, including the program a `Subsystem` line names, under that user's **login shell** from the password database. Some shells read a per-user startup file even when they are started only to run one command. If that file writes text to **standard output**, the text goes where the shell's output goes: into the SSH channel the SFTP client is about to parse. ## Why a few bytes of text break SFTP framing 1. The client opens a session channel and sends the `subsystem` request for `sftp`. 2. sshd starts the user's shell to run the external `sftp-server`; the shell reads its startup file and prints `Welcome to the transfer host`. 3. The shell then runs `sftp-server`, and the client sends `SSH_FXP_INIT`. 4. The client reads the channel expecting `SSH_FXP_VERSION`: a 32-bit length, a one-byte type, the version, then extension pairs. 5. Instead its first four bytes are `W`, `e`, `l`, `c`: read as a big-endian unsigned 32-bit length, that is 0x57656C63, or 1,466,264,675. No real SFTP packet is that large, so the client aborts. SFTP packets carry **no marker** the client could search for to resynchronise. RFC 4254, section 6.5, anticipated exactly this: because a subsystem is usually started through the user's shell, it advises subsystem protocols to begin with a "magic cookie" that sets them apart from output generated by shell initialisation scripts. SFTP version 3 has none; it starts with its length field, so any stray byte on standard output is fatal. **Standard error is different.** SSH carries it as `SSH_MSG_CHANNEL_EXTENDED_DATA` with the type `SSH_EXTENDED_DATA_STDERR`, separate from the channel data the SFTP client parses, so a message written to stderr does not corrupt the stream. ## Proving it Run a trivial command through the same account and count what comes back on standard output: ```bash # Must print 0 for an external sftp-server to work on this account ssh -T [email protected] true | wc -c ``` Any non-zero count is output that would land in front of `SSH_FXP_VERSION`. Reading verbose client logs for authentication failures is a separate skill and not needed here: authentication already succeeded. ## Fixes, from narrowest to broadest | Fix | What changes | When to prefer it | |---|---|---| | Guard the greeting | printed only by interactive shells | the account also needs a shell | | Send it to stderr | travels as extended data, not channel data | a quick fix for status lines | | `Subsystem sftp internal-sftp` | sshd serves SFTP in-process; no shell runs | transfer-only accounts | | Move the notice to `Banner` | sshd sends it before authentication, outside any channel | legal or welcome notices | - **Guarding** is the usual fix on shared hosts: test whether the shell is interactive before printing anything. Testing whether standard output is a terminal works too, because the SFTP client requests no terminal for its session. - **`internal-sftp`** removes the whole class of problem for SFTP, because no shell, and therefore no startup file, is involved. It also needs no files inside a chroot. - **`Banner`** is sshd's own pre-authentication message, delivered by the authentication protocol as `SSH_MSG_USERAUTH_BANNER`, so it never touches the SFTP stream. - sshd's manual makes the same demand of the per-user `~/.ssh/rc` file: it must not write to standard output, only to standard error. ## What not to do - **Do not tune the client.** No buffer size, request count or compression setting makes stray text parse as SFTP packets. - **Do not chase keys or ports.** Authentication succeeded and the channel opened; the failure follows the account's shell, not the network. - **Do not assume interactive ssh proves the account is healthy.** A terminal is meant to show the shell's output; SFTP treats the same bytes as protocol. - **Do not stop at the greeting.** Any command in the startup file that writes to standard output, such as a status line or a message-of-the-day script, breaks SFTP the same way.
- Why does interactive ssh to the same account keep working while SFTP fails?A terminal session is meant to display the shell's output, so the greeting is just text on screen. SFTP treats the channel's standard output as its binary protocol, so the same bytes are parsed as a packet length. The account and the authentication are identical; only the consumer of the output differs.
- Why can't the SFTP client simply skip the junk and find the real first packet?SFTP has no start marker or checksum to resynchronise on: a packet is just a 32-bit length, a type byte and a payload. Once stray bytes shift the stream, every later length is read from the wrong place. RFC 4254 suggested a magic cookie for subsystem protocols for this reason, but SFTP version 3 never adopted one.
- The greeting breaks the SSH key exchange, so the host key looks wrong
- A larger sftp client buffer lets it skip the extra text
- Text written to stderr corrupts SFTP exactly as stdout does
- PrintMotd no stops the shell startup file from printing
- internal-sftp still runs the user's shell startup files