public_git
/
pikvm
mirror of https://github.com/pikvm/pikvm.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

update

This commit is contained in:
Maxim Devaev 2026-04-04 00:43:18 +03:00
parent 448df62817
commit daf5d47e4b
4 changed files with 87 additions and 34 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

56
docs/_config.md
View File

@ -18,12 +18,14 @@ search:
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` suffix 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.
For automated deployment, you can put `.*yaml` files into `/etc/kvmd/override.d` directory.
The `override.yaml` file definitions takes precedence over the `override.d` directory
and it is intended for local manual configuration.
A complete list of all parameters can be viewed using the `kvmd -m` command.
A list of your non-default overrides can be viewed using the `kvmd -M` command.
Files with the `*.yaml` suffix 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.
To define the parameters within one section, an indent of 4 spaces is used.
@ -35,24 +37,40 @@ search:
Sections under the same keys **should be merged**:
* **Wrong:**
* **Wrong:**
```yaml
kvmd:
gpio:
drivers: ...
kvmd:
gpio:
scheme: ...
```
```yaml
kvmd:
gpio:
drivers: ...
kvmd:
gpio:
scheme: ...
```
* **Correct:**
* **Correct:**
```yaml
kvmd:
gpio:
drivers: ...
scheme: ...
```
```yaml
kvmd:
gpio:
drivers: ...
scheme: ...
```
For simple config overrides you don't need to use a text editor, you can do this with `kvmd-override` command.
For example, [enabling the microphone audio on PiKVM V3/V4](audio.md#microphone-outgoing-audio):
```console
[root@pikvm ~]# kvmd-override --set otg/devices/audio/enabled=true
```
This puts a config override looks like this:
```yaml
otg:
devices:
audio:
enabled: true
```
In the `/etc/kvmd/meta.yaml` file you can specify some information regarding this PiKVM installation in an almost free YAML format.

51
docs/config.md
View File

@ -14,6 +14,38 @@ Main default settings are stored in `/usr/lib/kvmd/main.yaml`. However, you shou
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.
-----
## A quick way to override simple parameters
Most of the PiKVM configuration consists of simple parameters with plain values (yes/no, a string, a number),
and you can quickly override them using the `kvmd-override` utility.
It reads your `/etc/kvmd/override.yaml` file, carefully adds the desired parameters,
validates the result and writes it to a file back. Also, it keeps all comments in the file.
Thus, for simple operations, you don't need to dive into a text editor and YAML syntax,
and you are guaranteed that the changes will always be syntactically correct.
For example, [enabling the microphone audio on PiKVM V3/V4](audio.md#microphone-outgoing-audio):
```console
[root@pikvm ~]# rw
[root@pikvm ~]# kvmd-override --set otg/devices/audio/enabled=true
[root@pikvm ~]# reboot
```
This puts a config override looks like this:
```yaml
otg:
devices:
audio:
enabled: true
```
That's all! However, it is important to know what is going on under the hood, so we recommend that you read this page to the end :)
-----
## How `override.yaml` is structured
@ -158,7 +190,9 @@ 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.
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.
There is a difference between `kvmd -m` and `kvmd -M`. The first one shows you a full configuration, the second one shows only your non-default overrides. Both work like override validators.
For example, if you accidentally used a semicolon instead of a colon between the key and the value like this:
@ -166,15 +200,15 @@ For example, if you accidentally used a semicolon instead of a colon between the
keymap; /usr/share/kvmd/keymaps/de
```
`kvmd -m` will display this message instead of outputting all configuration entries:
`kvmd -M` will display this message instead of outputting all your changes:
```
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.
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.
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.
-----
@ -200,14 +234,17 @@ Once the device restarts, your changes take effect.
-----
## Keeping customizations atomic
## Atomic configuration deployment
When you apply massive customizations, it may help separating changes into several files to keep them manageable.
When you configure your PiKVM fleet with some automation (for example, using the Ansible), you can put some atomic parts
of your configuration as YAML files into the `/etc/kvmd/override.d` directory. This way you can avoid editing of the `override.yaml`.
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.
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.
Thus, the division is as follows: `/etc/kvmd/override.d` is intended for vendor configs, and `/etc/kvmd/override.yaml` contains a manual tuning of a specific device.
Once you completed the customization and validated newly created/edited files, reboot your PiKVM for the changes to take effect.

10
docs/faq.md
View File

@ -228,7 +228,7 @@ If you run into any issues you can check this page which will list common errors
??? question "I can't find the PiKVM IP address in my network"
Follow the device guide of your PiKVM [here](cheatsheet.md).
Follow the device guide of your PiKVM [here](cheatsheet.md).
??? question "What is the default password? How do I change it?"
@ -240,13 +240,11 @@ If you run into any issues you can check this page which will list common errors
??? question "How do I get root access in the web terminal?"
See [here](auth.md#root-access-in-the-web-terminal).
See [here](auth.md#root-access-in-the-web-terminal).
??? question "Where is the PiKVM configuration located?"
Almost all KVMD (the main daemon controlling PiKVM) configuration files are located in `/etc/kvmd`. You can also find nginx configs and SSL certificates there. KVMD configs use [YAML](https://docs.ansible.com/ansible/latest/reference_appendices/YAMLSyntax.html) syntax. The specific platform parameters can be found in the file `/etc/kvmd/main.yaml` and **you should never edit it**. Use `/etc/kvmd/override.yaml` to redefine the system parameters.
Files that are not recommended for editing have read-only permissions. If you edit any of these files, you will need to manually make changes to them when you upgrade your system. You can view the current configuration and all available KVMD parameters using the command `kvmd -m`.
See [here](config.md)
??? question "I can't edit any file on PiKVM. Why is the system in read-only mode?"
@ -326,7 +324,7 @@ If you run into any issues you can check this page which will list common errors
??? question "How do I completely disable authorization in PiKVM?"
See [here](auth.md).
See [here](auth.md).
??? question "Can I have different hostnames for each of my PiKVMs?"

4
docs/id.md
View File

@ -157,7 +157,7 @@ otg:
revision: '1.00'
```
After changing validate the config using `kvmd -m`. You will see the full config list with changed and default values,
After changing validate the config using `kvmd -M`. You will see a list with your changes and default values,
or a message about configuration error.
If everything is fine, perform the soft reboot.
@ -179,4 +179,4 @@ Assuming you have PiKVM V4 Plus, follow these steps:
5. Run `kvmd-otgconf --import-usb-ids` as root on the PiKVM. This will fetch IDs of the connected physical USB devices and place them into the `/etc/kvmd/override.yaml` configuration file.
6. Run `ro` to switch to read-only mode.
7. Run `reboot` to reboot your PiKVM and apply newly the added customization.
8. Reconnect the host's display and keyboard/mouse back to the host.
8. Reconnect the host's display and keyboard/mouse back to the host.