This commit is contained in:
Maxim Devaev 2025-04-30 04:31:54 +03:00
parent c9b93ba95c
commit b396ff1a99
11 changed files with 185 additions and 316 deletions

View File

@ -144,3 +144,7 @@ ol li::marker {
.md-typeset li .admonition:only-child {
margin: 0;
}
.md-button--stretch {
width: 100%;
}

47
docs/_config.md Normal file
View File

@ -0,0 +1,47 @@
---
search:
exclude: true
---
??? note "Configuring PiKVM OS"
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.
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.
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.
To define the parameters within one section, an indent of 4 spaces is used.
Comments starts with the `#` symbol.
!!! warning "Only 4 spaces should be used for indentation"
Be careful when editing YAML and follow this rule.
Invalid indentation or tabs instead of spaces will cause an error when starting the services.
Sections under the same keys **should be merged**:
* **Wrong:**
```yaml
kvmd:
gpio:
drivers: ...
kvmd:
gpio:
scheme: ...
```
* **Correct:**
```yaml
kvmd:
gpio:
drivers: ...
scheme: ...
```

View File

@ -1,56 +0,0 @@
---
search:
exclude: true
---
1. Double-check the correct assembly of the device, and make sure that you have connected
all the necessary cables to the host: USB, HDMI and ATX.
2. [Flash the memory card with PiKVM OS](https://docs.pikvm.org/flashing_os){target=_blank}
and insert it to Raspberry Pi.
3. **Carefully read and follow [the First Steps Guide](first_steps.md){target=_blank}.**<br>
It describes how to perform the first power-on, how to find PiKVM on the network, login, change passwords, and so on.<br>
**Follow the steps described there and come back to this page.**
4. **Just reminding again:**
{!_passwd.md!}
5. Try to manage the computer using PiKVM with the Web Interface.<br>
Make sure that you get an image and both keyboard and mouse are working.
If something doesn't work, check out our [FAQ](faq.md) (it's really useful).
If nothing helped, you can get support in our [Discord chat](https://discord.gg/bpmXfz5).
6. ??? note "Note for the HDMI-USB dongle"
Many USB video capture devices tell the server's video card that the HDMI cable is supposedly disconnected.
This may lead to the fact that if you boot the server without an active stream, the server will not detect
your capture card. This is easy to fix:
* Switch filesystem to RW-mode:
```console
[root@pikvm ~]# rw
```
* Edit file `/etc/kvmd/override.yaml` and add these lines:
```yaml
kvmd:
streamer:
forever: true
cmd_append: [--slowdown]
```
* Finish:
```console
[root@pikvm ~]# ro
[root@pikvm ~]# systemctl restart kvmd
```
* Check that everything is working.
7. Configure access to PiKVM from the Internet using [port forwarding](https://docs.pikvm.org/port_forwarding)
or [Tailscale VPN](https://docs.pikvm.org/tailscale), if you need it.
8. Explore the features of PiKVM using the site's table of contents and have fun!

View File

@ -4,7 +4,7 @@ search:
---
??? danger "✮ ✮ ✮ CHANGE THE PASSWORDS! ✮ ✮ ✮"
??? note "Changing PiKVM Passwords"
PiKVM comes with the following default passwords:
* **Linux OS-level admin** (SSH, console...):

View File

@ -4,7 +4,7 @@ search:
---
??? example "Updating PiKVM OS"
??? note "Updating PiKVM OS"
To update, run following commands under the `root` user:

61
docs/cheatsheet.md Normal file
View File

@ -0,0 +1,61 @@
---
title: PiKVM Cheat Sheet
description: "Getting started with PiKVM"
---
# PiKVM Cheat Sheet
Here are **first steps guides** for each PiKVM device:
<div class="grid" markdown>
[PiKVM V4 Mini & Plus](v4.md){ .md-button .md-button--stretch }
[PiKVM V3](v3.md){ .md-button .md-button--stretch }
[DIY PiKVM V2](v2.md){ .md-button .md-button--stretch }
[DIY PiKVM V1](v1.md){ .md-button .md-button--stretch }
</div>
-----
## Quick Tips
{!_passwd.md!}
{!_config.md!}
{!_update_os.md!}
??? note "Connect to PiKVM via SSH"
SSH is the most common remote access method in the Linux world. PiKVM is accessible via SSH. This method is used to manage the device:
* **Linux, MacOS:** Open any terminal application and run: `ssh root@192.168.0.100` or `ssh root@pikvm`.
* **Windows:** Use [PuTTY](https://www.putty.org/) for this.
**The default `root` password is `root`.**
??? note "Connect to PiKVM via serial console"
A serial console is a convenient and fast way to connect to PiKVM when there is no network, or get boot logs and a console if something goes wrong.
1. Connect to the physical UART console:
* On PiKVM V3 or V4, you have a built-in USB-UART adapter in your device. Just disconnect the OTG cable and place the USB-C end into `IOIOI` port on V4 (or `CON` port on V3). Place the USB-A end into the port you want serial to be accessed, typically done on the host. If you have a Windows host, you may need to install this [driver](https://www.silabs.com/developers/usb-to-uart-bridge-vcp-drivers), other OS's may not need one.
* On DIY PiKVM V1 or V2, you'll need to get the right TTY to USB cable, we recommend the [RPi Debug Probe](https://www.pishop.us/product/raspberry-pi-debug-probe/) and follow existing RPi TTY serial setups.
2. Install GNU Screen on Linux or macOS host, or [Putty](https://www.putty.org/) on Windows.
3. Select the COM port in Putty (you can verify this looking in Device Manager), then select **115200** baud, or use `screen /dev/ttyUSB0 115200` for other OS's
4. You should now be able to see and interact with the Serial Port.
-----
## Getting User Support
If something doesn't work, check out our [FAQ](faq.md). Otherwise, head straight to our [Discord chat](https://discord.gg/bpmXfz5).

View File

@ -1,45 +0,0 @@
---
title: Structure of configuration files
description: "How PiKVM configuration files are structured"
---
# Structure of configuration files
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.
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.
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.
To define the parameters within one section, an indent of 4 spaces is used.
Comments starts with the `#` symbol.
!!! warning "Only 4 spaces should be used for indentation"
Be careful when editing YAML and follow this rule.
Invalid indentation or tabs instead of spaces will cause an error when starting the services.
??? example "Sections under the same keys should be merged"
* **Wrong:**
```yaml
kvmd:
gpio:
drivers: ...
kvmd:
gpio:
scheme: ...
```
* **Correct:**
```yaml
kvmd:
gpio:
drivers: ...
scheme: ...
```

View File

@ -1,209 +0,0 @@
---
title: First steps with PiKVM
description: "Getting started with PiKVM: power on and access the remote host"
---
# First steps
This guide is written primarily with V3 and V4 Mini/Plus in mind and covers the basic steps: what ports to connect and how to access a remote host that your PiKVM is connected to.
-----
## Wiring
Let's connect all the wires before you power up the device.
1. Connect **Ethernet** to the network (**not applicable** to DIY PiKVM built with Pi Zero 2).
2. Connect the **HDMI input** and the **OTG** port (USB emulation) to the remote computer.
3. Optionally, connect the **[ATX port](atx_board.md)** to control the power of the remote host.
## Power up
1. Optional: [setting up Wi-Fi or static IP](on_boot_config.md) before booting.<br>
*Remember that there is nothing more reliable than wired Ethernet.*
2. **Power up the device.**
3. **Do not turn off the device until it's fully booted for the first time.**<br>
*After turning on the power, PiKVM OS will generate unique SSH keys and certificates
and perform all necessary operations on the memory card. It takes a few minutes.*
## Connect and set up
### Configure the display
The operating system on your remote computer will treat PiKVM as an additional display and use it in the Extend mode by default. That's why you will see an empty desktop when you first connect.
To avoid that, go to the display settings in your remote computer's operating system and enable the mirror mode for the external screen that you operating system identifies as PiKVM. Refer to your operating system's documentation on that.
### Access PiKVM
By default, PiKVM receives a dynamic IP address via DHCP. PiKVM V3 and V4 will show it in the top row of the OLED display:
```console
192.168.0.100
(|) iface: eth0
cpu: 1% mem: 13%
```
??? example "PiKVM without OLED: finding device in the network"
To determine the IP address of your PiKVM, use one of the following methods:
* **Common way:** Open the web interface of your router and find the list of issued IP addresses there.
* **Linux-only:** Use command `arp-scan --localnet`.
* **Linux, MacOS, Windows:** Download and run [Angry IP Scanner](https://angryip.org).
* **Windows PowerShell:** Use command `arp -a`.
In order to find PiKVM using the ARP commands, you need to look for the following MACs: `B8:27:EB`, `DC:A6:32` or `E4:5F:01`.
Let's assume that PiKVM has received the address `192.168.0.100` and has also been assigned a hostname `pikvm`.
Type the URL in the browser's address bar and press **Enter**: https://192.168.0.26/ or https://pikvm/.
![Login screen](../v4/login-prompt.png)
Submit the default credentials and click **Login**:
- Username: `admin`
- Password: `admin`
- 2FA Code: disabled by default, skip this field
You will see the initial dashboard screen of the PiKVM where you can access the remote desktop, connect to the PiKVM command line, or log out:
![Initial UI](../v4/initial-ui.png)
### Change the default passwords
For security's sake, it's best to change the default passwords immediately after running PiKVM for the first time. To do that:
1. On the initial dashboard screen, click the **Terminal** button to open the web terminal. You will see this command line interface:
![MISSING SCREENSHOT](../v4/pikvm-web-terminal-start.png)
2. Gain superuser privileges:
```console
$ su -
```
When prompted for password, use `root`.
3. Run `rw` to change the access to the SD card to the write mode:
```console
[root@pikvm ~]# rw
```
4. Change the password for the superuser:
```console
[root@pikvm ~]# passwd root
```
Submit the new password, retype it the second time to confirm, press **Enter**, and you should see this:
```console
passwd: password updated successfully
```
5. Change the password for web access:
```console
[root@pikvm ~]# kvmd-htpasswd set admin
```
Submit the new password, retype it the second time to confirm, and press **Enter**.
6. Run `ro` to change the access to the SD card back to the read-only mode:
```console
[root@pikvm ~]# ro
```
7. Press **Ctrl+D** or type "exit" and press **Enter** to drop the root privileges.
8. Go back one page in the browser. You should be back to the initial dashboard screen.
### Access the remote system
1. On the initial dashboard screen, click the **KVM** button to access the remote desktop.
2. You should now see the host system's display and interact with it remotely using a keyboard and a mouse.
![Work remotely](../v4/remote-screen.png)
There are two alternative ways to connect to the PiKVM:
??? example "Connect to PiKVM via SSH"
SSH is the most common remote access method in the Linux world. PiKVM is accessible via SSH. This method is used to manage the device:
* **Linux, MacOS:** Open any terminal application and run: `ssh root@192.168.0.100` or `ssh root@pikvm`.
* **Windows:** Use [PuTTY](https://www.putty.org/) for this.
**The default `root` password is `root`.**
??? example "Connect to PiKVM via serial console"
A serial console is a convenient and fast way to connect to PiKVM when there is no network, or get boot logs and a console if something goes wrong.
1. Connect to the physical UART console:
* On PiKVM V3 or V4, you have a built-in USB-UART adapter in your device. Just disconnect the OTG cable and place the USB-C end into `IOIOI` port on V4 (or `CON` port on V3). Place the USB-A end into the port you want serial to be accessed, typically done on the host. If you have a Windows host, you may need to install this [driver](https://www.silabs.com/developers/usb-to-uart-bridge-vcp-drivers), other OS's may not need one.
* On DIY PiKVM V1 or V2, you'll need to get the right TTY to USB cable, we recommend the [RPi Debug Probe](https://www.pishop.us/product/raspberry-pi-debug-probe/) and follow existing RPi TTY serial setups.
2. Install GNU Screen on Linux or macOS host, or [Putty](https://www.putty.org/) on Windows.
3. Select the COM port in Putty (you can verify this looking in Device Manager), then select 115200, or use `screen /dev/ttyUSB0 115200` for other OS's
4. You should now be able to see and interact with the Serial Port.
## Further steps
1. **Get to know PiKVM OS**: read [this help section](webui.md) to better understand all the possibilities of the web user interface.
2. **Update and customize the system**:
- [Update](_update_os.md) the PiKVM operating system.
- [Harden the remote access](auth.md) by enabling 2FA and setting session expiration time.
- Configure access to PiKVM from the Internet using [port forwarding](port_forwarding.md) or [Tailscale VPN](tailscale.md).
- Enable a microphone for [two-way audio](audio.md) (**only for PiKVM V3 and V4 Mini/Plus**).
- Enable [HDMI pass-through](pass.md) (**only for PiKVM V4 Plus**)..
3. **Configure hardware**:
- Set up [ATX connection](atx_board.md).
- Install and set up [Wi-Fi antenna](wifi.md).
- Install and set up [LTE/5G modem](modem.md) (**only for PiKVM V4 Plus**).
- Choose Fahrenheit over Celsius to display on the OLED:
??? note "How to set up Fahrenheit"
Create a directory for a configuration file:
```console
[root@pikvm ~]# mkdir -p /etc/systemd/system/kvmd-oled.service.d
```
Create file `/etc/systemd/system/kvmd-oled.service.d/override.conf`:
```ini
[Service]
ExecStart=
ExecStart=/usr/bin/kvmd-oled --clear-on-exit --fahrenheit
```
Then run `systemctl restart kvmd-oled`. In some cases, if you still do not see Fahrenheit being displayed, reboot the device.
## Basic troubleshooting
{!_basic_troubleshooting.md!}
## Getting user support
If something doesn't work, check out our [FAQ](faq.md). Otherwise, head straight to our [Discord chat](https://discord.gg/bpmXfz5).

View File

@ -120,7 +120,7 @@ description: Getting started with PiKVM V1
## Wiring
!!! warning
Double check that the circuit is assembled correctly to avoid any damage of the hardware.
Double check that the circuit is assembled correctly to avoid any damage of the hardware.
PiKVM V1 requires several items available separately:
@ -151,6 +151,14 @@ After turning on the power, PiKVM OS generates unique SSH keys and certificates
**Do not turn off the device until it's fully booted for the first time.**
-----
## Configure the display
The operating system on your remote computer will treat PiKVM as an additional display and use it in the Extend mode by default. That's why you will see an empty desktop when you first connect.
To avoid that, go to the display settings in your remote computer's operating system and enable the mirror mode for the external screen that you operating system identifies as PiKVM. Refer to your operating system's documentation on that.
-----
## Access PiKVM
@ -252,7 +260,32 @@ To do that:
- Get to know PiKVM OS: read [this help section](webui.md) to better understand all the possibilities of the web user interface.
- Set up [ATX connection](atx_board.md) if you need to control the power of the remote system.
- ??? note "Note for the HDMI-USB dongle"
Many USB video capture devices tell the server's video card that the HDMI cable is supposedly disconnected.
This may lead to the fact that if you boot the server without an active stream, the server will not detect
your capture card. This is easy to fix:
* Switch filesystem to RW-mode:
```console
[root@pikvm ~]# rw
```
* Edit file `/etc/kvmd/override.yaml` and add these lines:
```yaml
kvmd:
streamer:
forever: true
cmd_append: [--slowdown]
```
* Finish:
```console
[root@pikvm ~]# ro
[root@pikvm ~]# systemctl restart kvmd
```
* Check that everything is working.
-----

View File

@ -182,6 +182,14 @@ After turning on the power, PiKVM OS generates unique SSH keys and certificates
**Do not turn off the device until it's fully booted for the first time.**
-----
## Configure the display
The operating system on your remote computer will treat PiKVM as an additional display and use it in the Extend mode by default. That's why you will see an empty desktop when you first connect.
To avoid that, go to the display settings in your remote computer's operating system and enable the mirror mode for the external screen that you operating system identifies as PiKVM. Refer to your operating system's documentation on that.
-----
## Access PiKVM
@ -283,7 +291,32 @@ To do that:
- Get to know PiKVM OS: read [this help section](webui.md) to better understand all the possibilities of the web user interface.
- Set up [ATX connection](atx_board.md) if you need to control the power of the remote system.
- ??? note "Note for the HDMI-USB dongle"
Many USB video capture devices tell the server's video card that the HDMI cable is supposedly disconnected.
This may lead to the fact that if you boot the server without an active stream, the server will not detect
your capture card. This is easy to fix:
* Switch filesystem to RW-mode:
```console
[root@pikvm ~]# rw
```
* Edit file `/etc/kvmd/override.yaml` and add these lines:
```yaml
kvmd:
streamer:
forever: true
cmd_append: [--slowdown]
```
* Finish:
```console
[root@pikvm ~]# ro
[root@pikvm ~]# systemctl restart kvmd
```
* Check that everything is working.
-----

View File

@ -71,6 +71,8 @@ plugins:
"4g.md": "modem.md"
"usb_dynamic.md": "usb.md"
"webrtc.md": "video.md"
"first_steps.md": "cheatsheet.md"
"cheat_sheet.md": "cheatsheet.md"
- glightbox:
touchNavigation: false
loop: false
@ -94,7 +96,6 @@ nav:
- "Getting started":
- "First steps": first_steps.md
- "Web UI Overview": webui.md
- "Configure PiKVM OS": config.md
- "Authentication & 2FA": auth.md
- "FAQ & Troubleshooting": faq.md
- "Flashing OS": flashing_os.md