SchilliX Files

###########################################################################
# HOWTO install a ZFS-Root based SchilliX
###########################################################################
# @(#)README.ZFS-Root	1.3 20/01/15 Copyright 2020 J. Schilling
###########################################################################
# Copyright J. Schilling. All rights reserved.
#
# The contents of this file are subject to the terms of the
# Common Development and Distribution License, Version 1.0 only.
# See the file CDDL.Schily.txt in this distribution or
# http://opensource.org/licenses/cddl1.php for details.
###########################################################################

A ZFS-Root based installation, where the whole OS directly boots into a ZFS
based / filesystem is a complex attempt.

IMPORTANT: a typical ZFS in one or more disks is based on the plain full disk
instead of a historical FDISK+Sun-Label based filesystem. If ZFS is used this
way, it automagically created an EFI label on the disk and used the whole disk.

	"installgrub" cannot yet deal with such a EFI based ZFS installation
	and for this reason, we need a FDISK+Sun-Label on a bootable disk.

	Read README.install and README.fdisk for more information.

 1. After the disk is partitioned using fdisk, a partition has to be labeled
    with a Sun disk label. Use "format" for this task.

    # format /dev/rdsk/<device>

	Example: format /dev/rdsk/c0d0p0

	Enter the partition menu by typing "par" and 
	create a root partition that spans the whole rest of the Sun label
	by typing "0" and answering questions appropriately.

	Important: partition "0" should begin at "cylinder 1" to give
	space for grub's stage2 file that is hold in the boot partition
	in slice 8. For the end of the partition, enter "$" to use the
	whole rest of the disk.

 2. Create a ZFS root pool on "slice 0" of the Sun label.

    This ZFS needs an alternate mount point.

	Example: zpool create -f -R /mnt rpool c0d0s0

	You need to use the option -f as well, since the zpool command
	otherwise warns about the overlapping slice "s2", which however
	is no problem in this context.

	If you like to set up a mirror, or other zpool features, this
	can be done here.

	Note that the current grub version does not yet support compression
	in the root pool.

 3. Create the swap, dump and the ZFS-root filesystem.

	You may like to use different sizes for swap and/or dump.

	Example:

	zfs create -b 4096 -V 2048m rpool/swap		# create 2G of swap
	zfs create -b 131072 -V 2048m rpool/dump	# create 2G of dump

	The swap block size should match the pagesize, which is 4k on amd64.
	The swap size should be 2x the RAM size if you have few memory and
	RAM/2 if you have plenty of memory.
	The Solaris installer sems to use a size of 2G.

	The dump size needs to be equal to the RAM size if you like to be
	able to get a full kernel core dump even from a highly active system.
	The Solaris installer seems to use a size of 1G.

	The size specified with -V refers to the reserved preallocated
	size. If the pool is not yet full, the data sets may grow on demand.

	#
	# This creates the intermediate directory for the root FS:
	#
	zfs create -o mountpoint=legacy -o canmount=off rpool/ROOT
	#
	# This creates the ZFS-root filesystem that is mounted as /
	#
	zfs create -o mountpoint=/ -o canmount=noauto rpool/ROOT/sxce_147

 4. Set up a uuid for the ZFS root.

	Example: zfs set org.opensolaris.libbe:uuid=`makeuuid` rpool/ROOT/sxce_147

 5. Mount the needed filesystems the right way.

	Example:

	zfs umount -a 
	zfs mount rpool/ROOT/sxce_147 
	zfs set mountpoint=/rpool rpool   
	zfs mount rpool 

 6. You may like to check the results

	Example: zfs list

	and get something like:

	NAME                  USED  AVAIL  REFER  MOUNTPOINT 
	rpool                16.7G  2.87G    31K  /mnt/rpool 
	rpool/ROOT           12.6G  2.87G    31K  legacy 
	rpool/ROOT/sxce_147  12.6G  2.87G  12.6G  /mnt 
	rpool/dump           2.00G  4.87G    16K  - 
	rpool/swap           2.12G  4.99G    16K  - 

 7. Install the OpenSolaris base binaries to the new filesystem under "/mnt"
    The next version of SchilliX will permit two different install variants.
    The current SchilliX release only supports to copy the content of the CD
    to the new filesystem /mnt by calling:

	 Copy the files tree from CD to the mounted disk using `star'.

		star -copy -p -sparse -no-fsync -time -xdot bs=1m fs=32m -C /.cdrom/ . /mnt

	     or:

		star -copy -p -sparse -no-fsync -time -xdot bs=1m fs=32m -C /media/SchilliX-0.8/ . /mnt

	    If you like to install from a lofi mounted SchilliX ISO image, do this:

		lofiadm -a /export/home/SchilliX-0.8.iso
		mkdir /mnt2
		mount -r -Fhsfs /dev/lofi/1 /mnt2
		star -copy -p -sparse -no-fsync -time -xdot bs=1m fs=32m -C /mnt2 . /mnt

 8. Set up the layout of the keyboard in:

		/mnt/boot/solaris/bootenv.rc

     and comment out the entry:

		setprop keyboard-layout German

	or replace "German" by the name of your keyboard layout.

 9. Create the grub loader config "/mnt/rpool/boot/grub/menu.lst", call:
    
	mkdir -p /mnt/rpool/boot/grub/bootsign
	cp menu.lst.zfs-root /mnt/rpool/boot/grub/menu.lst

    Make sure a boot signature that fits thefile "menu.lst" is available:

	touch /mnt/rpool/boot/grub/bootsign/pool_rpool
	mkdir -p /mnt/rpool/etc
	echo pool_rpool > /mnt/rpool/etc/bootsign

    This is needed to allow grub to locate the correct root pool via
    the "findroot" command in grub.

10. Install grub into the master boot record (using the `-m' option)
    or any other boot record of an existing partition, but remember to
    set this partition as bootable.

    # installgrub [-m]

	Example:
		cd /mnt/boot/grub/
		installgrub -m stage1 stage2 /dev/rdsk/c0d0s0

	IMPORTANT: if you did set up a zpool mirror, repeat this command with
	the other side of the mirror. This may result in something like:

		installgrub -m stage1 stage2 /dev/rdsk/c1d0s0

	note that the last argument depends on the location of the mirror.

