
TurboVNC Viewer v3.3.1 (build 20251219) [aarch64]
Copyright (C) 1999-2026 The VirtualGL Project and many others (see README.md)
Visit http://www.TurboVNC.org for more information on TurboVNC

USAGE
-----

vncviewer [options/parameters] [user@]host [options/parameters]

Connect to the specified TurboVNC host using the TurboVNC Session Manager,
which uses the TurboVNC Viewer's built-in SSH client to remotely start a new
TurboVNC session or to list all sessions running under your user account on the
host, allowing you to choose a session to which to connect.  The TurboVNC
Session Manager requires the TurboVNC Server (v3.0 or later), and by default,
it expects the TurboVNC Server to be installed under /opt/TurboVNC on the host.
Refer to the TurboVNC User's Guide for more details.

vncviewer [options/parameters] host:displayNum [options/parameters]
vncviewer [options/parameters] host::port [options/parameters]
vncviewer [options/parameters] host::uds_path [options/parameters]

Connect directly to the VNC server that is listening on the specified VNC
display number, TCP port, or Unix domain socket path on the specified host.
This mode of operation does not require the TurboVNC Server.

Multiple VNC servers and associated options/parameters can be specified by
separating the command-line arguments for each server with --.  The TurboVNC
Viewer will connect to the VNC servers serially and in the specified order.

vncviewer [options/parameters] -listen [port] [options/parameters]

Start the TurboVNC Viewer in "listen mode."  Refer to the description of the
Listen parameter below.

Options:
  -loglevel <level>
      Set logging level to <level>
      0 = errors only
      10 = status messages
      30 = informational messages (default)
      100 = debugging messages
      110 = SSH debugging messages
      150 = extended input device debugging messages

  [-config] <connection_info_file>
      Read connection information from <connection_info_file>.  A connection
      info file has an extension of .turbovnc, and each line of the file
      contains a TurboVNC Viewer parameter name and value separated by an
      equals sign (=).  (Any whitespace before the value is ignored.)  If the
      connection info file has an extension of .vnc, then it is assumed to be a
      connection info file from TurboVNC 2.2.x and prior, which used a format
      based on the TightVNC connection info file format.  Connection info files
      will, when opened on Windows or macOS or dragged & dropped onto the
      TurboVNC Viewer icon, launch the TurboVNC Viewer and initiate a new
      connection.  Parameter values specified in a connection info file
      override parameter values specified on the command line prior to the
      connection info file but not parameter values specified on the command
      line after the connection info file.

  -??
      List rarely-used advanced parameters and their descriptions.

Specifying boolean parameters:
  On:   -<param> or --<param> or <param>=1 or -<param>=1 or --<param>=1
  Off:  -no<param> or --no<param> or <param>=0 or -<param>=0 or --<param>=0
Parameters that take a value can be specified as:
  -<param> <value> or --<param> <value> or
  <param>=<value> or -<param>=<value> or --<param>=<value>
Parameter names and values are case-insensitive (except for hostnames,
unencrypted passwords/passphrases, filenames, SSH keys, and usernames.)

Default values for all parameters can be specified in
  /Users/drc/.vnc/default.turbovnc
using the connection info file syntax described above.

The parameters are:

CONNECTION PARAMETERS
---------------------

--> Listen
    Values: 0, 1 (default = 0)

    Start the viewer in "listen mode."  The viewer will listen on port 5500 (or
    on the port specified by the Port parameter) for reverse connections from a
    VNC server.  To connect a TurboVNC session to a listening viewer, use the
    vncconnect program on the TurboVNC host.

--> Port
    Values: 0-65535

    The TCP port number on which the VNC server is listening.  For Un*x VNC
    servers, this is typically 5900 + the X display number of the VNC session
    (example: 5901 if connecting to display :1.)  For Windows and Mac VNC
    servers, this is typically 5900.

    If listen mode is enabled, this parameter specifies the TCP port on which
    the viewer will listen for reverse connections from a VNC server.  (default
    = 5500)

--> RecvClipboard
    Values: 0, 1 (default = 1)

    Synchronize the local clipboard with the TurboVNC session's clipboard when
    the latter changes.

