#!/bin/bash

build() {
    local mod
#    for mod in aufs squashfs loop vfat ext4 iso9660 fuse; do
    for mod in aufs overlay squashfs loop vfat ext4 iso9660; do
        add_module "$mod"
    done

    add_runscript
#    add_binary /usr/bin/ntfs-3g
    add_binary /usr/bin/blkid
    add_binary /usr/bin/find
    add_binary /usr/bin/losetup
    add_binary /usr/bin/lsblk
}

help() {
    cat <<HELPEOF
This hook enables booting from an aufs or overlayfs root filesystem.
It can boot Arch from a full/subdir install, squashfs module stack, or image.

SETUP
-----

- install an aufs-capable kernel/module when using dir=/aufs mode

- add "fsck rootaufs3 subdir2" to HOOKS in /etc/mkinitcpio.conf

- setup a boot entry with the appropriate options, "changes" being the minimum


USAGE
-----

boot options:

- base_only:
    load only base modules whose path contains /base/0.

- break=pre|aufs|post:
    start an interactive debug shell at selected hook stages.

- changes[=path]:
    enable the hook and specify the RW filesystem for aufs mode.

    by default mounts a tmpfs filesystem
    if "path" is specified and is a block device or disk image, mounts that instead
    "changes=dirname" works only with "roothide"

    *WARNING*: the FS specified here WILL be modified, so use carefully

- changeso[=path]:
    overlayfs backend RW filesystem. Use with diro= or ofs=.

- copy2ram:
    copy selected squashfs modules to RAM. If a selected module cannot be
    copied, the hook keeps that and following modules on the original media.
    Use rammod= to copy only matching modules.

- debug:
    enable verbose debug shell behavior.

- delay=N:
    compatibility alias for rootdelay=N.

- dir=path:
    select aufs backend and load *.pfs modules from dir/base and dir/modules;
    load= selects dir/optional.
    roothide and tmpfs changes are enabled automatically when omitted.

- diro=path:
    select overlayfs backend with the same module directory handling as dir=.

- extramod=path[;pathN]:
    add modules from extra directories under the mounted media root.

- from=path:
    optional root image path. Supports plain paths, /dev/<dev>/path,
    UUID:<uuid>/path, LABEL:<label>/path, PARTUUID:<uuid>/path,
    PARTLABEL:<label>/path and the matching UUID=/LABEL=/PARTUUID=/PARTLABEL=
    forms. The hook uses losetup --find --show and does not assume /dev/loop0.

- load=pattern[;patternN]:
    load matching modules from dir/optional or diro/optional.

- mopt=opts:
    mount options passed through as root flags.

- nocd:
    do not search CD/DVD devices during media autodetection.

- nohd:
    do not search fixed disks during media autodetection.

- noload=pattern[;patternN]:
    exclude matching modules from base/modules/optional/extramod.

- norootcopy:
    skip copying rootcopy/ from the media directory.

- noswap:
    comment swap entries in the installed fstab instead of enabling them.

- ofs:
    compatibility switch selecting overlayfs backend together with diro=/changeso=.

- overlay=path1[,path2,pathN]:
    optional comma-separated RO filesystems or images to overlay.

- quiet:
    suppress most rootaufs3 messages.

- rammod=pattern[;patternN]:
    with copy2ram, copy only matching modules to RAM.

- ramsize=some_value%:
    custom tmpfs size for memory-backed changes. Default is 60%.

- ro|rw:
    boot root read-only or read-write. rw is selected by default unless ro is set.

- root=dev:
    root media device. If omitted, rootaufs3 searches media devices.

- rootdelay=N:
    wait for slow media devices.

- rootdir=dirname:
    boot a full install located in a subdirectory on the root media.

- roothide:
    do NOT add the real root FS at the bottom of the aufs stack

    by default the boot root filesystem is added as the base of the aufs stack
    this option prevents this behavior

- sgnfile=file:
    optional marker file inside dir=/diro=. When set, device autodetection
    accepts a candidate only if both dir=/diro= exists and dir/sgnfile exists. This avoids
    selecting another disk that has the same dir= name. If omitted, old
    directory-only autodetection is preserved.

- sort=digits|range:
    raise matching numbered modules in the aufs layer order. Example: sort=4-9.

- step:
    start the shell several times during the boot to perform debugging actions.

- xzm=extension:
    module filename extension to search for. Default is pfs.

userland created at boot time:

- /mnt:
    this dir contains the mount points of the individual filesystems composing the root aufs:
    * the real root is mounted as "home"
    * the RW fs is mounted as "live/memory/changes"
    * overlayed fs are mounted as "live/memory/images/their_basename"
    * /var/log/initrd.log

- remountr[wo]:
    scripts to remount the (real) root rw/ro

EXAMPLES
--------

boot options:

<kernel cmd> changes
  use real root as RO base, add a tmpfs RW on top
  used for example to test some modifications without altering the real fs

<kernel cmd> changes=/dev/sdb1
  same as above, but write to a filesystem on /dev/sdb1

<kernel cmd> changes=/test/ext2.img
  same as above, but write to a filesystem in the disk image /test/ext2.img

<kernel cmd> changes=/test/ext2.img overlay=/test/root.squash roothide
  use the squashfs file /test/root.squash RO base, hide the real root and write to /test/ext2.img
  used for "persisent live cd" type setups, reducing the footprint of the root filesystem while allowing modifications to persist

<kernel cmd> changes=dirname1 dir=dirname2 sgnfile=dirname2.sgn copy2ram rammod=01;firmware load=nvidia noload=ati
  use the squashfs files *.pfs from "dirname2" RO base, hide the real root and write to "dirname2"
  copy2ram squashfs *01* and *firmwar*
  use squashfs dirname2/optional/*nvidia*
  do not use squashfs *ati*
  roothide & changes autoaddition with dir=

prepare a formatted disk image:
# truncate -s 2G /test/ext2.img
# losetup /dev/loop0 /test/ext2.img
# mkfs.ext2 /test/ext2.img

make a squashfs root fs (requires squashfs-tools):
# mksquashfs /test/root.squash /mnt/arch-base
or http://wiki.puppyrus.org/pyppyrus/pr218/pfs3

WARNINGS
--------

This hook can potentially harm your system, so use carefully and make sure you have a recent backup before trying new things.

While adding the "fsck" hook to mkinicpio will ensure validation of the root filesystem, other fs may not be checked. Manual fsck may be required in case of unclean shutdown.

It is pretty experimental software and contains bugs and missing features.
HELPEOF
}

# vim: set ft=sh ts=4 sw=4 et:
