Merge branch 'main' into dev

ChangeLog.md

@@ -57,6 +57,11 @@ package is not installed) and on RHEL 7 and Fedora 19 and later (if the
 rather than trying to execute **xinitrc** or twm, if a window manager is
 specified and the session desktop file for the window manager cannot be found.
 
+6. Added a new parameter (`ExtSSHCommand`) to the TurboVNC Viewer that can be
+used to specify the external SSH client command.  In `Via`/`Tunnel` SSH
+command-line templates, including the default ones, `%S` is now replaced with
+the value of this new parameter.
+
 
 3.1.1
 =====

doc/auth.txt

@@ -3,8 +3,8 @@
 
 ** Terminology
 
-In an attempt to maintain consistency with other VNC implementations, TurboVNC
-uses the following terminology when referring to its security extensions:
+In an attempt to be consistent with other VNC implementations, TurboVNC uses
+the following terminology when referring to its security extensions:
 
 	Authentication Method :: {:}
 		A technique that the VNC server uses to validate authentication credentials
@@ -41,12 +41,12 @@ uses the following terminology when referring to its security extensions:
 	One-Time Password (OTP) Authentication :: {:}
 		Using the ''vncpasswd'' program, a unique password is generated "on the
 		fly" for the TurboVNC session, and the password is printed on the command
-		line (see the man page for ''vncpasswd'' for more details.)  The user
-		enters this password in the VNC viewer, and the VNC viewer sends the
-		password to the server as if it were a VNC password.  However, once the OTP
-		has been used to authenticate a viewer, the OTP is forgotten and cannot be
-		reused.  OTP authentication can be used, for instance, to launch or connect
-		to TurboVNC sessions from an automated web portal or from a job scheduler.
+		line.  (See the ''vncpasswd'' man page for more details.)  The user enters
+		this password into the VNC viewer, and the VNC viewer sends the password to
+		the server as if it were a VNC password.  However, once the OTP has been
+		used to authenticate a viewer, the OTP is forgotten and cannot be reused.
+		OTP authentication can be used, for instance, to launch or connect to
+		TurboVNC sessions from an automated web portal or from a job scheduler.
 		OTP authentication is also useful for allowing temporary access to a
 		TurboVNC session for collaboration purposes.  The
 		[[#TurboVNC_Session_Manager][TurboVNC Session Manager]] uses OTP
@@ -76,8 +76,8 @@ uses the following terminology when referring to its security extensions:
 		A password is sent to the server using a DES-encrypted
 		challenge/response scheme.  The password can be up to 8 characters long,
 		so the DES key length is 56 bits.  This is not a particularly strong form
-		of encryption by today's standards (56-bit DES was broken by brute force
-		attack in the late 90's.)
+		of encryption by today's standards.  (56-bit DES was broken by brute force
+		attack in the late 1990s.)
 
 	Unix Login/Plain Authentication :: {:}
 		Both the username and password are sent to the VNC server as plain text.
@@ -108,54 +108,71 @@ TurboVNC supports the following security types:
 
 || Server Security Type || Authentication Method || Encryption Method || \
 	Viewer Security Type || Authentication Scheme || Compatibility ||
-| None | None | None | None | None | RFB 3.3+ |
-| VNC | VNC Password | None | VNC | Standard VNC | RFB 3.3+ |
-| OTP | One-Time Password | None | VNC | Standard VNC | RFB 3.3+ |
-| Plain | PAM User/Password | None | Plain | Plain | RFB 3.7+ with VeNCrypt extensions |
-| TLSNone | None | Anonymous TLS | TLSNone | None | RFB 3.7+ with VeNCrypt extensions |
-| TLSVnc | VNC Password | Anonymous TLS | TLSVnc | Standard VNC | RFB 3.7+ with VeNCrypt extensions |
-| TLSOtp | One-Time Password | Anonymous TLS | TLSVnc | Standard VNC | RFB 3.7+ with VeNCrypt extensions |
-| TLSPlain | PAM User/Password | Anonymous TLS | TLSPlain | Plain | RFB 3.7+ with VeNCrypt extensions |
-| X509None | None | TLS/X.509 | X509None | None | RFB 3.7+ with VeNCrypt extensions |
-| X509Vnc | VNC Password | TLS/X.509 | X509Vnc | Standard VNC | RFB 3.7+ with VeNCrypt extensions |
-| X509Otp | One-Time Password | TLS/X.509 | X509Vnc | Standard VNC | RFB 3.7+ with VeNCrypt extensions |
-| X509Plain | PAM User/Password | TLS/X.509 | X509Plain | Plain | RFB 3.7+ with VeNCrypt extensions |
-| UnixLogin | PAM User/Password | None | UnixLogin | Unix Login | RFB 3.7+ with TightVNC extensions |
+| None | None | None | \
+	None | None | RFB 3.3+ |
+| VNC | VNC Password | None | \
+	VNC | Standard VNC | RFB 3.3+ |
+| OTP | One-Time Password | None | \
+	^ | ^ | ^ |
+| Plain | PAM User/Password | None | \
+	Plain | Plain | RFB 3.7+ with VeNCrypt extensions |
+| TLSNone | None | Anonymous TLS | \
+	TLSNone | None | RFB 3.7+ with VeNCrypt extensions |
+| TLSVnc | VNC Password | Anonymous TLS | \
+	TLSVnc | Standard VNC | RFB 3.7+ with VeNCrypt extensions |
+| TLSOtp | One-Time Password | Anonymous TLS | \
+	^ | ^ | ^ |
+| TLSPlain | PAM User/Password | Anonymous TLS | \
+	TLSPlain | Plain | RFB 3.7+ with VeNCrypt extensions |
+| X509None | None | TLS/X.509 | X509None | \
+	None | RFB 3.7+ with VeNCrypt extensions |
+| X509Vnc | VNC Password | TLS/X.509 | \
+	X509Vnc | Standard VNC | RFB 3.7+ with VeNCrypt extensions |
+| X509Otp | One-Time Password | TLS/X.509 | \
+	^ | ^ | ^ |
+| X509Plain | PAM User/Password | TLS/X.509 | \
+	X509Plain | Plain | RFB 3.7+ with VeNCrypt extensions |
+| UnixLogin | PAM User/Password | None | \
+	UnixLogin | Unix Login | RFB 3.7+ with TightVNC extensions |
 #OPT: hiCol=1,4
 
 	!!! NOTE: The security type names are case-insensitive.  The capitalization
-	conventions above are used in order to maintain consistency with the RFB
-	protocol specification.
+	conventions above are used for consistency with the RFB protocol
+	specification.
 
 ** Enabling Security Types
 
 The default behavior of the TurboVNC Server is for all security types except
-"TLSNone", "X509None", and "None" to be enabled and for VNC Password and OTP
+TLSNone, X509None, and None to be enabled and for VNC Password and OTP
 authentication to be preferred over PAM User/Password authentication.  However,
-the system administrator can disable one or more of the security types or set
-the preferred order of the security types by editing the TurboVNC security
-configuration file.  See the ''Xvnc'' man page for more details.
-
-If the VNC server allows multiple security types, then the VNC viewer's default
-security type will be determined by the server's preferred security type.  In
-this case, the user can override the default by passing command-line arguments
-to ''vncviewer''.  If the VNC server prefers a security type that supports
-Standard VNC authentication, then the user can force the use of
-Unix Login/Plain authentication by passing an argument of
-{pcode: -user __user-name__} to ''vncviewer'' when connecting to the TurboVNC
-session.  Similarly, if the VNC server prefers a security type that supports
-Unix Login/Plain authentication, then the user can force the use of Standard
-VNC authentication by passing an argument of ''-nounixlogin'' to ''vncviewer''.
-You can also accomplish the same thing by unchecking "Unix Login" or "Plain" or
-"Standard VNC" in the "Security" tab of the Options dialog or by limiting the
-available security types using the ''SecurityTypes'', ''User'', or
-''NoUnixLogin'' arguments/parameters.
+the system administrator can disable one or more of the security types or
+change their preferred order by editing the TurboVNC security configuration
+file.  See the ''Xvnc'' man page for more details.  Note that only the OTP
+security type is needed when using the
+[[#TurboVNC_Session_Manager][TurboVNC Session Manager]] with its default
+settings.
+
+If the VNC server allows multiple security types, then the TurboVNC Viewer's
+default security type will be determined by the server's preferred security
+type.  In this case, the user can override the default by using the TurboVNC
+Viewer's ''SecurityTypes'', ''User'', and ''NoUnixLogin'' parameters.  If the
+VNC server prefers a security type that supports Standard VNC authentication,
+then the user can force the use of Unix Login/Plain authentication by setting
+the TurboVNC Viewer's ''User'' parameter to __''user-name''__ when connecting
+to the VNC server.  Similarly, if the VNC server prefers a security type that
+supports Unix Login/Plain authentication, then the user can force the use of
+Standard VNC authentication by setting the ''NoUnixLogin'' parameter.  The same
+thing can also be accomplished by unchecking specific security types in the
+"Security" tab of the TurboVNC Viewer Options dialog or by using the
+''SecurityTypes'' parameter to limit the available security types or change
+their preferred order.
 
 If the system administrator has not restricted any of the server security types
-on a system-wide basis, then the user can choose to disable some or all of them
-for a particular TurboVNC session by using the ''-SecurityTypes'' command-line
-argument when starting the session.  See the ''Xvnc'' man page for more
-details.
+on a system-wide basis, then the user can disable some of them, or change their
+preferred order, for a particular TurboVNC session by using the
+''-securitytypes'' command-line argument when starting the session (or by
+setting the ''$securityTypes'' variable in {file: turbovncserver.conf}.)  See
+the ''Xvnc'' man page for more details.
 
 ** Further Reading
 

doc/compatibility.txt

@@ -2,7 +2,7 @@
 {anchor: Compatibility}
 
 In order to realize the full benefits of TurboVNC, it is necessary to use the
-TurboVNC Server and the TurboVNC Viewer in concert.  However, TurboVNC is fully
+TurboVNC Server and the TurboVNC Viewer together.  However, TurboVNC is
 compatible with TigerVNC, TightVNC, RealVNC, and other VNC flavors.  You can
 use the TurboVNC Viewer to connect to a non-TurboVNC server (or vice versa),
 although this will generally result in some decrease in performance, and
@@ -34,50 +34,50 @@ TurboVNC with other VNC flavors.
 		!!! * Experimentally determined by compressing every 10th frame in the
 		SPECviewperf 9 benchmark suite
 
-	TurboVNC, on the other hand, includes extensions to Tight encoding that
-	allow the JPEG quality to be specified on the standard 1-100 scale and
-	allow the JPEG chrominance subsampling to be specified seperately.
-	TigerVNC 1.2 (and later) includes the same extensions on the server side, so
-	the TigerVNC 1.2+ Server will behave like the TurboVNC Server when a
-	TurboVNC viewer is connected to it.
+	TurboVNC, on the other hand, includes extensions to Tight encoding that allow
+	the JPEG quality to be specified on the standard 1-100 scale and that allow
+	the JPEG chrominance subsampling to be specified seperately.  TigerVNC 1.2
+	and later includes the same extensions on the server side, so in this regard,
+	the TigerVNC 1.2+ Server behaves like the TurboVNC Server when a TurboVNC
+	viewer is connected to it.
 	{nl}{nl}
 	When a TurboVNC viewer is connected to a TightVNC or TigerVNC 1.0/1.1 server,
 	setting the JPEG quality to N in the TurboVNC Viewer sets the JPEG quality
-	level to N/10 on the TightVNC or TigerVNC server.  For instance, if you set
+	level to N/10 in the TightVNC or TigerVNC server.  For instance, if you set
 	the JPEG quality to 95 in the TurboVNC Viewer, this would translate to a JPEG
 	quality level of 9, which would set the actual JPEG quality/subsampling to
-	80/2X if connected to a TightVNC server or 100/1X if connected to a TigerVNC
+	80/2X if connected to a TightVNC server and 100/1X if connected to a TigerVNC
 	1.0/1.1 server.
 	{nl}{nl}
 
 	* Changing the JPEG chrominance subsampling option in the TurboVNC Viewer has
 		no effect when connected to a TightVNC or TigerVNC 1.0/1.1 server.
 		{nl}{nl}
 
-	* Normally, the TurboVNC Viewer GUI only allows you to select the compression
-		levels that are useful for TurboVNC servers, but you can specify
-		additional compression levels on the TurboVNC Viewer command line.  You
-		can also pass an argument of ''-compatiblegui'' to the viewer to expose all
-		10 compression levels in the GUI, which is useful when connecting to
+	* Normally, the TurboVNC Viewer Options dialog only allows you to select the
+		compression levels that are useful for the TurboVNC Server, but you can use
+		the TurboVNC Viewer's ''CompressLevel'' parameter to specify additional
+		compression levels.  You can also set the TurboVNC Viewer's
+		''CompatibleGUI'' parameter to expose all 10 compression levels in the
+		TurboVNC Viewer Options dialog, which is useful when connecting to
 		non-TurboVNC servers.  It should be noted, however, that our experiments
 		have shown that compression levels higher than 5 are generally not useful
-		in the TightVNC or TigerVNC Servers.  They increase CPU usage exponentially
-		without providing any significant savings in bandwidth relative to
+		in the TightVNC and TigerVNC Servers.  They increase CPU usage
+		exponentially without significantly reducing network usage relative to
 		Compression Level 5.
 		{nl}{nl}
 
 	* TurboVNC supports an extension to Tight encoding that allows the
-		server to tell the viewer not to use zlib to decompress a particular
+		server to tell the viewer to bypass zlib when decompressing a particular
 		subrectangle.  Zlib introduces a tremendous amount of performance overhead,
 		even when zlib compression level 0 (no compression) is used.  Thus, when a
 		TurboVNC viewer requests Compression Level 0 from the TurboVNC Server,
 		the TurboVNC Server bypasses zlib altogether.  TightVNC and TigerVNC
-		servers do not support this extension, and thus they will still use zlib to
-		"compress" the framebuffer updates even if you request Compression Level 0
-		using the TurboVNC Viewer.
+		servers do not support this extension, so they will still use zlib to
+		"compress" framebuffer updates even if you request Compression Level 0.
 		{nl}{nl}
 
-	* When properly configured, version 1.2 and later (except for versions
+	* When properly configured, version 1.2 and later (except versions
 		1.4.0 - 1.4.2, which contained a performance regression) of the TigerVNC
 		Server can be made to perform similarly to a single-threaded instance of
 		the TurboVNC Server.  However, all other versions of TigerVNC and TightVNC
@@ -89,45 +89,47 @@ TurboVNC with other VNC flavors.
 
 ** TightVNC or TigerVNC Viewers
 
-	* The TurboVNC Server will attempt to emulate the behavior of a TigerVNC
-		server and will translate JPEG quality levels into actual JPEG quality and
-		subsampling, as specified in {ref prefix="Section ": TigerVNC_JPEG_Qual}.
+	* When either a TightVNC or TigerVNC viewer is connected to a TurboVNC
+		session, the TurboVNC Server emulates the behavior of a TigerVNC server,
+		translating JPEG quality levels into actual JPEG quality and subsampling as
+		specified in {ref prefix="Section ": TigerVNC_JPEG_Qual}.
 		{nl}{nl}
 
 	* When either a TightVNC or TigerVNC viewer is connected to a TurboVNC
-		server and JPEG subencoding is disabled, setting the compression level to 0
-		in the viewer will cause the connection to abort with a "bad subencoding
-		value" error.  This is because the TurboVNC Server is attempting to send
-		the framebuffer updates with no zlib compression, and the TightVNC and
-		TigerVNC viewers don't support this.
+		session and JPEG subencoding is disabled, setting the compression level to
+		0 in the viewer will cause the connection to abort with a "bad subencoding
+		value" error.  This is because the TurboVNC Server attempts to send
+		framebuffer updates with no zlib compression, and the TightVNC and TigerVNC
+		viewers don't support that.
 		{nl}{nl}
 		A similar issue occurs when using more than four encoding threads in the
-		server.  Since the Tight encoding type is limited to four zlib streams,
-		any encoding threads beyond the first four cannot use zlib compression.
+		TurboVNC session.  Since the Tight encoding type is limited to four zlib
+		streams, any encoding threads beyond the first four cannot use zlib
+		compression.
 		{nl}{nl}
 
 	* Refer to {ref prefix="Section ": AdvancedCompression} for a description of
-		how the TurboVNC Server responds to requests for Compression Levels 0-9.
+		how the TurboVNC Server implements Compression Levels 0-9.
 		{nl}{nl}
 
 ** RealVNC
 
 The TurboVNC Viewer supports the Hextile, Raw, and ZRLE encoding types, which
-are compatible with RealVNC.  None of these encoding types can be selected from
-the TurboVNC Viewer GUI, but Hextile or ZRLE will be selected automatically
-when connecting to a RealVNC server.  Non-Tight encoding types, such as Hextile
-and Raw, can also be manually selected from the TurboVNC Viewer command line.
-In addition to Hextile, Raw, and ZRLE, the TurboVNC Server also supports the
-RRE, CoRRE, and Zlib legacy encoding types, for compatibility with older VNC
-viewers.
+are compatible with RealVNC.  None of those encoding types can be selected from
+the TurboVNC Viewer Options dialog, but Hextile or ZRLE will be selected
+automatically when connecting to a RealVNC server.  Non-Tight encoding types,
+such as Hextile and Raw, can also be specified using the TurboVNC Viewer's
+''Encoding'' parameter.  In addition to Hextile, Raw, and ZRLE, the TurboVNC
+Server also supports the RRE, CoRRE, and Zlib legacy encoding types, for
+compatibility with older VNC viewers.
 
 All of the non-Tight encoding types have performance drawbacks.  Raw encoding
-requires gigabit in order to achieve decent performance, and it can easily take
-up an entire gigabit connection's worth of bandwidth (it also doesn't perform
-particularly well with the TurboVNC Viewer, because of the need to convert the
-pixels from bytes to ints in Java.)  Hextile uses very small tiles, which
-causes it to incur a large amount of computational overhead.  It compresses too
-poorly to perform well on slow links but uses too much CPU time to perform well
-on fast links.  ZRLE improves upon this, but it is still too computationally
-intense for fast networks.  The ''vncviewer'' man page in the TurboVNC Linux
-packages has some additional information about how Hextile and ZRLE work.
+requires a gigabit or faster network in order to achieve decent performance,
+and it can easily take up all of the bandwidth on a gigabit network.  (It also
+doesn't perform particularly well in the TurboVNC Viewer, because of the need
+to convert pixels from bytes to ints in Java.)  Hextile uses very small tiles,
+which causes it to incur a large amount of computational overhead.  It
+compresses too poorly to perform well on slow networks but uses too much CPU
+time to perform well on fast networks.  ZRLE improves upon this, but it is
+still too computationally intense for fast networks.  The ''vncviewer'' man
+page contains additional information about how Hextile and ZRLE work.