blob: dceaa79319676fb2be49aedac0d16731508139bf [file] [log] [blame]
Pierre Ossmanf256a1a2014-09-17 14:09:58 +02001.TH vncserver 1 "" "TigerVNC" "Virtual Network Computing"
Constantin Kaplinskyb30ae7f2006-05-25 05:04:46 +00002.SH NAME
3vncserver \- start or stop a VNC server
4.SH SYNOPSIS
5.B vncserver
6.RI [: display# ]
7.RB [ \-name
8.IR desktop-name ]
9.RB [ \-geometry
10.IR width x height ]
11.RB [ \-depth
12.IR depth ]
13.RB [ \-pixelformat
14.IR format ]
DRCeed5d1f2009-03-26 19:16:19 +000015.RB [ \-fp
16.IR font-path ]
DRC8fb11912011-03-03 10:42:14 +000017.RB [ \-fg ]
Adam Tkac38ba8cf2011-04-27 11:28:09 +000018.RB [ \-autokill ]
Constantin Kaplinskyb30ae7f2006-05-25 05:04:46 +000019.RI [ Xvnc-options... ]
20.br
21.BI "vncserver \-kill :" display#
22.SH DESCRIPTION
23.B vncserver
24is used to start a VNC (Virtual Network Computing) desktop.
25.B vncserver
26is a Perl script which simplifies the process of starting an Xvnc server. It
DRC7fe258a2009-03-26 18:58:40 +000027runs Xvnc with appropriate options and starts a window manager on the VNC
28desktop.
Constantin Kaplinskyb30ae7f2006-05-25 05:04:46 +000029
30.B vncserver
31can be run with no options at all. In this case it will choose the first
DRC7fe258a2009-03-26 18:58:40 +000032available display number (usually :1), start Xvnc with that display number,
33and start the default window manager in the Xvnc session. You can also
34specify the display number, in which case vncserver will attempt to start
35Xvnc with that display number and exit if the display number is not
36available. For example:
Constantin Kaplinskyb30ae7f2006-05-25 05:04:46 +000037
38.RS
39vncserver :13
40.RE
41
42Editing the file $HOME/.vnc/xstartup allows you to change the applications run
DRC7fe258a2009-03-26 18:58:40 +000043at startup (but note that this will not affect an existing VNC session.)
Constantin Kaplinskyb30ae7f2006-05-25 05:04:46 +000044
45.SH OPTIONS
DRC7fe258a2009-03-26 18:58:40 +000046You can get a list of options by passing \fB\-h\fP as an option to vncserver.
Constantin Kaplinskyb30ae7f2006-05-25 05:04:46 +000047In addition to the options listed below, any unrecognised options will be
DRC7fe258a2009-03-26 18:58:40 +000048passed to Xvnc - see the Xvnc man page, or "Xvnc \-help", for details.
Constantin Kaplinskyb30ae7f2006-05-25 05:04:46 +000049
50.TP
51.B \-name \fIdesktop-name\fP
DRC7fe258a2009-03-26 18:58:40 +000052Each VNC desktop has a name which may be displayed by the viewer. The desktop
53name defaults to "\fIhost\fP:\fIdisplay#\fP (\fIusername\fP)", but you can
54change it with this option. The desktop name option is passed to the xstartup
55script via the $VNCDESKTOP environment variable, which allows you to run a
56different set of applications depending on the name of the desktop.
Constantin Kaplinskyb30ae7f2006-05-25 05:04:46 +000057
58.TP
59.B \-geometry \fIwidth\fPx\fIheight\fP
DRC7fe258a2009-03-26 18:58:40 +000060Specify the size of the VNC desktop to be created. Default is 1024x768.
Constantin Kaplinskyb30ae7f2006-05-25 05:04:46 +000061
62.TP
63.B \-depth \fIdepth\fP
DRC7fe258a2009-03-26 18:58:40 +000064Specify the pixel depth (in bits) of the VNC desktop to be created. Default is
6524. Other possible values are 8, 15 and 16 - anything else is likely to cause
Constantin Kaplinskyb30ae7f2006-05-25 05:04:46 +000066strange behaviour by applications.
67
68.TP
69.B \-pixelformat \fIformat\fP
DRC7fe258a2009-03-26 18:58:40 +000070Specify pixel format for Xvnc to use (BGRnnn or RGBnnn). The default for
Constantin Kaplinskyb30ae7f2006-05-25 05:04:46 +000071depth 8 is BGR233 (meaning the most significant two bits represent blue, the
72next three green, and the least significant three represent red), the default
DRC7fe258a2009-03-26 18:58:40 +000073for depth 16 is RGB565, and the default for depth 24 is RGB888.
Constantin Kaplinskyb30ae7f2006-05-25 05:04:46 +000074
75.TP
76.B \-cc 3
77As an alternative to the default TrueColor visual, this allows you to run an
78Xvnc server with a PseudoColor visual (i.e. one which uses a color map or
79palette), which can be useful for running some old X applications which only
80work on such a display. Values other than 3 (PseudoColor) and 4 (TrueColor)
81for the \-cc option may result in strange behaviour, and PseudoColor desktops
DRC7fe258a2009-03-26 18:58:40 +000082must have an 8-bit depth.
Constantin Kaplinskyb30ae7f2006-05-25 05:04:46 +000083
84.TP
85.B \-kill :\fIdisplay#\fP
86This kills a VNC desktop previously started with vncserver. It does this by
87killing the Xvnc process, whose process ID is stored in the file
DRC7fe258a2009-03-26 18:58:40 +000088"$HOME/.vnc/\fIhost\fP:\fIdisplay#\fP.pid". The
89.B \-kill
90option ignores anything preceding the first colon (":") in the display
91argument. Thus, you can invoke "vncserver \-kill $DISPLAY", for example at the
92end of your xstartup file after a particular application exits.
Constantin Kaplinskyb30ae7f2006-05-25 05:04:46 +000093
DRCeed5d1f2009-03-26 19:16:19 +000094.TP
95.B \-fp \fIfont-path\fP
DRC36546c12009-04-15 06:47:23 +000096If the vncserver script detects that the X Font Server (XFS) is running, it
97will attempt to start Xvnc and configure Xvnc to use XFS for font handling.
98Otherwise, if XFS is not running, the vncserver script will attempt to start
99Xvnc and allow Xvnc to use its own preferred method of font handling (which may
100be a hard-coded font path or, on more recent systems, a font catalog.) In
101any case, if Xvnc fails to start, the vncserver script will then attempt to
102determine an appropriate X font path for this system and start Xvnc using
103that font path.
104
105The
DRCeed5d1f2009-03-26 19:16:19 +0000106.B \-fp
DRC36546c12009-04-15 06:47:23 +0000107argument allows you to override the above fallback logic and specify a font
108path for Xvnc to use.
DRCeed5d1f2009-03-26 19:16:19 +0000109
DRC8fb11912011-03-03 10:42:14 +0000110.TP
111.B \-fg
Adam Tkacf586b842011-04-27 11:20:18 +0000112Runs Xvnc as a foreground process. This has two effects: (1) The VNC server
113can be aborted with CTRL-C, and (2) the VNC server will exit as soon as the
114user logs out of the window manager in the VNC session. This may be necessary
115when launching TigerVNC from within certain grid computing environments.
DRC8fb11912011-03-03 10:42:14 +0000116
Adam Tkac38ba8cf2011-04-27 11:28:09 +0000117.TP
118.B \-autokill
119Automatically kill Xvnc whenever the xstartup script exits. In most cases,
120this has the effect of terminating Xvnc when the user logs out of the window
121manager.
122
Constantin Kaplinskyb30ae7f2006-05-25 05:04:46 +0000123.SH FILES
124Several VNC-related files are found in the directory $HOME/.vnc:
125.TP
126$HOME/.vnc/xstartup
127A shell script specifying X applications to be run when a VNC desktop is
DRC7fe258a2009-03-26 18:58:40 +0000128started. If this file does not exist, then vncserver will create a default
129xstartup script which attempts to launch your chosen window manager.
Constantin Kaplinskyb30ae7f2006-05-25 05:04:46 +0000130.TP
131$HOME/.vnc/passwd
132The VNC password file.
133.TP
134$HOME/.vnc/\fIhost\fP:\fIdisplay#\fP.log
135The log file for Xvnc and applications started in xstartup.
136.TP
137$HOME/.vnc/\fIhost\fP:\fIdisplay#\fP.pid
138Identifies the Xvnc process ID, used by the
139.B \-kill
140option.
141
142.SH SEE ALSO
143.BR vncviewer (1),
144.BR vncpasswd (1),
145.BR vncconfig (1),
146.BR Xvnc (1)
147.br
Peter Åstrand4eacc022009-02-27 10:12:14 +0000148http://www.tigervnc.org
Constantin Kaplinskyb30ae7f2006-05-25 05:04:46 +0000149
150.SH AUTHOR
Pierre Ossmane37a1442014-09-17 14:08:16 +0200151Tristan Richardson, RealVNC Ltd., D. R. Commander and others.
Constantin Kaplinskyb30ae7f2006-05-25 05:04:46 +0000152
153VNC was originally developed by the RealVNC team while at Olivetti
Constantin Kaplinskybe1bda82006-06-02 04:43:52 +0000154Research Ltd / AT&T Laboratories Cambridge. TightVNC additions were
Pierre Ossmane37a1442014-09-17 14:08:16 +0200155implemented by Constantin Kaplinsky. Many other people have since
156participated in development, testing and support. This manual is part
157of the TigerVNC software suite.