#!/bin/bash

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

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

help() {
    cat <<HELPEOF
This hook enables booting from an overlayfs root filesystem.
It requires the "overlayfs" module.

It's loosely based on the archiso hook, with ideas from livecds & the ubuntu hook with the same name.
http://wiki.puppyrus.org/soft/arch-initrd/

SETUP
-----

- install the overlayfs module

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

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


USAGE
-----

boot options:

- changes[=path]:
    required to enable the hook, allows to specify the RW filesystem

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

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

-ramsize=some_value%
    ... Will let you set a custom size for the tmpfs partition
    which is used as the root (/) of your live filesystem
    when changes are not saved on a real filesystem
    (i.e., Always Fresh mode). The default value is 60% of
    available RAM memory.

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

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

- overlay=path1[,path2,pathN]:
    optional, allows to specfiy RO filesystems to overlay

    as with rootofs, pathX can be either a block device or disk image
    multiple paths can be specfied separated by comas, each one will be stacked under the RW file system in order (from bottom to top)

- dir=path:
    like a overlay, but similarly http://porteus.org initrd ( http://wiki.puppyrus.org/soft/porteus-initrd )
    load squashfs files *.pfs from dir/base & dir/modules
    - noload=squashfs1[;squashfs2;squashfsN]
    - load=squashfs1[;squashfs2;squashfsN]:
	load squashfs fron dir/optional/
     roothide & chandes autoaddition with dir=

- copy2ram:
    copy squashfs to RAM
    - rammod=squashfs1[;squashfs2;squashfsN]:
    copy only rammod

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

userland created at boot time:

- /mnt:
    this dir contains the mount points of the individual filesystems composing the root overlayfs:
    * 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 copy2ram rammode=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 dirmane2/optional/*ati*
  do not use squashfs *ati*
  roothide & chandes 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:
