KasmVNC/unix/vncserver.man

.TH vncserver 1 "" "KasmVNC" "Virtual Network Computing"
.SH NAME
vncserver \- start or stop a VNC server
.SH SYNOPSIS
.B vncserver
.RI [: display# ]
.RB [ \-geometry
.IR width x height ]
.RB [ \-depth
.IR depth ]
.RB [ \-pixelformat
.IR format ]
.RB [ \-fp
.IR font-path ]
.RB [ \-fg ]
.RB [ \-autokill ]
.RB [ \-noxstartup ]
.RB [ \-xstartup
.IR script ]
.RI [ Xvnc-options... ]
.br
.BI "vncserver \-kill :" display#
.br
.BI "vncserver \-list"
.SH DESCRIPTION
.B vncserver
is used to start a VNC (Virtual Network Computing) desktop.
.B vncserver
is used to launch a VNC desktop session. vncserver interprets the yaml based
server level and user level configurations and combines them to execute
Xvnc.

.B vncserver
can be run with no options at all. In this case it will choose the first
available display number (usually :1), start Xvnc with that display number,
and start the default window manager in the Xvnc session.  You can also
specify the display number, in which case vncserver will attempt to start
Xvnc with that display number and exit if the display number is not
available.  For example:

.RS
vncserver :13
.RE

vncserver can detect desktop environments and prompt the user to select one to
start with the session. The user can also manually edit the file
$HOME/.vnc/xstartup to customize what commands should be run on startup of a
new session.

.SH OPTIONS
You can get a list of options by passing \fB\-h\fP as an option to vncserver.
In addition to the options listed below, any unrecognised options will be
passed to Xvnc - see the Xvnc man page, or "Xvnc \-help", for details.

.TP
.B \-select-de [\fIde_name\fP]
Select Desktop Enviromnent to run. Cinnamon, Mate, LXDE, LXQT, KDE, Gnome, XFCE,
are supported.

To trigger a text UI prompt to select a Desktop Enviromnent, run \fBvncserver\fP
for the first time, or pass this option without arguments. To bypass the prompt,
pass this option with the Desktop Enviromnent argument.
Warning: $HOME/.vnc/xstartup will be overwritten.

To run a custom setup (not one of the supported Desktop Enviromnents), create
$HOME/.vnc/xstartup executable and specify \fB\-select-de manual\fP to signify you
don't want its contents to be auto-generated.

.TP
.B \-geometry \fIwidth\fPx\fIheight\fP
Specify the size of the VNC desktop to be created. Default is 1024x768.
.
.TP
.B \-depth \fIdepth\fP
Specify the pixel depth (in bits) of the VNC desktop to be created. Default is
24.  Other possible values are 8, 15 and 16 - anything else is likely to cause
strange behaviour by applications.
.
.TP
.B \-pixelformat \fIformat\fP
Specify pixel format for Xvnc to use (BGRnnn or RGBnnn).  The default for
depth 8 is BGR233 (meaning the most significant two bits represent blue, the
next three green, and the least significant three represent red), the default
for depth 16 is RGB565, and the default for depth 24 is RGB888.
.
.TP
.B \-cc 3
As an alternative to the default TrueColor visual, this allows you to run an
Xvnc server with a PseudoColor visual (i.e. one which uses a color map or
palette), which can be useful for running some old X applications which only
work on such a display.  Values other than 3 (PseudoColor) and 4 (TrueColor)
for the \-cc option may result in strange behaviour, and PseudoColor desktops
must have an 8-bit depth.
.
.TP
.B \-kill :\fIdisplay#\fP
This kills a VNC desktop previously started with vncserver.  It does this by
killing the Xvnc process, whose process ID is stored in the file
"$HOME/.vnc/\fIhost\fP:\fIdisplay#\fP.pid".  The
.B \-kill
option ignores anything preceding the first colon (":") in the display
argument.  Thus, you can invoke "vncserver \-kill $DISPLAY", for example at the
end of your xstartup file after a particular application exits.
.
.TP
.B \-fp \fIfont-path\fP
If the vncserver script detects that the X Font Server (XFS) is running, it
will attempt to start Xvnc and configure Xvnc to use XFS for font handling.
Otherwise, if XFS is not running, the vncserver script will attempt to start
Xvnc and allow Xvnc to use its own preferred method of font handling (which may
be a hard-coded font path or, on more recent systems, a font catalog.)  In
any case, if Xvnc fails to start, the vncserver script will then attempt to
determine an appropriate X font path for this system and start Xvnc using
that font path.

The
.B \-fp
argument allows you to override the above fallback logic and specify a font
path for Xvnc to use.
.
.TP
.B \-fg
Runs Xvnc as a foreground process.  This has two effects: (1) The VNC server
can be aborted with CTRL-C, and (2) the VNC server will exit as soon as the
user logs out of the window manager in the VNC session.  This may be necessary
when launching KasmVNC from within certain grid computing environments.
.
.TP
.B \-autokill
Automatically kill Xvnc whenever the xstartup script exits.  In most cases,
this has the effect of terminating Xvnc when the user logs out of the window
manager.
.
.TP
.B \-noxstartup
Do not run the %HOME/.vnc/xstartup script after launching Xvnc.  This
option allows you to manually start a window manager in your KasmVNC session.
.
.TP
.B \-xstartup \fIscript\fP
Run a custom startup script, instead of %HOME/.vnc/xstartup, after launching
Xvnc. This is useful to run full-screen applications.
.
.TP
.B \-list
Lists all VNC desktops started by vncserver.
.TP
.B \-dry-run
Print full command VNC server would be run with and exit. Won't run VNC server.

.SH FILES
.TP
/etc/kasmvnc/kasmvnc.yaml
System-wide KasmVNC config. By default, all settings are commented out. The
commented out settings are the defaults used. Uncomment if you want to change
them. Otherwise, there's no need.
.TP
$HOME/.vnc/kasmvnc.yaml
An optional user-level server config. Settings here override the system-wide
config.
.TP
$HOME/.vnc/xstartup
A shell script specifying X applications to be run when a VNC desktop is
started.  If this file does not exist, then vncserver will create a default
xstartup script which attempts to launch your chosen window manager.
.TP
$HOME/.kasmpasswd
The KasmVNC password file.
.TP
$HOME/.vnc/\fIhost\fP:\fIdisplay#\fP.log
The log file for Xvnc and applications started in xstartup.
.TP
$HOME/.vnc/\fIhost\fP:\fIdisplay#\fP.pid
Identifies the Xvnc process ID, used by the
.B \-kill
option.

.SH SEE ALSO
.BR vncviewer (1),
.BR vncpasswd (1),
.BR vncconfig (1),
.BR Xvnc (1)
.br
https://www.kasmweb.com

.SH AUTHOR
Kasm Technologies Corp., Tristan Richardson, RealVNC Ltd., D. R. Commander and others.

VNC was originally developed by the RealVNC team while at Olivetti
Research Ltd / AT&T Laboratories Cambridge.  TightVNC additions were
implemented by Constantin Kaplinsky. Many other people have since
participated in development, testing and support. KasmVNC has since
forked and the project and has added many modern features and made
the solution web native.

This manual is part of the KasmVNC software suite.