Setup PXE for 1st-time Users

PXE - Netbooting using PUPPY Linux

Preface
This document instructs how one Puppy Linux PC can be set up as a type of server that other PCs
on the same LAN can boot from, by solely using the resources provided by the server. And, it intends
to be strongly consistent with all of the Puppy contributors contributions in the area; namely, PXE on
Puppy Linuxes.

This manual does NOT intend to dwell on the particulars of architecture or structure of PXE. It simply
provides some simple instructions on how to accomplish this on you network.

This document has grown a bit and can appear to be complex in content. In reality, though, it is not,
as, it is broken into sections to make a simple setup occur, easily, and with good knowledge of what
one is doing.

This document is as accurate as one could make it. It may have inaccuracies, misspelling, and as
such, you are instructed to use at your own risk. No contributor to this documents generation is
responsible in ANY WAY, with the outcome that can be achieved by its use. Even though much eort
has gone into making this document accurate and straightforward; you are cautioned and advised to
use this document at your own risk!

Table of Contents
PXE - Netbooting using PUPPY Linux
Preface
Introduction
Objective
Preparation
Hardware
Software
Implementations
Implementation - Basic for PUPPY Linux users
PXE server
Steps
Procedure 1 - Implementation Steps/Instructions [you can use this or Procedure
2, below]
Example for starting your Netboot server after running mknetboot.sh
Procedure 2 - Implementation Steps/Instructions [you can use this or Procedure
1, above]
PXE Client
One sucessful PXE setup,using FATDOG as the server, went as follows:
Files Layout after Basic Implementation
Implementation #2 - Get fancy a little
Steps
Implementation #3 - Your MultiPUP ISO can give PXE clients boot options
Steps
Troubleshooting Tips
Setup PXE for 1st-time Users

Setup an Isolated Test Environment

Is your ISO OK?
Method 1
Method 2
PXEclient Stopped
...job control turned o
...File Not Found
...vmlinux Not Found
...Invalid or Corrupt kernel image
...Kernel Panic - not syncing: VFS Unable to .
-
References

Introduction
For over 20 years, the ability to boot a PC from another PC has been available. There have
been several technologies employed to do so. IBM-Intel introduced a spec and a technology to
make this very easy. That spec, today, is known as PXE. This technology has been employed in
EVERY motherboard that is currently manufactured which has on-board LAN connection(s)
built-in. It is commonly known as PXE, and it supports booting the motherboards PC from
another source on your LAN. Thus, the motherboard does NOT require any local Operating
System like Windows, Linux, Unix, Solaris, OS2, BeOS, ReactOS, etc. In essence, it will get its
Operating system from another machine over the LAN, instead of its own CD/DVD,
hard-drive(HDD), or USB/Firewire.

The machine, where its gets its stu to boot and run, is from a device on your LAN called a
PXE server; sometimes also called a Netboot server. The PC which will be booting from the
Netboot server is called Netboot client or PXE client.

The way this works for the PC that is not the server is that:
1. it will power-on, its BIOS (Mac users: OpenFirmware) will tell the PC to check the LAN,
rst, for booting instructions
2. a PXE server will give the PC everything it needs to run
3. once booted, the PC would operate on its own without ANY further need/use of the PXE
server, thereafter.

This oers enormous benets to any LAN and certainly those for home, classroom(s), etc.

This is a brief instructional document that is used to setup such the environment which allows
a PXE PC (also known as PXE client) to boot from a PXE server. And, in this document,
references to PXE and Netboot are to be viewed as meaning the same thing.

There are 3 separate implementation sections, below. They will show you How to implement
Network booting for:
1. booting an ISO containing a single Puppy
2. booting an ISO containing a single Puppy such that the boot process stops,
momentarily, giving users time to enter any boot-time parameters.
3. booting an ISO containing multiple Puppies such that the user can select which Puppy is
to be booted
It is recommended that everyone do section 1, rst, before attempting ANY of the remaining 2
Setup PXE for 1st-time Users

