89 lines
4.2 KiB
TeX
89 lines
4.2 KiB
TeX
\guidepart{rose}{Fix it}{When things go wrong}
|
|
{Symptom first, fix second. No essays.}
|
|
{\partitem{\iLifebuoy}{Troubleshooting, by symptom}}
|
|
\label{part:fix}
|
|
|
|
% =========================================================================================
|
|
\chapter{Troubleshooting, by symptom}\label{ch:trouble}
|
|
\chapmeta{as long as it takes}{You'll find your symptom and the fix in one place}
|
|
|
|
\begin{tldr}
|
|
Find the heading that matches what you're seeing. Try the fixes in order. Most problems are the network, the
|
|
password, or the baud rate.
|
|
\end{tldr}
|
|
|
|
\section{Connecting}
|
|
|
|
\fix{``Authentication failed''}{%
|
|
\begin{itemize}
|
|
\item Check the username, password, key path and the ticked \ui{Auth Methods}.
|
|
\item If the key has a passphrase, check how the passphrase is stored (\ui{Passphrase Mode}).
|
|
\item Two-factor server? Click \ui{Test} next to the TOTP secret and compare with your phone. Check your clock.
|
|
\item Saved password not being used? The vault might be locked: click \ui{Vault locked} in the status bar.
|
|
\end{itemize}}
|
|
|
|
\fix{``Host key verification failed''}{%
|
|
The server's fingerprint changed since you last connected. That happens when a server is rebuilt, but it's also exactly
|
|
what an attack looks like. \textbf{Check with whoever runs the server.} If it's legitimate:
|
|
\menu{Settings\then Known Hosts}, \ui{Remove} the entry, reconnect and accept the new key.}
|
|
|
|
\fix{It just says ``Connecting…'' forever}{%
|
|
\begin{itemize}
|
|
\item Click \ui{Test} in the profile editor. If that fails too, it's the network, a firewall or the wrong port.
|
|
\item Behind a corporate proxy? Set one up under \ui{Proxy} (SSH profiles).
|
|
\item Going through a bastion? Check each jump host on its own first.
|
|
\end{itemize}}
|
|
|
|
\fix{The session keeps reconnecting}{%
|
|
Check the network and the credentials, then the profile's auto-reconnect settings. Reconnection backs off (1\,s, 2\,s,
|
|
4\,s… up to 30\,s) and stops after the maximum number of attempts.}
|
|
|
|
\section{Serial}
|
|
|
|
\fix{The port won't open}{%
|
|
\begin{itemize}
|
|
\item Is the adapter plugged in? Hit refresh in the device list.
|
|
\item \textbf{Permission denied} on Linux: add yourself to \code{dialout} (or \code{uucp}), then log out and back in.
|
|
\item On a Mac, use \code{/dev/cu.*}, not \code{/dev/tty.*}.
|
|
\item \textbf{Port is in use by another program}: close \code{screen}, \code{minicom}, the Arduino IDE serial monitor or
|
|
whatever else has it open.
|
|
\end{itemize}}
|
|
|
|
\fix{Gibberish on screen}{The baud rate, parity or stop bits don't match the device. Check its manual.}
|
|
|
|
\section{Remote desktops}
|
|
|
|
\fix{VNC won't connect}{%
|
|
\begin{itemize}
|
|
\item VNC ports are 5900 plus the display number: \code{:0} is 5900, \code{:1} is 5901.
|
|
\item Check the password and how it's stored.
|
|
\item Using an SSH tunnel? Check the tunnel's host, user, login method and key, and the host key policy.
|
|
\item Connecting to a Mac? Turn on password access in macOS Screen Sharing settings (see p.\,\pageref{ch:vnc}).
|
|
\end{itemize}}
|
|
|
|
\section{Files}
|
|
|
|
\fix{Upload is greyed out or fails}{%
|
|
The folder is probably \proto[amber]{READ ONLY} for your user. Pick another, or check permissions on the server. Uploads
|
|
need an SSH session; other protocols can't do it.}
|
|
|
|
\fix{``NO READ'' on a folder}{You don't have permission to look inside. Try the parent folder, or ask the server's admin.}
|
|
|
|
\section{The terminal itself}
|
|
|
|
\fix{The terminal is the wrong size}{%
|
|
Resize the window or nudge a split divider; the terminal re-fits itself. Still wrong? Reconnect. Very old servers may
|
|
prefer a different \ui{Terminal Type} in the profile (try \code{vt100}).}
|
|
|
|
\fix{The scroll wheel moves the cursor instead of scrolling}{%
|
|
You're in a full-screen program (\code{less}, \code{vim}, \code{tmux}). That's how terminals work: the wheel sends arrow keys
|
|
there. Quit the program, or use its own scrolling (in \code{tmux}: \keys{Ctrl+B} then \kbd{[}).}
|
|
|
|
\fix{Emoji are in black and white}{Known limitation: colour emoji show as monochrome glyphs. Everything else renders
|
|
normally.}
|
|
|
|
\begin{quickwin}[Still stuck?]
|
|
Start Nexus Terminal with \code{--data-dir} pointing at an empty folder and try the same connection there. If it
|
|
works, something in your profile is off; duplicate the working one and compare.
|
|
\end{quickwin}
|