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