Difference between pages "Zope HOWTO" and "PXE network boot server"

From Funtoo
(Difference between pages)
Jump to: navigation, search
(interfaces.py)
 
(Installing and Configuring tftp-hpa (in.tftpd) for serving your network boot files)
 
Line 1: Line 1:
This page documents how to use Zope with Funtoo Experimental, which currently has good Zope support thanks to [[Progress Overlay Python]] integration.
+
== ''Howto: Turn your Funtoo machine into a Network Boot Server'' ==
 +
This guide helps explain how to set up a PXE server using in.tftpd and dnsmasq.
 +
This may be useful for installing an operating system on a machine that has no optical drive and/or an older BIOS which doesn't support booting from USB.  
  
== About Zope ==
+
This guide will cover the basics of getting your server set up to allow clients to boot from the network to a pxelinux/syslinux menu and choose an option of installing / running your preferred distribution or installing a MS Windows operating system - the possibilities are endless and you are free to use it as you wish!! The funtoo way!
  
Zope is an Open Source application server framework written in Python. It has an interesting history which you should familiarize yourself with before starting Zope development, as it contains several interesting twists and turns.
+
== Dependencies ==
 +
The following packages are required:
  
=== Zope History ===
+
* {{Package|net-dns/dnsmasq}}
 +
* {{Package|net-ftp/tftp-hpa}}
 +
* {{Package|sys-boot/syslinux}}
 +
For Windows PXE Booting:
 +
* {{Package|net-fs/cifs-utils}}
 +
* {{Package|net-fs/samba}}
 +
*A simple fileserving protocol configured and working properly. Both FTP and HTTP work fine. You can use either one.
 +
{{Note}} This guide will use System Rescue CD as an example of the PXE Boot Process.
 +