--> SendClipboard
    Values: 0, 1 (default = 1)

    Synchronize the TurboVNC session's clipboard with the local clipboard when
    the latter changes.

--> Server

    The VNC server to which to connect.  This can be specified in the format
    {host}[:{display_number}], {host}::{port}, or {host}::{uds_path}, where
    {host} is the host name or IP address of the machine on which the VNC
    server is running (the "VNC host"), {display_number} is an optional X
    display number, {port} is a TCP port, and {uds_path} is the path (which
    must begin with / or ~) to a Unix domain socket on the VNC host.  If no
    port, Unix domain socket path, or display number is specified, then the
    viewer will enable the TurboVNC Session Manager, which allows you to
    remotely start a new TurboVNC session or to choose an existing session to
    which to connect.

    When using the Tunnel parameter or the Jump parameter or the TurboVNC
    Session Manager, an SSH username (default = local username) can be
    specified by prefixing the VNC host with the username followed by @.

    In Unix domain socket paths, ~ is expanded to the user's home directory on
    the VNC host, %h is expanded to the VNC host name (from the point of view
    of the VNC host), %i is expanded to the numeric user ID on the VNC host,
    and %u is expanded to the username on the VNC host.  When listening on a
    Unix domain socket, the TurboVNC Server chooses a Unix domain socket path
    of ~/.vnc/%h_{display_number}.uds by default.

--> Shared
    Values: 0, 1 (default = 1)

    Request a shared VNC session.  When the session is shared, other users can
    connect to the session (assuming they have the correct authentication
    credentials) and collaborate with the user who started the session.  If
    this parameter is disabled and the TurboVNC session is using default
    settings, then you will only be able to connect to the session if no one
    else is already connected.

INPUT PARAMETERS
----------------

--> FSAltEnter
    Values: 0, 1 (default = 0)

    Toggle full-screen mode when Alt-Enter is pressed.

--> MenuKey
    Values: F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12, Pause, Print,
    ScrollLock, Escape, Insert, Delete, Home, PageUp, PageDown (default = F8)

    The key used to display the popup menu

--> ReverseScroll
    Values: 0, 1 (default = 0)

    Reverse the direction of mouse scroll wheel events that are sent to the VNC
    server.  This is useful when connecting from clients that have "natural
    scrolling" enabled.

--> ViewOnly
    Values: 0, 1 (default = 0)

    Ignore all keyboard and mouse events in the viewer window and do not pass
    those events to the VNC server.

DISPLAY PARAMETERS
------------------

--> AcceptBell
    Values: 0, 1 (default = 1)

    Produce a system beep when a "bell" event is received from the VNC server.

--> CompatibleGUI
    Values: 0, 1 (default = 0)

    Expose all compression levels (0-9) in the TurboVNC Viewer Options dialog
    (useful when connecting to non-TurboVNC servers.)  This parameter is
    effectively set when using any encoding type other than Tight or when
    selecting a compression level that is not useful for TurboVNC servers.

--> CursorShape
    Values: 0, 1 (default = 1)

    Normally, the TurboVNC Server and compatible VNC servers send only changes
    to the remote mouse cursor's shape and position.  This results in the best
    mouse responsiveness.  Disabling this parameter causes the server to
    instead render the mouse cursor and send it to the viewer as an image every
    time the cursor moves or changes shape.  Using a remotely rendered cursor
    can increase network "chatter" between host and client significantly, which
    may cause performance problems on slow networks.

--> DesktopSize
    Values: WxH, W0xH0+X0+Y0[,W1xH1+X1+Y1,...], Auto, or Server (default =
    Auto)

    If the VNC server supports remote desktop resizing, then attempt to resize
    the remote desktop to the specified size (example: 1920x1200) or
    reconfigure the server's virtual screens with a specified layout (example:
    1920x1200+0+0,1920x1200+1920+0).  Setting this parameter to "Auto" causes
    the remote desktop to be resized to fit in the viewer window without using
    scrollbars, and it causes the server's virtual screens to be reconfigured
    such that their screen boundaries align with the client's screen boundaries
    when the viewer window is in its default position.  Setting this parameter
    to "Server" or "0" disables remote desktop resizing and uses the desktop
    size and screen configuration set by the server.

