name : overlayroot.conf # 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 # the generated password will be stored for recovery in # /run/initramfs/overlayroot.passwd # * 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=""