diff --git a/docs/override.md b/docs/override.md new file mode 100644 index 00000000..21acb722 --- /dev/null +++ b/docs/override.md @@ -0,0 +1,159 @@ +--- +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 `/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: + +```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 pair 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: + +```yaml +vnc: + kvmd: + timeout: 7.0 +``` + +Anything that start 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. + +## 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's 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, you changes take effect. \ No newline at end of file diff --git a/docs/override/kvmd-hid-keymap.png b/docs/override/kvmd-hid-keymap.png new file mode 100644 index 00000000..e7b38334 Binary files /dev/null and b/docs/override/kvmd-hid-keymap.png differ diff --git a/docs/override/nano-start.png b/docs/override/nano-start.png new file mode 100644 index 00000000..32662a2f Binary files /dev/null and b/docs/override/nano-start.png differ diff --git a/docs/override/save-exit.png b/docs/override/save-exit.png new file mode 100644 index 00000000..ef9d93d4 Binary files /dev/null and b/docs/override/save-exit.png differ diff --git a/mkdocs.yml b/mkdocs.yml index a9021c21..d2899cfc 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -130,6 +130,7 @@ nav: - "Serial-over-USB": usb_serial.md - "GPIO (pins, relays, lamps, etc)": gpio.md - "Advanced usage": + - "Overriding system defaults": override.md - "On-boot configuration": on_boot_config.md - "Using VNC": vnc.md - "Multiport KVM-over-IP": multiport.md