Description

ZFS Mountroot provides the capability of configuring a ZFS root filesystem. ZFS Mountroot is NOT a complete boot solution; it relies on the existence of a small UFS boot environment to bootstrap the machine.

ZFS Mountroot was integrated in Solaris Nevada Build 37, but is off by default. The following web page provides instructions for manually turning on and setting up ZFS as your root filesystem. A script will be provided shortly to automatically perform the actions described in this script.

Known Problems

• The ZFS Mountroot does not current work on SPARC, check back soon for an update.
• ACLs are not entirely preserved when copying files from a ufs root to a zfs root. ZFS will convert ufs style ACLs to the new NFSv4 acls, but they may not be entirely identical.
• 5008936 ZFS and/or zvol should support dumps
• 6256649 the boot-archive check should not trip over changes in devid-cache

Instructions

1. BFU your system to Solaris Nevada build 37 or later bits.


2. Become superuser and create a zpool. See the zpool(1M) 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. I hope to generate a script or other more useful method of creating these shortly.
   # 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:

   Name	Permissions	Owner	Group
   /system/object	dr-xr-xr-x	root	root
   /system/contract	dr-xr-xr-x	root	root
   /tmp	drwxrwxrwxt	root	sys
   /proc	dr-xr-xr-x	root	root
   /etc/svc/volatile	drwxr-xr-x	root	sys
   /var/run	drwxr-xr-x	root	sys
   /dev/fd	dr-xr-xr-x	root	root
   /etc/mnttab	-r--r--r--	root	root

   
   
8. 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 -


9. 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
      
   
   
10. This prototype identifies your zfs root filesystem using two entries in /etc/system. Edit /zfsroot/etc/system to include the following entries.
    rootfs:zfs
    zfsroot:root_pool/root_filesystem
    
    
11. Edit boot/solaris/filelist.ramdisk on your zfs filesystem to include:
    etc/zfs/zpool.cache


12. Make the following directory. This will be used to mount your UFS root filesystem when booted off of ZFS.
    # mkdir /zfsroot/ufsroot


13. Edit zfs's /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.

14. The following is a big hack to get around having to copy your zfs root boot archive to your ufs filesystem before each reboot.
    # mv /zfsroot/sbin/bootadm /zfsroot/sbin/bootadm.real

    Create a file named /zfsroot/sbin/bootadm and add the following script to it.

    #!/usr/bin/sh
    
    /sbin/bootadm.real "$@"
    /usr/bin/cp /platform/i86pc/boot_archive /ufsroot/platform/i86pc/boot_archive.zfs
    
    

    Make sure this file is executable.

    #chmod +x /zfsroot/sbin/bootadm
    
    

    Note: This script will not be preserved across bfu operations. Users are advised to copy this script to a safe location before bfu and restore it post bfu. The sequence of operations should be as follows.
    
    # cp $root/sbin/bootadm $root/sbin/bootadm.savescript
    bfu your zfs filesystem
    # cp $root/sbin/bootadm $root/sbin/bootadm.real
    # cp $root/sbin/bootadm.savescript $root/sbin/bootadm
    

15. Create a boot archive for the zfs root and copy it over to UFS.
    # /usr/sbin/bootadm update-archive -R /zfsroot
    # cp /zfsroot/platform/i86pc/boot_archive /platform/i86pc/boot_archive.zfs


16. Edit /boot/grub/menu.lst on your UFS filesystem to include an entry for ZFS. If you want this to boot by default, place this entry as the first boot environment entry. Your entry should look something like this.
    title Solaris ZFS
    root (hd0,0,a)
    kernel /platform/i86pc/multiboot
    module /platform/i86pc/boot_archive.zfs
    

    The root and kernel entries should be identical to the UFS entry already in this file.

17. Reboot, cross your fingers, and remember to select your ZFS boot environment from the grub menu. blogs.sun.com/images/smileys/smile.gif" class="smiley" alt=":-)" title=":-)" />

Filing Bugs

File bugs early and often! If you aren't sure if something is a bug, that's a bug. Please file a bug and mention your uncertainty in the bug report. All ZFS bugs should be filed via The Opensolaris Bug Database under kernel/zfs.

Thank you!