HOWTO Set up PXE server for Porteus Kiosk edition

[fanthom]

EDIT:\\
This HOWTO is not valid since Kiosk 3.1 release. please refer to a new one posted on porteus-kiosk.org:
http://porteus-kiosk.org/pxe-server.html

thanks

Since version 2.0.5 Porteus Kiosk gained the ability of booting over network through the PXE protocol. From now on the kiosk can be easily deployed, and kept up to date, on multiple PC's without bothering to burn a dozen CD's or usb sticks. Certainly useful, but please be mindful that this feature brings some restrictions that are not present in the standard way of booting:

1) 'copy2ram' is forced by default as pxe components have to be downloaded from the server on the client PC during the initial booting phase. PXE firmware, kernel and initial ramdisks are unpacked 'on the fly' but xzm modules must be stored in tmpfs (RAM). This may affect PC's with low RAM so booting over a network is not recommended for machines with less than 128MB of memory.

2) Copying of files over a network does not preserve original permissions so /rootcopy folder can not be used when doing a PXE boot. Please use xzm modules (even for a single files) which can be kept in the /base or /modules folders as normal.

3) The same ISO image is shipped to every client PC so the 'static IP' feature can not be enabled during the wizard to avoid IP conflicts in the network. Please use 'DHCPC' option instead.

4) PXE boot requires a wired connection between the server and client.

5) PXE services are not included in kiosk (unlike our desktop edition). Admin probably needs additional software like network profiling/monitoring tools and such utilities always brings extra size to the ISO and could compromise security. It's better to use another operating system which should work as a server. You may use your favorite linux distribution (or even Windows) for this task. The only requirement is the presence of the following services:
a) dhcpcd - used for assigning IP addresses to the clients
b) tftpd - used for transporting PXE components (firmware, kernel, initrds)
c) httpd - used for transporting of xzm modules on client's PCs (http protocol is faster than tftp)
I recommend using any recent Porteus desktop edition as it has everything we need provided by default.

My server is up and running and has all required services active - what i need to do next?

a) Run the kiosk wizard and make sure that 'PXE client component' is enabled. Set other features to match the client PC's specification as the Kiosk will run on the client and not the server.

b) Unpack the ISO to some folder on the server. If you previously skipped answering the 'http server IP and port' question then please edit
/some_folder/boot/pxelinux.cfg/default and update 'http_server=' cheatcode like in this example:

Code: Select all

http_server=192.168.1.34:8090

NOTE: It is also possible to mount the ISO (mount -o loop porteus-kiosk.iso /path) instead of unpacking it.

c) Point your dhcpc, tftp and http daemons to the folder where the ISO is unpacked. dhcpcd should be able to upload PXE firmware: /boot/pxelinux.0, tftpd should be able to transport vmlinuz and both initrds (/boot/vmlinuz, /boot/initrd.xz and /boot/pxelinux.cfg/initrdpxe.xz), and httpd should be pointed to the /porteus folder which holds xzm modules.

To automate the process of starting required services, I have prepared a script which I use in the Porteus standard edition (it should also work for any other linux distro).
Be aware that in porteus we are using 'dnsmasq' for dhcpcd and tftpd services and 'webfsd' which acts as http daemon. Both are small, fast and can be configured from a command line - perfect for scripting. If you are using different utilities then you have to tweak their configs according to my script.

Code: Select all

#!/bin/bash
# Run services necessary for booting Porteus Kiosk over the network.

# Path to folder where Kiosk ISO is unpacked/mounted:
PXEDATA=/home/guest/kiosk-pxe
# Server IP address:
IP=192.168.1.34
# Port on which the HTTP daemon is listening:
PORT=8090

# Start the DHCP server and the TFTP server:
killall dnsmasq 2>/dev/null
dnsmasq --enable-tftp --tftp-root=$PXEDATA/boot --dhcp-boot=pxelinux.0,"$IP",$IP --dhcp-range=$(echo $IP | cut -d. -f1-3).50,$(echo $IP | cut -d. -f1-3).250,infinite --log-dhcp

# Start the HTTP server:
killall webfsd 2>/dev/null
webfsd -i $IP -p $PORT -r $PXEDATA/porteus -u nobody -g nogroup

# Enable packet forwarding so pxe clients can connect to internet:
echo 1 > /proc/sys/net/ipv4/ip_forward