--> FullScreen
    Values: 0, 1 (default = 0)

    Start the viewer in full-screen mode.

--> Scale
    Values: 1-1000, Auto, or FixedRatio (default = 100)

    Reduce or enlarge the remote desktop image.  The value is interpreted as a
    scaling factor in percent.  The default value of 100% corresponds to the
    original remote desktop size.  Values below 100 reduce the image size,
    whereas values above 100 enlarge the image proportionally.  If this
    parameter is set to "Auto", then automatic scaling is performed.  Automatic
    scaling reduces or enlarges the remote desktop image such that the entire
    image will fit in the viewer window without using scrollbars.  If this
    parameter is set to "FixedRatio", then automatic scaling is performed, but
    the original aspect ratio is preserved.  Enabling automatic scaling
    disables automatic desktop resizing.

--> Span
    Values: Primary, All, Auto (default = Auto)

    Multi-screen spanning mode

    Values:
    "Primary" = The viewer window should span only the primary monitor.
    "All" = The viewer window should span all monitors.
    "Auto" = The viewer window should span all monitors only if the window
    cannot fit on the primary monitor.

    When using automatic desktop resizing, "Auto" has the same effect as
    "Primary" when in windowed mode and the same effect as "All" when in
    full-screen mode.  This parameter has no effect on macOS unless "Displays
    have separate Spaces" is disabled in the system settings.

--> Toolbar
    Values: 0, 1 (default = 1)

    Show the toolbar by default.

ENCODING PARAMETERS
-------------------

--> CompressLevel
    Values: 0-9 (default = 1)

    When Tight encoding is used, the compression level specifies the amount of
    zlib compression to apply to subrectangles encoded using the indexed color,
    mono, and raw subencoding types.  If the JPEG subencoding type is enabled,
    then the compression level also defines the "palette threshold", or the
    minimum number of unique colors that a subrectangle must have before it is
    encoded using JPEG.  Higher compression levels have higher palette
    thresholds and thus favor the use of indexed color subencoding, whereas
    lower compression levels favor the use of JPEG.

    Compression Level 1 is usually the default when JPEG is enabled, because
    extensive experimentation has revealed little or no benefit to using higher
    compression levels with most 3D and video workloads.  However, v1.1 and
    later of the TurboVNC Server also supports Compression Level 2 when JPEG is
    enabled.  Compression Level 2 can reduce the network usage of certain types
    of low-color workloads by about 20-40% (with a commensurate increase in CPU
    usage.)

    In v1.2 or later of the TurboVNC Server, compression levels 5-7 map to
    compression levels 0-2, but they also enable interframe comparison in the
    server.  Interframe comparison maintains a copy of the remote framebuffer
    for each connected viewer and compares each framebuffer update with the
    copy to ensure that redundant updates are not sent to the viewer.  This
    prevents unnecessary network traffic if an ill-behaved application draws
    the same thing over and over again, but interframe comparison also causes
    the TurboVNC Server to use more CPU time and much more memory.

--> Encoding
    Values: Tight, ZRLE, Hextile, Raw (default = Tight)

    Preferred RFB encoding type to use.  If the server does not support the
    preferred encoding type, then the next best one will be chosen.  There
    should be no reason to use an encoding type other than Tight when
    connecting to a TurboVNC session, but this parameter can be useful when
    connecting to other types of VNC servers, such as RealVNC.

--> JPEG
    Values: 0, 1 (default = 1)

    Enable the JPEG subencoding type when using Tight encoding.  This causes
    the Tight encoder to use JPEG compression for subrectangles that have a
    high number of unique colors and indexed color subencoding for
    subrectangles that have a low number of unique colors.  If this parameter
    is disabled, then the Tight encoder will select between indexed color or
    raw subencoding, depending on the size of the subrectangle and its color
    count.

--> Quality
    Values: 1-100 (default = 95)

    JPEG quality to use when compressing JPEG images with the Tight+JPEG
    encoding methods.  Lower quality values produce grainier JPEG images with
    more noticeable compression artifacts, but lower quality values also use
    less network bandwidth and CPU time.  The default value of 95 should be
    perceptually lossless (that is, any image compression artifacts it produces
    should be imperceptible to the human eye under most viewing conditions.)

