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. Normally, it should be possible to simply run ssh root@pikvm in a terminal window to connect to your PiKVM. However, this can fail for various reasons. In that case, you will have to connect using PiKVM's IP address.

To connect to PiKVM via SSH, do this:

  1. Discover PiKVM's IP address in the local network. There are several ways to do that:

    • Open the web interface of your router and find the list of issued IP addresses there.
    • Linux-only: install and run arp-scan: sudo arp-scan --localnet.
    • Linux, MacOS, Windows: Download and run Angry IP Scanner.
    • Windows PowerShell: Use the arp -a command.

    In each case, look for the entry that says "Raspberry Pi Trading Ltd" and copy its IP address to the clipboard. Let's assume that the IP address is 192.168.0.100.

  2. Run the SSH client to connect to PiKVM:

    • Linux, MacOS: Open any terminal application and run: ssh root@192.168.0.100.
    • Windows: Use PuTTY for this.

  3. Submit your root user credentials. The default password is root. If you haven't changed it, you absolutely should do it.

  4. You should now be able to see and interact with the serial port. All the system tools in PiKVM will be available in the terminal window. Once you are done, type exit and press Enter, or simply press Ctrl+d to terminate the session.

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 universal asynchronous receiver / transmitter (UART) console from your host computer:

    • 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 the IOIOI port on V4 (or the 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 operating systems 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 picocom on a Linux or a macOS host (available in Homebrew and MacPorts), or Putty on Windows.

  3. Identify the port that your operating system exposes for connecting to the PiKVM.

    • Windows: look this up in the Device Manager

    • Linux: open a terminal program, run sudo dmesg | grep ttyand look for a message like this:

    [14362.388405] usb 1-2: cp210x converter now attached to ttyUSB0

    This means you will need to use /dev/ttyUSB0.

    • macOS: open the terminal and list all USB serial devices with ls /dev/cu.usbserial-*. Look for a device that contains cu.usbserial, e.g. /dev/cu.usbserial-FT0RVWSW.

  4. Connect via the serial port:

    • Windows: select the COM port in Putty and use the 115200 baud rate, then connect.

    • Linux/macOS: open your terminal program and run sudo picocom -b 115200 $USB_SERIAL_DEVICE where $USB_SERIAL_DEVICE is the device you looked up, e.g. /dev/ttyUSB0 on Linux or /dev/cu.usbserial-FT0RVWSW on macOS.

    After running the command, press Enter to get to a login prompt.

  5. Submit your root user credentials.

  6. You should now be able to see and interact with the serial port. All the system tools in PiKVM will be available in the terminal window. Once you are done, press Ctrl+a and then immediately Ctrl+x to terminate the session.

Getting User Support

If something doesn't work, check out our FAQ. Otherwise, head straight to our Discord chat.