---
title: Overriding system settings
description: How to override PiKVM defaults the right way
---

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 `/usr/lib/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:

```yaml
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:

```yaml
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:

```yaml
vnc:
    kvmd:
        timeout: 7.0
```

An important rule is that sections under the same keys **should be merged**:

* **Wrong:**

    ```yaml
    kvmd:
        gpio:
            drivers: ...
    kvmd:
        gpio:
            scheme: ...
    ```

* **Correct:**

    ```yaml
    kvmd:
        gpio:
            drivers: ...
            scheme: ...
    ```

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.

```yaml
# 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:

```yaml
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:

```sh
[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:

![keymap in kvmd](kvmd-hid-keymap.png)

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

List all keymaps in that directory:

```sh
[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:

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

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

![override.yaml in nano](nano-start.png)

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

```yaml
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.

![Save and exit](save-exit.png)

`^` 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:

```yaml
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:

```sh
[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:

```sh
[root@pikvm ~]# reboot
```

Once the device restarts, your changes take effect.


-----
## Keeping customizations atomic

When you apply massive customizations, it may help separating changes into several files to keep them manageable.

To do that, create these YAML files inside the `/etc/kvmd/override.d/` directory. KVMD will apply all configurations in the following order: `main.yaml` -> legacy `auth.yaml` -> `override.d` -> `override.yaml`. Inside the `override.d` directory, KVMD will apply YAML files in alphabetical order, so please pay attention to how you name them.

We recommend sticking with a particular file-naming scheme, e.g. `0000-vendor-otg-serial.yaml`. We do reserve `-vendor-` and `-pikvm-` prefixes for our own future needs, though.

Once you completed the customization and validated newly created/edited files, reboot your PiKVM for the changes to take effect.


-----
## Legacy notes

* Older installations may have used the outdated `/etc/kvmd/auth.yaml` for authorization settings.
    It existed even before the introduction of `/etc/override*` mechanism.
    It has never been recommended for use in this documentation and should contain only the string `{}`, meaning an empty configuration.

    However, if you have used it, you should move your configuration from `/etc/kvmd/auth.yaml`
    somewhere in `/etc/kvmd/override.d` or even `/etc/kvmd/override.yaml`,
    and then delete the source file `/etc/kvmd/auth.yaml`.

    For example, if the `/etc/kvmd/auth.yaml` contained the following text:

    ```yaml
    enabled: false
    ```

    You can move it to `/etc/kvmd/override.d/9999-auth.yaml` and change the nesting of the parameters as follows:

    ```yaml
    kvmd:
        auth:
            enabled: false
    ```

* Early YAML configurations could contain the `!include` directive, which loaded the content of another file to the appropriate level.
    It still works, but has been deprecated and should not be used. Support will be removed in the future.