Go to main content

man pages section 1: User Commands

Exit Print View

Updated: July 2017

vncserver (1)


vncserver - start or stop a VNC server


/usr/bin/vncserver  [:display#] [-name desktop-name] [-geometry widthx-
height] [-depth depth]  [-pixelformat  format]  [-fp  font-path]  [-fg]
[-autokill] [Xvnc-options...]
vncserver -kill :display#


vncserver(1)               Virtual Network Computing              vncserver(1)

       vncserver - start or stop a VNC server

       /usr/bin/vncserver  [:display#] [-name desktop-name] [-geometry widthx-
       height] [-depth depth]  [-pixelformat  format]  [-fp  font-path]  [-fg]
       [-autokill] [Xvnc-options...]
       vncserver -kill :display#

       vncserver  is  used to start a VNC (Virtual Network Computing) desktop.
       vncserver is a Perl script which simplifies the process of starting  an
       Xvnc server.  It runs Xvnc with appropriate options and starts a window
       manager on the VNC desktop.

       vncserver can be run with no options at  all.  In  this  case  it  will
       choose the first available display number (usually :1), start Xvnc with
       that display number, and start the default window manager in  the  Xvnc
       session.   You  can also specify the display number, in which case vnc-
       server will attempt to start Xvnc with that display number and exit  if
       the display number is not available.  For example:

              vncserver :13

       Editing  the file $HOME/.vnc/xstartup allows you to change the applica-
       tions run at startup (but note that this will not  affect  an  existing
       VNC session.)

       You  can get a list of options by passing -h as an option to vncserver.
       In addition to the options listed below, any unrecognised options  will
       be  passed  to  Xvnc  -  see  the  Xvnc  man page, or "Xvnc -help", for

       -name desktop-name
              Each VNC desktop has a  name  which  may  be  displayed  by  the
              viewer. The desktop name defaults to "host:display# (username)",
              but you can change it with this option.  The desktop name option
              is passed to the xstartup script via the $VNCDESKTOP environment
              variable, which allows you to run a different  set  of  applica-
              tions depending on the name of the desktop.

       -geometry widthxheight
              Specify  the  size  of the VNC desktop to be created. Default is

       -depth depth
              Specify the pixel depth (in bits) of the VNC desktop to be  cre-
              ated.  Default  is 24.  Other possible values are 8, 15 and 16 -
              anything else is likely to cause strange behaviour  by  applica-

       -pixelformat format
              Specify  pixel  format  for Xvnc to use (BGRnnn or RGBnnn).  The
              default for depth 8 is BGR233 (meaning the most significant  two
              bits represent blue, the next three green, and the least signif-
              icant three represent red), the default for depth 16 is  RGB565,
              and the default for depth 24 is RGB888.

       -cc 3  As  an  alternative to the default TrueColor visual, this allows
              you to run an Xvnc server with a PseudoColor  visual  (i.e.  one
              which uses a color map or palette), which can be useful for run-
              ning some old X applications which only work on such a  display.
              Values  other than 3 (PseudoColor) and 4 (TrueColor) for the -cc
              option may result in strange behaviour, and PseudoColor desktops
              must have an 8-bit depth.

       -httpd Instruct  Xvnc  to  run  a  mini-httpd if the VNC Java applet is

       -kill :display#
              This kills a VNC desktop previously started with vncserver.   It
              does  this  by  killing  the  Xvnc  process, whose process ID is
              stored in the file  "$HOME/.vnc/host:display#.pid".   The  -kill
              option  ignores  anything preceding the first colon (":") in the
              display argument.  Thus, you can invoke "vncserver  -kill  $DIS-
              PLAY", for example at the end of your xstartup file after a par-
              ticular application exits.

       -fp font-path
              If the vncserver script detects that the X Font Server (XFS)  is
              running, it will attempt to start Xvnc and configure Xvnc to use
              XFS for font handling.  Otherwise, if XFS is  not  running,  the
              vncserver  script  will  attempt to start Xvnc and allow Xvnc to
              use its own preferred method of font handling (which  may  be  a
              hard-coded  font  path  or, on more recent systems, a font cata-
              log.)  In any case, if Xvnc fails to start, the vncserver script
              will  then  attempt  to determine an appropriate X font path for
              this system and start Xvnc using that font path.

              The -fp argument allows you to override the above fallback logic
              and specify a font path for Xvnc to use.

       -fg    Runs  Xvnc  as  a foreground process.  This has two effects: (1)
              The VNC server can be aborted  with  CTRL-C,  and  (2)  the  VNC
              server will exit as soon as the user logs out of the window man-
              ager in the VNC session.  This may be necessary  when  launching
              TigerVNC from within certain grid computing environments.

              Automatically  kill Xvnc whenever the xstartup script exits.  In
              most cases, this has the effect of  terminating  Xvnc  when  the
              user logs out of the window manager.

       Several VNC-related files are found in the directory $HOME/.vnc:

              A  shell  script  specifying X applications to be run when a VNC
              desktop is started.  If this file does not exist, then vncserver
              will  create  a default xstartup script which attempts to launch
              your chosen window manager.

              The VNC password file.

              The log file for Xvnc and applications started in xstartup.

              Identifies the Xvnc process ID, used by the -kill option.

       vncviewer(1), vncpasswd(1), vncconfig(1), Xvnc(1)

       Tristan Richardson, RealVNC Ltd.
       D. R. Commander

       VNC was originally developed by the  RealVNC  team  while  at  Olivetti
       Research  Ltd  /  AT&T Laboratories Cambridge.  TightVNC additions were
       implemented by Constantin Kaplinsky. Many other people participated  in
       development, testing and support.

       See attributes(5) for descriptions of the following attributes:

       |      ATTRIBUTE TYPE         |      ATTRIBUTE VALUE        |
       |Availability                 |x11/server/xvnc              |
       |Interface Stability          |Volatile                     |

TigerVNC                          13 Mar 2011                     vncserver(1)