steps. Doing so, will insure everyone gets a base understanding of how the PXE process
works in Puppy Linux. Understanding the process almost guarantees you will achieve the PXE
(Netboot) environment you'll want on your LAN.

Objective
There are many scenarios for which Netbooting is useful. One example is illustrated here: To
setup a class room so that student PCs can boot Puppy Linux. Each students PC will simply
be started without having to install an OS on any PC. Booting a LiveCD on only one PC, acting
as a PXE server, is enough for all PCs in the classroom to start and run Puppy, reliably.

For this particular scenario, another real DHCP server (router) is assumed to already exist on
the network. This real DHCP server can be the corporate DHCP server, or, it can be the
DHCP services provided by many of the home routers. Two DHCP servers usually cannot
co-exist, but with a clever conguration, this can be done within the PXE server. The PXE
server start its DHCP service which will be used during netbooting the PXE clients, and the
standard real DHCP server will be used once the Puppy Linux has been netbooted up and
is running on the PXE client.

The PXE server will also start a service which will allow PCs on the LAN to nd the libraries they
can use to boot their PCs over the LAN without the use of any media, local, on the booting
PCs.

Assumption: We will ONLY address using wired Ethernet devices in this document.

Preparation
Hardware
1. For the Server
a. Puppy LiveCD/LiveDVD
b. 512MB RAM
c. LAN
d. crossover cable for isolated testing using only 1 PC and a PXE
server (only required if there are problems, later)
2. For the LAN PC capable of PX E via its BIOS
Setup PXE for 1st-time Users

(Mac users: Use the OpenFirmware)

a. 512MB RAM
b. LAN via motherboard

Note 1: These 2 items will allow a minimal setup for PXE server and PXEclient

Software
1. For the Server
a. Two additional software pieces (PETs) for Puppy Linux
i. DNSMASQ - comes pre-congured for your use. It is used to
provide the services needed for the PXE clients needs
ii. Netboot Script - contains scripts and menu item for creating the
libraries and les that the PXE clients use when booting.
b. The ISO for the Puppy derivative you want to start on the PXEclients
2. For the LAN PC capable of PXE, aka PXE client
a. No software is used for this PC
b. nada
c. zilch
d. nothing

Implementations
There are 3 implementations oered in this section. The rst Implementation, Basic
Implementation, is required to structure the Netboot environment. The following
Implementations allow the PXE client some local options as it boots. The 3 implementations
are:
1. Basic - Required setup for Netbooting a single Puppy ISO
2. Getting a Little Fancy - Setup to use the Puppy F2 key prior to PXE Boot
3. Boot MultiPUP - Giving PXE booting a selection of Puppy distros to boot

Implementation - Basic for PUPPY Linux users

PXE server

Steps
The general steps to implement a PXE server is as follows. It prepares the programs and les
required for this particular setup so that it can provide all necessary items that a PXEclient
requires to boot.

The procedure to setup and use a Netboot (PXE) environment is below. (You must choose
EITHER Procedure 2 or Procedure 1...although worded dierently, BOTH, ACHIEVE EXACTLY
THE SAME RESULTS!)

Procedure 1 - Implementation Steps/Instructions [you can use this or Procedure 2, below]

1. Go and install dnsmasq PET (you only need to do this once)

Setup PXE for 1st-time Users

For 64bit Puppies - get it from [here]

For 32bit Puppies - get it from [here]

2. Go and install the netboot script PET from [here] (you only need to do this once)

3. Download and save a Puppy Linux ISO youll want to use for PXEclient(s) to boot. Save this
somewhere - preferably outside your pup-save directory as ISO les can be quite large
(100- 150MB, depending on which puppy you choose)

4. Run mknetboot.sh
a. From console - open console/terminal, then type mknetboot.sh followed by Enter.
Follow the prompts.
b. From menu - open Menu, choose Utility, Gexec (Execute a Command). When a
dialog opens, type mknetboot.sh and click OK. Then follow the prompts.

