Skip to content

Building PiKVM OSΒΆ

The assembly of PiKVM OS is carried out using a special build environment. Here the minimum required for its use, imposed on the build machine:

  • kernel >= 5.8
  • glibc >= 2.33
  • docker >= 19.03.13
  • git

Docker must work in privileged mode.

  1. When starting with a clean OS you need to install and configure Docker. An example for Ubuntu:

    [user@localhost ~]$ sudo apt-get install git make curl binutils -y
    [user@localhost ~]$ sudo apt-get install
    [user@localhost ~]$ sudo usermod -aG docker $USER

    Re-login to apply the changes.

  2. Checkout the build environment:

    [user@localhost ~]$ git clone --depth=1
    [user@localhost ~]$ cd os
  3. Determine the target board and platform:

    • Choose the board:

      • BOARD=rpi4 for Raspberry Pi 4.
      • BOARD=zero2w
      • BOARD=rpi3
      • BOARD=rpi2
    • Choose the platform:

      • PLATFORM=v4mini-hdmi for PiKVM V4 Mini.
      • PLATFORM=v4plus-hdmi for PiKVM V4 Plus.
      • PLATFORM=v3-hdmi for RPi4 and PiKVM V3 HAT.
      • PLATFORM=v2-hdmi for RPi3a+/RPi4 or Zero2W with HDMI-CSI bridge.
      • PLATFORM=v2-hdmiusb for RPi4 with HDMI-USB dongle.
      • PLATFORM=v1-hdmi for RPi2 or 3b+ with HDMI-CSI bridge and the Pico HID.
      • PLATFORM=v1-hdmiusb for RPi2 or 3b+ with HDMI-USB dongle and the Pico HID.
  4. Create the build config file for the target system and and the BOARD and PLATFORM variables. You can also set some other parameters as you wish (see below). Please note: if your password contains the # character, you must escape it using a backslash like ROOT_PASSWD = pass\#word.

    # Base board
    BOARD = rpi4
    # Hardware configuration
    PLATFORM = v2-hdmi
    # Target hostname
    HOSTNAME = pikvm
    # ru_RU, etc. UTF-8 only
    LOCALE = en_US
    # See /usr/share/zoneinfo
    TIMEZONE = Europe/Nicosia
    # For SSH root user
    ROOT_PASSWD = rootpass
    # Web UI credentials: user=admin, password=adminpass
    WEBUI_ADMIN_PASSWD = adminpass
    # IPMI credentials: user=admin, password=adminpass
    IPMI_ADMIN_PASSWD = adminpass
  5. Build the OS. It may take about one hour depending on the Internet connection:

    [user@localhost os]$ make os


    If you get an error about failing to retrieving a file, please edit the Makefile and remove de3. from the repo URL.

  6. Create an image. It will be stored in the images directory as a file with *.img extension:

    [user@localhost os]$ make image
  7. Flash the result image to SD card.