Skip to content

On-boot configuration & production deployment

At the first boot, PiKVM generates encryption keys and performs other actions necessary to configure the device.

Some parameters, such as connecting to Wi-Fi, or configuring a static interface for wired Ethernet, can be easily changed by the user if there is physical access to the memory card. This is convenient for quick customization of your device before the first use.

All settings are made using a file pikvm.txt on the first section of the memory card. After applying the settings, the file is automatically deleted.

Setting up Wi-Fi

Note

Devices based on Raspberry Pi Zero 2 W does not support 5GHz Wi-Fi.

  1. Remove the PiKVM memory card. The device must be turned off.

  2. Insert the memory card into the computer and mount the first FAT32 partition.

  3. Among the system files you will see the file pikvm.txt. If you haven't enabled PiKVM yet, this file will contain a single line FIRST_BOOT=1.

  4. To connect to Wi-Fi with DHCP, you will need an ESSID (network name) and a password. Add this to pikvm.txt. If the file doesn't exists, just create it. Like following:

    WIFI_ESSID='mynet'
WIFI_PASSWD='p@s$$w0rd'

    Note that backslash in the password should be escaped: \ should be written as \\.

    If there was a string FIRST_BOOT=1 in the file, do not remove it. This is the trigger needed to initialize the OS at the first boot. On the contrary, if the file pikvm.txt does not exist, you should not add this line.

  5. Unmount partition and return the memory card to PiKVM.

  6. A few things to keep in mind:

    • Note that after applying the settings, the pikvm.txt file will be deleted.
    • WPA3 is not supported. Enable WPA2 on your router, while AES is supported, some aspects of it is not and you may need to disable AES for it to connect.
    • There is a possibility that, in countries that support channel 13, the device will not connect. You will need to configure your router to disable channels 12-14 or disable Auto scan mode.

Other available options

A number of other parameters can be applied in the same way as with Wi-Fi.

Note

The parameters must be specified strictly each on a separate line.

  • FIRST_BOOT=1
    Triggers initialization of the first OS startup. The following actions are performed:

    • Generates unique /etc/machine-id for internal systemd machinery.
    • Generates unique SSL certificates for HTTPS and VNC.
    • Mass Storage image partition is reformatted to fill the available space at the end of SD card (only for V2+).
    • Different minor things are performed like fc-cache update.

    Note that this option does not reset the OS to factory defaults. There is no way to do this other than reflashing.

  • ENABLE_OTG_SERIAL=1
    Only for V2+. Enables a virtual serial port on a USB emulator, that can be used to log in to PiKVM from the target host side. Disabled for security reasons.

  • SSH_PORT=1234
    Changes SSH server port to 1234 instead of 22.

  • ETH_DHCP=1
    Configures Ethernet port for DHCP. This is a default for PiKVM OS.

  • ETH_ADDR=192.168.0.100/24
    ETH_DNS=8.8.8.8
    ETH_GW=192.168.0.1
    Configures a static IP on the Ethernet port. Only IPv4 is available here. For IPv6 you'll need to change systemd configuration files on the live OS. All three options must be set simultaneously to avoid incorrect configuration.

  • WIFI_ESSID=foo
    WIFI_PASSWD=bar
    Configures Wi-Fi with DHCP, described in more detail in previous paragrpah. Both options must be set simultaneously to avoid incorrect configuration.

  • WIFI_HIDDEN=1
    Allows to connect to hidden Wi-Fi network. Available only on new images >= 2024.03.12.

  • WIFI_REGDOM=US
    Changes Wi-Fi regulatory domain to the US. Other domains available by ISO 3166-1 alpha-2 country codes.

  • WIFI_ADDR=192.168.0.100/24
    WIFI_DNS=8.8.8.8
    WIFI_GW=192.168.0.1
    Configures a static IP on the Wifi. Only IPv4 is available here. For IPv6 you'll need to change systemd configuration files on the live OS. All three options must be set simultaneously with WIFI_ESSID and WIFI_PASSWD to avoid incorrect configuration.

Advanced production deployment

For a production environment, it may be important to integrate PiKVM into an existing infrastructure automatically. Usually, such actions are performed by special scripts written by the administrator.

To run such scripts, PiKVM OS suggests placing them in pikvm-scripts.d directory (/boot/pikvm-scripts.d on the system itself) on the same partition next to pikvm.txt file.

If pikvm.txt exists, all the parameters described there will be applied, and the contents inside pikvm-scripts.d will be checked if this directory exists. Scripts in this directory are run in alphabetical order, the failure will be ignored, it is assumed that the script author should handle this situation.

If the script needs to reboot the OS, it should create an empty file /boot/pikvm-reboot.txt. The reboot is performed once after all scripts.

In order not to copy scripts manually on each memory card on each PiKVM, it may make sense to build a custom OS image containing everything you need.