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