tigervnc/unix/vncserver/vncserver.man

.TH vncserver 1 "" "TigerVNC" "Virtual Network Computing"
.SH NAME
vncserver \- start or stop a VNC server
.SH SYNOPSIS
.B vncserver
.RI [: display# ]
.RB [ \-fg ]
.RB [ \-autokill ]
.RB [ \-noxstartup ]
.RB [ \-xstartup 
.IR script ]
.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 a Perl script which simplifies the process of starting an Xvnc server.  It
runs Xvnc with appropriate options and starts a window manager on the VNC
desktop.

.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

Editing the file $HOME/.vnc/xstartup allows you to change the applications run
at startup (but note that this will not affect an existing VNC session.)

.SH OPTIONS
You can get a list of options by passing \fB\-h\fP as an option to vncserver.

.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 \-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 TigerVNC 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 TigerVNC 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.

.SH FILES
Several VNC-related files are found in the directory $HOME/.vnc:
.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
/etc/tigervnc/vncserver-config-defaults
The optional system-wide equivalent of $HOME/.vnc/config. If this file exists
and defines options to be passed to Xvnc, they will be used as defaults for
users. The user's $HOME/.vnc/config overrides settings configured in this file.
The overall configuration file load order is: this file, $HOME/.vnc/config,
and then /etc/tigervnc/vncserver-config-mandatory. None are required to exist.
.TP
/etc/tigervnc/vncserver-config-mandatory
The optional system-wide equivalent of $HOME/.vnc/config. If this file exists
and defines options to be passed to Xvnc, they will override any of the same
options defined in a user's $HOME/.vnc/config. This file offers a mechanism
to establish some basic form of system-wide policy. WARNING! There is
nothing stopping users from constructing their own vncserver-like script
that calls Xvnc directly to bypass any options defined in
/etc/tigervnc/vncserver-config-mandatory. The overall configuration file load
order is: /etc/tigervnc/vncserver-config-defaults, $HOME/.vnc/config, and then
this file. None are required to exist.
.TP
$HOME/.vnc/config
An optional server config file wherein options to be passed to Xvnc are listed
to avoid hard-coding them to the physical invocation. List options in this file
one per line. For those requiring an argument, simply separate the option from
the argument with an equal sign, for example: "geometry=2000x1200" or
"securitytypes=vncauth,tlsvnc". Options without an argument are simply listed
as a single word, for example: "localhost" or "alwaysshared".
.TP
$HOME/.vnc/passwd
The VNC 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.tigervnc.org

.SH AUTHOR
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. This manual is part
of the TigerVNC software suite.