* Advanced Configuration

** Server Settings

The TurboVNC Server is normally configured in the following ways, in increasing
order of precedence:

	#. A system-wide configuration file ({file: /etc/turbovncserver.conf}), which
		can be used to modify the default values of certain ''vncserver'' and
		''Xvnc'' command-line options
	#. A per-user configuration file ({file: ~/.vnc/turbovncserver.conf}), which
		can be used to modify the default values of certain ''vncserver'' and
		''Xvnc'' command-line options
	#. ''vncserver'' and ''Xvnc'' command-line options
	#. ''tvncconfig'', which can be used to modify certain TurboVNC Server
		parameters in a running TurboVNC session
	#. A system-wide security configuration file
		({file: /etc/turbovncserver-security.conf}), which can be used to configure
		certain TurboVNC Server security features as well as restrict the scope of
		TurboVNC Server features that users are allowed to configure

Refer to the TurboVNC man pages for more information:

	#Verb: <<---
	man -M /opt/TurboVNC/man vncserver
	man -M /opt/TurboVNC/man Xvnc
	man -M /opt/TurboVNC/man vncconnect
	man -M /opt/TurboVNC/man vncpasswd
	man -M /opt/TurboVNC/man tvncconfig
	---

{nl}
This section documents rarely-used advanced TurboVNC Server settings that can
be configured using environment variables.

| Environment Variable | {pcode: TVNC_ALRALL = __0 \| 1__} |
| TurboVNC Server Parameter | {pcode: ALRAll = __False \| True__} |
| Summary | Disable/Enable automatic lossless refresh for regions that were \
drawn using X11 functions other than ''X[Shm]PutImage()'' |
| Default Value | Disabled |
#OPT: hiCol=first

	Description :: See {ref prefix="Section ": ALR}

| Environment Variable | {pcode: TVNC_ALRCOPYRECT = __0 \| 1__} |
| Summary | Disable/Enable automatic lossless refresh for regions that were \
drawn using CopyRect |
| Default Value | Enabled |
#OPT: hiCol=first

	Description :: See {ref prefix="Section ": ALR}

| Environment Variable | {pcode: TVNC_COMBINERECT = __{c}__} |
| Summary | Combine framebuffer updates with more than __''{c}''__ rectangles \
into a single rectangle spanning the bounding box of all of the constituent \
rectangles |
| Default Value | ''100'' |
#OPT: hiCol=first

	Description :: Applications can sometimes draw many thousands of points or
	tiny lines using individual X11 calls, and this can cause the VNC server to
	send many thousands of tiny rectangles to the VNC viewer.  The overhead
	associated with this can bog down the viewer, and in extreme cases, the
	number of rectangles may even exceed the maximum number that is allowed in a
	single framebuffer update (65534.)  Thus, if a framebuffer update contains
	more than __''{c}''__ rectangles, the TurboVNC Server will coalesce it into a
	single rectangle that covers all of the rectangles in the update.  For
	applications that generate many tiny rectangles, increasing the value of
	''TVNC_COMBINERECT'' may significantly increase the number of pixels sent to
	the viewer, which will increase network usage.  However, for those same
	applications, lowering the value of ''TVNC_COMBINERECT'' will increase the
	number of rectangles sent to the viewer, which will increase the CPU usage of
	both the server and the viewer.

| Environment Variable | {pcode: TVNC_ICEBLOCKSIZE = __{s}__} |
| Summary | Set the block size for the interframe comparison engine (ICE) to \
__''{s}''__ x __''{s}''__ pixels.  Setting __''{s}''__ to 0 causes the ICE to \
compare full rectangles, as TurboVNC 1.2.x did. |
| Default Value | ''256'' |
#OPT: hiCol=first

	Description :: If interframe comparison is enabled (see
	{ref prefix="Section ": InterframeComparison}), then the TurboVNC Server
	compares each rectangle of each framebuffer update on a block-by-block basis
	and sends only the blocks that have changed.  This prevents large rectangles
	from being re-transmitted if only a few pixels in the rectangle have changed.
	Using smaller block sizes can decrease network usage if only a few pixels
	have changed between updates.  However, using smaller block sizes can also
	interfere with the Tight encoder's ability to efficiently split rectangles
	into subrectangles, thus increasing host CPU usage (and sometimes increasing
	network usage as well, which defeats the purpose of interframe comparison.)
	Setting the block size to 0 causes the ICE to compare full framebuffer update
	rectangles, as TurboVNC 1.2.x did.
	{nl}{nl}
	The default block size of 256x256 was chosen based on extensive low-level
	experiments using the same set of RFB session captures that were used when
	designing the TurboVNC encoder.  For most of those datasets, 256x256 blocks
	produced the lowest network and CPU usage, but actual mileage may vary.
	There were rare cases in which 64x64 blocks or full-rectangle comparison
	produced better network and CPU usage.

