vncserver

Launch a VNC Server on next available display

$ vncserver

$ vncserver --geometry [width]x[height]

$ vncserver --kill :[display_number]

vncserver [:] [options]
vncserver -kill :
vncserver -list

-geometry WxH
    Specifies the initial desktop width and height, e.g., 1024x768.

-depth D
    Sets the color depth for the session, commonly 8, 16, or 24 bits.

-name "Desktop Name"
    Assigns a descriptive name to the VNC desktop window shown in the viewer.

-kill :
    Terminates the VNC server session running on the specified display number.

-list
    Displays a list of all currently running VNC server sessions.

-randr WxH
    (TigerVNC specific) Changes the resolution of an existing VNC session.

-rfbport PORT
    Specifies an alternative RFB (Remote FrameBuffer) port to listen on.

-clean
    Removes stale lock files or socket files that might prevent a new session from starting.

-localhost
    Configures the VNC server to only accept connections from the local machine (127.0.0.1). Ideal for SSH tunneling.

-noxstartup
    Prevents the execution of the user's ~/.vnc/xstartup script upon session start.

-xstartup SCRIPT
    Specifies an alternative script to execute instead of ~/.vnc/xstartup.

-fg
    Runs the VNC server in the foreground, useful for debugging or systemd service management.

-verbose
    Provides more detailed output during the command execution.

:
    Starts a new VNC session on the specified display number (e.g., :1).

vncserver is a command-line utility used to start, stop, and manage VNC (Virtual Network Computing) server sessions on a Unix-like system. It creates a virtual X server desktop environment that can be remotely accessed by a VNC client (vncviewer). This allows users to establish graphical sessions on a headless server or access a separate desktop instance from their local machine. Upon its first execution, vncserver prompts the user to set a password for the VNC session. It typically manages display numbers, allocates appropriate TCP ports (usually 5900 + display_number), and executes the ~/.vnc/xstartup script to initialize the desktop environment (e.g., GNOME, KDE, XFCE). While powerful for remote access, direct VNC connections are unencrypted, necessitating the use of secure tunnels like SSH for production environments.

Security: VNC's RFB protocol itself does not provide encryption. For secure connections, always use an SSH tunnel (e.g., ssh -L 5901:localhost:5901 user@remote-host) when connecting to vncserver over an untrusted network.
Configuration: The graphical environment and applications launched within a VNC session are largely controlled by the ~/.vnc/xstartup script. Users often need to customize this script to launch their preferred desktop environment or window manager.
Implementation Differences: vncserver implementations vary slightly between different VNC distributions (e.g., TigerVNC, TightVNC, RealVNC), which may lead to minor differences in options or behavior.

The first time vncserver is run by a user, it will prompt to set a VNC access password. This password is then stored in ~/.vnc/passwd. To change or set the password later, use the vncpasswd command.

The ~/.vnc/xstartup file is a shell script executed by vncserver when a new session starts. It defines what desktop environment or window manager (e.g., GNOME, XFCE, Openbox) will be launched. If this file is missing or incorrectly configured, users might see a blank gray screen upon connecting. It requires execute permissions (chmod +x ~/.vnc/xstartup).

To terminate a running VNC session, use the vncserver -kill : command, where : is the number displayed when the server was started (e.g., :1).

If connecting directly without an SSH tunnel, ensure that the firewall on the server allows incoming connections to the VNC port. VNC servers typically listen on ports 5900 + (e.g., 5901 for display :1, 5902 for :2).

VNC (Virtual Network Computing) was originally developed at AT&T Laboratories Cambridge in the late 1990s. vncserver emerged as a fundamental utility within VNC distributions, simplifying the management of remote X server sessions. Its design allowed users to easily spin up virtual desktops accessible over the network, making it a popular choice for remote administration and development environments on Unix-like systems. Over time, various forks and implementations like TightVNC and TigerVNC have continued its development, adapting to modern operating system features like systemd integration.

vncviewer(1), vncpasswd(1), ssh(1), systemctl(1)