Andy Dixon
b6a7d51ddd
Bump the workspace to 3.0.1 and bring the user guide up to date: an RDP chapter, shell integration and inline images, SSH certificates and CAs, known_hosts import/export, stored credentials and master password change, profile sync (replacing the Alchementary Link migration chapter), the Diagnostics tab and log, and refreshed screenshots throughout. The welcome screen's protocol line now lists RDP.
107 lines
5.1 KiB
TeX
107 lines
5.1 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:
|
|
choose \ui{Accept \& Update} in the warning (or \ui{Accept Once} to defer the decision). Under a Strict or Accept-new
|
|
policy there's no prompt: \menu{Settings\then Known Hosts}, \ui{Remove} the entry and reconnect.}
|
|
|
|
\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}}
|
|
|
|
\fix{RDP won't connect}{%
|
|
\begin{itemize}
|
|
\item Linux box running xrdp? Tick \ui{Allow servers without NLA}.
|
|
\item ``Logon failed''? Check the domain. Kerberos users: the KDC must be reachable directly, not through the proxy.
|
|
\item Certificate warning after a server rebuild? That's expected once; compare the fingerprint, then
|
|
\ui{Accept \& Update}.
|
|
\item Going through an RD Gateway? It needs a certificate from a public CA and Basic authentication over HTTPS.
|
|
\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}
|
|
|
|
\section{Still stuck?}
|
|
|
|
\fix{Something odd that isn't on this list}{%
|
|
Look at \code{nexus.log} in your data folder (\menu{Settings\then Diagnostics} shows where): connections, reconnects,
|
|
host-key checks and errors, never passwords or what's on screen. Start Nexus Terminal with \code{RUST\_LOG=debug} for
|
|
more detail. Reporting a bug? \ui{Copy Diagnostics} and paste it in.}
|
|
|