| Environment Variable | {pcode: TVNC_ICEDEBUG = __0 \| 1__} |
| Summary | Disable/Enable the ICE debugger |
| Default Value | Disabled |
#OPT: hiCol=first

	Description :: If interframe comparison is enabled (see
	{ref prefix="Section ": InterframeComparison}), then setting this environment
	variable to ''1'' will cause the interframe comparison engine (ICE) to change
	the color of duplicate screen regions without culling them from the
	framebuffer update stream.  This allows you to easily see which applications
	are generating duplicate updates.

| Environment Variable | {pcode: TVNC_MT = __0 \| 1__} |
| Summary | Disable/Enable multithreaded image encoding |
| Default Value | Enabled |
#OPT: hiCol=first

	Description :: See {ref prefix="Section ": Multithreading}

| Environment Variable | {pcode: TVNC_NTHREADS = __{n}__} |
| Summary | Use __''{n}''__ threads (1 <\= __''{n}''__ <\= 8) to perform image \
	encoding |
| Default Value | __''{n}''__ = the number of CPU cores in the system, up to \
	a maximum of 4 |
#OPT: hiCol=first

	Description :: See {ref prefix="Section ": Multithreading}

| Environment Variable | {pcode: TVNC_PROFILE = __0 \| 1__} |
| TurboVNC Server Parameter | {pcode: Profile = __False \| True__} |
| Summary | Disable/enable profiling output |
| Default Value | Disabled |
#OPT: hiCol=first

	Description :: If profiling output is enabled, then the TurboVNC Server will
	continuously benchmark itself and periodically print the throughput of
	various stages in its image pipeline to the TurboVNC session log.

** Viewer Settings

The TurboVNC Viewer is normally configured in the following ways, in increasing
order of precedence:

	#. A per-user configuration file ({file: ~/.vnc/default.turbovnc}), which can
		be used to modify the default values of TurboVNC Viewer parameters
	#. TurboVNC Viewer parameters, which can be set on the command line or in a
		connection info file

Run

	#Verb: <<---
	/opt/TurboVNC/bin/vncviewer -?
	---

on Linux/Un*x and Mac systems or

	#Verb: <<---
	c:\Program Files\TurboVNC\vncviewer.bat -?
	---

on Windows systems to display a full list of supported command-line
options/parameters and their descriptions.

{nl}
This section documents rarely-used advanced TurboVNC Viewer settings that can
be configured using environment variables or Java system properties.

Java system properties can be set using the ''JAVA_TOOL_OPTIONS'' environment
variable.  For instance, on Linux/Un*x and Mac systems, you could execute:

	#Verb: <<---
	JAVA_TOOL_OPTIONS=-Dturbovnc.sessmgr=0 /opt/TurboVNC/bin/vncviewer
	---

to start the TurboVNC Viewer with the TurboVNC Session Manager disabled.

| Java System Property | ''turbovnc.ciphersuites'' |
| Summary | Available cipher suites for TLS encryption |
| Default Value | System-dependent |
#OPT: hiCol=first

	Description :: If the logging level is 100 or higher, then the TurboVNC
	Viewer will print a list of cipher suites that are available for use with the
	current TLS encryption method.  (This occurs during RFB authentication if one
	of the TLS* or X509* security types is selected.)  You can then use this
	property to further restrict the list of available cipher suites or change
	their preferred order.

