vim Freezes Over SSH? Check stty Before Blaming the VPN

Sessions like this stay connected while the editor starts, then the screen stops updating even though the SSH process is plainly alive. Typing produces nothing, Ctrl-C appears to do nothing, and the obvious conclusion is that the VPN dropped something. Most of the time the tunnel is fine and the remote pseudo-terminal is in a state nobody intended, because echo, canonical input and flow control live in the terminal rather than in the network. Finding out which of those three moved is a two-command job.

The freeze lives in the terminal, not the tunnel

A pseudo-terminal carries more than bytes. It holds line-discipline flags that decide whether input is echoed, whether reads wait for a newline, whether certain characters generate signals, and whether output can be stopped by a control character. An interactive editor switches that terminal into raw mode for the duration and is expected to restore the previous settings on exit. When the restore does not happen, the shell you return to is not the shell you left, even though the connection never dropped.

Compare terminals before concluding anything. A second session running the same editor proves the client and the path can do the work; it says nothing about the terminal whose flags are broken.

Read the settings on the terminal that froze

Identify the device first, then read both forms of its state. The readable form shows what is set, and the machine form is the one you can feed back later.

tty
stty -a
stty -g

Three flag groups explain most of these reports. Echo settings decide whether keystrokes appear at all, so a terminal with echo off looks dead while the shell is receiving every character. Canonical mode decides whether a program sees input one line at a time, so a terminal left in canonical mode makes a raw-mode application seem to ignore keys until Enter. Flow-control settings decide whether the terminal obeys XON and XOFF characters, and that group produces the most convincing fake freeze of the three.

Record the output before changing anything, particularly when the session carries custom key bindings somebody depends on. The machine form is the safest record, with the caveat that it is implementation-specific and should be restored by the same kind of system that produced it.

Repair that one terminal, not the session you are typing in

The standard repair restores the sane profile the manual page lists, and it affects one terminal only. If the editor still holds unsaved work in that terminal, leave it alone until the work is saved.

From another shell, target the frozen device explicitly so the terminal you are working in stays untouched.

stty -F /dev/pts/7 -a
stty -F /dev/pts/7 sane

A blank screen with a corrupted display is a separate problem from broken line discipline, and the reset program addresses it by emitting terminal initialization sequences. Try the state repair first, because it changes settings you can inspect, while the reset sequence rewrites the screen and explains nothing about how it broke.

The Ctrl-S trap behind a convincing freeze

When software flow control is enabled and the usual characters are assigned, Ctrl-S tells the terminal to stop sending output and Ctrl-Q tells it to resume. The session stays alive throughout, a single Ctrl-Q is often the whole repair, and nothing appears in any log, which is how this one survives so many escalations.

Inspect the actual settings instead of assuming it. The start and stop characters can be reassigned or disabled, and a terminal with flow control off will not react to either.

If the state returns, or SSH itself stalls

A recurring bad state points at something that changes the flags without restoring them: a startup file, a wrapper script, a multiplexer resetting the wrong window, or an application that dies while holding raw mode. Add a conditional check that reports the state instead of an unconditional reset, since a blanket reset hides the cause and can override deliberate settings.

When ordinary SSH traffic stalls as well, or the repair changes nothing, the terminal stops being the suspect.

ssh -vvv [email protected]
ping -M do -s 1400 -c 3 host.example.com

A stall that appears only during large transfers suggests a path MTU problem, while one that also swallows single keystrokes points at the path or the server rather than at packet size. Keep the terminal evidence separate from the network evidence, because a working editor in a second session is not proof that the first terminal was ever healthy.