First, you must have a workspace containing a built kernel. If you
need more information on building kernels, see chapter 4 and especially
section 4.3. Once you have built a kernel, you need to make an Install
tarball using the Install command.
The Install(1) utility creates a tar file that can be extracted into an appropriate machine's root directory. It utilizes an existing built kernel tree and the kernel makefiles to determine the correct contents of the tar file. See Install(1) or the output of 'Install -h' for a complete list of options; only the most commonly-used options are described here.
The tar file constructed by Install is specific to an architecture, such as sun4u or i86pc. There are two ways to specify the architecture for which you want Install to create an archive. The first is to be in the architecture's subdirectory (usr/src/uts/<arch>) when running Install; the second and preferred method is to use the -k <arch> option. Note that current releases of ON support only one architecture in each ISA: sun4u on SPARC and i86pc on x86/amd64.
Another setting which is usually specified is the "glomname", using the -G option. This is the name of the subdirectory in /platform/<arch>/ that the binaries will go into, and is generally of the form "kernel.something". If you don't use a glomname, you will overwrite the current kernel and modules on the target machine, and are likely to make BFUing the machine later a more difficult task, as well as running the risk of having to boot from alternate media to fix your machine if the new kernel does not boot.
A simple invocation of Install might look like:
$ Install -G kernel.foo -k sun4u ... lots of spew ... Creating tarfile /tmp/Install.username/Install.sun4u.tar Install complete
You can now copy /tmp/Install.username/Install.sun4u.tar to your test machine and extract it in the root directory. It's best to use the '-o' option when extracting so that file ownership will be correct.
On x86 with build 14 or newer, you will need to add your kernel to the boot archive before you will be able to boot it. To do this, add the line:
platform/i86pc/kernel.foo
to /boot/solaris/filelist.ramdisk, where kernel.foo is the
glomname (the argument to -G). This requirement is eliminated in
build 18 and newer, and does not apply to SPARC.
After installing your kernel, reboot the test machine and have it use the new kernel by running:
(SPARC) # reboot -- 'kernel.foo/sparcv9/unix'
(AMD64) # reboot -- 'kernel.foo/amd64/unix'
(x86) # reboot -- 'kernel.foo/unix'
Note that you will need to use either this reboot syntax each time you wish to boot the test kernel, or use similar arguments to the bootloader or OBP. Otherwise, the normal kernel installed by BFU or the regular installation will be booted.
Although Install is useful for developers who have changed only kernel code, it is of limited value for others. In particular, if a recent flag day notice indicates that newer kernels are incompatible with existing userland libraries or commands, Install cannot be used to test the updated kernel until you have upgraded your userland via BFU or some other mechanism such as the regular installation or upgrade procedure.
Like bfu (see section 5.3), Install is rather closely attached to its particular release, so you should use the current version from the gate matching the release you are building. Normally this is in the public/bin subdirectory of the gate; however, for installations outside Sun it is located in /opt/onbld/bin.
It is critical that Install users install the correct set of platform-specific modules, especially on SPARC systems. Failure to do so can result in an unbootable system. See section 5.2.2 below for more information on how platform-specific modules relate to Install.
One major advantage of Install over BFU is the ability to keep your existing kernel in place so that you can still boot if the test kernel proves toxic. We strongly recommend that if you use Install to test kernels, you take advantage of this feature and use distinct locations (see the -G option described in section 5.2.1 above) for each new kernel you test. Otherwise, you will likely have to boot from alternate media to repair your system following the installation of a bad kernel.
Ordinarily, Install does not generate archives with implementation-specific modules. If these archives are installed onto a system which requires the missing modules, the system may fail to boot or work properly. If you do this, you will need to boot from a known-working kernel and correct the problem.
An example symptom of the problem (on an Enterprise 3500):
SunOS Release on81 Version jrhyason_[ws-vmstat]_05/15/01 64-bit Copyright 1983-2001 Sun Microsystems, Inc. All rights reserved. DEBUG enabled obpsym: symbolic debugging is available. Read 297063 bytes from misc/forthdebug ====> WARNING: consconfig: consconfig_util_openvp failed: err 6 vnode 0x2803c80 ====> WARNING: consconfig: consconfig_util_link I_PLINK failed: error 22 configuring IPv4 interfaces: hme0. ...
The console is gone!
To include the needed modules in your Install tarball, make sure to use
$ Install -i <implementation>
to include implementation-specific modules. But how do you know what sun4u implementation you need? First, obtain your machine's "official" implementation name from the output of 'uname -i'. Then, in usr/src/uts/sun4u, run "grep IMPLEMENTED_PLATFORM */Make*" to see a list of implementations and the corresponding platform name reported by uname(1).
In the example above, the E3500 reports:
$ uname -i SUNW,Ultra-Enterprise
And we see from the grep output:
$ grep IMPLEMENTED_PLATFORM */Make* ... sunfire/Makefile:IMPLEMENTED_PLATFORM = SUNW,Ultra-Enterprise ...
In this case, the "-i sunfire" argument must be added to get the correct behavior.
Additionally, one of the easiest ways to get tripped up with Install wads comes from the fact that not all drivers are delivered by ON. This has been particularly noticeable with x86, but it also happens with SPARC, especially framebuffer drivers. One way to work around this is to do:
# cd /platform/{sun4u,i86pc}
# mkdir glomname
# (cd kernel; tar cf - .) | (cd glomname; tar xf -)
and then install the Install glom image. This will copy your existing drivers to the new kernel installation, ensuring that the drivers which are not part of ON (or OpenSolaris as a whole) are available when you reboot.