--> Subsampling
    Values: 1X, 2X, 4X, Gray (default = 1X)

    Chrominance subsampling level to use when compressing JPEG images with the
    Tight+JPEG encoding methods

    When compressing an image using JPEG, the RGB pixels are first converted to
    the YCbCr colorspace, a colorspace in which each pixel is represented as a
    brightness (Y, or "luminance") value and a pair of color (Cb and Cr, or
    "chrominance") values.  After this colorspace conversion, chrominance
    subsampling can be used to discard some of the chrominance components in
    order to save bandwidth.

    Values:
    "1X" = Retain the chrominance components for all pixels (best image quality
    but highest network and CPU usage.)
    "2X" = Retain the chrominance components for every other pixel.
    "4X" = Retain the chrominance components for every fourth pixel (typically
    implemented as 2X subsampling in both X and Y directions.)
    "Grayscale" = Discard all chrominance components, leaving only luminance.

    2X and 4X subsampling typically produce noticeable aliasing of lines and
    other sharp features, but with photographic or other "smooth" image
    content, it may be difficult to detect any difference between 1X, 2X, and
    4X.

--> Samp

    Alias for Subsampling

SECURITY AND AUTHENTICATION PARAMETERS
--------------------------------------

--> Jump

    Tunnel the VNC connection through the specified SSH server ("jump host") as
    well as through the SSH server running on the VNC host.  The jump host can
    be specified in the format [{ssh_user}@]{jump_host}[:{ssh_port}], where
    {ssh_user} is the SSH username on the jump host (default = local username)
    and {ssh_port} is the TCP port on which the jump host's SSH server is
    listening (default = the default value of the SSHPort parameter.)  This
    parameter is functionally equivalent to the ProxyJump OpenSSH configuration
    keyword.  When using this parameter, the VNC host should be specified from
    the point of view of the jump host.

    For Unix domain socket connections, this parameter is equivalent to the Via
    parameter.  For TCP connections, this parameter creates a multi-level SSH
    tunnel to the VNC host, which ensures that the VNC connection is encrypted
    on the server-area network and eliminates the need to open RFB ports in the
    VNC host's firewall.  The Via parameter, by comparison, creates an SSH
    tunnel to the gateway host and forwards the RFB/TCP connection directly to
    the VNC host from the gateway host.

    When using the built-in SSH client, this parameter and the ProxyJump
    OpenSSH configuration keyword do not allow multiple comma-separated SSH
    hops to be specified.

--> J

    Alias for Jump (for compatibility with OpenSSH)

--> LocalUsernameLC
    Values: 0, 1 (default = 0)

    When the SendLocalUsername parameter is set, or when using SSH tunneling
    without a specified SSH username, convert the local username to lowercase
    before using it for authentication.  This may be useful with Windows
    clients, since Windows allows mixed-case usernames but Un*x and Mac systems
    generally don't.

--> NoUnixLogin
    Values: 0, 1 (default = 0)

    Disable Unix Login authentication when connecting to TightVNC-compatible
    servers and Plain authentication when connecting to VeNCrypt-compatible
    servers.  Setting this parameter effectively removes "Plain" (and its
    encrypted derivatives) and "UnixLogin" from the value of the SecurityTypes
    parameter.  This is useful if the server is configured to prefer a security
    type that supports Unix Login/Plain authentication and you want to override
    that preference for a particular connection (for instance, to use a
    one-time password.)

--> SecurityTypes
    (default =
    X509Plain,X509Vnc,X509None,TLSPlain,TLSVnc,TLSNone,VNC,Plain,UnixLogin,None)

    A comma-separated list of the security types that can be used if the server
    supports them.  "VNC" and "None" are the standard VNC password and
    no-password authentication schemes supported by all VNC servers.  The seven
    supported VeNCrypt security types ("Plain", "TLSNone", "TLSVnc",
    "TLSPlain", "X509None", "X509Vnc", and "X509Plain") are combinations of
    three encryption methods (None, Anonymous TLS, and TLS with X.509
    certificates) and three authentication schemes (None, Standard VNC, and
    Plain.)  The "UnixLogin" security type enables user/password authentication
    using the TightVNC security extensions rather than VeNCrypt.  "Plain" and
    "UnixLogin" authenticate using a plain-text username and password, so it is
    strongly recommended that those types be used only with TLS encryption or
    SSH tunneling.  The order of this list does not matter, since the server's
    preferred order is always used.

    When using the TurboVNC Session Manager, this parameter is effectively set
    to "VNC" unless the SessMgrAuto parameter is disabled.