5. Start/restart the PXE servers service by clicking menu > Network > Netboot Server

Ex ample for starting your Netboot server after running mknetboot.sh

Invokng the server AFTER running mknetboot.sh for creating the image needed by the PXE
PC

The Neboot server Debug mode window indicates it is waiting for a PXE to service

Setup PXE for 1st-time Users

Important Note 2: When you have achieved success in your use of your PXE server, you are
advised to move the /tmp/netboot directory to a permanet location. This folder contains the
real les used during PXEclient booting. Its your choice where to save this. It can be saved to a
local drive on your server or into a folder under the /root folder. This is required i you want your
setup eorts to survive over a reboot. Otherwise, the les that were built for your PXEclient to boot
will be lost, even, when you do a session save at shutdown. This is because NOTHING in /tmp
folder is ever saved over a reboot (session save of reboot DOES CAPTURE the contents of the
/root folder.And, there are other choices you can make for a permanent location.)

Procedure 2 - Implementation Steps/Instructions [you can use this or Procedure 1, above]

1. Install the appropriate DNSMASQ.PET

For FATDOG users, download from here (64bit dnsmasq.pet)
For other PUPPY users, download from here (32bit dnsmasq.pet)
Check that dnsmasq is installed in your system's path by opening a terminal/console to the
desktop and typing "dnsmasq -d". If you get a "command not found" response, report this
as a DNSMASQ.PET bug.
2. Install the netboot-server.pet
Same PET for any Puppy version, download from here
The PET's installation creates the /root/tftpboot directory structure. It also adds gpxelinux.0
(from syslinux-4.03) and the "default" les into their proper locations.
3. Using the Downloaded ISO you want your PX Eclients to boot up, then: From the ISO,
ex tract the les necessary for PX Eclient booting into the /root/tftpboot folder's chain
After downloading, open a terminal window and type "mknetboot.sh". This script will led you
to a chooser window where you must tell him where the ISO you downloaded is located. It
will them, build the remaining les needed for PXEclient to boot. It also properly places them
where the PXE client can nd them when you power-on that PC.
From step 2, above, the running of thIs script will symlink the proper vmlinuz and initrd.gz
into /root/tftpboot/pxelinux.cfg directory so that any PXEclient PC gets all necessary les to
boot to a Puppy desktop when powered on.

4. Start/Restart the Netboot-Server by clicking menu>Network>Netboot-Server

5. Power-on a PX E capable PC. It will boot over the LAN

Note 3: This applies to anyone using 32bit Puppy ISOs. The latest puppies of today (namely, Wary
5.0, Lupu 5.2, etc.), have a bug in their init script, causing PXEclient failure during booting this class
of PUPs. In order to correct this, you may need to edit a change in the default le. While it's being
xed, a workaround is to edit the PXE server's "default" le and add "PDEV1=rootfs" to the line that
contains the word "append". Assuming you used the steps above, the les path is
/root/tftpboot/pxelinux.cfg/default. Earlier version of puppies, as well as future version of puppies,
will work ne (the bug has been reported and xed for future releases).

This completes server preparation. This machine is now waiting to service any PXEclient needing
to boot.

PXE Client
To have your PC to start as a PXEclient, you must tell it use its PXE function. This is a BIOS
controlled feature and can be utilized in one of 2 ways:
1. Automatically
Setup PXE for 1st-time Users

2. Use the PCs startup hotkey

Automatically: You have already entered your BIOS, and set it up so that it will look to the
Network, rst, for booting instructions. When this is saved, the PC, when it boots, will start
its PXE function.

OR

Hotkey: Many PCs provide a hotkey option at boot so that you can instruct the computer to
start from an alternate location ie. CDROM, USB, 2nd HDD, or LAN. If you select LAN, the PC
will start its PXE function.

