Pierre Ossman | f256a1a | 2014-09-17 14:09:58 +0200 | [diff] [blame] | 1 | .TH vncserver 1 "" "TigerVNC" "Virtual Network Computing" |
Constantin Kaplinsky | b30ae7f | 2006-05-25 05:04:46 +0000 | [diff] [blame] | 2 | .SH NAME |
| 3 | vncserver \- 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 ] |
DRC | eed5d1f | 2009-03-26 19:16:19 +0000 | [diff] [blame] | 15 | .RB [ \-fp |
| 16 | .IR font-path ] |
DRC | 8fb1191 | 2011-03-03 10:42:14 +0000 | [diff] [blame] | 17 | .RB [ \-fg ] |
Adam Tkac | 38ba8cf | 2011-04-27 11:28:09 +0000 | [diff] [blame] | 18 | .RB [ \-autokill ] |
Llorenç Garcia Martinez | 5d771f4 | 2015-10-23 13:42:13 +0200 | [diff] [blame] | 19 | .RB [ \-noxstartup ] |
Constantin Kaplinsky | b30ae7f | 2006-05-25 05:04:46 +0000 | [diff] [blame] | 20 | .RI [ Xvnc-options... ] |
| 21 | .br |
| 22 | .BI "vncserver \-kill :" display# |
Pierre Ossman | c16bb27 | 2014-09-17 14:18:31 +0200 | [diff] [blame] | 23 | .br |
| 24 | .BI "vncserver \-list" |
Constantin Kaplinsky | b30ae7f | 2006-05-25 05:04:46 +0000 | [diff] [blame] | 25 | .SH DESCRIPTION |
| 26 | .B vncserver |
| 27 | is used to start a VNC (Virtual Network Computing) desktop. |
| 28 | .B vncserver |
| 29 | is a Perl script which simplifies the process of starting an Xvnc server. It |
DRC | 7fe258a | 2009-03-26 18:58:40 +0000 | [diff] [blame] | 30 | runs Xvnc with appropriate options and starts a window manager on the VNC |
| 31 | desktop. |
Constantin Kaplinsky | b30ae7f | 2006-05-25 05:04:46 +0000 | [diff] [blame] | 32 | |
| 33 | .B vncserver |
| 34 | can be run with no options at all. In this case it will choose the first |
DRC | 7fe258a | 2009-03-26 18:58:40 +0000 | [diff] [blame] | 35 | available display number (usually :1), start Xvnc with that display number, |
| 36 | and start the default window manager in the Xvnc session. You can also |
| 37 | specify the display number, in which case vncserver will attempt to start |
| 38 | Xvnc with that display number and exit if the display number is not |
| 39 | available. For example: |
Constantin Kaplinsky | b30ae7f | 2006-05-25 05:04:46 +0000 | [diff] [blame] | 40 | |
| 41 | .RS |
| 42 | vncserver :13 |
| 43 | .RE |
| 44 | |
| 45 | Editing the file $HOME/.vnc/xstartup allows you to change the applications run |
DRC | 7fe258a | 2009-03-26 18:58:40 +0000 | [diff] [blame] | 46 | at startup (but note that this will not affect an existing VNC session.) |
Constantin Kaplinsky | b30ae7f | 2006-05-25 05:04:46 +0000 | [diff] [blame] | 47 | |
| 48 | .SH OPTIONS |
DRC | 7fe258a | 2009-03-26 18:58:40 +0000 | [diff] [blame] | 49 | You can get a list of options by passing \fB\-h\fP as an option to vncserver. |
Constantin Kaplinsky | b30ae7f | 2006-05-25 05:04:46 +0000 | [diff] [blame] | 50 | In addition to the options listed below, any unrecognised options will be |
DRC | 7fe258a | 2009-03-26 18:58:40 +0000 | [diff] [blame] | 51 | passed to Xvnc - see the Xvnc man page, or "Xvnc \-help", for details. |
Constantin Kaplinsky | b30ae7f | 2006-05-25 05:04:46 +0000 | [diff] [blame] | 52 | |
| 53 | .TP |
| 54 | .B \-name \fIdesktop-name\fP |
DRC | 7fe258a | 2009-03-26 18:58:40 +0000 | [diff] [blame] | 55 | Each VNC desktop has a name which may be displayed by the viewer. The desktop |
| 56 | name defaults to "\fIhost\fP:\fIdisplay#\fP (\fIusername\fP)", but you can |
| 57 | change it with this option. The desktop name option is passed to the xstartup |
| 58 | script via the $VNCDESKTOP environment variable, which allows you to run a |
| 59 | different set of applications depending on the name of the desktop. |
Pierre Ossman | 23f67c3 | 2014-09-17 16:28:56 +0200 | [diff] [blame] | 60 | . |
Constantin Kaplinsky | b30ae7f | 2006-05-25 05:04:46 +0000 | [diff] [blame] | 61 | .TP |
| 62 | .B \-geometry \fIwidth\fPx\fIheight\fP |
DRC | 7fe258a | 2009-03-26 18:58:40 +0000 | [diff] [blame] | 63 | Specify the size of the VNC desktop to be created. Default is 1024x768. |
Pierre Ossman | 23f67c3 | 2014-09-17 16:28:56 +0200 | [diff] [blame] | 64 | . |
Constantin Kaplinsky | b30ae7f | 2006-05-25 05:04:46 +0000 | [diff] [blame] | 65 | .TP |
| 66 | .B \-depth \fIdepth\fP |
DRC | 7fe258a | 2009-03-26 18:58:40 +0000 | [diff] [blame] | 67 | Specify the pixel depth (in bits) of the VNC desktop to be created. Default is |
| 68 | 24. Other possible values are 8, 15 and 16 - anything else is likely to cause |
Constantin Kaplinsky | b30ae7f | 2006-05-25 05:04:46 +0000 | [diff] [blame] | 69 | strange behaviour by applications. |
Pierre Ossman | 23f67c3 | 2014-09-17 16:28:56 +0200 | [diff] [blame] | 70 | . |
Constantin Kaplinsky | b30ae7f | 2006-05-25 05:04:46 +0000 | [diff] [blame] | 71 | .TP |
| 72 | .B \-pixelformat \fIformat\fP |
DRC | 7fe258a | 2009-03-26 18:58:40 +0000 | [diff] [blame] | 73 | Specify pixel format for Xvnc to use (BGRnnn or RGBnnn). The default for |
Constantin Kaplinsky | b30ae7f | 2006-05-25 05:04:46 +0000 | [diff] [blame] | 74 | depth 8 is BGR233 (meaning the most significant two bits represent blue, the |
| 75 | next three green, and the least significant three represent red), the default |
DRC | 7fe258a | 2009-03-26 18:58:40 +0000 | [diff] [blame] | 76 | for depth 16 is RGB565, and the default for depth 24 is RGB888. |
Pierre Ossman | 23f67c3 | 2014-09-17 16:28:56 +0200 | [diff] [blame] | 77 | . |
Constantin Kaplinsky | b30ae7f | 2006-05-25 05:04:46 +0000 | [diff] [blame] | 78 | .TP |
| 79 | .B \-cc 3 |
| 80 | As an alternative to the default TrueColor visual, this allows you to run an |
| 81 | Xvnc server with a PseudoColor visual (i.e. one which uses a color map or |
| 82 | palette), which can be useful for running some old X applications which only |
| 83 | work on such a display. Values other than 3 (PseudoColor) and 4 (TrueColor) |
| 84 | for the \-cc option may result in strange behaviour, and PseudoColor desktops |
DRC | 7fe258a | 2009-03-26 18:58:40 +0000 | [diff] [blame] | 85 | must have an 8-bit depth. |
Pierre Ossman | 23f67c3 | 2014-09-17 16:28:56 +0200 | [diff] [blame] | 86 | . |
Constantin Kaplinsky | b30ae7f | 2006-05-25 05:04:46 +0000 | [diff] [blame] | 87 | .TP |
| 88 | .B \-kill :\fIdisplay#\fP |
| 89 | This kills a VNC desktop previously started with vncserver. It does this by |
| 90 | killing the Xvnc process, whose process ID is stored in the file |
DRC | 7fe258a | 2009-03-26 18:58:40 +0000 | [diff] [blame] | 91 | "$HOME/.vnc/\fIhost\fP:\fIdisplay#\fP.pid". The |
| 92 | .B \-kill |
| 93 | option ignores anything preceding the first colon (":") in the display |
| 94 | argument. Thus, you can invoke "vncserver \-kill $DISPLAY", for example at the |
| 95 | end of your xstartup file after a particular application exits. |
Pierre Ossman | 23f67c3 | 2014-09-17 16:28:56 +0200 | [diff] [blame] | 96 | . |
DRC | eed5d1f | 2009-03-26 19:16:19 +0000 | [diff] [blame] | 97 | .TP |
| 98 | .B \-fp \fIfont-path\fP |
DRC | 36546c1 | 2009-04-15 06:47:23 +0000 | [diff] [blame] | 99 | If the vncserver script detects that the X Font Server (XFS) is running, it |
| 100 | will attempt to start Xvnc and configure Xvnc to use XFS for font handling. |
| 101 | Otherwise, if XFS is not running, the vncserver script will attempt to start |
| 102 | Xvnc and allow Xvnc to use its own preferred method of font handling (which may |
| 103 | be a hard-coded font path or, on more recent systems, a font catalog.) In |
| 104 | any case, if Xvnc fails to start, the vncserver script will then attempt to |
| 105 | determine an appropriate X font path for this system and start Xvnc using |
| 106 | that font path. |
| 107 | |
| 108 | The |
DRC | eed5d1f | 2009-03-26 19:16:19 +0000 | [diff] [blame] | 109 | .B \-fp |
DRC | 36546c1 | 2009-04-15 06:47:23 +0000 | [diff] [blame] | 110 | argument allows you to override the above fallback logic and specify a font |
| 111 | path for Xvnc to use. |
Pierre Ossman | 23f67c3 | 2014-09-17 16:28:56 +0200 | [diff] [blame] | 112 | . |
DRC | 8fb1191 | 2011-03-03 10:42:14 +0000 | [diff] [blame] | 113 | .TP |
| 114 | .B \-fg |
Adam Tkac | f586b84 | 2011-04-27 11:20:18 +0000 | [diff] [blame] | 115 | Runs Xvnc as a foreground process. This has two effects: (1) The VNC server |
| 116 | can be aborted with CTRL-C, and (2) the VNC server will exit as soon as the |
| 117 | user logs out of the window manager in the VNC session. This may be necessary |
| 118 | when launching TigerVNC from within certain grid computing environments. |
Pierre Ossman | 23f67c3 | 2014-09-17 16:28:56 +0200 | [diff] [blame] | 119 | . |
Adam Tkac | 38ba8cf | 2011-04-27 11:28:09 +0000 | [diff] [blame] | 120 | .TP |
| 121 | .B \-autokill |
| 122 | Automatically kill Xvnc whenever the xstartup script exits. In most cases, |
| 123 | this has the effect of terminating Xvnc when the user logs out of the window |
| 124 | manager. |
Pierre Ossman | 23f67c3 | 2014-09-17 16:28:56 +0200 | [diff] [blame] | 125 | . |
Pierre Ossman | c16bb27 | 2014-09-17 14:18:31 +0200 | [diff] [blame] | 126 | .TP |
Llorenç Garcia Martinez | 5d771f4 | 2015-10-23 13:42:13 +0200 | [diff] [blame] | 127 | .B \-noxstartup |
| 128 | Do not run the %HOME/.vnc/xstartup script after launching Xvnc. This |
| 129 | option allows you to manually start a window manager in your TigerVNC session. |
| 130 | . |
| 131 | .TP |
Pierre Ossman | c16bb27 | 2014-09-17 14:18:31 +0200 | [diff] [blame] | 132 | .B \-list |
| 133 | Lists all VNC desktops started by vncserver. |
| 134 | |
Constantin Kaplinsky | b30ae7f | 2006-05-25 05:04:46 +0000 | [diff] [blame] | 135 | .SH FILES |
| 136 | Several VNC-related files are found in the directory $HOME/.vnc: |
| 137 | .TP |
| 138 | $HOME/.vnc/xstartup |
| 139 | A shell script specifying X applications to be run when a VNC desktop is |
DRC | 7fe258a | 2009-03-26 18:58:40 +0000 | [diff] [blame] | 140 | started. If this file does not exist, then vncserver will create a default |
| 141 | xstartup script which attempts to launch your chosen window manager. |
Constantin Kaplinsky | b30ae7f | 2006-05-25 05:04:46 +0000 | [diff] [blame] | 142 | .TP |
graysky | 02cbc22 | 2015-10-19 08:26:44 -0400 | [diff] [blame] | 143 | $HOME/.vnc/config |
| 144 | An optional server config file wherein options to be passed to Xvnc are listed |
| 145 | to avoid hard-coding them to the physical invocation. List options in this file |
| 146 | one per line. For those requiring an argument, simply separate the option from |
| 147 | the argument with an equal sign, for example: "geometry=2000x1200" or |
| 148 | "securitytypes=vncauth,tlsvnc". Options without an argument are simply listed |
| 149 | as a single word, for example: "localhost" or "alwaysshared". |
| 150 | .TP |
Constantin Kaplinsky | b30ae7f | 2006-05-25 05:04:46 +0000 | [diff] [blame] | 151 | $HOME/.vnc/passwd |
| 152 | The VNC password file. |
| 153 | .TP |
| 154 | $HOME/.vnc/\fIhost\fP:\fIdisplay#\fP.log |
| 155 | The log file for Xvnc and applications started in xstartup. |
| 156 | .TP |
| 157 | $HOME/.vnc/\fIhost\fP:\fIdisplay#\fP.pid |
| 158 | Identifies the Xvnc process ID, used by the |
| 159 | .B \-kill |
| 160 | option. |
| 161 | |
| 162 | .SH SEE ALSO |
| 163 | .BR vncviewer (1), |
| 164 | .BR vncpasswd (1), |
| 165 | .BR vncconfig (1), |
| 166 | .BR Xvnc (1) |
| 167 | .br |
Peter Åstrand | 4eacc02 | 2009-02-27 10:12:14 +0000 | [diff] [blame] | 168 | http://www.tigervnc.org |
Constantin Kaplinsky | b30ae7f | 2006-05-25 05:04:46 +0000 | [diff] [blame] | 169 | |
| 170 | .SH AUTHOR |
Pierre Ossman | e37a144 | 2014-09-17 14:08:16 +0200 | [diff] [blame] | 171 | Tristan Richardson, RealVNC Ltd., D. R. Commander and others. |
Constantin Kaplinsky | b30ae7f | 2006-05-25 05:04:46 +0000 | [diff] [blame] | 172 | |
| 173 | VNC was originally developed by the RealVNC team while at Olivetti |
Constantin Kaplinsky | be1bda8 | 2006-06-02 04:43:52 +0000 | [diff] [blame] | 174 | Research Ltd / AT&T Laboratories Cambridge. TightVNC additions were |
Pierre Ossman | e37a144 | 2014-09-17 14:08:16 +0200 | [diff] [blame] | 175 | implemented by Constantin Kaplinsky. Many other people have since |
| 176 | participated in development, testing and support. This manual is part |
| 177 | of the TigerVNC software suite. |