mac geekery

Have you ever thought that having that emergency partition on your desktop was hackish and ugly? Or have you thought that it would be truly handy to have a boot DVD available via NetBoot for recovery purposes? Well, good news, Mac OS X can act as a NetBoot server just as well as Mac OS X Server itself can. All a Mac needs to NetBoot is a server running TFTP and either NFS or HTTP, and all are built in to a normal Mac OS X machine.

In fact, any machine that can serve those basic protocols can be a NetBoot server. The reason one would prefer a Mac for this is because Apple has a protocol called Boot Service Discovery Protocol (BSDP) that it built into its bootpd server. While this is not strictly required for NetBoot, it is the protocol that makes the image show up in the Startup Disk preference pane and that simply makes life easier (you’ll see how much easier when I explain the alternative). Even better, Apple went as far as to document most of how to do this process in the manpage for bootpd. Some things are missing, but I hope this guide will clear those things up. And for good measure, I’ll show you how to do this without having to use BSDP at all (Debian NetBoot server, anyone?).

Getting Started

Now, there are several ways of doing this and they depend on what you have at your disposal. If you have a copy of Mac OS X Server, then stop reading this and refer to the System Imaging Admin Guide for how to make a NetBoot image and serve it the really, really easy way.

Yet, if you have a pair (or more) of Macs running Mac OS X (or a machine running Darwin) and plan on using one that’s not running Mac OS X Server to host this, then read on and use the easy way of making and serving the image. If you plan on serving the image from a machine based on an OS other than Mac OS X or Darwin, then you’ll want to follow the more in-depth steps and, hopefully, you know how to setup TFTP and NFS on your server.

The Easy Way

The easy way works for people with multiple Macs who just want one machine to serve up an image or two. It could also work for large organizations that want to load-balance their NetBoot service without the expense of multiple NetBoot servers. Granted, you will loose the ability to easily manage those remote servers (that’s what you’re paying for with Mac OS X Server), but if you just want a remote mirror, then this works.

All of the following commands must be done as root.

Create the NetBoot Share Directories

NetBoot images must be kept together for various reasons, so we create two directories in /Library/NetBoot to store the various parts of this. The first is the NetBoot share point, NetBootSP0. This directory will contain the image files. The second share is NetBootClients0 which will hold client data for diskless NetBoots. We’ll set this up, but you generally don’t want this because it doubles the amount of traffic on the network (among other things).

mkdir -p /Library/NetBoot/NetBootSP0
mkdir /Library/NetBoot/NetBootClients0
chown root:admin NetBoot*
chmod 775 NetBoot*

Now, the names for the shares are not hard-coded into bootpd. Rather, the symlinks .sharepoint and .clients are hard-coded and each /Library/NetBoot on mounted drives has a pair of these symlinks that point to the respective share point and client data directories for that drive. By custom, they are named with incrementing integers (NetBootSP0, NetBootSP1, etc.) but can be just about anything. So, that said, we have to make those links. If you don’t create both of these, bootpd won’t advertise the images for you and your log will have the following:

bootpd[9656]: bsdpd: no client sharepoints defined
bootpd[9656]: bootpd: NetBoot service turned off

So, create both folders and link both folders as follows, even if you won’t be using diskless NetBoot:

ln -s /Library/NetBoot/NetBootSP0 /Library/NetBoot/.sharepoint
ln -s /Library/NetBoot/NetBootClients0 /Library/NetBoot/.clients

Configure and Enable NFS

Like most services in Mac OS X, NFS is a bastardized version that gets its configuration out of NetInfo rather than an exports file. That said, NetInfo is easy to setup for something like this. You could use NetInfo Manager, but that just takes all the fun out of this, so here’s how to do this with nicl (say “nickel”).

nicl . -create /exports
nicl . -create /exports '\/Library\/NetBoot\/NetBootSP0'
nicl . -create '/exports/\/Library\/NetBoot\/NetBootSP0' opts ro

