Skip to content

PiKVM Cheat Sheet

Here are first steps guides for each PiKVM device:

PiKVM V4 Mini & Plus

PiKVM V3

DIY PiKVM V2

DIY PiKVM V1

Basics

Changing PiKVM Passwords

PiKVM comes with the following default passwords:

  • Linux OS-level admin (SSH, console...):

    • Username: root
    • Password: root

  • KVM user (Web Interface, API, VNC...):

    • Username: admin
    • Password: admin
    • No 2FA code

They are two separate accounts with independent passwords.

To change passwords, you will need to use the console access via SSH or the Web Terminal. If you are using the Web Terminal, enter the su - command to get the root access (enter the root user password).

[root@pikvm ~]# rw
[root@pikvm ~]# passwd root
[root@pikvm ~]# kvmd-htpasswd set admin
[root@pikvm ~]# ro

If you require additional user for the Web UI access, use the following:

[root@pikvm ~]# kvmd-htpasswd add <user> # Add a new user with password
[root@pikvm ~]# kvmd-htpasswd del <user> # Remove/delete a user

Optionally you can enable the two-factor authentication for more security.

Changing the VNCAuth key and IPMI password at the first start of PiKVM is not required, since these services are disabled by default. But it is here just so that you remember their existence.

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

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:

    kvmd:
    gpio:
        drivers: ...
kvmd:
    gpio:
        scheme: ...

  • Correct:

    kvmd:
    gpio:
        drivers: ...
        scheme: ...
Updating PiKVM OS

To update, run following commands under the root user:

[root@pikvm ~]# pikvm-update

If you encounter an error like:

[root@pikvm ~]# pikvm-update
bash: pikvm-update: command not found

It's most likely you have an old OS release. You can update the OS as follows:

[root@pikvm ~]# rw
[root@pikvm ~]# pacman -Syy
[root@pikvm ~]# pacman -S pikvm-os-updater
[root@pikvm ~]# pikvm-update

Next time you will be able to use the usual method with pikvm-update.

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 for this.

The default root password is root.

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, 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 and follow existing RPi TTY serial setups.

  2. Install GNU Screen on Linux or macOS host, or Putty 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. Otherwise, head straight to our Discord chat.