Once you have performed one of the above 2 Procedures,

Restart the PC; Stand back!; Smile when it barks (barking only occurs when
certain Puppies boot to their desktop).

Caution :
All Puppy distros have a *.sfs that is shipped with the Puppy ISO youve downloaded. If any of
those ISO sfs les exists on the PXEclients HDD/USB/CD/DVD devices, it may aect your
PXEclient booting.

For example, if there exists a lupu-511.sfs anywhere, in any device on your PC you are trying
to get started using PXE, Puppy will uses that one, and will ignore the one which is present in
the initramfs that resides on the PXE server! The one which is saved on the PXE server is the
one the PXEclient is suppose to use. So when he uses the lupu-511.sfs on your local PC,
problems can arise.

Its useless to go further if you dont have PXEclient boot success at this stage. You should
retrace the steps outlined to get the PXEserver setup so that it boots your Puppy PXEclient.
Otherwise, you will have to troubleshoot the PXE systems problems.

One sucessful PXE setup,using FATDOG as the server, went as follows:

The above steps have been tested and found to work, awlessly using Puppy FATDOG
as a PXE server.
The PXE server manipulated the ISO of a LightHouse 5.02 Puppy linux for use by any
PXEclients.
Several 32bit PXEclients were tested.
Each PXEclient booted to a Lighthouse desktop, over the LAN, from the PXE server.
Once booted, the PXEclients disconnected from the PXE server and operated on their
own.
One should expect that these steps would work the same when using a 32bit Puppy as a PXE
server, too.

Files Layout after Basic Implementation

When netboot script is installed, it will create the following minimal directory hierarchy required
for Netbooting to work. If you want to change the default settings, then you need to know this
structure. The Netboot-server script creates this structure, identically, for all Puppies.

Netboot directory structure and their explanations after running the netboot script
(mknetboot.sh).
Setup PXE for 1st-time Users

/root/tftpboot/ <== the root directory for Netbooting

(Only 4 les are needed in this directory for a PXEclient to boot.)

/root/tftpboot/pxelinux.0 <== Netboot loader, comes from the pet
/root/tftpboot/pxelinux.cfg/default <== Netboot cong le, comes from the pet.
/root/tftpboot/pxelinux.cfg/vmlinuz <== the linux kernel for use by PXE client, created by mknetboot.sh
/root/tftpboot/pxelinux.cfg/initrd.gz <== the huge initrd for use by PXE client, created by mknetboot.sh

Implementation #2 - Get fancy a little

All right, so the basic works. PXE PC boots straight to puppy, no question asked. For a little fancy,
how do we get to show the menus that is normally shown when one boots from LiveCD?

Steps
All you need to do to show the menus is to follow these steps:
1. Open the ISO le that you have used with mknetboot.sh which created that huge initrd.
2. Copy everything on that ISO, les and folders, to /root/tftpboot/pxelinux.cfg/, except
the following, that I mention below:
a. Dont copy vmlinuz
b. Dont copy initrd.gz
c. Dont copy any les that ends with .sfs (*.sfs)
d. Dont copy boot.cat and isolinux.bin
3. Rename the /root/tftpboot/pxelinux.cfg/default to /root/tftpboot/pxelinux.cfg/default-old
4. Rename /root/tftpboot/pxelinux.cfg/isolinux.cfg to /root/tftpboot/pxelinux.cfg/default
5. Edit /root/tftpboot/pxelinux.cfg/default; nd anything that says pmedia=cd and delete
it. (Dont delete the entire line, just delete the wording pmedia=cd on its line.)
6. Youre Netboot (PXE) server system is ready to go.
Console commands for steps 3-5, above

# mv /root/tftpboot/pxelinux.cfg/default /root/tftpboot/pxelinux.cfg/default-old
# mv /root/tftpboot/pxelinux.cfg/isolinux.cfg /root/tftpboot/pxelinux.cfg/default
# geany /root/tftpboot/pxelinux.cfg/default