11. Populate the /mnt/dev directory with the correct entries by using devfsadm:

	Example:
		devfsadm -r /mnt

12. Edit `/mnt/etc/vfstab' to reflect the proper device paths to filesystems.

	Use "vfstab.zfs-root" as a reference.

	Important: a ZFS-Root version of /etc/vfstab looks different from
	a UFS based one. For a ZFS-root, it should be sufficient to copy
	the _unmodified_ "vfstab.zfs-root" to /mnt/etc/vfstab

13. Generate an initial ramdisk for grub which is needed to boot where
    <mount-point> is the mounted ZFS root of the new system.

    # bootadm update-archive -R <mount-point>

	Example:
		bootadm update-archive -R /mnt

14. Set up ZFS dump device for kernel dumps

	Example: dumpadm -r /mnt -d /dev/zvol/dsk/rpool/dump

	XXX This does not seem to work here, so better call
	XXX dumpadm -d /dev/zvol/dsk/rpool/dump
	XXX after you did boot the new installation

15. Set owner/group and permissions on the new root directory.

	Call chown root:root /mnt; chmod g-s,u=rwx,g=rx,o=rx /mnt

16. Final settings on the root pool

	Call:
 
	#
	# Set appropriate ZFS error mode
	#
	zpool set failmode=continue rpool 
	#
	# Set up root dataset for grub
	# 
	zpool set bootfs=rpool/ROOT/sxce_147 rpool 

17. Unmount the ZFS root filesystems

	zfs umount -a 
	zfs umount /mnt

18. Export the ZFS root pool

	zpool export rpool

Now boot the new installation.