Differences

This shows you the differences between two versions of the page.

--- lanternterminal:sessions [2026-11-07 16:04] – Add Lantern Terminal 0.1.0 documentation slaterm
+++ lanternterminal:sessions [2026-11-11 08:56] (current) – Update Lantern Terminal guides for 0.6.0 slaterm
@@ Line 1: / Line 1: @@
-====== Sessions, appearance and workspaces ======
+====== Lantern Terminal user guide ======
-===== Opening a saved session =====
+===== Theme =====
-Create and save a connection with **File → New session**. To open it later, find it in the **Sessions** pane and double-click its name, or select it and choose **File → Connect selected**. Expand its folder if necessary and clear the filter if it is hiding entries. **Edit → Go to Session Manager** brings the pane into view.
+Choose **Options → Theme → System**, **Light** or **Dark**. Themes apply immediately and the choice is saved with your settings. System uses the desktop palette available when the application starts. These controls affect the application interface; terminal foreground/background/cursor colours remain session settings. The new-session wizard uses the same readable palette and shows the fields for its selected protocol.
-===== Connection details =====
+===== SSH authentication and server trust =====
-Choose **File → Quick Connect** for an immediate SSH2/SFTP/Telnet/raw/serial/local connection. **File → New session** walks through protocol, endpoint and name/folder. Saved entries are in the Sessions pane. Double-click an entry, or select entries/folders and choose **Connect selected**.
+A password prompt appears only if the server offers password or keyboard-interactive authentication. If the error is **Permission denied (publickey)**, choose an authorised private key under Session Properties → Connection → SSH2 → Private key / identity, or use your SSH agent. Trusting the server fingerprint does not authenticate your account. Accepted server keys are shared by the application profile and survive recreating saved sessions.
+===== Connections =====
+Choose **File → Quick Connect** (F4) for an immediate SSH2/SFTP/Telnet/RLogin/RDP/raw/serial/local connection. **File → New session** walks through protocol, endpoint and name/folder. Saved entries are in the Sessions pane. Double-click an entry, or select entries/folders and choose **Connect selected**.
 For SSH, supply the hostname, port, username and optionally a private key in Session Properties. Authentication and unknown/changed host-key messages appear in the terminal. Accept a key only after checking its fingerprint. The host-key database belongs to the current application profile. **Tools → Manage host keys** lets you inspect/import/export it.