echo "PXE services for Porteus Kiosk should be started now."

Once services are started you need to check if they are actually working

Please run 'ps auxww' command in terminal and you should see similar lines to these:

Code: Select all

nobody    3123  0.0  0.0  12824   696 ?        S    15:16   0:00 dnsmasq --enable-tftp --tftp-root=/home/guest/kiosk-pxe/boot --dhcp-boot=pxelinux.0,192.168.1.34,192.168.1.34 --dhcp-range=192.168.1.50,192.168.1.250,infinite --log-dhcp
nobody    3126  0.0  0.0  25272   472 ?        Ss   15:16   0:00 webfsd -i 192.168.1.34 -p 8090 -r /home/guest/kiosk-pxe/porteus -u nobody -g nogroup

You can also open your browser and navigate to the 192.168.1.34:8090 address and you should see /porteus folder being hosted there.

If service test passes then you can test the Kiosk ISO booted over PXE. You can do this directly on the server with the help of the virtualization software:
a) make sure that your firewall is not blocking anything PXE related
b) start VirtualBox and create new session with network interface set to the 'bridged mode'
c) launch virtual session -> press F12 to select booting device -> press 'l' for LAN
d) enjoy Porteus Kiosk booted over the network

Please use this thread to post about the difficulties you experience when setting up PXE server for Kiosk or suggest improvements to our PXE boot process.

Thanks for using Porteus and happy PXE booting!

[ElliotFriend]

Thanks for the tutorial! I'm using the 64-bit version of Porteus 2 as my server, and everything is working fantastically!!

Two things I'd like to comment on:

1. I tried setting this up using the 32-bit version, and I was unable to get your script to work because apparently the 32-bit version uses "Monkey" for it's HTTP server. How would you use the script to configure Monkey for this setup? I didn't want to fart around with that, so I just switched to the 64-bit version.
2. When I run that script, I get an error message telling me "open /etc/mime.types: No such file or directory" - indeed, that file doesn't exist. Can you explain what that error might be referring to? I'm guessing something with webfsd trying to figure out which file type to serve (that's a complete shot in the dark).

Thanks again! Great HOWTO!

[fanthom]

hello Elliot,

glad that you found my HOWTO useful

1) sorry - forgotten that in 2.0 32bit we still use monkeyd. all should be sorted when 2.1 is released as there will be webfsd only. if you still are willing to use 32bit version + monkeyd then please do as follows:
- copy /boot/syslinux/pxelinux.cfg/web folder somewhere
- edit 'Server_root' variable in /web/conf/monkey.conf to match /path_to_Kiosk/porteus folder
- start monkeyd as follows:

Code: Select all

./monkey -c conf -D

2) as per this document:

Code: Select all

Multipurpose Internet Mail Extensions (MIME) types associate file contents and file extensions with the way the server and the client handle files.

so i guess it's for telling the client what type of content is hosted and which group of apps should be used to open it.
even if i'm interpreting it incorrectly - mime does not affect booting over PXE so this error can be ignored.

Cheers

[psicodelico]

porteus and drbl?

[fanthom]

hello psicodelico,

i'm guessing that you suggest implementing support for drbl in Kiosk - is it?
must admit that i'm not familiar with it but from the description i see that it's Linux specific and requires NFS. our current implementation is bit simpler (PXE+httpd server) and can work on any OS (Linux, *BSD, Windows, probably also Mac).

maybe i'm not aware of something so please list advantages of drbl over PXE+httpd.

[jdarby]

Would it be possible to integrate the httpd server from Porteus Desktop Edition into an existing PXE environment (DHCP, TFTP?)
I use Fog for TFTP and an Active Directory DC for DHCP.

[fanthom]

hi jdarby,

it could be http daemon from porteus desktop edition but does not have to. in fact it can be any http server installed on any operating system as kiosk downloads modules with the help of 'wget' utility and i guess that pretty much everything is compatible with wget.
http daemon can be installed on different PC than dhcp/tftp. there is one condition only: when you enter IP of the http server in the browser address bar it must open on the /porteus directory listing /base and /modules as wget downloads the modules in following order:
server_ip/porteus/base/X1.xzm
server_ip/porteus/base/X1.xzm
server_ip/porteus/base/Xn.xzm
server_ip/porteus/modules/X1.xzm
server_ip/porteus/modules/Xn.xzm

please let me know if you get into troubles.