pikvm/docs/vnc.md

# VNC

As an alternative to the web interface, 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 keys. 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. Switch the PiKVM filesystem to read-write mode using command `rw`.

2. *Optional:* Change client's keyboard layout if you're using an non-US keyboard.
    To do this edit file `/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" />

3. *Optional and not recommended:* This step is not nessessory if you're using TigerVNC
    as it uses the Web UI login and password.
    Some other VNC clients (for example TightVNC) can't use this type of authentication.
    In this case you can enable single 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**, it is better to use another client,
    for example, the already recommended TigerVNC.

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

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

    Also note that `vncauth` (step 3) will not work with 2FA.


-----
## Configuring the client

We recommend [TigerVNC](https://tigervnc.org) for a better experience on 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)


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