Overriding system defaults

PiKVM OS has various low-level settings you can customize: timeout for the kvmd daemon, default keymap for the emulated keyboard, scroll rate for VNC sessions, logs formatting, etc. To do that, you need to override default settings.

How overrides work in PiKVM OS

Main default settings are stored in /etc/kvmd/main.yaml. However, you should never edit that file. To override these and other defaults, you need to edit /etc/kvmd/override.yaml instead.

PiKVM OS applies settings from main.yaml first and then applies anything it finds in override.yaml. This approach helps keeping defaults and customizations safely separate from each other.

How override.yaml is structured

The /etc/kvmd/override.yaml file has YAML syntax. All configurations are stored as key-value pairs.

Consider this example:

file: /etc/kvmd/ipmipasswd

Here, file is a key, or the name of a configuration entry, and /etc/kvmd/ipmipasswd is the value. Keys and values are separated by a semicolon.

YAML files can have nested key-value pairs:

ipmi:
    auth:
        file: /etc/kvmd/ipmipasswd

To nest key-value pairs correctly, use four spaces rather than tabulation for indentation.

There is no need to copy and paste an entire configuration tree of key-value pairs to change just one setting. For example, if you want to change just the kvmd timeout, you only need the timeout setting and its parent keys, kvmd and vnc:

vnc:
    kvmd:
        timeout: 7.0

Anything that starts with # is considered a comment. This is useful when you need to document your customizations, e.g., write down the rationale for changing a particular default.

You can start new lines with comments if you need to write a longer explanation.

# 2025-05-08: changed the default timeout to 7.0 after some troubleshooting.
vnc:
    kvmd:
        timeout: 7.0

You can also write inline comments like this:

vnc:
    kvmd:
        timeout: 7.0 #this seems to work better

Let's practice changing a default setting by switching to a German keyboard map by default. This is just an example to explain how overrides work.

Change file system access to read-write

For safety reasons, access to the file system of PiKVM OS is read-only by default. You need to temporarily change it to read-write to be able to save changes to the configuration file. To do it, use the rw command:

[root@pikvm ~]# rw

Identify the configuration entry

Before you start editing, you need to find the setting you will need to override. Run kvmd -m to look up configuration entries you can redefine. This command will print the entire list. We need the keymap setting somewhere in the kvmd group:

So, the correct hierarchy is kvmd/hid/keymap, and the path to keymaps is /usr/share/kvmd/keymaps/.

List all keymaps in that directory:

[root@pikvm ~]# ls /usr/share/kvmd/keymaps/
ar    cz  de     en-gb  en-us-altgr-intl  es  fi  fr     fr-ca  hr  is  ja  lv  nl  pl  pt-br  sl  th
bepo  da  de-ch  en-us  en-us-colemak     et  fo  fr-be  fr-ch  hu  it  lt  mk  no  pt  ru     sv  tr

You will need de, which is a two-letter code for German.

Edit override.yaml

Now, let's open override.yaml for editing. PiKVM ships with both nano and vim. We generally recommend nano over vim for new users:

[root@pikvm ~]# nano /etc/kvmd/override.yaml

nano has a console user interface, so it displays the text file right in the terminal window:

Scroll down to the bottom of the file (use Ctrl+End, PageDown, or ArrowDown keys). Type this:

kvmd:
    hid:
        keymap: /usr/share/kvmd/keymaps/de

Don't forget to indent each child key with four spaces.

Save the file

Now, you need to save the configuration file and exit. Nano displays hints on the most important keyboard shortcuts at the bottom of its window.

^ stands for Ctrl on Windows and Linux and for Cmd on macOS. M stands for Alt.

Press Ctrl+O to save the configuration file and then Ctrl+X to quit nano.

Validate the configuration

Before attempting to make your changes take effect, you should always validate override.yaml. To do that, run kvmd -m. If there are any syntax errors, kvmd will complain about them.

For example, if you accidentally used a semicolon instead of a colon between the key and the value like this:

keymap; /usr/share/kvmd/keymaps/de

kvmd -m will display this message instead of outputting all configuration entries:

ConfigError: The node 'vnc' must be a dictionary

If you see any errors in the output, fix them and run kvmd -m again to verify that the error is gone.

Note that kvmd -m does not validate configuration entries for correct key names. So if your changes don't work, that's #1 thing to check for when troubleshooting.

Change access to read-only

Before you go to the next step, change the file system access mode to read-only. To do that, run the ro command:

[root@pikvm kvmd-webterm]# ro

Reboot your PiKVM

There are close to a dozen various system daemons that depend on configuration settings. The easiest way to apply your changes is to simply reboot your PiKVM:

[root@pikvm ~]# reboot

Once the device restarts, your changes take effect.