Go to main content

man pages section 1: User Commands

Exit Print View

Updated: Wednesday, July 27, 2022
 
 

vncserver (1)

Name

vncserver - start or stop a VNC server

Synopsis

vncserver  [:display#]  [-name  desktop-name]  [-geometry widthxheight]
[-depth depth] [-pixelformat format] [-fp font-path] [-fg]  [-autokill]
[-noxstartup] [-xstartup script] [Xvnc-options...]
vncserver -kill :display#
vncserver -list

Description

vncserver(1)               Virtual Network Computing              vncserver(1)



NAME
       vncserver - start or stop a VNC server

SYNOPSIS
       vncserver  [:display#]  [-name  desktop-name]  [-geometry widthxheight]
       [-depth depth] [-pixelformat format] [-fp font-path] [-fg]  [-autokill]
       [-noxstartup] [-xstartup script] [Xvnc-options...]
       vncserver -kill :display#
       vncserver -list

DESCRIPTION
       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.)


OPTIONS
       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
       details.


       -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
              1024x768.

       -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-
              tions.

       -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.

       -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.

       -autokill
              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.

       -noxstartup
              Do not run the %HOME/.vnc/xstartup script after launching  Xvnc.
              This  option  allows  you  to manually start a window manager in
              your TigerVNC session.

       -xstartup script
              Run a custom startup  script,  instead  of  %HOME/.vnc/xstartup,
              after launching Xvnc. This is useful to run full-screen applica-
              tions.

       -list  Lists all VNC desktops started by vncserver.


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

       $HOME/.vnc/xstartup
              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.

       /etc/tigervnc/vncserver-config-defaults
              The  optional  system-wide  equivalent  of $HOME/.vnc/config. If
              this file exists and defines options to be passed to Xvnc,  they
              will be used as defaults for users. The user's $HOME/.vnc/config
              overrides settings configured in this file.  The overall config-
              uration  file  load  order is: this file, $HOME/.vnc/config, and
              then /etc/tigervnc/vncserver-config-mandatory. None are required
              to exist.

       /etc/tigervnc/vncserver-config-mandatory
              The  optional  system-wide  equivalent  of $HOME/.vnc/config. If
              this file exists and defines options to be passed to Xvnc,  they
              will  override  any  of  the  same  options  defined in a user's
              $HOME/.vnc/config. This file offers  a  mechanism  to  establish
              some basic form of system-wide policy. WARNING! There is nothing
              stopping users from constructing their own vncserver-like script
              that  calls  Xvnc  directly  to  bypass  any  options defined in
              /etc/tigervnc/vncserver-config-mandatory.   Likewise,  any   CLI
              arguments passed to vncserver will override ANY config file set-
              ting of the same name. The overall configuration file load order
              is:  /etc/tigervnc/vncserver-config-defaults, $HOME/.vnc/config,
              and then this file.  None are required to exist.

       $HOME/.vnc/config
              An optional server config file wherein options to be  passed  to
              Xvnc  are listed to avoid hard-coding them to the physical invo-
              cation. List options in  this  file  one  per  line.  For  those
              requiring an argument, simply separate the option from the argu-
              ment with an equal sign, for  example:  "geometry=2000x1200"  or
              "securitytypes=vncauth,tlsvnc".  Options without an argument are
              simply listed as a single  word,  for  example:  "localhost"  or
              "alwaysshared".

       $HOME/.vnc/passwd
              The VNC password file.

       $HOME/.vnc/host:display#.log
              The log file for Xvnc and applications started in xstartup.

       $HOME/.vnc/host:display#.pid
              Identifies the Xvnc process ID, used by the -kill option.



ATTRIBUTES
       See attributes(7) for descriptions of the following attributes:


       +---------------+------------------+
       |ATTRIBUTE TYPE | ATTRIBUTE VALUE  |
       +---------------+------------------+
       |Availability   | x11/server/xvnc  |
       +---------------+------------------+
       |Stability      | Volatile         |
       +---------------+------------------+

SEE ALSO
       vncviewer(1), vncpasswd(1), vncconfig(1), Xvnc(1)
       https://www.tigervnc.org


AUTHOR
       Tristan Richardson, RealVNC Ltd., D. R. Commander and others.

       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 have since par-
       ticipated in development, testing and support. This manual is  part  of
       the TigerVNC software suite.



NOTES
       Source  code  for open source software components in Oracle Solaris can
       be found at https://www.oracle.com/downloads/opensource/solaris-source-
       code-downloads.html.

       This     software     was    built    from    source    available    at
       https://github.com/oracle/solaris-userland.   The  original   community
       source  was  downloaded  from  https://github.com/TigerVNC/tigervnc/ar-
       chive/v1.10.1.tar.gz.

       Further information about this software can be found on the open source
       community website at http://tigervnc.org/.



TigerVNC                                                          vncserver(1)