Installation

Manual Install Instructions

System Requirements

 The following conditions must be true in order to use ZFS Boot alpha bits.

• The rootpool must be either fully contained on a single vdev or in a mirrored configuration. Multiple disk pools, aside from a mirrored configuration, are not supported.
• The disk containing the rootpool must be labeled with an SMI label. This means that you can not create a zpool using the whole disk notation (ex: c0d0) as this will cause an EFI label to be written. Instead, a slice notation must be used (ex. c0d0s0).
• A ZFS root filesystem can not be placed in the pool's top level filesystem.

Terminology

rootpool: A rootpool is a pool containing a bootable environment
mountroot: ZFS Mountroot was a previous prototype which relied on a UFS partition during bootstrap. Mountroot is mentioned in the instructions below, as some may wish to upgrade a system running ZFS Mountroot to ZFS Boot.
top level filesystem:  The filesystem that is automatically created when a pool is created.

Instructions

Note: If you are already running ZFS Mountroot, you can skip steps 1-9

1. BFU your UFS filesystem to Solaris Nevada build 42 or later.
2. Become superuser and create a zpool:please note the conditions described above before creating your rootpool. See the zpool man page for information about the zpool command.
    # /usr/sbin/zpool create pool_name vdev_list
3. Create a root filesystem in your new pool as root.
    # /usr/sbin/zfs create pool_name/root_filesystem
4. Change the mountpoint property for your newly created filesystem to legacy.
    # zfs set mountpoint=legacy pool_name/root_filesystem
5. Create a directory to mount your zfs filesystem
    # mkdir /zfsroot
    # mount -F zfs pool_name/root_filesystem /zfsroot
6. Populate your zfs root filesystem. To do this, copy all of the files in the UFS root filesystem to the newly created zfs root filesystem. The following command does this without crossing mountpoints. This command will take on the order of 30 minutes, give or take. Note, this will not cross mountpoints, if /usr, /var, or other filesystems are on other mountpoints, they will need to be copied over following this command.
    # cd /
    # find . -xdev -depth -print | cpio -pvdm /zfsroot
7. The directory structure for several auto generate filesystems need to be created. They can be manually created using the following commands or a script can be found at /home/tabriz/projects/zfs/zfs_boot/mountroot/mountroot_setup. If you have mounted your zfsroot in a location other than /zfsroot, you will need to modify this script.
    # mkdir /zfsroot/system/object
    # mkdir /zfsroot/system/contract
    # mkdir /zfsroot/tmp
    # mkdir /zfsroot/proc
    # mkdir /zfsroot/etc/svc/volatile
    # mkdir /zfsroot/var/run
    # mkdir /zfsroot/dev/fd
    # touch /zfsroot/etc/mnttab
    The permission on each of these files should be as follows:

1. Update the /etc/vfstab (on your UFS filesystem) to mount this zfs filesystem automatically on boot of your UFS root. This will be useful later in the setup process. Your entry should be of the following format:
   pool_name/root_filesystem - /zfsroot zfs - yes -
2. Populate the /devices filesystem. /devices is a devfs pseudo filesystem which sits on top of a ufs backing store. When a system is booted, /devices is mounted on top of this backing store and hides the underlying ufs backing store. To get at the underlying files, the system needs to be booted off of another root. The do this, follow the directions below.
   1. Before you reboot, take note of the /dev/dsk/c#t#d#s# of your UFS root filesystem. You will need this to mount it when booted off of another root. Now, reboot to another root. There are several options for doing this.
      1. boot off of the failsafe archive listed in grub
      2. boot off of the network
      3. boot off of a cdrom
   2. Mount your UFS root filesystem. For example:
      # mount /dev/dsk/c1t0d0s0 /a
   3. Create a cpio archive of the files in /a/devices (assuming you mounted on /a).
       # cd /a
       # tar cvf /a/devices.tar devices
   4. Reboot your system. When you come up, your zfs root should be mounted on the mountpoint created in step #5. If not, explicitly mount it as follows.
       # mount -F zfs pool_name/root_filesystem> /zfsroot
   5. Populate /devices on zfs
       # cd /zfsroot
       # tar xvf /devices.tar
       This is where mountroot users need to pick back up
3. BFU your zfsroot to our Alpha Bits: available  here and resolve any conflicts.
    # bfu /path_to_downloaded_bits/archives/i386/nightly /zfsroot
    # acr /zfsroot
    Details of how to BFU something can be found under BFU Instructions
4. This prototype identifies your root filesystem type using an entry in /etc/system (fyi: this is a temporary solution). Edit /zfsroot/etc/system to include the following entry.
   rootfs:zfs
    Note: Mountroot users will need to remove the zfsroot line. This information is now passed up from the bootloader. 
5. Edit /zfsroot/boot/solaris/filelist.ramdisk to include:
   etc/zfs/zpool.cache