Now that the path is exported to world, you want to start NFS. To do so, follow these steps in their exact order:

service com.apple.portmap start
mountd
nfsd -t -u

The service command coupled with the records in NetInfo trigger inner workings of Mac OS X such that you do not need to repeat this procedure after a restart. Corollary: You could restart after the service command and be done as well.

Setup AFP

Diskless NetBoot requires an AFP connection to the server for the clients directory, and System Image Utility can push an image to a server over AFP if the share is setup right. So, we set them both up right so you can do both things.

nicl . -create /config/SharePoints/NetBootSP0
nicl . -create /config/SharePoints/NetBootSP0 afp_name NetBootSP0
nicl . -create /config/SharePoints/NetBootSP0 afp_shared 1
nicl . -create /config/SharePoints/NetBootSP0 afp_guest 0 
nicl . -create /config/SharePoints/NetBootSP0 directory_path /Library/NetBoot/NetBootSP0
nicl . -create /config/SharePoints/NetBootClients0
nicl . -create /config/SharePoints/NetBootClients0 afp_name NetBootClients0
nicl . -create /config/SharePoints/NetBootClients0 afp_shared 1
nicl . -create /config/SharePoints/NetBootClients0 afp_guest 0 
nicl . -create /config/SharePoints/NetBootClients0 directory_path /Library/NetBoot/NetBootClients0

Now turn on AFP in the Sharing preference pane. If it was already on, the changes are immediate.

Configure and Enable TFTP

TFTP is used to distribute the boot loader and kernel to the client system. We need to make some things work as expected here for NetBoot to send the right files to the client. While you could symlink the whole /Library/NetBoot folder to /private/tftpboot and it would work, that would also mean you couldn’t add other share points in there from other partitions. I’m all about the flexability, so run the following to setup the tftp root and then start the service:

mkdir /private/tftpboot/NetBoot
ln -s /Library/NetBoot/NetBootSP0 /private/tftpboot/
service tftp start

Configure and Enable BSDP

All the hard work has been done, so there’s just a couple of final steps to getting bootpd to answer BSDP requests. The first is to tell it to be a NetBoot server, and the second is which interface to listen on. Once you’ve run those commands, service starts it and sets it to start in the future.

nicl . -create /config/NetBootServer
nicl . -create /config/dhcp netboot_enabled en0
service bootps start

Now, check your system.log at this point and make sure you get a clean bootpd startup like the following. If you didn’t, you did something wrong. Run over the steps again.

bootpd[461]: interface en0: ip 10.0.1.4 mask 255.255.255.0
bootpd[461]: server name mymac.local
bootpd[461]: subnets init using domain . failed: 
bootpd[461]: bsdpd: re-reading configuration
bootpd[461]: bsdpd: shadow file size will be set to 48 megabytes
bootpd[461]: bsdpd: age time 00:15:00

Download and Install the Admin Tools

Apple provides the Server Admin Tools as a free download. Mostly these tools interact with the server processes servermgrd and the LDAP server, but at least one tool is useful in its own right: System Image Utility. Using this utility, one can make a NetBoot image with all of the proper information setup for you. As you’ll see later, this is a very good thing. Use this utility to make your first image so you have a reference to go by.

Create the NetBoot Image

There are many types of NetBoot images we can make with this tool:

• A standard NetBoot image made from the installation media
• A standard NetInstall image made from the installation media
• A custom NetBoot image made from a completed install
• A custom NetInstall image made from a completed install

• A custom NetInstall image made from a set of packages

The last is the easiest to make, so it will be the example. Open System Image Utility and click on Install in the toolbar. Name the image, give it an ID under 4096, and describe it.

alt=“siu-general” title=“siu-general” class=“center” />

On the Contents tab, change the source to Custom Package Install and click on the add button to add a completed package you’ve pulled down at some point in time. When all the packages you want to install have been added, click on Create and select the freshly-made NetBoot drive from the menu.