| Java System Property | {pcode: turbovnc.primary = __0 \| 1__} |
| Summary | Disable/enable the use of the X11 PRIMARY clipboard selection |
| Default Value | Enabled |
#OPT: hiCol=first

	Description :: X11 has two ways of copying/pasting text.  When text is
	selected in most X11 applications, it is copied to the PRIMARY
	selection, and it can be pasted by pressing the middle mouse button.  When
	text is explicitly copied using a "Copy" menu option or a hotkey (such as
	CTRL-C), it is copied to the CLIPBOARD selection, and it can only be pasted
	using a "Paste" menu option or a hotkey (such as CTRL-V.)  Normally, on X11
	platforms, the TurboVNC Viewer transfers the PRIMARY selection from client to
	server, and when receiving a clipboard update from the server, it sets both
	the PRIMARY and CLIPBOARD selections with the server's clipboard contents.
	Disabling this property causes only the CLIPBOARD selection to be transferred
	from client to server.  (In other words, the clipboard will not be
	transferred unless you explicitly copy something using a menu option or a
	hotkey.)  Also, if this property is disabled, then clipboard changes from the
	server will only affect the client's CLIPBOARD selection.  (In other words,
	you will have to use a menu option or a hotkey to paste the server's
	clipboard contents.)

| Environment Variable | {pcode: TVNC_PROFILE = __0 \| 1__} |
| Summary | Disable/enable profiling output |
| Default Value | Disabled |
#OPT: hiCol=first

	Description :: If profiling output is enabled, then the TurboVNC Viewer will
	continuously benchmark itself and periodically print the throughput of
	various stages in its image pipeline to the console.  The TurboVNC Viewer's
	''ProfileInterval'' parmeter can be used to specify the time period over
	which performance statistics are averaged and reported.

{anchor: TVNC_SERVERARGS}
| Environment Variable | ''TVNC_SERVERARGS'' |
| Java System Property | ''turbovnc.serverargs'' |
| Summary | Additional arguments that the TurboVNC Session Manager will pass \
	to ''vncserver'' when starting a new TurboVNC session \
