Network Boot of PIXILAB Player

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

If your server comes with Blocks 3 from the outset, most of this is already done. If so, you can skip down to Obtaining the PIXILAB Player 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.

Updating your Blocks Server

Start by updating your server software. Make sure you follow all instructions in that article. Also update Blocks to version 3 or later.

Enabling the TFTP server

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.

Adding Firewall Rule for TFTP

The Linux firewall may need to be updated to allow for the TFTP traffic, this is already done in the Blocks server image running Ubuntu 20.04 or newer. To do so, 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.

Configuring the DHCP Server

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

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.

Copy the PIXILAB Player files to the server

First install the PIXILAB Player on a USB stick. Make sure you use PIXILAB Player version 3.0.1 or later. 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.

Implementation Details

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.

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

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

Web Server

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.