If you’ve ever told Software Update to download and save the package, look in /Library/Packages for those packages.

Fix the NetBoot Image

By default, the image is disabled. We need to change this. Change directories to be inside the NBI image and then run the following commands to clean up the plist and enable the image:

defaults write $PWD/NBImageInfo IsEnabled -bool true
defaults delete $PWD/NBImageInfo EnabledSystemIdentifiers
defaults delete $PWD/NBImageInfo DisabledSystemIdentifiers
plutil -convert xml1 NBImageInfo.plist
killall -HUP bootpd

Tweak the NetBoot Image

System Image Utility lets you hack the image, if you want to. Click on List in the toolbar, pick the image to edit, then click on Edit in the toolbar. It offers to backup the original image for you, if you like, and then mounts the image inside the NBI folder at /path/to/folder.nbi/mnt. Go here and do anything you like to the image, or change values in System Image Utility to your heart’s desire. When you click on Save the program will make any changes you’ve requested (like adding additional packages) and then unmount the image.

If you edited the disk in Terminal, make sure you’ve changed directories out of the mnt directory before saving the changes.

Boot the Mac

Make sure you’re on the same ethernet network as the new server and then go to Startup Disk and you should see the image name as the available image on the network. Pick it and restart and you should boot off the other machine at this point.

The Hard Way

All of that supposes that you’re using a Mac as the server. It can get a lot harder to do this if you’re not, but it’s still very possible to do. You’ll need to make the image and NBI resources on a Mac and then move the folder to the server to be served. Having read the above, you know the paths that are expected for NFS and TFTP so you should make those work in your environment. I’ll go over making the image by hand and setting the boot variables so that the Mac side is done. These instructions will center around imaging the install DVD and using it as the NetBoot device, but the same instructions would work for any mounted image or drive with an install of Mac OS X on it.

Make an Image

On the Mac, mount the drive with an installed copy of Mac OS X then do something like the following:

The following commands presume you are working with a PPC image and your working directory is inside the NBI directory.

For more on NetBooting Intel images, look at the information on Mike Bombich’s NetBoot page on how to make a hybrid image. Essentially, you add an “i386” architecture to the NBImageInfo.plist file and then put the boot loader, kernel, and kernel extension cache in an i386 folder inside the NBI folder. Be absolutely sure the image you’ve made can boot both architectures if you do this!

There are two ways to make this image: read-only and read/write. Read-only is smaller and has a chance of being below 2GB for delivery over HTTP (Apache 1.3). Read/write will be larger, allow editing, and must be deployed over NFS or HTTP with Apache 2.0. If you pick read-only, then you’ll need twice the disk space free as the amount of space used on the target device and your format code is UDZO (read-only compressed). If you choose read/write, your format code is UDRW. System Image Utility makes UDRW images.

$ mount
...
/dev/disk2s3 on /Volumes/Macintosh HD (local, journaled)
$ hdiutil create -srcdevice disk2s3 -format [format code] image.dmg

$ hdiutil convert -format UDRW -o imagerw.dmg image.dmg
$ hdiutil mount imagerw.dmg
[do stuff]
$ hdutil detatch imagerw.dmg
$ hdiutil convert -format UDZO -o image.dmg imagerw.dmg

Setup the NBI folder

The paths below reference the startup drive. You’ll want to mount the image and use the files on the image instead if it’s a different version of Mac OS X than the one you’re using. If it’s the same version, go ahead and use the local disk for this. If you’re using an install DVD with the same major version as the system you’re booted to, either use the local kernel and extensions or copy the extension cache from the DVD directly rather than regenerating it as the DVD doesn’t have extensions in the Extensions folder.