Go to your PXE client on your LAN, Restart the PC; You should see the option allowing
you to go to Options by hitting F2 key.

Implementation #3 - Your MultiPUP ISO can give PXE clients boot

options
Again, the basic works. Netbooting is working. The PXE client PC boots straight to puppy, no
question asked. For an even fancier approach to your PXE clients, you may want to present them
with a menu showing several Puppy distros for their selection at boot time.

For example, when the PXE client starts up, the user will see a selection menu that allows them to
choose which Puppy they want to choose. In this implementation we show how to setup the
Netboot server to provide the PXE clients a menu that has Wary, Puppy, QuickSet, SPUP, and
FATDOG as options that they can boot on their PCs.

In addition to your currently running PXE server, we are going to:

1. download an application that lets you take several ISOs and combines them into one ISO.
Setup PXE for 1st-time Users

Then,
2. run a program from your Netboot PET which puts the contents of that ISO where your PXE
clients can nd it.

Steps
Assumption: DNSMASQ and Netboot have both been installed, and tested, before beginning
these step.
1. Download the ISO for each Puppy distro you want to include in the combined ISO you
want to make. For my needs, I downloaded the following ISOs:
a. Wary 503
b. Puppy 5.2
c. QuickSET 5.1.1
d. SPUP 5.3
e. FATDOG 5.1.1
2. Download and run the MultiPUP application This program combines these 5 ISOs into 1
single ISO
3. Next, open a terminal and run mkmulti.sh This program make the single ISO usable by
any PXE client on the LAN
4. Start the Netboot services via Menu > Network > Netboot-Server

Go to your PXE client on your LAN, Restart the PC; You should see the Menu of
options allowing you to go to boot any of the distros you prepared. (In my case I
see the 5 distros which are the boot options I have in my MultiPUP ISO)

Troubleshooting Tips

Most often problem: The latest puppies of today (namely, Wary 5.0, Lupu 5.2), have a bug in
their init script, causing PXEclient failure during booting this class of PUPs. While it's being xed, a
workaround is to edit the PXE server's "default" le and add "PDEV1=rootfs" to the line that contains
the word "append".

If you retraced you steps and are still experiencing diculties, you may want to setup an
Isolated Test environment.

Setup an Isolated Test Environment

This provides a sure-red way of knowing whether your PXE server is setup properly so that a
PXEclient can boot from it. In this Isolated Test, we will remove both the server and the
PXEcient from your network LAN. Then, you willconnect, only, these 2 PCs together for this
test. These will be the only 2 PCs in this isolated environment. This environment can be set up
in one of two ways:
Easiest method - you can use a separate ethernet switch/hub; not your main LAN
Little harder - you can use a cross-over cable in place of a switch

In the easiest method:

1. connect the PXEservers ethernet LAN cable to any port on the switch/hub and connect
the PXEclients LAN cable to the next port on that same switch/hub.
Setup PXE for 1st-time Users

2. boot up the Puppy PXEserver
3. On the server desktop, click menu > Network > Netboot Server to get it restarted
4. Then we are going to power-on the PXEclient to see if it connects

In the little harder

1. using a cross-over cable, we plug one end of cable into the PXEservers and we plug the
other end of the cable into the PXEclient

2. boot up the Puppy PXEserver
3. Assign the following network personality
4. On the server desktop, click menu > Network > Netboot Server to get it restarted
5. Then we are going to power-on the PXEclient to see if it connects

Note: On the PXEserver, we MAY need to set a static address, mask, and gateway for these units
on the isolated network to see each other so that the PXEclient can boot.

Is your ISO OK?

ISOs can be veried in several ways.

Method 1
The number 1 muethod of verication is to download the checksum le when you download
the ISO. In Puppy, many distro owners provide an ....sio.md5.txt le along with the ...iso
le. In the md5.txt le is the checksum value of the ISO at the point it was created. On Linux,
there is usually a tool available to recreate a checksum value of a download ISO le. The value
that the tool provides is to be compared with the value in the checksum le. Your ISO is good if
the value of the tool compares identically with the le; and, IF NOT, YOUR DOWNLOAD IS BAD.

