Network Boot of PIXILAB Player

IMPORTANT: This method of starting PIXILAB Player applies to player version 6, and is not supported on the current version of PIXILAB Player.

This document describes how to configure your existing Linux-based Blocks server to allow PIXILAB Player version 6 and earlier to boot from the server over the network, rather than from a USB stick or internal drive.

If your provisioned your server from the desktop server image provided by Pixilab, most of this is already done. If so, you can skip down to Installing PIXILAB Player on the server and continue from there.

If you bring in a Blocks data folder from an older (pre-Blocks 3) installation, you must update the configuration file to enable the tftp server, as described below. Alternatively, consider re-installing your server based on the latest server image.

If your server is very old, you may want to make a new server based on our current Linux server image. Alternatively, update your server software manually before proceeding.

Network booting needs a TFTP server. Such a server is built into Blocks, but must be configured before it can be used. This is done by adding the following two lines to Blocks' configuration file, unless they're already there:

tftp:
  port: 8069

The YML file format is sensitive to indentation. Make sure you keep the indentation exactly as shown above. The linux server from our images with Ubuntu 20.04 has default port 8069 as default port. Previous versions with Ubunti 18.04 had port 9069 as default tftp port.

If your server is based on a Linux server image older than 190711, as indicated by the "version" file found in the /home/pixi-server directory, or has no such version file, you need to update the firewall settings as described in this section.

Open a webmin interface and select the Linux Firewall module from the Networking section in the left hans menu.

Select the Network Addresss Translation (NAT) IP table from the dropdown.

Click the green add rule button in the PREROUTING section or click on a rule to edit an existing.

In essence we need to specify:

• Action to take: Redirect.
• Network protocol: Equals UDP
• Target port for redirect: Port range = 8069 (default tftp adress on the blocks server.)
• Destination TCP or UDP port:Equals port 69 (for tftp)

Click Create (Save if edit existing rule)

Click apply configuration down the bottom of the overview.

If your server is based on our Linux image dated 190711 or later, this step is already taken care of.

A DHCP server is required as part of the network boot procedure. The method described here assumes you're using the DHCP feature built into our Linux-based server. See below if you're using another DHCP server.

Using Webmin:

• Open the Client options settings.
• Locate the "Boot filename" entry.
• Type grub/grubnetx64.efi.signed into the text field.
• Select the radio button next to this text field.
• Click Save at the bottom of the window.

If you can't use the DHCP server that's built into our Linux-based server, e.g., becuse you already have another DHCP server that you prefer to use instead, then you need to make some additional configuration of that DHCP server to network boot PIXILAB Player.

• Make sure that the boot file is set to "grub/grubnetx64.efi.signed".
• Point to the IP address of your Blocks server using the "next-server" option.

This assumes you're using the standard Linux "ISC dhcpd" server, in which case these settings are found in the /etc/dhcp/dhcpd.conf file:

next-server 10.0.1.13;
filename "grub/grubnetx64.efi.signed";

Replace 10.0.1.13 with the actual IP address of your Blocks server. If you're using webmin to configure your DHCP server, the corresponding settings are found under "Edit Client Options" and look like this:

First install the PIXILAB Player on a USB stick. Test the resulting USB stick by booting your player computer from it, as you may have done in the past. This is a good way to make sure the player itself works as desired before transferring it to the server. Once you have a working USB stick, proceed as follows:

• Insert the player USB into your Linux-based Blocks server. It will appear as a number of disks.
• Open the Kiosk disk, so you can see its files and folders.
• Open the public folder found inside PIXILAB-Blocks-root in a new window, so you have them both side by side (see illustration below).
• If there isn't already a folder in the public folder named PIXILAB_Player, make one (see illustration).
• Drag all the items from the Kiosk disk (boot, docs, xzm, etc) into the PIXILAB_Player folder.

Your server is now set up for network boot of players. If you need to update your PIXILAB Player later on, just replace the files inside the PIXILAB_Player folder mentioned above with new files, and restart your players.

The computer you use as player must be configured to boot from the network. This is done in the BIOS settings. See Network Boot Support for detils.

This section describes some implementation details that may be of use to you if you're trying to make network boot work with other solutions than those built into our Linux-based server, or using another domain name than pixi.guide. You don't nee to know these details if you can follow the instructions given above.

Network booting requires close cooperation between three services:

• DHCP Server. Provides the IP address to the player, and points the player to the boot-loader code.
• TFTP Server. Provides the boot-loader code requested by the BIOS of the player.
• Web Server. Provides the bulk of the player code, as well as its configuration details.

Those services may all reside on the same computer (as is the case when using those built into our Linux-based server). Or they may live across multiple servers or other devices.

This information is provided only as an overview and starting point for you if you need to configure such services. PIXILAB does not support other methods than those built into our Linux-based server.

The DHCP server first gives the IP address for the player. It can then also inform devices that support network booting of where to find the bootstrap-loader. Two custom fields are of particular importance here:

• Boot filename (option 67). Defines the name of the boot-strap file to load from the TFTP server (in the standard configuration, this name is grub/grubnetx64.efi.signed, as shown above).
• Boot file server (option 66). IP address of the TFTP server. Not required if the TFTP server is the same as the DHCP server.

The TFTP server responds with the file specified by the Boot filename DHCP server option (e.g., grub/grubnetx64.efi.signed). Other files may be loaded as well using this method. Once this step is done, subsequent files are loaded using HTTP from a web server.

The TFTP server must respond to port 69, and must support TFTP options negotiation.

The final pieces are downloaded from a web server. The starting URL for this phase is specified in a file inside the PIXILAB Player. This file is found on the Kiosk volume at boot/grub/grub.cfg.

set timeout="1"
set fallback="1"

menuentry "Kiosk UEFI PXE" {
	linux	vmlinuz quiet http_server=http://pixi.guide/public/PIXILAB_Player
	initrd initrd.xz pxelinux.cfg/initrdpxe.xz
}

menuentry "Reboot" {
	reboot
}

If your Blocks server uses another domain name than pixi.guide, change this URL to match. Likewise, if you're using another web server than Blocks to serve the PXE boot files, change the path accordingly.