--> SendLocalUsername
    Values: 0, 1 (default = 0)

    When using user/password authentication schemes (Unix Login, Plain),
    authenticate using the local username rather than prompt for a username. 
    As with the User parameter, setting this parameter effectively disables any
    authentication schemes that don't require a username.

--> SSHConfig
    (default = /Users/drc/.ssh/config)

    Path to an OpenSSH configuration file to use with the built-in SSH client. 
    If specified on the command line or in a connection info file, TurboVNC
    Viewer parameters take precedence over the OpenSSH configuration file.

--> F

    Alias for SSHConfig (for compatibility with OpenSSH)

--> SSHKey

    When using the built-in SSH client with the publickey SSH authentication
    method, this parameter specifies the text of an SSH private key to use when
    authenticating with the SSH server.  You can use \n within the string to
    specify a new line.

--> SSHKeyFile

    When using the built-in SSH client with the publickey SSH authentication
    method, this parameter specifies a file that contains an SSH private key
    (or keys) to use when authenticating with the SSH server.  This parameter
    and the SSHKey parameter behave like the OpenSSH -i option and IdentityFile
    configuration keyword.  The SSH client will attempt to use the following
    private keys, in order, when authenticating with the SSH server:

    1. Any key specified with this parameter or the SSHKey parameter, if the
    key is already provided by the SSH agent (ssh-agent or Pageant) or a valid
    passphrase is supplied for the key using the SSHKeyPass parameter
    2. Any key specified with the IdentityFile OpenSSH configuration keyword,
    if the key is already provided by the SSH agent
    3. Any other keys provided by the SSH agent, in the order provided
    4. Any key specified with this parameter, the SSHKey parameter, or the
    IdentityFile OpenSSH configuration keyword, if a valid passphrase is not
    supplied for the key
    5. /Users/drc/.ssh/id_rsa, /Users/drc/.ssh/id_ecdsa,
    /Users/drc/.ssh/id_ed25519, and /Users/drc/.ssh/id_dsa (in that order), if
    this parameter, the SSHKey parameter, and the IdentityFile OpenSSH
    configuration keyword are not specified

--> i

    Alias for SSHKeyFile (for compatibility with OpenSSH)

--> SSHKeyPass

    When using the built-in SSH client with the publickey SSH authentication
    method, this parameter specifies the passphrase for the SSH key(s)
    specified with the SSHKey or SSHKeyFile parameter.

--> SSHPort
    Values: 0-65535 (default = 22)

    When using the built-in SSH client, this parameter specifies the TCP port
    on which the VNC host's or gateway host's SSH server is listening.  This
    parameter does not apply to jump hosts.

--> p

    Alias for SSHPort (for compatibility with OpenSSH)

--> Tunnel
    Values: 0, 1 (default = 0)

    Tunnel the VNC connection through the SSH server running on the VNC host.

    When using the TurboVNC Session Manager, this parameter is effectively set
    unless the SessMgrAuto parameter is disabled or the Jump parameter is
    specified.

    This parameter is effectively set if the Server parameter specifies a Unix
    domain socket connection to a remote host.

--> User

    The username to use for Unix Login authentication (TightVNC-compatible
    servers) or Plain authentication (VeNCrypt-compatible servers.)  Specifying
    this parameter effectively removes any types from the value of the
    SecurityTypes parameter except for "Plain" (and its encrypted derivatives)
    and "UnixLogin", thus allowing only authentication schemes that require a
    username.

--> X509CA
    (default = /Users/drc/.vnc/x509_ca.pem)

    X.509 Certificate Authority certificate to use with the X509* security
    types.  This is used to check the validity of the server's X.509
    certificate.

--> X509CRL
    (default = /Users/drc/.vnc/x509_crl.pem)

    X.509 Certificate Revocation List to use with the X509* security types.
    This is used to check the validity of the server's X.509 certificate.

