---
title: VNC
description: How to enable and configure VNC for accessing your PiKVM
---

# VNC

As an alternative to the Web UI, a regular VNC client can be used to
access to the PiKVM.

The main advantage of VNC over the browser is the ability to expand the
image to the full screen, as well as complete interception of all
keyboard shortcuts. In some cases, VNC will be more responsive than the
browser, especially on weak client computers.

!!! warning
    Don't use VNC without X.509 or TLS encryption on untrusted networks!
    Otherwise your password will be transmitted over the network in plain text.
    Unfortunately, this is the reality of the VNC protocol.
    
!!! note
    The performance of VNC on PiKVM does not make sense to compare with regular VNC servers
    or a similar remote access tool at the OS level.
    PiKVM will run a little slower due to the fact that access is done at the hardware level.

    A typical video processing chain looks like this:

    * Regular VNC/RDP/TeamViewer/Etc: `OS -> Remote access server -> Network -> Client`.
    * PiKVM: `OS -> Video card -> PiKVM video capture -> PiKVM server -> Network -> Client`.


-----
## Enabling VNC on the PiKVM side

1. The recommended client is [TigerVNC](https://github.com/TigerVNC/tigervnc/releases).

2. Switch the PiKVM filesystem to read-write mode using command `rw`.

3. ??? tip "Optional for *non-TigerVNC* clients: Change the keybobard layout for non-US keyboard"

        This step is nessessory if you're using a client that does not support
        the direct keyboard access.

        In this case you can force the client layout in `/etc/kvmd/override.yaml`:

        ```yaml
        vnc:
            keymap: /usr/share/kvmd/keymaps/ru
        ```

        All available keymaps are located in `/usr/share/kvmd/keymaps`:

        <img src="keymaps.png" />

4. ??? warning "Optional for *non-TigerVNC* and NOT RECOMMENDED: Enable VNCAuth method"

        This step is nessessory if you're using a client that does not support the user/password
        auth method like TightVNC (don't confuse it with TigerVNC).

        In this case you can enable VNCAuth passphrases mode in `/etc/kvmd/override.yaml`:

        ```yaml
        vnc:
            auth:
                vncauth:
                    enabled: true
        ```

        To set passphrases edit the file `/etc/kvmd/vncpasswd`.

        **But once again: THIS IS AN UNSAFE AUTHORIZATION METHOD and it is better to use TigerVNC.**

5. Enable `kvmd-vnc` daemon. VNC will be available on the port 5900: `systemctl enable --now kvmd-vnc`.

6. Switch filesystem back to read-only: `ro`.

!!! note
    With enabled [2FA](auth.md#two-factor-authentication), you will need to append the one-time code
    to the password without spaces. That is, if the password is `foobar` and the code is `123456`,
    then the string `foobar123456` should be used as a password.


-----
## Configuring the client

We recommend [TigerVNC](https://tigervnc.org) for a better experience on a desktop.

If you're using PiKVM V3+ or DIY based on CSI bridge, you can try
the [latest version (>= 1.13.0) of TigerVNC with H.264 support](https://github.com/TigerVNC/tigervnc/releases).
It will improve performance and save traffic.

H.264 video mode is available in binary builds for Windows, for other OS it needs to be compiled manually
(`ffmpeg` libraries required to build).

Here are our recommended settings for TigerVNC:

| Compression tab | Security tab |
|-----------------|--------------|
| <img src="tigervnc_compression.png" width="300" /> | <img src="tigervnc_security.png" width="300" /> |
| If your client does not support H.264, choose **Tight** | |

For iOS and Android the recommended application is bVNC:

* [Google Play](https://play.google.com/store/apps/details?id=com.iiordanov.bVNC)
* [App Store](https://apps.apple.com/us/app/bvnc-pro/id1506461202)


-----
## Hotkeys

Inside a VNC session, you can use several hotkeys related to PiKVM, independent of the VNC client.
Hotkeys are triggered by quickly pressing and releasing each key sequentially (that is, you don't need to hold them down like `Ctrl+Alt+Del`).

* `LeftAlt, LeftAlt, P` - Paste text from the clipboard.<br>
    *PiKVM does not have access to the clipboard, so pasting works as if you had typed this text. ASCII always works, layout switching is not supported. To type text in a different language, you need the layout on the host to match the one you are using (and keymap is also configured as described above for some VNC clients)*

* `LeftAlt, LeftAlt, 1` (1-8) - Switch to channel 1 with [PiKVM Switch](switch.md), when you have one or two switches.

* `LeftAlt, LeftAlt, 3, 2` - Switch to unit 3, channel 2 of [PiKVM Switch](switch.md) chain, when you have more than two switches.<br>
    *Single-key port numbers do not work if there are more than two candles.*


-----
## Unsupported clients

* **RealVNC** - Does not support most widely used open VNC protocol extensions.
* **Remmina** - Slightly imperfect algorithms for matching settings with the server, we are working on it.
* **Guacamole** - Incorrectly implements vencrypt, no JPEG compression.
* **Vinagre** - Incorrectly implements vencrypt, dead.