WANBoot technical overview

Wanboot is significantly different from prior methods of "jumpstart install" for Solaris, in many ways. Yet it still retains some commonalities. Primary differences are in the bootstrapping. As such, I do not explain quite ALL things for a newbie user. You are expected to know a little bit about "traditional" jumpstart usage, such as how to put together a "rules" file, and a "sysidcfg" file.

Contents

• Server setup
• Client setup
• Client sequence
• Client-specific wanboot configs

Server setup

The sun documentation for this is, as usual, overly complex, to the point of potentially making you more confused, rather than less. So here's a simplified method.

1. On the server side, from your DVD image, you can do the usual "Solaris_10/Tools/setup_install_image $DESTDIR" Once you have done that, make sure to http-share out at minimum, $DESTDIR/boot, and $DESTDIR/Solaris_10/Tools/Boot.
   (If you arent using flash archives to install, then you'll also need to distribute out $DESTDIR/Solaris_10/Product somehow)

   It is indeed vexing that they name BOTH of the critical directories as "boot". What you need to know, is the following translations, for your wanboot.conf:

     root_file=(http://$DESTDIR/boot/sparc.miniroot)
     boot_file=(http://$DESTDIR/Tools/Boot/platform/{sun4v,sun4u}/wanboot)
     #Although interestingly, the sun4u one seems to work for sun4v also
   

2. Copy from /usr/lib/inet/wanboot, wanboot-cgi and bootlog-cgi, to your webserver CGI directory. (and replace the dash with a dot. ie: "wanboot.cgi")
3. Set up at minimum, /etc/netboot/wanboot.conf from the example at /etc/inet/wanboot.conf-sample.
   Except remove the bad comments about boot_file, and just put in the proper URL for it as mentioned above.

   Comment out all the authentication/encryption stuff unless you know how to use it. Optionally validate your file, with
   /usr/sbin/bootconfchk /etc/netboot/wanboot.conf

4. Create your own /etc/netboot/system.conf file, with at minimum, two lines, such as

   SjumpsCF=http://path/to/rules/dir
    #(You need to understand "normal" jumpstart rules file usage)
   SsysidCF=http://path/to/directory (which CONTAINS a sysidcfg file)
   

You should now be set up on the server side.

Client setup

You either have to boot from a Solaris 9+ cdrom with

boot cdrom -F wanboot [...]

or you have to be able to set the "network-boot-arguments" variable in EEPROM. If you dont have it, then your EEPROM is too old to support direct wanboot, and you must boot from cdrom/dvd instead.

Sample EEPROM settings

setenv network-boot-arguments host-ip=1.2.3.4,hostname=namehere,router-ip-1.2.3.1,subnet-mask=255.255.255.0,file=http://1.2.3.20/wanboot.cgi

The above is the MINIMUM you must set. There are a few extra optional things you may set in eeprom which I wont go into here, such as proxy information, and encryption keys.

Client sequence

In theory, if you have followed the above directions carefuly, everything should work fine. But when they do NOT go fine, it is useful to have the following information, to attempt to figure out where things have gone wrong!

Per my observations, a wanboot client goes through the following steps, after you type "boot net - install".
( no further args needed, since they are all specified in network-boot-arguments, however you MAY specify others. Such as the ubiquitous "-s" option, if needed! ) This summary ignores any encryption back-and-forth issues.

0. (If and only iff the "file" value from network-boot-arguments begins with http or https, treat that as the CGI-based information source for the 'Requests', below)
1. Request "bootfile" via CGI. This is actually the "boot_file" defined in the most appropriate "wanboot.conf" file, as determined by wanboot.cgi. It wants the actual FILE, not the string, back.
2. (Server-side info) The above request goes through a multi-step process on the server side, to choose what values to return.
   • Do a special lookup to determine the most client-specific "wanboot.conf" file
   • Look up the "boot_file" argument in it
   • Pass that whole file back as the returned value for the CGI request.
   
   Side note: This is analogous to the old tftp bootstrap, of going to the tftp boot server and requesting SUNW.`uname -i`. In fact, you can specify "file=tftp://1.2.3.4/old-bootstrap-file", and then continue to do an otherwise "normal" oldfashioned style jumpstart. This is rather important, since the newer EEPROMS have disabled the ability to set "tftpboot-server" as a "boot net" command line option!

3. Request "bootfs" for this client. This is a particularly murky operation, that aparently returns an ISO FILESYSTEM, containing what wanboot.cgi deems to be the "most appropriate" versions of wanboot.conf and system.conf, for that particular client.
   Of particular interest, is that the "system.conf" file is specified as a relative path to the wanboot.conf file chosen, unless you explicitly use absolute-url syntax
4. Request "rootfs" parameter from wanboot.
   This goes through a server-side parsing similar to the "bootfile" steps, to return the file (root ramdisk) (at least for solaris 10: not tested on solaris 9) specified by the "root_file" value in the appropriate "wanboot.conf" file
   • (Note: in above step, looks for wanboot.conf in client-specific dir, then subnet specific dir, then global /etc/netboot. Then looks for file matching name of "system_conf" parameter.
     WARNING: it will perform the same search location order as for the wanboot.conf file!! Therefore, it is possible to end up using a subnet-level wanboot.conf,but a client-specific system.conf, even if you specify "system_conf=system.conf" in the subnet wanboot.conf!!)

5. Directly requests via HTTP (or possibly other protocols if directed?) the miniroot specified in rootfs.
   • Oddly, at this point, it goes through some dumb backflips to silently pass back (percent complete) updates to the server, while being COMPLETELY SILENT ON CONSOLE. This information gets logged, by default, to /tmp/bootlog.[hostname], if you have the boot_logger cgi enabled in wanboot.conf
6. Requests the sysidcfg file from the directory specified by SsysidCF in system.conf, via direct HTTP request
7. ...
8. /tmp/_install_config is created. Either by a loopback mount of /usr/sbin/install.d/install_config, or... (?magic?) This contains the "rules" files, and if you are lucky, jumpstart "profiles" that you need. If you are "unlucky", see the "crucial difference" warning I have lower down.

From here on in, it would appear to be a "standard" jumpstart. It checks the "rules" file in /tmp/_install_config, finds a matching "profile",and does an install based on the information there.

With one crucial difference: They seem to have partially broken profile aquisition, on the wanboot side only. You cannot have a profile (as specified in the rules file) in a subdirectory; only in the same directory as the rules file. This happens whether you use http or nfs as the transport for the jumpstart directory, given by SjumpsCF. Yet oddly, doing a "normal" jumpstart, does not have this problem. This is noted from Solaris 10 2008/10 release.

Client-specific wanboot configs

If you wish to overwrite the global default files on the server, of

/etc/netboot/wanboot.conf
/etc/netboot/system.conf

you must create either a subnet specific wanboot.conf, or a client-specific one. It was not clear from the sun docs I initially read, that the file must be named "wanboot.conf", in an appropriately named directory. So, create either of

/etc/netboot/1.2.3.0/wanboot.conf
/etc/netboot/1.2.3.0/01AABBCCDDEEFF/wanboot.conf

where "AABBCCDDEEFF" is the macaddress of the client machine, in uppercase. Do note that the "wanboot.cgi" program would appear to be hardcoded to look under "/etc/netboot" for the information. There is no apparent config file for "wanboot.cgi" itself, that I have found.

Old School tftp tip for traditional jumpstarts

This is a bit out of place,but just to get the information "out on the net", for those people tring to do a "normal" jumpstart, and getting stuck:

As mentioned above, a machine whose eeprom supports the new "network-boot-arguments" variable, cannot be hand-commanded with the old style of

boot net:host-ip=1.2.3.4,router-ip=1.2.3.1,tftp-server=1.2.3.50

The good news is, you can do the same thing, with

boot net:host-ip=1.2.3.4,router-ip=1.2.3.1,file=tftp://1.2.3.50/explicit-file.here

(Or, if you prefer, shove those extras permenantly into the "network-boot-arguments" variable.

The better news is, you can replace tftp from your network permenantly, albeit not quite directly. You cant quite specify a bootstrap file to load DIRECTLY, with "file=http://xxx". However, you can specify an old fashioned inetboot.XYZ file as a wanboot.conf's "boot_file" argument. After that, you'll then be at the mercy of dhcp (or in.rarpd) on your network.