Skip to content

Update VNC install guide #2488

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Oct 29, 2025
Merged

Update VNC install guide #2488

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file modified content/install-guides/_images/xfce4.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
54 changes: 27 additions & 27 deletions content/install-guides/vnc.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ additional_search_terms:
- linux

### Estimated completion time in minutes (please use integer multiple of 5)
minutes_to_complete: 30
minutes_to_complete: 15

author: Jason Andrews

Expand All @@ -29,67 +29,67 @@ multitool_install_part: false # Set to true if a sub-page of a multi-page arti
layout: installtoolsall # DO NOT MODIFY. Always true for tool install articles
---

Virtual Network Computing (VNC) is one of the common tools used to connect to a remote Linux desktop. During development it may be useful to quickly create a remote desktop on an Arm server.
Virtual Network Computing (VNC) is one of the common tools used to connect to a remote Linux desktop. During development, it can be useful to quickly create a remote desktop on an Arm server.

This section provides info about how to setup VNC on a remote Arm Linux machine.

Feel free to seek out additional VNC tutorials or add more information to this page.
This guide provides information about how to set up VNC on a remote Arm Linux machine.

This installation only works on newer versions of Ubuntu and Debian. It was successfully tested on **Ubuntu 22.04** and is known to fail on **Ubuntu 20.04**.

## What is VNC?

VNC is a client server application. A VNC server runs on a remote machine. A VNC client runs on the local machine and connects to the remote server.
VNC is a client-server application. A VNC server runs on a remote machine. A VNC client runs on the local machine and connects to the remote server.

### How do I install the VNC server and xfce4 desktop?

To use VNC, a VNC server needs to be installed. There are multiple VNC servers which can be used. This recipe uses [TigerVNC](https://tigervnc.org/).
To use VNC, you need to install a VNC server. There are multiple VNC servers you can use. This guide uses [TigerVNC](https://tigervnc.org/).

Desktop software is also needed. There are many options for this, but using [xfce4](https://www.xfce.org/) makes for a minimal install with good performance.
You also need desktop software. There are many options for this, but using [xfce4](https://www.xfce.org/) provides a minimal install with good performance.

Install the desktop software.
Install the desktop software:

```bash
sudo apt-get install xfce4 xfce4-goodies xorg dbus-x11 x11-xserver-utils xfce4-terminal -y
```

Install the VNC server.
Install the VNC server:

```bash
sudo apt-get install tigervnc-standalone-server tigervnc-common -y
```

### How do I set a VNC password?

Run the password command to set a password for VNC. This is not the password for the user account, just for the VNC client to connect to the VNC server.
Run the `vncpasswd` command to set a password for VNC. This is not the password for your user account, but for the VNC client to connect to the VNC server.

```console
vncpasswd
```

Remember the password for later when the client is connected.
Remember this password for later when you connect the client.

### How do I configure the desktop startup for VNC?

Create a file at `$HOME/.vnc/xstartup` with the contents:
Create a file at `$HOME/.vnc/xstartup` with the following contents:

```console
#!/bin/sh
unset SESSION_MANAGER
unset DBUS_SESSION_BUS_ADDRESS
exec startxfce4
```
Make sure the `xstartup` file has executable permission.
Make sure the `xstartup` file has executable permissions:

```console
chmod +x $HOME/.vnc/xstartup
```

### How do I set up a systemd service to manage VNC?

To create a systemd service to start the VNC server create the file `/etc/systemd/system/vncserver@.service`
To create a systemd service to start the VNC server, create the file `/etc/systemd/system/vncserver@.service`.

Use sudo or root as it is located in a read-only area.
```console
Use `sudo` or root privileges because this file is in a system directory.

```ini
[Unit]
Description=Remote desktop service (VNC)
After=syslog.target network.target
Expand All @@ -105,9 +105,8 @@ Use sudo or root as it is located in a read-only area.

[Install]
WantedBy=multi-user.target

```
The commands below are for any Linux distribution using `systemd`.
```
The following commands are for any Linux distribution that uses `systemd`.

To start the VNC service:

Expand All @@ -129,24 +128,25 @@ sudo systemctl restart vncserver@1.service

### How do I use port forwarding via SSH to connect to VNC?

The default port for the first instance of VNC is `5901`. SSH port forwarding is the best solution for accessing the Linux desktop on a cloud machine. This way no additional ports need to be opened in the security group.
The default port for the first instance of VNC is `5901`. SSH port forwarding is the recommended solution for accessing the Linux desktop on a cloud machine. This way, no additional ports need to be opened in the security group.

SSH to your remote Linux machine. Refer to [SSH](/install-guides/ssh/) for additional details.
SSH to your remote Linux machine. See [SSH](/install-guides/ssh/) for additional details.

Substitute your private key file and public IP address of the remote machine.
Substitute your private key file and the public IP address of the remote machine in the following command:

```console
ssh -i <private_key> -L 5901:localhost:5901 ubuntu@<public_ip_address>
```

Once connected via SSH, use a VNC client to connect. [Download](https://sourceforge.net/projects/tigervnc/files/stable/1.12.0/) an install a TigerVNC client for your computer.
Once connected via SSH, use a VNC client to connect. [Download](https://sourceforge.net/projects/tigervnc/files/stable/1.12.0/) and install a TigerVNC client for your computer.

Open the VNC client and enter the following for the VNC server:

Open the VNC client and enter the following for the VNC server.
```console
localhost:5901
```
You will be prompted for the password created earlier with `vncpasswd`.
You will be prompted for the password you created earlier with `vncpasswd`.

A remote Linux Desktop should appear on your local computer. Make sure to close the VNC client first and then exit the SSH connection.
A remote Linux desktop should appear on your local computer. When you are finished, close the VNC client first and then exit the SSH connection.

![Linux desktop #center](/install-guides/_images/xfce4.png)
Loading