blob: 5127056eff0f165c46508f49002085df7473b547 [file] [log] [blame]
DRC36546c12009-04-15 06:47:23 +00001.TH vncserver 1 "15 Apr 2009" "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 ]
Constantin Kaplinskyb30ae7f2006-05-25 05:04:46 +000018.RI [ Xvnc-options... ]
19.br
20.BI "vncserver \-kill :" display#
21.SH DESCRIPTION
22.B vncserver
23is used to start a VNC (Virtual Network Computing) desktop.
24.B vncserver
25is a Perl script which simplifies the process of starting an Xvnc server. It
DRC7fe258a2009-03-26 18:58:40 +000026runs Xvnc with appropriate options and starts a window manager on the VNC
27desktop.
Constantin Kaplinskyb30ae7f2006-05-25 05:04:46 +000028
29.B vncserver
30can be run with no options at all. In this case it will choose the first
DRC7fe258a2009-03-26 18:58:40 +000031available display number (usually :1), start Xvnc with that display number,
32and start the default window manager in the Xvnc session. You can also
33specify the display number, in which case vncserver will attempt to start
34Xvnc with that display number and exit if the display number is not
35available. For example:
Constantin Kaplinskyb30ae7f2006-05-25 05:04:46 +000036
37.RS
38vncserver :13
39.RE
40
41Editing the file $HOME/.vnc/xstartup allows you to change the applications run
DRC7fe258a2009-03-26 18:58:40 +000042at startup (but note that this will not affect an existing VNC session.)
Constantin Kaplinskyb30ae7f2006-05-25 05:04:46 +000043
44.SH OPTIONS
DRC7fe258a2009-03-26 18:58:40 +000045You can get a list of options by passing \fB\-h\fP as an option to vncserver.
Constantin Kaplinskyb30ae7f2006-05-25 05:04:46 +000046In addition to the options listed below, any unrecognised options will be
DRC7fe258a2009-03-26 18:58:40 +000047passed to Xvnc - see the Xvnc man page, or "Xvnc \-help", for details.
Constantin Kaplinskyb30ae7f2006-05-25 05:04:46 +000048
49.TP
50.B \-name \fIdesktop-name\fP
DRC7fe258a2009-03-26 18:58:40 +000051Each VNC desktop has a name which may be displayed by the viewer. The desktop
52name defaults to "\fIhost\fP:\fIdisplay#\fP (\fIusername\fP)", but you can
53change it with this option. The desktop name option is passed to the xstartup
54script via the $VNCDESKTOP environment variable, which allows you to run a
55different set of applications depending on the name of the desktop.
Constantin Kaplinskyb30ae7f2006-05-25 05:04:46 +000056
57.TP
58.B \-geometry \fIwidth\fPx\fIheight\fP
DRC7fe258a2009-03-26 18:58:40 +000059Specify the size of the VNC desktop to be created. Default is 1024x768.
Constantin Kaplinskyb30ae7f2006-05-25 05:04:46 +000060
61.TP
62.B \-depth \fIdepth\fP
DRC7fe258a2009-03-26 18:58:40 +000063Specify the pixel depth (in bits) of the VNC desktop to be created. Default is
6424. Other possible values are 8, 15 and 16 - anything else is likely to cause
Constantin Kaplinskyb30ae7f2006-05-25 05:04:46 +000065strange behaviour by applications.
66
67.TP
68.B \-pixelformat \fIformat\fP
DRC7fe258a2009-03-26 18:58:40 +000069Specify pixel format for Xvnc to use (BGRnnn or RGBnnn). The default for
Constantin Kaplinskyb30ae7f2006-05-25 05:04:46 +000070depth 8 is BGR233 (meaning the most significant two bits represent blue, the
71next three green, and the least significant three represent red), the default
DRC7fe258a2009-03-26 18:58:40 +000072for depth 16 is RGB565, and the default for depth 24 is RGB888.
Constantin Kaplinskyb30ae7f2006-05-25 05:04:46 +000073
74.TP
75.B \-cc 3
76As an alternative to the default TrueColor visual, this allows you to run an
77Xvnc server with a PseudoColor visual (i.e. one which uses a color map or
78palette), which can be useful for running some old X applications which only
79work on such a display. Values other than 3 (PseudoColor) and 4 (TrueColor)
80for the \-cc option may result in strange behaviour, and PseudoColor desktops
DRC7fe258a2009-03-26 18:58:40 +000081must have an 8-bit depth.
Constantin Kaplinskyb30ae7f2006-05-25 05:04:46 +000082
83.TP
84.B \-kill :\fIdisplay#\fP
85This kills a VNC desktop previously started with vncserver. It does this by
86killing the Xvnc process, whose process ID is stored in the file
DRC7fe258a2009-03-26 18:58:40 +000087"$HOME/.vnc/\fIhost\fP:\fIdisplay#\fP.pid". The
88.B \-kill
89option ignores anything preceding the first colon (":") in the display
90argument. Thus, you can invoke "vncserver \-kill $DISPLAY", for example at the
91end of your xstartup file after a particular application exits.
Constantin Kaplinskyb30ae7f2006-05-25 05:04:46 +000092
DRCeed5d1f2009-03-26 19:16:19 +000093.TP
94.B \-fp \fIfont-path\fP
DRC36546c12009-04-15 06:47:23 +000095If the vncserver script detects that the X Font Server (XFS) is running, it
96will attempt to start Xvnc and configure Xvnc to use XFS for font handling.
97Otherwise, if XFS is not running, the vncserver script will attempt to start
98Xvnc and allow Xvnc to use its own preferred method of font handling (which may
99be a hard-coded font path or, on more recent systems, a font catalog.) In
100any case, if Xvnc fails to start, the vncserver script will then attempt to
101determine an appropriate X font path for this system and start Xvnc using
102that font path.
103
104The
DRCeed5d1f2009-03-26 19:16:19 +0000105.B \-fp
DRC36546c12009-04-15 06:47:23 +0000106argument allows you to override the above fallback logic and specify a font
107path for Xvnc to use.
DRCeed5d1f2009-03-26 19:16:19 +0000108
DRC8fb11912011-03-03 10:42:14 +0000109.TP
110.B \-fg
111This version of vncserver will always launch Xvnc in such a way that, when the
112user exits the window manager in their VNC session, Xvnc will terminate.
113Specifying this option will additionally make Xvnc run as a foreground process,
114which means that it can be aborted with CTRL-C. This may be necessary when
115launching TigerVNC from within certain grid computing environments.
116
Constantin Kaplinskyb30ae7f2006-05-25 05:04:46 +0000117.SH FILES
118Several VNC-related files are found in the directory $HOME/.vnc:
119.TP
120$HOME/.vnc/xstartup
121A shell script specifying X applications to be run when a VNC desktop is
DRC7fe258a2009-03-26 18:58:40 +0000122started. If this file does not exist, then vncserver will create a default
123xstartup script which attempts to launch your chosen window manager.
Constantin Kaplinskyb30ae7f2006-05-25 05:04:46 +0000124.TP
125$HOME/.vnc/passwd
126The VNC password file.
127.TP
128$HOME/.vnc/\fIhost\fP:\fIdisplay#\fP.log
129The log file for Xvnc and applications started in xstartup.
130.TP
131$HOME/.vnc/\fIhost\fP:\fIdisplay#\fP.pid
132Identifies the Xvnc process ID, used by the
133.B \-kill
134option.
135
136.SH SEE ALSO
137.BR vncviewer (1),
138.BR vncpasswd (1),
139.BR vncconfig (1),
140.BR Xvnc (1)
141.br
Peter Åstrand4eacc022009-02-27 10:12:14 +0000142http://www.tigervnc.org
Constantin Kaplinskyb30ae7f2006-05-25 05:04:46 +0000143
144.SH AUTHOR
145Tristan Richardson, RealVNC Ltd.
DRC7fe258a2009-03-26 18:58:40 +0000146.br
147D. R. Commander
Constantin Kaplinskyb30ae7f2006-05-25 05:04:46 +0000148
149VNC was originally developed by the RealVNC team while at Olivetti
Constantin Kaplinskybe1bda82006-06-02 04:43:52 +0000150Research Ltd / AT&T Laboratories Cambridge. TightVNC additions were
Constantin Kaplinskyb30ae7f2006-05-25 05:04:46 +0000151implemented by Constantin Kaplinsky. Many other people participated in
152development, testing and support.