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.