cputty
======

cputty is a fork of PuTTY 0.85 <https://www.chiark.greenend.org.uk/~sgtatham/putty/>
that adds cluster SSH: one console window whose keystrokes go to many
SSH sessions at once, in the style of the classic cssh tools on Solaris
and Linux. It runs on Linux (GTK 3) and Windows.

This is not an official PuTTY release and is not supported by the PuTTY
developers. Please report problems with cputty at
<https://github.com/gluffis/cputty/issues>, not to the PuTTY team.
Security vulnerabilities should be reported privately instead: see
SECURITY.md.


Cluster SSH: the cputty program
-------------------------------

  cputty -l root web1 web2 web3          (Linux)
  cputty.exe -l root web1 web2 web3      (Windows)

cputty opens one ordinary PuTTY terminal window for each host on the
command line, plus a console window:

 - Keystrokes typed in the console go to every session that is ticked
   in the console's host list. Typing in a terminal window goes to that
   session alone, so you can switch between driving the whole cluster
   and fixing one machine.

 - The All, None and Invert buttons change which sessions are ticked.
   The console title and status line show how many sessions are
   receiving input.

 - A text field shows what you are typing, so you can see the command
   you are sending. It holds the current line (up to 200 characters)
   and clears on Return, on Escape, or after 15 seconds without typing.
   Tick "Hide typed text" to stop it showing anything, for example
   while typing passwords.

 - Each session translates keystrokes itself, so per-session terminal
   modes (such as application cursor keys) work. On Windows, dead keys
   and other keyboard-layout features work in broadcast input too.

 - Sessions whose connection has closed stop receiving console input.
   The console's "New session" button, and New Session, Duplicate
   Session and Saved Sessions from a terminal window's menu, open in the
   same process and join the host list.

 - Terminal windows open in a cascade from the top left of the screen,
   each a little below and to the right of the last, so you can see
   each one open. The console goes in the bottom right corner, in front.
   (Window positions can't be chosen under Wayland, so there the
   desktop places the windows.)

 - The console's "Arrange windows" button tiles all the terminal
   windows and the console evenly over the screen, in rows, with the
   console in the bottom right corner. The terminals resize to fit
   their tiles; the console never gets smaller than it can usefully be.

 - The console stays open when all the sessions have closed, so that
   you can open more. Closing the console closes every session (it asks
   first if any are still connected) and exits cputty.

All putty options are accepted and apply to every host, including
hosts opened later from a group. Every non-option argument is a host
or the name of a host group. A host can be written as host,
user@host, host:port or the name of a saved session ([address]:port
for an IPv6 address). A password given with -pw is offered to every
host. With no hosts, cputty opens just the console, from which you can
open a group or a new session (or, with -load, the saved session).
See "man cputty" for details.


Host groups
-----------

A group is a name for a set of hosts. The console lists your groups:
click one to open a session to each of its hosts. To make a group,
open and tick the hosts you want, press "Save ticked hosts as group"
and type a name. Right-click a group to delete it. A group name can also be used
on the command line:

  cputty -l root web

Groups are kept in a plain text file that you can also edit by hand,
one group per line: the name, then its hosts, separated by spaces.
Lines starting with # are comments.

  # name  hosts
  web     arrange=yes web1 web2 root@web3:2222
  db      db1 db2

arrange=yes makes opening the group also arrange all the windows, as
the "Arrange windows" button does; the Save dialog has a checkbox for
it. (A word containing = is a setting like this rather than a host.)

The file is ~/.config/putty/cputty-groups (or ~/.putty/cputty-groups,
wherever your PuTTY settings are) on Linux, and
%APPDATA%\cputty\groups.txt on Windows. The console picks up changes
to it when you next switch to the console.


Other differences from upstream PuTTY
-------------------------------------

 - SSH only. Telnet, Rlogin, SUPDUP, Raw and serial-line connections
   have been removed from every program, along with the Telnet proxy
   type. A saved session that used one of the removed protocols opens
   as SSH on port 22; one that used the Telnet proxy refuses to
   connect rather than connecting directly. There is no PuTTYtel.

 - Faster default builds. CMake builds a Release (optimised) build by
   default with link-time optimisation. Cryptographic code is
   deliberately kept at -O2 without link-time optimisation, so that
   PuTTY's side-channel tests still hold. Some hot paths (buffer
   appends and scrollback compression) have been tuned.

 - Hardened Linux builds. On Unix, CMake turns on the exploit
   mitigations Linux distributions use for their own packages: stack
   protector, _FORTIFY_SOURCE=3 (except in Debug builds), stack clash
   and control-flow protection, and full RELRO.

 - Version strings identify the build as cputty, for example
   "cputty 1.1.1 (based on PuTTY 0.85)" and the SSH banner
   "SSH-2.0-PuTTY_cputty_1.1.1", so servers don't mistake it for an
   official PuTTY release.

The other programs (putty, plink, pscp, psftp, puttygen, pageant, pterm)
otherwise behave as in PuTTY 0.85.


Downloads
---------

Release binaries for Linux x86_64 and Windows x86_64, plus Debian
packages, are on the releases page:

  https://github.com/gluffis/cputty/releases

 - cputty_VERSION_amd64.deb installs only cputty and can be installed
   alongside Debian's putty packages.
 - cputty-suite_VERSION_amd64.deb installs the SSH-only putty, plink,
   pscp, psftp, puttygen and pageant, and replaces Debian's putty and
   putty-tools packages.


Building
--------

cputty is built using CMake <https://cmake.org/>. In the source
directory:

  cmake -B build
  cmake --build build -j

This builds a Release build with link-time optimisation. Pass
-DPUTTY_LTO=OFF to turn link-time optimisation off, or
-DCMAKE_BUILD_TYPE=Debug for a debug build. On Unix, the exploit
mitigations described above are on by default; -DPUTTY_HARDENING=OFF
turns them off. On Linux you need the GTK 3 development files.

To cross-compile the Windows programs on Linux with mingw-w64:

  cmake -B build-win64 -DCMAKE_TOOLCHAIN_FILE=cmake/toolchain-mingw.cmake
  cmake --build build-win64 -j

To install on Linux:

  cmake --build build --target install

Man pages are built from the Halibut (.but) files in the doc
subdirectory when Halibut is installed. Halibut is at
<https://www.chiark.greenend.org.uk/~sgtatham/halibut/>.

release/build-release.sh VERSION builds all the release files (Linux
tarball, both Debian packages, Windows zip and SHA256SUMS).

On Unix, pterm would like to be setuid or setgid, as appropriate, to
permit it to write records of user logins to /var/run/utmp and
/var/log/wtmp. (It will not use this privilege for anything else, and
drops all privileges before starting up complex subsystems like GTK.)
The install step doesn't add these privileges, so if you want login
recording to work, chown/chgrp and chmod the pterm binary yourself
after installation. Otherwise pterm still works, but doesn't update
the login databases.


Licence
-------

cputty is distributed under the same MIT licence as PuTTY. See the
file LICENCE. PuTTY is copyright Simon Tatham and the other PuTTY
contributors; the cluster and other changes in this fork are offered
under the same terms.