# This is the overlayroot config file
# By default, overlayroot is not enabled.
# To enable overlayroot:
#   1) edit the 'overlayroot' definition below
#   2) reboot
#
# Supported values:
#  * overlayroot=tmpfs or overlayroot=tmpfs:PARAMETERS
#    write all changes to a temporary (ram only) backing device
#    A tmpfs mount will be created, and usable filesystem can
#    grow to 1/2 available memory.
#
#    available parameters:
#     * see COMMON PARAMETERS
#
#    examples:
#     overlayroot=tmpfs
#     overlayroot=tmpfs:swap=1
#
#  * overlayroot=DEVICE or overlayroot=device:PARAMETERS
#    mount DEVICE as overlayfs and write changes there
#    device must already have kernel mountalbe filesystem on it.
#
#    available parameters are:
#     * dev: default: "" [REQUIRED]
#       use given device for backing filesystem.
#       Note, 'overlayroot=/dev/vdb' is translated to
#             'overlayrooot=device:dev=/dev/vdb'
#     * timeout: default: 0
#       if 'dev' provided does not exist, wait up to many seconds for
#       it to appear.
#     * see COMMON PARAMETERS
#
#    examples:
#      overlayroot=/dev/xvdb
#      overlayroot=/dev/vdb
#      overlayroot=device:dev=/dev/sdb,timeout=180
#      overlayroot=device:dev=LABEL=my-flashdrive,timeout=180
#
#  * overlayroot=crypt:PARAMETERS
#    use an encrypted [dmcrypt] device as the backing device. Parameters
#    are comma delimited key=value pairs.
#
#    available parameters are:
#     * dev: default: "" [REQUIRED]
#       use given device for backing filesystem.
#     * mapname: default: "secure"
#       the name of the map device to be created in /dev/mapper
#     * pass: default: ""
#       if not provided or empty, password is randomly generated
#     * fstype: default: "ext4"
#       mapname=mapper,pass=foo,fstype=ext4,mkfs=1
#     * mkfs: default: 1
#         0: never create filesystem
#         1: if pass is given and mount fails, create a new one
#            if no pass given, create new
#         2: if pass is given and mount fails, fail
#            if no pass given, create new
#     * timeout: default: 0
#       if 'dev' provided does not exist, wait up to many seconds for
#       it to appear.
#     * see COMMON PARAMETERS
#
#    examples:
#      crypt:mapname=mapper,pass=foo,fstype=ext4,mkfs=1,dev=vdb
#      crypt:mapname=mapper,pass=foo,fstype=ext3,mkfs=1,dev=/dev/disk/by-label/my-jumpdrive,timeout=120
#      crypt:dev=xvdb
#
#  * overlayroot=disabled
#    if set explicitly to 'disabled', or an empty string, then
#    overlayroot will do nothing.
#
#
# COMMON PARAMETERS:
#   The following parameters are supported for each of overlayroot=
#   values above.
#   * swap: default: 0
#     allowed values: 0, 1
#     indicate if swap partitions should be allowed.  By default swap entries
#     are removed from /etc/fstab to disable swap.
#     Swap *files* are always disabled, independent of this setting.
#
#   * recurse: default: 1
#     allowed values: 0, 1
#     indicate if all mounts should be made read-only, or just /.
#     if set to 1, then all filesystems will be mounted read-only.
#     if set to 0, only root will be set to read-only, and changes
#     to other filesystems will be permenant.  For example, if
#     /home is on a separate partition from / and recurse set to 0
#     then changes to /home will go through to the original device.
#
#  * debug: default: 0
#     allowed values: 0, 1
#     enable debug output if set to 1
#
#  * dir: default: "/overlay"
#    the directory under the filesystem to use for writes
#    default is to use top level directory.  For example, use
#    'dir=my-tests/run1' and later 'dir=my-tests/run2'
#
#  * driver: default: "auto"
#    This can be 'overlay' or 'overlayfs'.  It will affect which filesystem
#    is used to provide the overlay and the entries in fstab.
#    The default value is almost certainly correct.
#
# overlayroot_cfgdisk:
#  * default: 'disabled'
#    If this variable is set, it references a disk/filesystem that
#    may exist, and include a 'overlayroot.conf' file in it's root directory
#    If a such a device exists, then it's overlayroot.conf file can
#    set overlayroot as above.
#
#    examples:
#    * overlayroot_cfgdisk="LABEL=OROOTCFG"
#    * overlayroot_cfgdisk="/dev/vdb"
#
#    Note: if you enable this setting, then you must be careful to be sure
#          that no filesystems are created that match this without your
#          knowledge.  This is because code on that filesystem is executed
#          as root in the initramfs environment.
#
# Notes:
#  * This file is managed by dpkg as a conffile, so changes to it
#    will force dpkg config file prompts on package updates that contain a
#    change.  Instead of putting changes here, put them in
#    /etc/overlayroot.local.conf
#  * you can pass the same 'overlayroot=' parameters on the kernel
#    command line, and they will override any values set here.
#    This includes 'overlayroot=' or 'overlayroot=disabled' to disable
#    a value set in this file.
#  * if you specify crypt:dev=/dev/vdb, then DATA WILL BE LOST
#    on /dev/vdb.  A safer value would be to use
#     crypt:dev=/dev/vdb,pass=somepassword,mkfs=0
#    However, you would then have to have previously set up the luks device.
#    Do that like the following:
#      $ MAPNAME="secure"; DEV="/dev/vdg"; PASSWORD="foobar"
#      $ sudo wipefs -a $DEV
#      $ printf "%s" "$PASSWORD" |
#         sudo cryptsetup luksFormat "${$DEV}" --key-file -
#      $ printf "%s" "$PASSWORD" |
#         sudo cryptsetup luksOpen "${DEV}" "${MAPNAME}" --key-file -
#      $ sudo mke2fs -t "ext4" "/dev/mapper/${MAPNAME}"
#
# Security Note:
#    IT IS INSECURE TO SET THIS PASSWORD HERE IN THIS CLEARTEXT CONFIGURATION
#    FILE OR ON THE KERNEL COMMAND LINE.
#    Randomly generated passwords are more secure, but you won't be able to
#    read your encrypted disk on reboot.
#    Randomly generated passwords are generated by calculating the sha512sum
#    of a concatenation of:
#      - stat -L /dev/* /proc/* /sys/*
#        + some unpredictability of access/modify times of a number of kernel
#          files, directories, and block devices
#      - /proc/sys/kernel/random/boot_id
#        + 16-bytes uuid, consider this a 'salt'
#      - /proc/sys/kernel/random/uuid
#        + 16-bytes uuid, consider this psuedo randomness
#      - /dev/urandom
#        + 4096-bytes of psuedo randomness
#      - $DEV
#        + 4096-bytes from the head of the disk
#        + security-paranoid users can write 4096-bytes of randomness to
#          this device and specify mkfs=1 before rebooting into an
#          crypt+overlayroot setup
#    The result is stored in r-------- /dev/.initramfs/overlayroot.XXXXXXX,
#    which is a tmpfs in memory.
overlayroot_cfgdisk="disabled"
overlayroot="tmpfs"