-SSH settings include jump hosts, agent forwarding, compression, algorithm preferences and local/remote/dynamic forwards. Forward lines use ''L|127.0.0.1:8080:target:80'', ''R|127.0.0.1:8080:target:80'' or ''D|127.0.0.1:1080''. **Forwarding only** requests no shell. Trusted advanced OpenSSH options use one ''Key=Value'' line each.
+SSH settings include jump hosts (one or a chain: ''user@host:port,user2@host2''; each is checked and logged in to like the session itself), agent and X11 forwarding, compression, Kerberos (GSSAPI) login, algorithm preferences and local/remote/dynamic forwards. **Use FIPS-approved algorithms only** limits key exchange, ciphers, MACs and key types to FIPS-approved ones and refuses Ed25519 and DSA keys with a clear message; it limits algorithms, it does not make Lantern a validated FIPS module. Forward lines use ''L|127.0.0.1:8080:target:80'', ''R|127.0.0.1:8080:target:80'' or ''D|127.0.0.1:1080''. **Forwarding only** requests no shell. Trusted advanced OpenSSH options use one ''Key=Value'' line each.
-Local shells use a PTY on Linux and ConPTY on Windows. Serial connections use device paths or COM names and configurable baud/format/flow/break settings. Telnet negotiates terminal type and window size. Raw TCP passes bytes without protocol framing.
+**SSH engine.** Each SSH2 session uses one of two engines, chosen under **Session properties → Connection → SSH2 → SSH engine**:
+  * **Built-in (libssh)** (default) handles SSH inside Lantern. The status bar shows the cipher, key exchange and MAC actually negotiated, and the connection state comes straight from the protocol. Host-key questions, key passphrases, keyboard-interactive and password prompts appear in the terminal; type the answer and press Enter (Ctrl+C cancels). Like OpenSSH it tries SSH agent keys first (on Windows, the Windows OpenSSH agent), then the private key you selected, then your default ''.ssh'' keys. It shares the profile's host-key file with the OpenSSH engine, so a key accepted by one is trusted by the other.
+  * **OpenSSH** runs the system ''ssh'' program, with your OpenSSH client's full feature set.
+The built-in engine understands about 40 of the additional OpenSSH options (for example ''ServerAliveInterval'', ''ServerAliveCountMax'', ''ConnectTimeout'', ''StrictHostKeyChecking'', ''UserKnownHostsFile'', ''IdentityFile'', ''IdentitiesOnly'', ''ProxyJump'', ''ForwardAgent'', ''ForwardX11'', ''LocalForward'', the algorithm lists and the authentication switches). A session that uses an option it does not know, or a proxy command on Windows, automatically uses OpenSSH and notes this in the Activity pane. SFTP terminal tabs use OpenSSH; the SFTP Browser uses the built-in engine.
+**Copy Public Key to Server** (Tools menu, or right-click an SSH session or tab) puts your public key on a server so the session can log in without a password, like ''ssh-copy-id''. Choose the ''.pub'' file (the session's key is offered first). Lantern logs in (asking for the password in the window if needed), creates ''~/.ssh'' and ''authorized_keys'' if they are missing, sets the permissions SSH needs (700 and 600), adds the key unless it is already there, then tries a login with only the key. It tells you if the server has a misspelt ''authorised_keys'' file, which SSH ignores. The server needs a Unix-like shell; Windows servers keep keys elsewhere.
+**SSH Agent** (Tools menu) lists the agent's keys and adds key files (with their passphrase, how long to keep them, and whether to ask before each use), smartcard or token keys through a PKCS#11 library, removes one or all keys, and locks or unlocks the agent. On Linux, **Start an Agent for Lantern** starts an agent that every new session uses; it stops when Lantern closes. On Windows, start the "OpenSSH Authentication Agent" service instead.
+**RDP (Windows Remote Desktop).** Choose the RDP protocol (port 3389) in a new session or Quick Connect, or type ''rdp://host'' in the connection bar. The remote desktop appears in the tab and follows the tab's size (**Connection → RDP → Remote desktop size**, or a fixed size). The first time, Lantern shows the server's certificate fingerprint and asks whether to trust it; the answer is remembered in ''known_rdp_certificates'' in the settings folder, and a changed certificate is refused. Give the user name in the session and either a credential name under **Connection → RDP** (the password comes from the system password store) or nothing, in which case the password is asked when connecting and never saved. Keys and the mouse go to the remote desktop; the buttons above it send Ctrl+Alt+Del and the Windows key and switch to full screen (Ctrl+Alt+End also sends Ctrl+Alt+Del). Copied text goes both ways. Find, logging and file transfers are not available on RDP tabs. A Windows domain can be given in the session (also in the new-session wizard and Quick Connect), in the login window, or as ''DOMAIN\user'' in the user name.
+**BBSes and door games.** Use **Tools → New BBS session…** (not File → New session, which makes ordinary sessions). Choose Telnet (the default), RLogin, SSH2 or Raw TCP, then enter the host and a name. This sets up the session the way BBSes expect: the CP437 character set, the ANSI-BBS screen, the built-in VGA font, an 80×25 screen that scales the font to fit the window, and BBS keys (Backspace sends 0x08, Delete sends 0x7F). For sessions you already have, right-click them (or a folder) in the Sessions pane and choose **Apply BBS settings…**, or use **Options → Apply BBS settings to this session…** for the current tab; your other settings are kept. Each of these is also a separate setting in Session Properties:
+  * **Terminal → Emulation → ANSI-BBS emulation** behaves like a DOS ANSI.SYS screen: bold text is the bright colour, blinking text blinks, clearing the screen moves the cursor to the top left, CP437 symbols such as ☺ ♥ ♪ appear for control bytes in ANSI art, and ANSI music is ignored (it is not played). **iCE colours** turns the blink attribute into bright backgrounds, as many ANSI artists intended; a BBS can also switch iCE colours on itself. **Terminal type** offers ''ansi-bbs'', ''ansi'' and ''xterm''.
+  * **Terminal → Appearance → Use the built-in VGA font** draws text with an 8×16 PC-style font. Block and line-drawing characters fill their cells exactly, so ANSI art has no gaps at any size.
+  * Copying text from a BBS screen gives the equivalent Unicode characters.
+**RLogin** (port 513) logs you straight in. As in SyncTERM, the BBS user name goes in **Username** and the password (or the key some door servers give you) in **Connection → RLogin → Client user name**. To keep a password out of the settings file, create a credential in **Tools → Manage credentials**, give it the user name, press **Set password…** to store the password in the system password store, and enter the credential's name under **Connection → RLogin → Credential name**.
+**BBS Directory.** To find a BBS and connect without making a session first, use the **BBS Directory** button on the toolbar (or **Tools → BBS Directory…**). It downloads the Synchronet BBS List and the Telnet BBS Guide, keeps the BBSes you have used at the top, and saves a BBS as a session when you press **Save as session**. See [[lanternterminal:bbsdirectory|BBS Directory]].
+**Importing a BBS list.** **Tools → Import BBS list (SyncTERM)…** reads a SyncTERM dialling directory (''syncterm.lst''). A preview lists every entry; untick any you do not want and choose the folder. Nothing is saved if you cancel. Passwords are left out unless you tick the option to store them in the system password store; RLogin sessions then log in with them. Modem and other unsupported entries are listed as skipped.
+SyncTERM-Lua scripts (for example LORD or TradeWars bots) run with **Script → Run** once you are at the right point in the game; see the [[lanternterminal:lua|Lua guide]].
+Local shells use a PTY on Linux and ConPTY on Windows. Serial connections use device paths or COM names and configurable baud/format/flow/break settings. Telnet negotiates terminal type, window size and binary mode. RLogin sends your user names and terminal type and reports the window size when asked. Raw TCP passes bytes without protocol framing.
 ===== Profiles and settings =====
-Right-click entries to edit, rename, cut/copy/paste or delete. Live filtering narrows the tree; a trailing ''/'' includes matching folders. Global Settings controls application behaviour. Default Session sets initial preferences for new sessions and offers explicit propagation of changed fields. Multi-selection editing changes only modified fields.
+Right-click entries to edit, rename, cut/copy/paste or delete. To arrange sessions or folders yourself, select one entry and choose **Move up (manual order)** or **Move down (manual order)**. This switches sorting to Manual and stores the current sibling order. Clear the filter before arranging entries. Choose Natural or Alphabetical in Global Settings to sort automatically again. Expanded folders and manual order survive restarting.
+Select a saved session, then choose **Create desktop shortcut…** from its context menu, or **File → Create session desktop shortcut…**. Choose where to save the Linux ''.desktop'' launcher or Windows ''.lnk'' shortcut. The shortcut retains the configuration root and stable session ID, so renaming or moving the session does not break it. Your desktop may ask you to allow launching a new Linux desktop file. Removing the saved session leaves a shortcut that reports the missing session. Live filtering narrows the tree; a trailing ''/'' includes matching folders. Global Settings controls application behaviour. Default Session sets initial preferences for new sessions and offers explicit propagation of changed fields. Multi-selection editing changes only modified fields.
 **Options → Session properties** edits the active session. Several transport settings take effect on reconnect; appearance/input options can apply immediately. Save active ad hoc settings with **File → Save current session**. If automatic saving is disabled, use **Options → Save settings now** to commit changes before exit. Global, session and invocation options use separate scopes.
-Imports accept native JSON/XML and simple comma/tab text rows (''name,host,protocol,port,username,folder''). Use tabs for values containing commas. Import is previewed before applying and asks how to handle conflicting session names. Export does not contain passwords or private-key bytes.
+Imports accept native JSON/XML and simple comma/tab text rows (''name,host,protocol,port,username,folder''). Use tabs for values containing commas. Import is previewed before applying and asks how to handle conflicting session names. Imported settings are merged with yours: commands, credentials, button bars and snapshots with the same ID or name are updated, everything else is added, and nothing is deleted. If the file contains anything that runs a program on your computer (proxy command, extra SSH options, pre-connect program, local shell, environment, logon script, launch-application or run-script commands, or a Python interpreter path), the preview lists each one and defaults to No. From the command line, ''--import'' refuses such files (exit code 3) unless ''--trust-import'' is also given. Export does not contain passwords or private-key bytes.
-===== Terminal and colours =====
+===== Terminal =====
 The terminal supports colour, Unicode, primary/alternate screens, cursor modes, line drawing, selection and scrollback. In **Session properties → Terminal → Appearance**, foreground, background and cursor colours each have a swatch and **Choose colour…** button. Select from the visual palette; entering a colour code is optional. Use **Ctrl+Shift+C / Ctrl+Shift+V** to copy/paste. Ctrl+C remains a remote interrupt unless Windows-style copy hotkeys are explicitly enabled. Shift+PageUp/PageDown scroll locally. Hold Shift to select locally when a remote application uses mouse tracking. Ctrl+mouse wheel changes font size.
-Use the toolbar phrase box for temporary highlights, or configure permanent pattern/colour/regex rows under Terminal → Highlighting. Search with Ctrl+F. Clear screen, scrollback and reset are separate Edit commands. Hex View displays recent received bytes. Multi-line paste asks for confirmation at the configured threshold. Cancelling sends nothing; **Edit → Cancel pending paste/send** stops queued paced input.
+**Keyboard shortcuts.** Lantern's own shortcuts use Ctrl+Shift so ordinary control keys reach the remote program: Ctrl+Shift+S new session, Ctrl+Shift+O Quick Connect, Ctrl+Shift+N local shell, Ctrl+Shift+F find, Ctrl+Shift+P print, Ctrl+Shift+W close tab, Ctrl+Shift+Q exit, Ctrl+Tab / Ctrl+Shift+Tab switch tabs, Ctrl+= / Ctrl+- zoom. Function keys: F1 lists every shortcut, F2 Session properties, F3 / Shift+F3 find next / previous, F4 Quick Connect, F5 Reconnect, F6 next split pane, F7 SFTP Browser, F8 Zmodem upload, F9 start/stop logging, F11 full screen, F12 run a script, Shift+F12 cancel it, Ctrl+F12 run the last script again. F10 always goes to the remote program, and Alt+F1 … Alt+F12 send the plain function key to it. Programs that need all their function keys (Midnight Commander, some BBS doors) can have them back: tick **Terminal → Input → Function keys go to the remote program**. Every other Ctrl and Alt key (Ctrl+P, Ctrl+F, Ctrl+S, Alt+F …) is sent to the session, and a key mapped in the session's key mappings always goes to the session. Alt+1…9 tab switching is off by default; turn it on in Global settings → Terminal → Tabs.
+Use the toolbar phrase box for temporary highlights, or configure permanent pattern/colour/regex rows under Terminal → Highlighting. Search with Ctrl+Shift+F. Clear screen, scrollback and reset are separate Edit commands. Hex View displays recent received bytes. Multi-line paste asks for confirmation at the configured threshold. Cancelling sends nothing; **Edit → Cancel pending paste/send** stops queued paced input.
+**Terminal types and graphics.** Besides xterm, VT100/VT220, ANSI, ANSI-BBS and Linux, the terminal type can be **Wyse 60** or **SCO ANSI** (for older Unix systems and applications); each sends its own function, cursor and editing keys, and VT100/VT220 sessions send VT keys. **Sixel** images (for example from ''img2sixel'' or ''chafa -f sixel'') appear at the cursor and scroll with the text. Programs can switch to **132 columns** (the font shrinks to fit) and use **double-width and double-height lines**, left/right margins and protected (selectively erased) text.
 Lock a session from File; choose a local unlock password. Locked sessions stay connected but hide their screen and reject scripted reads and broadcast input. Unlock restores the same session.
@@ Line 33: / Line 70: @@
 ===== Tabs, groups and commands =====
-Drag tabs to reorder within a group. Window menu commands create horizontal/vertical groups, collapse them, or move a tab to the next group. Right-click tabs for reconnect, clone, rename/reset, save and properties. Active Sessions lists open connections and supports selected disconnect/close/lock actions.
+Drag tabs to reorder within a group. **Tear-off tabs:** drag a tab down out of the tab bar to open it in its own window (the session keeps running), or drag it onto another window's tab bar to move it there. Right-click a tab for **Move to New Window** or **Dock to Main Window**; **Window → Dock All Tabs to Main Window** brings every torn-off tab back. Closing a torn-off window docks its tabs. Lantern's shortcuts work in torn-off windows and act on the tab you are typing in. (On Wayland desktops, dragging onto a tab bar in another window may not work; use the menus.) Window menu commands create horizontal/vertical groups, collapse them, or move a tab to the next group. Right-click tabs for reconnect, clone, rename/reset, save and properties. Active Sessions lists open connections and supports selected disconnect/close/lock actions.
 The Command window's destination selector is explicit: active, all, visible, or selected groups. **Send** submits text to exactly that scope; locked/disconnected tabs are skipped. Mark a group with **Window → Send commands to this group**. Group recipients have a leading asterisk in their tab labels.
-Commands have labels, descriptions, folder, colour and a typed action. **Tools → New command/button** adds one. Commands can send text, run Python scripts, launch a trusted local application, connect a saved session, or invoke supported terminal menu actions. Literal send strings recognise ''\r'', ''\n'', ''\t'' and ''\e''.
+Commands have labels, descriptions, folder, colour and a typed action. Script actions also accept a quoted argument list. **Tools → New command/button** adds one. Commands can send text, run Python scripts, launch a trusted local application, connect a saved session, or invoke supported terminal menu actions. Literal send strings recognise ''\r'', ''\n'', ''\t'' and ''\e''.
+Right-click commands or command folders to **Cut**, **Copy** and **Paste**. Copies receive independent IDs and preserve their exact action text and escapes. Paste uses the selected command folder. Cutting moves the existing commands only when you paste in the same application window; pasting into another instance copies them. Nothing runs merely because it is copied or pasted.
+Choose **Tools → Manage button bars…** or **Manage bars…** on the button toolbar. Create, copy, rename or delete named bars; add/edit/remove buttons and move them up/down. A bar links to saved command definitions: editing a command updates every bar using that command. Removing a button or deleting a bar keeps its commands. Deleting a command removes its buttons from every bar. **Copy buttons** and **Copy bar commands** put action records on the clipboard so they can be pasted into Command Manager or another bar.
+Right-click selected commands and choose **Add to button bar** to link existing actions to a bar. **Paste commands** in the bar manager creates independent copies of the clipboard actions and adds them in order. The toolbar selector chooses the active session's bar; without an active session it chooses the global bar. **Use global bar** follows the global choice, and **No button bar** hides action buttons. **Use globally** in the bar manager sets the global choice. Session Properties → Terminal → Buttons and Global Settings → Terminal → Buttons also offer the bar selector. Old single-bar configurations migrate to a bar called Default.
 Save a named snapshot from File to retain session settings and tab-group layout. Manage snapshots to open, rename, duplicate or delete them. Snapshots are not remote process checkpoints.
-===== Backups and moving computers =====
+===== Files and logs =====
+File transfers (Zmodem, Xmodem, Ymodem, Kermit, the SFTP Browser) are described in [[lanternterminal:transfers|File transfers]].
+Open an SFTP terminal from an SSH tab. Its interactive client supports ''help'', ''ls'', ''cd'', ''lcd'', ''pwd'', ''get'', ''put'', recursive transfers, permissions and filename completion. Quote paths containing spaces. Use the Transfer menu for SFTP uploads or terminal text/binary sends.
+Start, pause/resume and stop logs through File. Session Properties controls raw/text mode, filename templates, append, timestamps, line prefixes and rotation. ''%Y/%M/%D'' are date, ''%h/%m/%s'' are time, ''%H'' host and ''%S'' session. Raw logs preserve received bytes; text logs filter terminal escape sequences. Logging failures are reported without closing the connection.
+The optional TFTP server starts only when chosen in Transfer. Configure upload/download roots, UDP port, overwrite and client-address restrictions in Global Settings. Use octet transfer mode. It rejects paths outside its configured roots.
+===== Sync between computers =====
+To have the same sessions on several computers, choose a folder that Nextcloud, Syncthing, Dropbox or a network share keeps the same everywhere, and set it in **Options → Global settings → General → Sync** on each computer. Lantern writes ''lantern-sync.json'' there and reads the other computers' changes every few seconds. Sessions, folders, credential user names (never passwords), commands, button bars and the default session are synced; when the same session was changed on two computers the newest change wins, and deletions carry over. Settings that belong to one computer are kept as they are on each computer: local shells, serial ports, private key and certificate files, known-hosts files, proxy and pre-connect programs, logon scripts, log and transfer folders and the RLogin client user name. **Tools → Sync Now** syncs at once. If the file in the folder is damaged, Lantern leaves it alone and says so.
+===== Updates =====
+Lantern checks the website once a day and tells you when a new version is out. **Update Now** downloads it, checks it and installs it: the Debian package asks for your password, and on Windows the installer runs while Lantern closes. A copy that was not installed from a package opens the download page instead. **Not Now** asks again tomorrow; **Skip This Version** stays quiet until the next one. **Help → Check for Updates…** checks at once, and the window has a box to turn the daily check off (also **Global settings → General → Updates**).
+===== Automation and help =====
+Run Python or Lua scripts from Script, cancel them independently of the session, or record send actions into an editable Python or Lua file. See SCRIPTING-GUIDE.md for prompt matching and examples. Recording is a send-action skeleton and may need explicit waits before reuse. Recognised password/passphrase/PIN prompt entries are replaced by comments, but review any recording before sharing it.
+**Help → Features and capabilities** lists included and unavailable compatibility features. Build instructions and the detailed specification are available offline. **Help → About** shows version and the exact configuration directory.
+===== Saved-session launch commands =====
+Use a saved session's stable ID, unique name or full folder/name. Repeat ''--open-session'' to open several sessions. An ambiguous name produces a message instead of selecting an arbitrary connection. The earlier ''--session'' spelling remains an alias.
+<code sh>
+lantern-terminal --open-session 'Work/Server'
+lantern-terminal --config "$HOME/terminal-work" --open-session SESSION_ID
+lantern-terminal --config "$HOME/terminal-work" --open-session SESSION_ID --create-shortcut "$HOME/Desktop/Server.desktop"
+</code>
+On Windows, use a ''.lnk'' output filename for ''--create-shortcut''. A shortcut contains references and launch arguments, not saved passwords or private-key contents.
+===== Lua automation =====
+Choose **Script → Run** and select a ''.lua'' file. Lua is included with the application. The same files work as logon scripts and saved script commands. Choose **Script → Cancel** to stop a script while retaining the connection. Script output and errors appear in Activity. **Help → Lua scripting guide** opens the API and examples. Recording can save ''.py'' or ''.lua'' send-action scripts; review them before use.
+===== Reusing an unlocked SSH key =====
+Select the private key (for example ''id_ed25519'', without ''.pub'') in the session’s key-file setting. To avoid entering its passphrase on each connection, load it through **Tools → Add identity to agent…** and verify it under **Tools → Agent identities**. The passphrase unlocks the local private key; it is separate from a server password.
+Windows needs its OpenSSH Authentication Agent service running. If the agent reports “No such file or directory”, open PowerShell as Administrator and run:
+<code powershell>
+Set-Service ssh-agent -StartupType Automatic
+Start-Service ssh-agent
+Get-Service ssh-agent
+</code>
-**Help → About Lantern Terminal** displays the active configuration directory. Close the application when you can disconnect, then copy that directory to a backup location. The ''--config'' command-line option selects a different directory.
+Then add the identity again. On Linux, use an agent provided by the desktop or start one in the environment that launches the application. Do not put key passphrases into automation scripts.
-Use **Tools → Export settings…** and **Tools → Import settings…** to move session settings. Exports omit passwords and private-key bytes. Keys, local file paths and installed shell/device names may need updating on the destination computer. Workspace snapshots retain settings and tab layout; they do not keep remote processes alive or record a remote machine's state.
+===== Connection state and tab reuse =====
-[[lanternterminal:start|Back to Lantern Terminal]]
+“Reuse disconnected tabs” only replaces an idle disconnected tab. Connecting sessions and SSH password, passphrase or host-key prompts keep their own tabs when you open another session. The status bar shows **Connecting…**, **Session open**, or **Connected** as the connection progresses; **Session open** means the client is running while authentication confirmation is pending. Older Windows OpenSSH authentication messages are also recognised. Reconnect All skips active connections and pending logins.