From 257bcb7286315c8f6eacf025ac1c42b9b5ae806a Mon Sep 17 00:00:00 2001 From: Maxim Devaev Date: Wed, 23 Jul 2025 15:39:07 +0300 Subject: [PATCH] update --- docs/_config.md | 11 ++++++----- docs/config.md | 20 +++++++++++++++++++- 2 files changed, 25 insertions(+), 6 deletions(-) diff --git a/docs/_config.md b/docs/_config.md index 6bf55330..c62903d3 100644 --- a/docs/_config.md +++ b/docs/_config.md @@ -6,14 +6,13 @@ search: ??? note "Configuring PiKVM OS" + The following is a brief guide to configuring PiKVM. For more information (including the basics of YAML syntax and how to use a text editor in the Linux console), please refer to [this page](config.md). + Most of the PiKVM configuration files are located in the `/etc/kvmd` directory. - The `/etc/kvmd/main.yaml` file defines the platform config and **you should never edit it**. To redefine system parameters use the file `/etc/kvmd/override.yaml`. All other files that are also not recommended for editing have read-only permissions. + The `/etc/kvmd/main.yaml` file defines the platform config and **you should never edit it**. To redefine system parameters use the file `/etc/kvmd/override.yaml`. All other files that are also not recommended for editing have read-only permissions. You can also create several files with the `.*yaml` extension and put then into `/etc/kvmd/override.d` directory to split your customization into logical parts. The `override.yaml` file definitions takes precedence over the `override.d` directory. - In the `/etc/kvmd/meta.yaml` file you can specify some information regarding the host that this PiKVM manages. - - !!! tip - A complete list of all parameters can be viewed using the `kvmd -m` command. + A complete list of all parameters can be viewed using the `kvmd -m` command. Files with the suffix `*.yaml` uses the [YAML syntax](https://docs.ansible.com/ansible/latest/reference_appendices/YAMLSyntax.html) and describes a parameter tree with key-value pairs of different types. @@ -45,3 +44,5 @@ search: drivers: ... scheme: ... ``` + + In the `/etc/kvmd/meta.yaml` file you can specify some information regarding this PiKVM installation in an almost free YAML format. diff --git a/docs/config.md b/docs/config.md index b1df6bdc..a2a2311a 100644 --- a/docs/config.md +++ b/docs/config.md @@ -5,12 +5,16 @@ 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. @@ -62,6 +66,8 @@ vnc: 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: @@ -70,6 +76,8 @@ For safety reasons, access to the file system of PiKVM OS is read-only by defaul [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: @@ -88,6 +96,8 @@ bepo da de-ch en-us en-us-colemak et fo fr-be fr-ch hu it lt mk 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: @@ -110,6 +120,8 @@ kvmd: 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. @@ -120,6 +132,8 @@ Now, you need to save the configuration file and exit. Nano displays hints on th 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. @@ -140,6 +154,8 @@ If you see any errors in the output, fix them and run `kvmd -m` again to verify 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: @@ -148,6 +164,8 @@ Before you go to the next step, change the file system access mode to read-only. [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: @@ -156,4 +174,4 @@ There are close to a dozen various system daemons that depend on configuration s [root@pikvm ~]# reboot ``` -Once the device restarts, your changes take effect. \ No newline at end of file +Once the device restarts, your changes take effect.