jabawok.net scratchpad

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
This page was created due to lack of sufficient documentation about the PXE Boot process on the official Porteus Kiosk web site. Porteus-Kiosk maintainers: please feel free to use my work to improve the official documentation.

It is possible to run Porteus-Kiosk on machines with no local storage, booting via PXE. Config is retrieved from the pxe server over http during bootup. This is NOT possible using the official remote management feature, as detailed below.

==== Porteus customisation and boot methods primer ====
=== How porteus kiosk official remote management operation works ===
This requires local storage (a hard disk in the client machine)
  * The client boots from local media 
  * reads remote config URL setting from it's locally stored kiosk.sgn (encrypted config)
  * it then retrieves the remote url and compares the config. If there's a change it encrypts the new config and stores the the sgn file in it's local config, then reboots.

For this reason the remote management feature in porteus kiosk wont work on PXE - there's no way for the client to "reburn" it's configuration once it checks for remote management, as it has no local storage.

=== How porteus-kiosk works from PXE ===
  * The kernel, initrd and initrd.xz and initrdpxe.xz (network modules) need loading via pxelinux. 
  * The initrd script initialises network, then downloads via http the docs/kiosk.sgn (encrypted config) and xzm modules (see kernel parameters for location).
  * Boot continues normally (xzm modules unpacked and overlaid etc)

Porteus-Kiosk settings are stored in the docs/kiosk.sgn file which is encrypted with an unknown private key. This was briefly investigated but the developers appear to have made the questionable decision to obscure this method. A head start to further investigations would be a string search for "first_run", "/opt/scripts/extras" and the /opt/scripts directory in general. @fanthom: please document this method in the open on the porteus kiosk web site documentation, so it can be properly audited. Security through obscurity is not security at all.

=== Porteus-Kiosk encrypted config file kiosk.sgn details ===
This file is generated by the kiosk wizard that runs when the original ISO is booted. This welcome wizard then generates an ISO file with the kiosk.sgn burnt in, which can optionally be "installed" on local storage or saved for transfer to the PXE server. To extract the kiosk.sgn file after "installing" porteus, simply boot up an alternate live distro, mount the second partition, and take a copy of /docs/kiosk.sgn
This should then be copying into the http structure of the PXE server.

==== Creating a porteus kiosk config ====
  * Create a new VM with 2G memory and a small hard disk (4G?), 
  * boot the iso, 
  * run through the wizard - install porteus to the hard disk
  * boot knoppix or similar
  * mount the "ISO" partition (sda2) and extract via scp the docs/kiosk.sgn encrypted settings file.

==== Implementation notes ====

  * The http component should be served from a custom port on the web server (eg 8088) as the document root. This should contain the file structure from the iso, with replaced kiosk.sgn and any additional xzm modules required.
  * The tftp portion for pxe boot should be served from a directory under the tftproot. An additional initrd file is required for pxe booting and the pxelinux config should look something like this: 
<code>KERNEL /porteus-kiosk-4.5.0/vmlinuz
APPEND initrd=/porteus-kiosk-4.5.0/initrd.xz,/porteus-kiosk-4.5.0/initrdpxe.xz http_server=10.2.100.32:8088</code>
  * A custom splash screen can be created in docs/default.jpg on the web server