|
#OPT: hiCol=first

	Description :: The TurboVNC Session Manager will pass these command-line
	arguments to the ''vncserver'' script when starting a new TurboVNC session on
	the TurboVNC host.  This can be used, for instance, to enable
	[[#ALR][automatic lossless refresh]].

{anchor: TVNC_SERVERDIR}
| Environment Variable | ''TVNC_SERVERDIR'' |
| Java System Property | ''turbovnc.serverdir'' |
| Summary | The directory in which the TurboVNC Server is installed on the \
	TurboVNC host |
| Default Value | ''/opt/TurboVNC'' |
#OPT: hiCol=first

	Description :: The TurboVNC Session Manager will execute ''bin/vncserver''
	and ''bin/vncpasswd'' from this directory on the TurboVNC host.

| Java System Property | {pcode: turbovnc.sessmgr = __0 \| 1__} |
| Summary | Disable/enable the TurboVNC Session Manager |
| Default Value | Enabled |
#OPT: hiCol=first

	Description :: Disabling this property will completely disable the TurboVNC
	Session Manager.

| Environment Variable | {pcode: TVNC_SINGLESCREEN = __0 \| 1__} |
| Java System Property | {pcode: turbovnc.singlescreen = __0 \| 1__} |
| Summary | Disable/enable forcing a single-screen layout when using \
	automatic desktop resizing |
| Default Value | Disabled |
#OPT: hiCol=first

	Description :: If automatic desktop resizing and multi-screen spanning are
	enabled, then the TurboVNC Viewer normally requests a screen layout from the
	server that fits within the viewer window without using scrollbars and that
	aligns the server's screen boundaries with the client's when the viewer
	window is in its default position.  Setting this environment variable or
	property to ''1'' restores the automatic desktop resizing behavior of version
	2.1.x and prior of the TurboVNC Viewer, requesting a single-screen layout
	from the server even if it supports multi-screen layouts.

| Java System Property | ''turbovnc.sshauth'' |
| Summary | Preferred authentication methods for the built-in SSH client |
| Default Value | ''publickey,keyboard-interactive,password'' |
#OPT: hiCol=first

	Description :: This property can be used to enable or disable particular SSH
	authentication methods, as well as to specify their preferred order.  The
	same thing can be accomplished using the ''PreferredAuthentications''
	directive in the OpenSSH config file.

| Java System Property | {pcode: turbovnc.sshbannerdlg = __0 \| 1__} |
| Summary | Display the banner message from the SSH server in a dialog box |
| Default Value | Disabled |
#OPT: hiCol=first

	Description :: The default behavior of the TurboVNC Viewer is to display the
	banner message from the SSH server on the command line.  Enabling this
	property causes the viewer to display the banner message in a dialog box
	instead.

| Environment Variable | ''VNC_VIA_CMD'', ''VNC_TUNNEL_CMD'' |
| Java System Property | ''turbovnc.via'', ''turbovnc.tunnel'' |
| Summary | SSH command-line templates for use with the ''Via'' and \
	''Tunnel'' parameters (respectively) |
| Default Value | See below |
#OPT: hiCol=first

	Description :: When the ''Via'' parameter is used along with the ''ExtSSH''
	parameter, the TurboVNC Viewer reads the ''VNC_VIA_CMD'' environment variable
	or the ''turbovnc.via'' property, expands patterns beginning with the "%"
	character, and uses the resulting command line to establish the secure tunnel
	to the VNC gateway.  If ''VNC_VIA_CMD'' and ''turbovnc.via'' are not set,
	then this command-line template defaults to one of the following values:
	{nl}{nl}
	|| Connection Type || Default ''VNC_VIA_CMD''/''turbovnc.via'' Value ||
	| TCP port | ''%S -f -L %L:%H:%R %G sleep 20'' |
	| Unix domain socket | ''%S -J %G -- %H exec socat stdio unix-connect:%R'' |
	{nl} \
	When the ''Tunnel'' parameter is used along with the ''ExtSSH'' parameter,
	the TurboVNC Viewer reads the ''VNC_TUNNEL_CMD'' environment variable or the
	''turbovnc.tunnel'' property, expands patterns beginning with the "%"
	character, and uses the resulting command line to establish the secure tunnel
	to the VNC host.  If ''VNC_TUNNEL_CMD'' and ''turbovnc.tunnel'' are not set,
	then this command-line template defaults to one of the following values:
	{nl}{nl}
	|| Connection Type || Default ''VNC_TUNNEL_CMD''/''turbovnc.tunnel'' Value ||
	| TCP port | ''%S -f -L %L:localhost:%R %H sleep 20'' |
	| Unix domain socket | ''%S -- %H exec socat stdio unix-connect:%R'' |
	{nl} \
	The following patterns are recognized in the ''VNC_VIA_CMD'' and
	''VNC_TUNNEL_CMD'' environment variables and their corresponding properties.
	Note that ''%H'' and ''%R'' must be present in the command-line template, and
	''%G'' must also be present if using the ''Via'' parameter.  If the VNC
	server is listening on a TCP port, then ''%L'' must also be present.  If the
	VNC server is listening on a Unix domain socket, then ''%L'' can optionally
	be used to forward a local TCP port to the remote Unix domain socket (for
	instance, by setting ''VNC_TUNNEL_CMD'' to ''%S -f -L %L:%R %H sleep 20''.)
	If ''%L'' is not present, then the TurboVNC Viewer expects the SSH command
	line to connect standard input and standard output to the remote Unix domain
	socket.
	{nl}{nl}
	| ''%%'' | A literal "%" |
	| ''%G'' | gateway host name or IP address |
	| ''%H'' | remote VNC host name or IP address (if using the ''Via'' \
		parameter, then this is specified from the point of view of the gateway) |
	| ''%L'' | local TCP port number |
	| ''%R'' | remote TCP port number or the escaped name of a Unix domain \
		socket on the VNC host |
	| ''%S'' | the external SSH client command, which can be specified using \
		the TurboVNC Viewer's ''ExtSSHCommand'' parameter |
