* 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 interframe comparison to \
__''{s}''__ x __''{s}''__ pixels.  Setting __''{s}''__ to 0 causes the \
TurboVNC Server 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 TurboVNC Server 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 interframe comparison 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 TurboVNC Server 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}''__ <\= 4) 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 list of command-line options and commonly-used
parameters and their descriptions.  Replace ''-?'' with ''-??'' to display a
list of advanced parameters and their descriptions.  For convenience, those
lists are duplicated below:

	- [[viewer_parameters.txt][TurboVNC Viewer command-line options and commonly-used parameters]!*]
	- [[viewer_advanced_parameters.txt][TurboVNC Viewer advanced parameters]!*]

{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.  The
Java system properties listed below can also be specified in
{file: ~/.vnc/default.turbovnc}.

| Java System Property | {pcode: turbovnc.fshidedock = __0 \| 1__} |
| Summary | Always show/always hide the menu bar and dock in full-screen mode |
| Platforms | Mac |
| Default Value | Hide the menu bar and dock in full-screen mode if bump \
	scrolling is enabled |
#OPT: hiCol=first

	Description :: By default, the Mac TurboVNC Viewer hides the menu bar and
	dock in full-screen mode if bump scrolling is enabled.  Setting this property
	to ''0'' or ''1'' causes the viewer to always show or always hide the menu
	bar and dock in full-screen mode, irrespective of bump scrolling.

| 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.)

| 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 | {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.