* Download System Rescue CD[http://www.sysresccd.org]
 +
{{Note}} The following packages are only required if you intend to install Microsoft Windows via Network Boot (NOT REQUIRED IN THIS HOWTO)
 +
*NFS support - Kernel configuration : CONFIG_NFS_FS=y||m
  
{{Note}} This HOWTO targets Zope 2.13, which includes Five. It is typically the version you should be using for new Zope projects.
+
== Understanding the PXE/Network Boot process ==
 +
A PXE Network boot isn't much different than a traditional boot from your hard drive, in fact you will probably find the boot loader to be very similar to what you are already familiar with!  In a nut shell here is what happens:  You set your BIOS / Boot options to boot from Network. The client will obtain an IP address from the PXE server (via DNSMasq), after the IP address is obtained it simply looks for the tftp daemon running on the server (tftp-hpa). The DHCP Server sends the PXE information to the NIC and it loads up a menu that you define in your pxelinux configuration (syslinux), or depending on your configuration it may go straight into the OS / Installation that you configure.
  
* There are two versions of Zope, Zope 2 and Zope 3. One might assume that Zope 3 is the version that people should use for new software development projects by default, but this is not the case. Most Zope-based projects continue to use Zope 2. Zope 3 was an attempt to redesign Zope 2 from scratch, and is completely different from Zope 2, but it was not adopted by the community.
+
Sounds easy huh? For the most part it is very simple to set up. However if you plan to set up a MS Windows install via the network, it gets a bit more tricky, mainly due to MS not using a case sensitive file system, and requiring files to be located using drive letters and back slashes "\" instead of slashes "/"  What this requires is a remapping file. With a remapping file, tftp daemon will remap the characters, symbols, and/or drive letters to suit the needs. This is why I recommend tftp-hpa in this guide.
  
* There is also something called [http://codespeak.net/z3/five/ Five] (named because it is "2 + 3") that backports many of the new features of Zope 3 into the Zope 2 framework. Several projects will use Zope 2 plus Five in order to use some of the newer features in Zope. Five was merged into mainline Zope 2 in early 2010, and first appeared in Zope 2.8.
+
DNSMasq actually provides a tftp server if you want to use it, however I recommend the use of tftp-hpa as it allows remapping in the event you ever intend to boot a Windows environment over your network.  
  
* You can learn more about the history of Zope 2, 3 and Five in the [http://svn.zope.org/Zope/trunk/src/Products/Five/README.txt?view=markup Five README].
+
This guide will cover the basics of getting your PXE server up and running for a linux based client, in this guide we will be using System Rescue CD (which is a Gentoo Live CD Image).  
  
* To make things even more interesting, work on [http://docs.zope.org/zope2/releases/4.0/ Zope 4] is underway, and it will be based on 2.13 rather than 3.x. It includes a number of [http://docs.zope.org/zope2/releases/4.0/CHANGES.html#restructuring incompatible changes] with prior versions.
+
In the event that you want to install Microsoft Windows over the network, you will have your server already configured, and you will only need to do some minor config changes, host your Windows installation files / Preinstallation Environment and set your tftp remapping configuration. (This can become a headache if you plan to host several releases of MS Windows over the network - due to conflicting remappings)
=== Zope Resources ===
+
  
Now that you understand what version of Zope you should be targeting (2.13), we can point you towards the correct documentation :)
+
It is also very important to understand that the PXE network is only responsible for giving you network access up until the operating system is loaded. What this means is that your kernel you are loading will need to have support for the network card on your client(s). You may want to consider a generic kernel that supports several different NICs.  For Windows, this means you will probably want to include all NIC drivers in your installation files and ensure that they are loaded during installation.
  
; '''[http://docs.zope.org/zope2/zope2book/ The Zope 2 Book]'''
+
== Installing and Configuring tftp-hpa (in.tftpd) for serving your network boot files ==
: This book provides a general introduction to Zope concepts and ZMI. It is a good place to start, but doesn't provide a direct introduction to Zope development. It's recommended that you skim through this book to familiarize yourself with Zope. It generally does not assume much prior knowledge about Web development or Python.
+
Install the tftp server using portage:  
; '''[http://docs.zope.org/zope2/zdgbook/ Zope Developer's Guide]'''
+
<console>
: This guide will give you a better introduction to Zope development. It assumes you already know Python. Skip chapters 1 and 2 and start in [http://docs.zope.org/zope2/zdgbook/ComponentsAndInterfaces.html chapter 3], which covers components and interfaces. [http://docs.zope.org/zope2/zdgbook/Products.html Chapter 5] covers the creation of your first product.
+
###i## emerge net-ftp/tftp-hpa
; '''[http://codespeak.net/z3/five/manual.html The Five Manual]'''
+
</console>
: We're not done yet. There is a bunch of stuff in Zope 2.13 that is not in the official documentation. Namely, the stuff in Five.
+
; '''[http://docs.zope.org/ztkpackages.html ZTK Documentation]'''
+
: ZTK 
+
; '''ZCA'''
+
: [http://www.muthukadan.net/docs/zca.html A Comprehensive Guide to Zope Component Architecture] offers a good introduction to the programming concepts of ZCA. We also have a new page on [[Zope Component Architecture]] which will help you to understand the big picture of ZCA and why it is useful. ZCML ("Z-camel") is a part of ZCA and  was introduced in Zope 3, so typically you will find ZCML documented within Zope 3 documentation and book.
+
; '''Content Components'''
+
: Views and Viewlets: [http://docs.zope.org/zope.viewlet/index.html This tutorial on viewlets] also contains some viewlet-related ZCML examples near the end. The "Content Component way" of developing in Zope seems to be a Zope 3 thing and tied to ZCML. Chapter 13+ of Stephan Richter's ''Zope 3 Developer's Handbook'' (book) seems to cover this quite well. You will probably also want to check out Philipp Weitershausen's ''Web Component Development with Zope 3'' (book).
+
; '''[http://wiki.zope.org/zope2/Zope2Wiki Zope 2 Wiki]'''
+
: Main wiki page for all things related to Zope 2.
+
; '''[http://docs.zope.org docs.zope.org]'''
+
: This is the main site for Zope documentation.
+
  
== First Steps ==
+
Create a directory for your tftp server - this is where your pxe configuration files and any files that will be accessed directly from the PXE boot process will be located (You can put it anywhere you have access to, I will be using /tftproot):  
 
+
First, you will need to emerge {{Package|net-zope/zope}}:
+
 
<console>
 
<console>
###i## emerge -av zope
+
###i## mkdir /tftproot
 
</console>
 
</console>
  
Zope is now installed.
+
Edit your PXE configuration:
 +
Set the path to /tftproot or your preferred directory created above. We are going to also go ahead and add a remapping file just in case you intend to use it later it will be ${INTFTPD_PATH}tftpd.remap:
 +
<console>
 +
###i## nano /etc/conf.d/in.tftpd
 +
# Path to server files from
 +
# Depending on your application you may have to change this.
 +
# This is commented out to force you to look at the file!
 +
#INTFTPD_PATH="/var/tftp/"
 +
#INTFTPD_PATH="/tftpboot/"
 +
INTFTPD_PATH="/tftproot/"
  
== Project Skeleton ==
+
# For more options, see in.tftpd(8)
 +
# -R 4096:32767 solves problems with ARC firmware, and obsoletes
 +
# the /proc/sys/net/ipv4/ip_local_port_range hack.
 +
# -s causes $INTFTPD_PATH to be the root of the TFTP tree.
 +
# -l is passed by the init script in addition to these options.
 +
INTFTPD_OPTS="-m ${INTFTPD_PATH}tftpd.remap -R 4096:32767 -s ${INTFTPD_PATH}"
 +
</console>
  
{{Note}} Zope should be run by a regular user account, not as the root user.
+
No need to worry about the the contents of the tftpd.remap file for now, but to prevent the daemon from panicking on a missing file, just create an empty one like so:
  
The first step in using Zope is to ensure that you are using a regular user account. Create a new directory called <tt>zope_test</tt>:
 
 
<console>
 
<console>
$##bl## cd
+
###i## touch /tftproot/tftpd.remap
$##bl## mkdir zope_test
+
 
</console>
 
</console>
  
Now, enter the directory, and create an "instance", which is a set of files and directories that are used to contain a Zope project:
+
== Installing and Configuring DNSMasq for DHCP / PXE Booting ==
 +
Install {{Package|net-dns/dnsmasq}} if you don't already have it installed (use the tftp useflag):
 +
Even though we won't be using the built-in tftp server for dnsmasq, we will still need it to be tftp-aware:
 
<console>
 
<console>
$##bl## cd zope_test
+
###i## echo "net-dns/dnsmasq tftp" >> /etc/portage/package.use/dnsmasq && emerge -av net-dns/dnsmasq
$##bl## /usr/lib/zope-2.13/bin/mkzopeinstance
+
 
</console>
 
</console>
 +
DNSMasq is a powerful daemon that has the capability of functioning as a DNS cacheing server, DHCP Server, TFTPD Server, and more. For now we will be focusing on one thing in the configuration, the DHCP Server.
  
You will see the following output, and will be prompted to answer a few questions:
+
The DNSMasq configuration file is located at:  /etc/dnsmasq.conf and it is a very large file however there are only 3 options we need for this to work, you can later enable DNS and custom dhcp mappings if needed. Those 3 configuration options are:
<console>
+
Please choose a directory in which you'd like to install
+
Zope "instance home" files such as database files, configuration
+
files, etc.
+
  
Directory: instance
+
#dhcp-boot=pxelinux.0  #Tells the filename to grab from the tftp server for booting This is provided by the syslinux package we will be configuring in the next step
Please choose a username and password for the initial user.
+
#dhcp-range=192.168.0.100,192.168.0.250,72h #customize this range to suite your network needs.  
These will be the credentials you use to initially manage
+
#interface=eth0 #The interface that will be acting as a DHCP server. If you want the DHCP server to run on a different interface be sure to change this option
your new Zope instance.
+
  
Username: admin
+
== Configuring PXELinux (based on syslinux) ==
Password: ****
+
Install {{Package|sys-boot/syslinux}}:
Verify password: ****
+
<console>
 +
###i## emerge -av sys-boot/syslinux
 
</console>
 
</console>
  
Now, we will start our Zope instance:
+
PXE booting only requires one file that is installed by syslinux, however we you will probably want to use more later on. For now we will use the pxelinux.0 file as we mentioned earlier while setting up DNSMasq, as well as a basic menu using the menu.c32 and a graphical menu using the vesamenu.c32.
 
<console>
 
<console>
$##bl## cd instance
+
###i## cd /usr/share/syslinux
$##bl## bin/runzope
+
###i## cp menu.c32 vesamenu.c32 pxelinux.0 /tftproot
 +
###i## cd /tftproot
 
</console>
 
</console>
  
Now that Zope is running, you can visit <tt>localhost:8080</tt> in your Web browser. You will see a nice introductory page to Zope.
+
PXELinux can boot a different option for each device's MAC address on your network, or it can also boot a default for all nic's on the network if a MAC address config isn't found. I will be covering the default method as it works for most simple setups. If you prefer a different boot configuration for each MAC address on your NICs then you can google for "pxelinux.cfg MAC config" and find tons of documentation for doing so. 
 +
To set up the default config, first create the following directory:
 +
<console>
 +
###i## mkdir /tftproot/pxelinux.cfg
 +
</console>  
  
If you now go to the <tt>localhost:8080/manage</tt> URL, you will be prompted to log in. Enter the username and password you specified. You are now logged in to the ZMI (Zope Management Interface.)
+
Inside this directory is where the "default" config as well as any other custom configurations by MAC will reside. Here is an example of a graphical menu used to boot System Rescue CD, the file should be located at ''<code>/tftproot/pxelinux.cfg/default</code>'':
 +
<console>
 +
###i## nano /tftproot/pxelinux.cfg/default
 +
# The default menu style - using vesa menu in this example
 +
DEFAULT vesamenu.c32
 +
# If you have a png image in the /tftproot directory you can specify it here like so:
 +
Menu Background netboot-1.png
 +
# Prompt user for selection
 +
prompt 0
  
You can stop your application by pressing Control-C. In the future, you can start and stop your Zope instance using the following commands:
+
#Global label identifier
 +
label System Rescue CD
 +
        # Set this entry as the default selection
 +
        menu default
 +
        # Actual viewable label text
 +
MENU LABEL System Rescue CD
 +
        # The timeout for the entry is a bit unclear, but 10000 is equivalent to 10 Seconds.  
 +
        TIMEOUT 10000
 +
        TOTALTIMEOUT 10000
 +
        # The kernel image to load.  This entry would actually reside at /tftproot/srcd/isolinux/rescue64  The path is relative to /tftproot or your tftp directory
 +
kernel srcd/isolinux/rescue64
 +
        # The initrd relative to tftproot directory and specifying the netboot server, protocol, and file
 +
        # In this example the http protocol is used on server 192.168.0.1. The file is sysrcd.dat
 +
        # If you have your http server set up to host files at /var/www/localhost/htdocs then this file would be located in that directory
 +
append initrd=srcd/isolinux/initram.igz netboot=http://192.168.0.1/sysrcd.dat
 +
</console>
  
 +
== Mounting the ISO Image and Hosting the Compressed File System ==
 +
In the above configuration example I was using a mounted System Rescue CD image at /tftproot/srcd  The kernel and initrd are located inside the isolinux directory of the ISO, the compressed filesystem is located at the top level of the ISO (i.e. /tftproot/srcd/sysrcd.dat)
 +
 +
In order to replicate the exact settings I used in this config you may do the following:
 
<console>
 
<console>
$##bl## zopectl start
+
###i## cd /tftproot
$##bl## zopectl stop
+
###i## mkdir srcd
 +
###i## mount -o loop /path/to/systemrescuecd.iso srcd/
 
</console>
 
</console>
 +
Be sure to replace the "/path/to/systemrescuecd.iso" with the actual path you downloaded the System Rescue CD to and the actual filename.
  
{{Note}} <tt>zopectl start</tt> will cause your instance to run in the background rather than consuming a shell console.
+
Now you need to be sure that 2 files reside on your HTTP or FTP server, whichever you prefer to use for the netboot process is fine, but the System Rescue CD Netboot process will do 3 things:
 
+
#Load Kernel
== First Project ==
+
#Load Initrd
 
+
#Request the compressed filesystem from the network
We will create a single very primitive Zope package, consisting of an Interface for a TODO class, and a TODO class.
+
The files needed for the 3rd step are located in the srcd/ directory if you mounted it with the above command. System Rescue CD uses a .dat file for the compressed filesystem, and it is verified during boot with a md5sum using the .md5 file in the srcd/ directory. The filenames are sysrcd.dat and sysrcd.md5. They need to be hosted on your fileserver/http server that you specify for the netboot argument in the pxelinux.cfg/default file. If you have a basic Apache/Lighttpd server set up you can do the following:
 
+
Create the following files and directories relative to your project root:
+
 
+
* Create the directory <tt>lib/python/example</tt>.
+
* Create the file <tt>lib/python/example/__init__.py</tt> by typing <tt>touch lib/python/example/__init__.py</tt>.
+
* Create these files:
+
 
+
=== <tt>example-configure.zcml</tt> ===
+
 
+
This file registers the <tt>example</tt> directory you created in <tt>lib/python</tt> as a ''package'', so that it is seen by Zope. Edit <code>/etc/package-includes/example-configure.zcml</code>:
+
{{File
+
|/etc/package-includes/example-configure.zcml|<pre>
+
<include package="example" />
+
</pre>}}
+
 
+
=== <tt>interfaces.py</tt> ===
+
 
+
The following file defines the <tt>ITODO</tt> interface, and also uses some Zope Schema functions to define what kind of data we expect to store in objects that implement <tt>ITODO</tt>. Edit <code>/lib/python/example/interfaces.py</code> with your favorite text editor:
+
 
+
{{File
+
|/lib/python/example/interfaces.py|<pre>
+
from zope.interface import Interface
+
from zope.schema import List, Text, TextLine, Int
+
 
+
class ITODO(Interface):
+
    name = TextLine(title=u'Name', required=True)
+
    todo = List(title=u"TODO Items", required=True, value_type=TextLine(title=u'TODO'))
+
    daysleft = Int(title=u'Days left to complete', required=True)
+
    description = Text(title=u'Description', required=True)
+
</pre>}}
+
 
+
=== <tt>TODO.py</tt> ===
+
 
+
Now, we define <tt>TODO</tt> to be a ''persistent'' object, meaning it can be stored in the ZODB. We specify that it implements our previously-defined <tt>ITODO</tt> interface, and provide reasonable defaults for all values when we create a new TODO object. Edit <code>/lib/python/example/TODO.py<code> using your favorite text editor:
+
<pre>
+
from persistent import Persistent
+
from zope.interface import implements
+
from example.interfaces import ITODO
+
 
+
class TODO(Persistent):
+
    implements(ITODO)
+
    name = u''
+
    todo = []
+
    daysleft = 0
+
    description = u''
+
</pre>
+
 
+
=== <tt>configure.zcml</tt> ===
+
 
+
Create the <tt>/lib/python/example/configure.zcml</tt> configuration file:
+
<pre>
+
<configure xmlns="http://namespaces.zope.org/zope"
+
    xmlns:five="http://namespaces.zope.org/five"
+
    xmlns:browser="http://namespaces.zope.org/browser">
+
</configure>
+
</pre>
+
 
+
== Debug Mode ==
+
 
+
We can test our first project by entering debug mode:
+
 
<console>
 
<console>
$##bl## bin/zopectl debug
+
###i## ln -s /tftproot/srcd/sysrcd.dat /var/www/localhost/htdocs/
Starting debugger (the name "app" is bound to the top-level Zope object)
+
###i## ln -s /tftproot/srcd/sysrcd.md5 /var/www/localhost/htdocs/
 
</console>
 
</console>
  
Now, let's try creating a new TODO object and writing it out to a ZODB database:
+
== Starting the services and preparing for use ==
 +
First we want to start the PXE server:
 
<console>
 
<console>
>>> from ZODB import FileStorage, DB
+
###i## /etc/init.d/in.tftpd start
>>> storage = FileStorage.FileStorage('mydatabase.fs')
+
>>> db = DB(storage)
+
>>> connection = db.open()
+
>>> import transaction
+
>>> root = connection.root()
+
>>> from example.TODO import TODO
+
>>> a = TODO
+
>>> a.name = u'My TODOs'
+
>>> a.TODOS = [ u'Do Laundry', u'Wash Dishes' ]
+
>>> a.daysleft = 1
+
>>> a.description = u'Things I need to do today.'
+
>>> root[u'today'] = a
+
>>> transaction.commit()
+
 
</console>
 
</console>
 +
And now DNSMasq:
 +
<console>
 +
###i## /etc/init.d/dnsmasq start
 +
</console>
 +
If you are using Apache ensure it is running (If you use Lighttpd or Nginx replace this step with the appropriate service)
 +
<console>
 +
###i## /etc/init.d/apache2 status
 +
</console>
 +
If the service is not running, you should start it:
 +
<console>
 +
###i## /etc/init.d/apache2 start
 +
</console>
 +
If all your configuration options are correct and you have your HTTP/FTP server running and hosting the files properly, your configuration should be done on the server side for hosting ''System Rescue CD''!!  Don't get carried away just yet, we still have to test things are working :D
 +
 +
== Testing your first network boot ==
 +
The first thing you want to do now is set up your client to boot from the network. This may vary on different machines / bios, common methods are:
 +
*Pressing F12 at boot to select boot method
 +
*Pressing F1, F10, or DEL at boot to enter BIOS Setup
 +
*Consult your motherboard documentation for the appropriate method of selecting boot device if the above don't work
 +
 +
You will want to choose a method to boot from Network as the first boot device. It may also be called "Boot From Lan" "Network Boot" "PXE Boot"  Once you have selected the appropriate method you may need to save the settings, proceed on to booting.  If you chose the right method you should be seeing some text on your screen, such as:  PXE Boot.. Obtaining DHCP....  If all is well you will be presented with your PXELinux Boot menu.  If your client system is still booting from the hard drive, or you see a failure related to obtaining DHCP IP address, please verify your settings in the above section "Installing and Configuring DNSMasq for DHCP / PXE Booting"[http://www.funtoo.org/index.php?title=Installing_and_Configuring_DNSMasq_for_DHCP_/_PXE_Booting&action=submit#Installing_and_Configuring_DNSMasq_for_DHCP_.2F_PXE_Booting] -make sure that your interface is set correctly, and that you are offering a DHCP range on the same internal network range as the IP address your server has.  If you have any error relating to unable to find PXE boot, please verify that you have the pxelinux.0 file in your /tftproot  and that your /etc/dnsmasq.conf  has the ""dhcp-boot=pxelinux.0"" configuration option.. **note that the 0 is a zero and not an o.
 +
 +
Upon a successful PXE configuration you will be presented with the network boot menu, with the option to boot System Rescue CD.  If you have the appropriate files in the correct locations and your http/ftp server is working properly, you should be able to select the System Rescue CD menu entry and successfully boot via network. Congratulations!!
 +
 +
== Adding more operating systems / installations to your working PXE setup ==
 +
I know that by example, a lot of people probably want to use something other than the System Rescue CD. The main things have been outlined above for most linux distributions. MS Windows, see [http://www.funtoo.org/wiki/PXE_Network_Windows_Installation PXE Network Windows Installation] is quiet a bit more difficult than any linux install. I will try to cover the most important steps to serving a Windows Installation from the network soon.
  
[[Category:HOWTO]]
+
If you are wondering how you go about hosting a different Linux install other than the System Rescue CD, the main things to look at are the pxelinux.cfg/default file to edit the kernel and initrd lines. You also need to be sure that those files are accessible by the PXE loader, and if your initrd requires a compressed filesystem, be sure that you have a working ftp/http server hosting the compressed filesystem (Remember once boot process has been handed over to your kernel that you are no longer accessing the network via tftp but instead by the core services provided by the initrd + drivers provided by your kernel) I will add that you may use the fetch=tftp:// protocol in the kernel cmdline, however it doesn't seem to work as stable as using http/ftp method.  Each distro is different you may need to consult the documentation for the specific  distro's needed boot cmdline.  For the most part you will find it to be very similar(i.e. kernel+initrd+compressed-filesystem) Ubuntu doesn't even use a compressed filesystem on their ISO's it basically just uses a kernel and an initrd.  I am currently working on getting a Funtoo netboot image developed, tested, and providing information on how to host a Funtoo Base system over the network via your Funtoo PXE Netboot Server.
[[Category:Featured]]
+
[[Category:HOWTO]]

Revision as of 06:15, 14 January 2014

Howto: Turn your Funtoo machine into a Network Boot Server

This guide helps explain how to set up a PXE server using in.tftpd and dnsmasq. This may be useful for installing an operating system on a machine that has no optical drive and/or an older BIOS which doesn't support booting from USB.

This guide will cover the basics of getting your server set up to allow clients to boot from the network to a pxelinux/syslinux menu and choose an option of installing / running your preferred distribution or installing a MS Windows operating system - the possibilities are endless and you are free to use it as you wish!! The funtoo way!

Dependencies

The following packages are required:

For Windows PXE Booting:

  • net-fs/cifs-utils
  • net-fs/samba
  • A simple fileserving protocol configured and working properly. Both FTP and HTTP work fine. You can use either one.

Note Note: This guide will use System Rescue CD as an example of the PXE Boot Process.

  • Download System Rescue CD[1]

Note Note: The following packages are only required if you intend to install Microsoft Windows via Network Boot (NOT REQUIRED IN THIS HOWTO)

  • NFS support - Kernel configuration : CONFIG_NFS_FS=y||m

Understanding the PXE/Network Boot process

A PXE Network boot isn't much different than a traditional boot from your hard drive, in fact you will probably find the boot loader to be very similar to what you are already familiar with! In a nut shell here is what happens: You set your BIOS / Boot options to boot from Network. The client will obtain an IP address from the PXE server (via DNSMasq), after the IP address is obtained it simply looks for the tftp daemon running on the server (tftp-hpa). The DHCP Server sends the PXE information to the NIC and it loads up a menu that you define in your pxelinux configuration (syslinux), or depending on your configuration it may go straight into the OS / Installation that you configure.

Sounds easy huh? For the most part it is very simple to set up. However if you plan to set up a MS Windows install via the network, it gets a bit more tricky, mainly due to MS not using a case sensitive file system, and requiring files to be located using drive letters and back slashes "\" instead of slashes "/" What this requires is a remapping file. With a remapping file, tftp daemon will remap the characters, symbols, and/or drive letters to suit the needs. This is why I recommend tftp-hpa in this guide.

DNSMasq actually provides a tftp server if you want to use it, however I recommend the use of tftp-hpa as it allows remapping in the event you ever intend to boot a Windows environment over your network.

This guide will cover the basics of getting your PXE server up and running for a linux based client, in this guide we will be using System Rescue CD (which is a Gentoo Live CD Image).

In the event that you want to install Microsoft Windows over the network, you will have your server already configured, and you will only need to do some minor config changes, host your Windows installation files / Preinstallation Environment and set your tftp remapping configuration. (This can become a headache if you plan to host several releases of MS Windows over the network - due to conflicting remappings)

It is also very important to understand that the PXE network is only responsible for giving you network access up until the operating system is loaded. What this means is that your kernel you are loading will need to have support for the network card on your client(s). You may want to consider a generic kernel that supports several different NICs. For Windows, this means you will probably want to include all NIC drivers in your installation files and ensure that they are loaded during installation.

Installing and Configuring tftp-hpa (in.tftpd) for serving your network boot files

Install the tftp server using portage:

# emerge net-ftp/tftp-hpa

Create a directory for your tftp server - this is where your pxe configuration files and any files that will be accessed directly from the PXE boot process will be located (You can put it anywhere you have access to, I will be using /tftproot):

# mkdir /tftproot

Edit your PXE configuration: Set the path to /tftproot or your preferred directory created above. We are going to also go ahead and add a remapping file just in case you intend to use it later it will be ${INTFTPD_PATH}tftpd.remap:

# nano /etc/conf.d/in.tftpd
# Path to server files from
# Depending on your application you may have to change this.
# This is commented out to force you to look at the file!
#INTFTPD_PATH="/var/tftp/"
#INTFTPD_PATH="/tftpboot/"
INTFTPD_PATH="/tftproot/"

# For more options, see in.tftpd(8)
# -R 4096:32767 solves problems with ARC firmware, and obsoletes
# the /proc/sys/net/ipv4/ip_local_port_range hack.
# -s causes $INTFTPD_PATH to be the root of the TFTP tree.
# -l is passed by the init script in addition to these options.
INTFTPD_OPTS="-m ${INTFTPD_PATH}tftpd.remap -R 4096:32767 -s ${INTFTPD_PATH}"

No need to worry about the the contents of the tftpd.remap file for now, but to prevent the daemon from panicking on a missing file, just create an empty one like so:

# touch /tftproot/tftpd.remap

Installing and Configuring DNSMasq for DHCP / PXE Booting

Install net-dns/dnsmasq if you don't already have it installed (use the tftp useflag): Even though we won't be using the built-in tftp server for dnsmasq, we will still need it to be tftp-aware:

# echo "net-dns/dnsmasq tftp" >> /etc/portage/package.use/dnsmasq && emerge -av net-dns/dnsmasq

DNSMasq is a powerful daemon that has the capability of functioning as a DNS cacheing server, DHCP Server, TFTPD Server, and more. For now we will be focusing on one thing in the configuration, the DHCP Server.

The DNSMasq configuration file is located at: /etc/dnsmasq.conf and it is a very large file however there are only 3 options we need for this to work, you can later enable DNS and custom dhcp mappings if needed. Those 3 configuration options are:

  1. dhcp-boot=pxelinux.0 #Tells the filename to grab from the tftp server for booting This is provided by the syslinux package we will be configuring in the next step
  2. dhcp-range=192.168.0.100,192.168.0.250,72h #customize this range to suite your network needs.
  3. interface=eth0 #The interface that will be acting as a DHCP server. If you want the DHCP server to run on a different interface be sure to change this option

Configuring PXELinux (based on syslinux)

Install sys-boot/syslinux:

# emerge -av sys-boot/syslinux

PXE booting only requires one file that is installed by syslinux, however we you will probably want to use more later on. For now we will use the pxelinux.0 file as we mentioned earlier while setting up DNSMasq, as well as a basic menu using the menu.c32 and a graphical menu using the vesamenu.c32.

# cd /usr/share/syslinux
# cp menu.c32 vesamenu.c32 pxelinux.0 /tftproot
# cd /tftproot

PXELinux can boot a different option for each device's MAC address on your network, or it can also boot a default for all nic's on the network if a MAC address config isn't found. I will be covering the default method as it works for most simple setups. If you prefer a different boot configuration for each MAC address on your NICs then you can google for "pxelinux.cfg MAC config" and find tons of documentation for doing so. To set up the default config, first create the following directory:

# mkdir /tftproot/pxelinux.cfg

Inside this directory is where the "default" config as well as any other custom configurations by MAC will reside. Here is an example of a graphical menu used to boot System Rescue CD, the file should be located at /tftproot/pxelinux.cfg/default:

# nano /tftproot/pxelinux.cfg/default
# The default menu style - using vesa menu in this example
DEFAULT vesamenu.c32
# If you have a png image in the /tftproot directory you can specify it here like so:
Menu Background netboot-1.png
# Prompt user for selection
prompt 0 

#Global label identifier
label System Rescue CD
        # Set this entry as the default selection
        menu default
        # Actual viewable label text
	MENU LABEL System Rescue CD
        # The timeout for the entry is a bit unclear, but 10000 is equivalent to 10 Seconds. 
        TIMEOUT 10000
        TOTALTIMEOUT 10000
        # The kernel image to load.  This entry would actually reside at /tftproot/srcd/isolinux/rescue64   The path is relative to /tftproot or your tftp directory
	kernel srcd/isolinux/rescue64
        # The initrd relative to tftproot directory and specifying the netboot server, protocol, and file
        # In this example the http protocol is used on server 192.168.0.1. The file is sysrcd.dat
        # If you have your http server set up to host files at /var/www/localhost/htdocs then this file would be located in that directory
	append initrd=srcd/isolinux/initram.igz netboot=http://192.168.0.1/sysrcd.dat

Mounting the ISO Image and Hosting the Compressed File System

In the above configuration example I was using a mounted System Rescue CD image at /tftproot/srcd The kernel and initrd are located inside the isolinux directory of the ISO, the compressed filesystem is located at the top level of the ISO (i.e. /tftproot/srcd/sysrcd.dat)

In order to replicate the exact settings I used in this config you may do the following:

# cd /tftproot 
# mkdir srcd 
# mount -o loop /path/to/systemrescuecd.iso srcd/

Be sure to replace the "/path/to/systemrescuecd.iso" with the actual path you downloaded the System Rescue CD to and the actual filename.

Now you need to be sure that 2 files reside on your HTTP or FTP server, whichever you prefer to use for the netboot process is fine, but the System Rescue CD Netboot process will do 3 things:

  1. Load Kernel
  2. Load Initrd
  3. Request the compressed filesystem from the network

The files needed for the 3rd step are located in the srcd/ directory if you mounted it with the above command. System Rescue CD uses a .dat file for the compressed filesystem, and it is verified during boot with a md5sum using the .md5 file in the srcd/ directory. The filenames are sysrcd.dat and sysrcd.md5. They need to be hosted on your fileserver/http server that you specify for the netboot argument in the pxelinux.cfg/default file. If you have a basic Apache/Lighttpd server set up you can do the following:

# ln -s /tftproot/srcd/sysrcd.dat /var/www/localhost/htdocs/
# ln -s /tftproot/srcd/sysrcd.md5 /var/www/localhost/htdocs/

Starting the services and preparing for use

First we want to start the PXE server:

# /etc/init.d/in.tftpd start

And now DNSMasq:

# /etc/init.d/dnsmasq start 

If you are using Apache ensure it is running (If you use Lighttpd or Nginx replace this step with the appropriate service)

# /etc/init.d/apache2 status

If the service is not running, you should start it:

# /etc/init.d/apache2 start

If all your configuration options are correct and you have your HTTP/FTP server running and hosting the files properly, your configuration should be done on the server side for hosting System Rescue CD!! Don't get carried away just yet, we still have to test things are working :D

Testing your first network boot

The first thing you want to do now is set up your client to boot from the network. This may vary on different machines / bios, common methods are:

  • Pressing F12 at boot to select boot method
  • Pressing F1, F10, or DEL at boot to enter BIOS Setup
  • Consult your motherboard documentation for the appropriate method of selecting boot device if the above don't work

You will want to choose a method to boot from Network as the first boot device. It may also be called "Boot From Lan" "Network Boot" "PXE Boot" Once you have selected the appropriate method you may need to save the settings, proceed on to booting. If you chose the right method you should be seeing some text on your screen, such as: PXE Boot.. Obtaining DHCP.... If all is well you will be presented with your PXELinux Boot menu. If your client system is still booting from the hard drive, or you see a failure related to obtaining DHCP IP address, please verify your settings in the above section "Installing and Configuring DNSMasq for DHCP / PXE Booting"[2] -make sure that your interface is set correctly, and that you are offering a DHCP range on the same internal network range as the IP address your server has. If you have any error relating to unable to find PXE boot, please verify that you have the pxelinux.0 file in your /tftproot and that your /etc/dnsmasq.conf has the ""dhcp-boot=pxelinux.0"" configuration option.. **note that the 0 is a zero and not an o.

Upon a successful PXE configuration you will be presented with the network boot menu, with the option to boot System Rescue CD. If you have the appropriate files in the correct locations and your http/ftp server is working properly, you should be able to select the System Rescue CD menu entry and successfully boot via network. Congratulations!!

Adding more operating systems / installations to your working PXE setup

I know that by example, a lot of people probably want to use something other than the System Rescue CD. The main things have been outlined above for most linux distributions. MS Windows, see PXE Network Windows Installation is quiet a bit more difficult than any linux install. I will try to cover the most important steps to serving a Windows Installation from the network soon.

If you are wondering how you go about hosting a different Linux install other than the System Rescue CD, the main things to look at are the pxelinux.cfg/default file to edit the kernel and initrd lines. You also need to be sure that those files are accessible by the PXE loader, and if your initrd requires a compressed filesystem, be sure that you have a working ftp/http server hosting the compressed filesystem (Remember once boot process has been handed over to your kernel that you are no longer accessing the network via tftp but instead by the core services provided by the initrd + drivers provided by your kernel) I will add that you may use the fetch=tftp:// protocol in the kernel cmdline, however it doesn't seem to work as stable as using http/ftp method. Each distro is different you may need to consult the documentation for the specific distro's needed boot cmdline. For the most part you will find it to be very similar(i.e. kernel+initrd+compressed-filesystem) Ubuntu doesn't even use a compressed filesystem on their ISO's it basically just uses a kernel and an initrd. I am currently working on getting a Funtoo netboot image developed, tested, and providing information on how to host a Funtoo Base system over the network via your Funtoo PXE Netboot Server.