cp -p /usr/standalone/ppc/bootx.bootinfo booter
cp -p /mach_kernel mach.macosx
kextcache -l -n -s -z -m mach.macosx.mkext /System/Library/Extensions
defaults write $PWD/NSImageInfo Name -string 'Name of the image'
defaults write $PWD/NSImageInfo BootFile -string booter
defaults write $PWD/NSImageInfo Index -int 1001
defaults write $PWD/NSImageInfo IsEnabled -bool true
defaults write $PWD/NSImageInfo Kind -int 1
defaults write $PWD/NSImageInfo RootPath -string image.dmg
defaults write $PWD/NSImageInfo Type -string NFS
plutil -convert xml1 NBImageInfo.plist

If you are deploying this on a non-Mac OS X system, the defaults and plutil commands do not need to be run as only the Mac bootpd uses the NBImageInfo file. They exist for completeness so that this image can be deployed on a Mac server.

Setup TFTP and NFS

Make sure these are enabled on your server and that the following paths work:

tftp://server.name/NetBoot/NetBootSP0/ImageName.nbi/booter
tftp://server.name/NetBoot/NetBootSP0/ImageName.nbi/mach.macosx
tftp://server.name/NetBoot/NetBootSP0/ImageName.nbi/mach.macosx.mkext
nfs://server.name/Library/Volumes/NetBootSP0/ImageName.nbi/image.dmg

If you want to use other names or paths and are deploying on a Mac, read bootpd’s manpage for how to specify an image name and location. If you are deploying on something else, just note what the actual paths are over each protocol.

Set the Mac’s Boot Arguments

There are three Open Firmware boot variables that matter here:

• boot-device controls what hardware device you boot from and the boot loader on that device
• boot-file controls what file the boot loader will pass control to when it is done loading

• boot-args are the arguments passed to the kernel when the boot loader executes it

Both the boot-device and boot-file arguments will use TFTP and require the use of backslashes instead of slashes to delimit the directories. For example:

boot-device enet:10.10.10.10,NetBoot\NetBootSP0\TigerDVD.nbi\booter
boot-file enet:10.10.10.10,NetBoot\NetBootSP0\TigerDVD.nbi\mach.macosx

Here’s an example that does not use conventional directories:

boot-device enet:10.10.10.10,MacNetBootImages\TigerDVD\booter
boot-file enet:10.10.10.10,MacNetBootImages\TigerDVD\mach.macosx

Lastly, you need to tell the kernel where to get its root filesystem from. Your choices are HTTP and NFS. Here’s a pair of examples:

boot-args rp=nfs:10.10.10.10:/private/tftpboot/NetBoot/NetBootSP0:TigerDVD.nbi/image.dmg

boot-args rp=nfs:10.10.10.10:/tftpboot/MacNetBootImages:TigerDVD/image.dmg


	
boot-args rp=http:10.10.10.10:/NetBoot/NetBootSP0:TigerDVD.nbi/image.dmg

boot-args rp=http:10.10.10.10:/MacNetBootImages:TigerDVD/image.dmg

Note the colon in the path (and the use of normal slashes). The colon delineates the NetBoot share point from the image name and path within.

Pray

Just that. It would appear several of these steps require the blood of a virgin Dutch chicken. Accept no substitutes.

Credit

A lot of this information was based on me testing this out with a copy of Mac OS X Server at my side and watching what it did. A lot of it was reading the bootpd manpage from head to toe. A lot of it was from Mike Bombich’s great NetBoot resources and previous work with NetBoot. His site’s tips center around using Mac OS X Server in creative ways, and my experience is with using Mac OS X in very perverse ways, so it worked out well, I think. Below are pages consulted in the creation of this guide:

• Mike’s NetBoot Tips (for the Intel information and how to make the kernel extension cache)
• How to NetBoot across subnets (for the OF variables)
• How to setup NFS in Mac OS X
• The bootpd source code (mainly bsdp_init)
• Some previous efforts
• Some previous efforts of mine

• Some priceless NetBoot troubleshooting tips

Due to some site issues, this article has been re-dated for today as this was, technically, the first day it appeared in the site’s RSS feed.