Method 2
Sometimes, a Puppy distro owner does NOT provide a checksum le. In this case youll create
a CD/DVD from the ISO. To insure that your ISO is NOT corrupt, burn it to a CD. Boot it on any
one of your PCs, and see if it boots to the desktop without a kernal panic or some other
error. If it does, you can draw the conclusion that the download is a good one.

PXEclient Stopped

...job control turned o

Setup PXE for 1st-time Users

You have probably setup one of the 32bit Pups that has a bug in the init script. to correct, see
note 3, above.

...File Not Found

You may not have set your TFTP folder up correctly.
Try following the setup steps again for your ISO.

...vmlinux Not Found

You may not have set your TFTP folder up correctly.
An example of the problem could look like this:
At the booting PC you would see
....
Could not nd kernel image: vmlinuz
boot:

And at the Netboot server you would see (in the Debug mode window)
dnsmasq: started, version 2.55 DNS disabled
dnsmasq: compile time options: IPv6 GNU-getopt no-DBus no-I18N DHCP TFTP
dnsmasq-dhcp: DHCP, IP range 10.0.0.110 -- 10.0.0.200, lease time 1h
dnsmasq-tftp: TFTP root is /root/tftpboot
dnsmasq-dhcp: DHCPDISCOVER(eth0) 00:0d:9d:5d:b3:66
dnsmasq-dhcp: DHCPOFFER(eth0) 10.0.0.138 00:0d:9d:5d:b3:66
dnsmasq-dhcp: DHCPREQUEST(eth0) 10.0.0.138 00:0d:9d:5d:b3:66
dnsmasq-dhcp: DHCPACK(eth0) 10.0.0.138 00:0d:9d:5d:b3:66
dnsmasq-tftp: sent /root/tftpboot/pxelinux.0 to 10.0.0.138
dnsmasq-tftp: error 0 TFTP Aborted received from 10.0.0.138
dnsmasq-tftp: failed sending /root/tftpboot/pxelinux.0 to 10.0.0.138
dnsmasq-tftp: sent /root/tftpboot/pxelinux.0 to 10.0.0.138
dnsmasq-tftp: sent /root/tftpboot/pxelinux.cfg/default to 10.0.0.138
dnsmasq-tftp: le /root/tftpboot/pxelinux.cfg/vmlinuz not found
dnsmasq-tftp: le /root/tftpboot/pxelinux.cfg/vmlinuz.cbt not found
dnsmasq-tftp: le /root/tftpboot/pxelinux.cfg/vmlinuz.0 not found
dnsmasq-tftp: le /root/tftpboot/pxelinux.cfg/vmlinuz.com not found
dnsmasq-tftp: le /root/tftpboot/pxelinux.cfg/vmlinuz.c32 not found

Resolution: Try following the setup steps at the Netboot server, again, for the ISO you want
the PC to boot.

...Invalid or Corrupt kernel image

The build of your PXE les created a corrupt le.
Download the ISO (check it against its MD5 checksum) and follow the setup steps for your
ISO.

Setup PXE for 1st-time Users

...Kernel Panic - not syncing: VFS Unable to .

You may have setup one of the 32bit Pups that has a bug in the init script. to correct
see note 3, above.

References

Puppy Linux Forum The Netboot Forum Thread

MultiPUP The ability to make an ISO that boots Multiple Distros

For keeping track

<script type="text/javascript">

var _gaq = _gaq || [];

_gaq.push(['_setAccount', 'UA-23486657-1']);
_gaq.push(['_setDomainName', '.google.com']);
_gaq.push(['_trackPageview']);

(function() {
var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') +
'.google-analytics.com/ga.js';
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
})();

</script>