Skip to content

First steps

First power on

  1. Optional: setting up Wi-Fi or static IP before booting.
    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.
    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.

Getting access to PiKVM

By default, PiKVM receives a dynamic IP address via DHCP. PiKVM V3+ devices show it on the built-in OLED display.

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

For future examples, let's assume that PiKVM has received the address 192.168.0.100, which you have successfully detected using the instructions above. The device has also been assigned a hostname pikvm.

Access to PiKVM Web Interface

We recommend using the latest Google Chrome or Chromium, as they support the largest number of PiKVM features. Safari and Firefox are in second place. Internet Explorer and the pre-Chromium versions of Microsoft Edge are not supported.

For the first time, it is better to use a browser without extensions or incognito mode, as some extensions may disrupt the work of PiKVM.

Type the URL in the browser's address bar and press Enter: https://192.168.0.100/ or https://pikvm/.

The default user is admin, the password is also admin, and no 2FA code.

After logging in, you will get access to the menu with the main functions. Using the Web Terminal, you can change system settings and passwords.

The latest versions of Google Chrome on Mac OS do not allow access to the page with a self-signed certificate, which is used in PiKVM by default. You can proceed by typing thisisunsafe and Chrome will then load the page.

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

Access 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, or use screen /dev/ttyUSB0 115200 for other OS's

  4. You should now be able to see and interact with the Serial Port.

Obtaining root access

  • If you have logged in via SSH, then most likely you are already root.
  • To get root in the Web Terminal, use command su - and enter the root password.

PiKVM OS (and the underlying Arch Linux ARM upstream) often receives software updates. After installation, it makes sense to update the OS. It's best to do this now, when you have physical access to the device, because if something goes wrong (for example, the power goes out during the update or some upstream change), you will need to reflash the memory card.

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.

And now, after all...

✮ ✮ ✮ CHANGE THE PASSWORDS! ✮ ✮ ✮

PiKVM comes with the following default passwords:

  • Linux admin (SSH, console, etc.): user root, password root.
  • PiKVM Web Interface (API, VNC...): user admin, password admin, no 2FA code.

These are two separate entities with independent accounts.

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 set <user> # Set a new user with password or change of an existing one
[root@pikvm ~]# kvmd-htpasswd del <user> # Remove/delete a user

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

Changing the VNCAuth passkey 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

Most of the PiKVM settings are done through configuration files. All configuration changes must be made from under the root user (i.e. the administrator).

The PiKVM memory card is mounted in read-only mode. It protects the filesystem from damage in case of sudden power outage. To edit any files and make changes, it is necessary to remount the file system to the read-write mode.

Enabling write mode

  • To enable write-mode, run command rw (under root).
  • To disable it, run command ro.
  • If you receive the message "Device is busy", perform reboot.

In this handbook, you will often find instructions for editing configuration files. The simplest and most beginner-friendly text editor is nano, but you can also use vim.

Editing files in the Web Terminal 
[kvmd-webterm@pikvm ~]$ su -
[root@pikvm ~]# rw
[root@pikvm ~]# nano /etc/kvmd/override.yaml
[root@pikvm ~]# ro
[root@pikvm ~]# exit
[kvmd-webterm@pikvm ~]$

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

What's next?

FAQ and Troubleshooting

If you have any questions or run into problems, take a look at the FAQ. Seriously, it's really useful!

For any other help and support, you can contact us via the Discord chat.