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¶
Remove the PiKVM memory card. The device must be turned off.
Insert the memory card into the computer and mount the first FAT32 partition.
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
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:
Note that backslash in the password should be escaped:
\should be written as
If there was a string
FIRST_BOOT=1in 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.
Unmount partition and return the memory card to PiKVM.
A few things to keep in mind:
- WPA3 is not supported. Enable WPA2 on your router.
- 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.
The parameters must be specified strictly each on a separate line.
Triggers initialization of the first OS startup. The following actions are performed:
- Generates unique
/etc/machine-idfor 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.
- Generates unique
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.
Changes SSH server port to 1234 instead of 22.
Configures Ethernet port for DHCP. This is a default for PiKVM OS.
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.
Configures Wi-Fi with DHCP, described in more detail in previous paragrpah. Both options must be set simultaneously to avoid incorrect configuration.
Changes Wi-Fi regulatory domain to the US. Other domains available by ISO 3166-1 alpha-2 country codes.
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_PASSWDto 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 exists, all the parameters described there will be applied, and the contents inside
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
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.