6. If you would like to have your UFS root filesystem mounted while booted of ZFS, make a directory named "ufsroot" on your zfs filesystem. This will be used to mount your UFS root filesystem when booted off of ZFS.
   # mkdir /zfsroot/ufsroot
7. Edit /zfsroot/etc/vfstab to include mount instructions for your new root and ufs root. The entries should look similar to the following:
   root_pool/root_filesystem - / zfs - no -
   /dev/dsk/c1t0d0s0 /dev/rdsk/c1t0d0s0 /ufsroot ufs - yes -
   Make sure to comment out the line trying to mount your UFS root on "/". Also note that it recommended to have a separate slice for swap/dump. If you have followed the above procedures, you will most likely already have a swap slice set aside. See bugid 5008936 for more details.
8.  Mountroot users only: You can remove the bootadm hack previously needed to generate a boot archive for the zfs root filesystem. The boot loader is now capable of reading the archive and kernel directly out of your zfs root filesystem. The hack was most likely blown away during the bfu to our bits, but you may still have a bootadm.real executable which can be removed.
9. mkdir -p boot/grub in your top level filesystem. For example, if your zfsroot filesystem is "rootpool/rootds", you will need to mkdir -p boot/grub in /rootpool (or wherever "rootpool" is mounted).
10. Copy /zfsroot/boot/grub/menu.lst to your top level filesystem.
    # cp /zfsroot/boot/grub/menu.lst /rootpool/boot/grub
11. Edit /rootpool/boot/grub/menu.lst to include an entry for this boot environment. If you want this to boot by default, place this entry as the first boot environment entry, or edit the default= line accordingly. The kernel line of your menu.lst must contain a -B zfsroot=/  entry where rootpool is the pool containing your root filesystem and rootds is the root filesystem. This information is used to identify which dataset you would like to boot from (there can be multiple bootable datasets in a single pool).
     Your entry should look something like this.
    title Solaris ZFS
    root (hd0,0,h)
    kernel /platform/i86pc/multiboot -B zfsroot=rootpool/rootds
    module /platform/i86pc/boot_archive
    The root entry has the following format (hdx,x,x) where the first entry in the tuple is the disk identifier, the second entry is the partition number (0-3), and the third entry is the slice number (a-h), where a is slice 0 and h is slice 7. The root command is not needed unless your boot environment is on a different disk slice than is given to the installgrub command. Please see step #20 for more information on the root entry.
12. Create a boot archive for the zfs root.
    # /usr/sbin/bootadm update-archive -R /zfsroot
13. Lastly, time to install the new bootloader. The grub bootloader is installed via a utility called installgrub(1M). It takes, as its parameters, a pointer to stage1 and stage2 (available in your newly bfu'd filesystem at /zfsroot/boot/grub/stageN ) and the raw device containing a boot environment. The example below shows how to installgrub on a system which has the ZFS root filesystem on c0d0s7.
     # installgrub /zfsroot/boot/grub/stage1 /zfsroot/boot/grub/stage2 /dev/rdsk/c0d0s7
    Note: Installgrub will install stage1 and stage2 of the grub boot loader on the boot area of a disk partition. There is only one grub instance per partition, however you can install/boot multiple boot instances by using the grub root command. If, for example, you have a UFS root on c2d0s0 and a ZFS root on c2d0s7, and you have installgrub grub as shown above, you can add the following entry to the menu.lst file to provide boot capabilities for your UFS root.
    title Solaris UFS
    root (hd0,0,a)
    kernel /platform/i86pc/multiboot
    module /platform/i86pc/boot_archive
    
14. Reboot, cross your fingers, and remember to select your ZFS boot environment from the grub menu. =)

BFU Instructions

 For information on what BFU is, see the BFU entry in the  Developer's Reference Guide.

If you built ZFS boot bits from source, your BFU archives can be found in the archives/i386/nightly directory of your OpenSolaris source tree. If you did not build your own archives, you can download them from the Downloads page for this project.

For detailed instructions on installing from a BFU archive see  the Developers' Reference.

When deploying BrandZ on a fresh Solaris install, this will probably look like:

# GZIPBIN=/usr/bin/gzip ; export GZIPBIN
# cd  path/to/tarball
# bunzip2 -d -c zfsboot_bits.tar.bz2 | tar xf -
# ./bfu.sh path/to/tarball/zfsboot_bits/archives/i386/nightly

Be aware that the full pathname is required for the correct functioning of the bfu script. Don't assume that a relative pathname is sufficient.

Note that BFU requires requires manual resolution of configuration file conflicts and its use can be hazardous. After running the bfu script, you will be in the /bfu.conflicts directory. The automatic conflict resolution tool, called acr, should handle all conflicts correctly. If you have difficulty or would like to resolve conflicts manually, please refer to the Develpers' Reference