1# 2# Copyright OpenEmbedded Contributors 3# 4# SPDX-License-Identifier: MIT 5# 6 7# Class for generation of overlayfs mount units 8# 9# It's often desired in Embedded System design to have a read-only rootfs. 10# But a lot of different applications might want to have a read-write access to 11# some parts of a filesystem. It can be especially useful when your update mechanism 12# overwrites the whole rootfs, but you want your application data to be preserved 13# between updates. This class provides a way to achieve that by means 14# of overlayfs and at the same time keeping the base rootfs read-only. 15# 16# Usage example. 17# 18# Set a mount point for a partition overlayfs is going to use as upper layer 19# in your machine configuration. Underlying file system can be anything that 20# is supported by overlayfs. This has to be done in your machine configuration. 21# QA check fails to catch file existence if you redefine this variable in your recipe! 22# 23# OVERLAYFS_MOUNT_POINT[data] ?= "/data" 24# 25# Per default the class assumes you have a corresponding fstab entry or systemd 26# mount unit (data.mount in this case) for this mount point installed on the 27# image, for instance via a wks script or the systemd-machine-units recipe. 28# 29# If the mount point is handled somewhere else, e.g. custom boot or preinit 30# scripts or in a initramfs, then this QA check can be skipped by adding 31# mount-configured to the related OVERLAYFS_QA_SKIP flag: 32# 33# OVERLAYFS_QA_SKIP[data] = "mount-configured" 34# 35# To use the overlayfs, you just have to specify writable directories inside 36# their recipe: 37# 38# OVERLAYFS_WRITABLE_PATHS[data] = "/usr/share/my-custom-application" 39# 40# To support several mount points you can use a different variable flag. Assume we 41# want to have a writable location on the file system, but not interested where the data 42# survive a reboot. Then we could have a mnt-overlay.mount unit for a tmpfs file system: 43# 44# OVERLAYFS_MOUNT_POINT[mnt-overlay] = "/mnt/overlay" 45# OVERLAYFS_WRITABLE_PATHS[mnt-overlay] = "/usr/share/another-application" 46# 47# If your recipe deploys a systemd service, then it should require and be 48# started after the ${PN}-overlays.service to make sure that all overlays are 49# mounted beforehand. 50# 51# Note: the class does not support /etc directory itself, because systemd depends on it 52# For /etc directory use overlayfs-etc class 53 54REQUIRED_DISTRO_FEATURES += "systemd overlayfs" 55 56inherit systemd features_check 57 58OVERLAYFS_CREATE_DIRS_TEMPLATE ??= "${COREBASE}/meta/files/overlayfs-create-dirs.service.in" 59OVERLAYFS_MOUNT_UNIT_TEMPLATE ??= "${COREBASE}/meta/files/overlayfs-unit.mount.in" 60OVERLAYFS_ALL_OVERLAYS_TEMPLATE ??= "${COREBASE}/meta/files/overlayfs-all-overlays.service.in" 61 62python do_create_overlayfs_units() { 63 from oe.overlayfs import mountUnitName 64 65 with open(d.getVar("OVERLAYFS_CREATE_DIRS_TEMPLATE"), "r") as f: 66 CreateDirsUnitTemplate = f.read() 67 with open(d.getVar("OVERLAYFS_MOUNT_UNIT_TEMPLATE"), "r") as f: 68 MountUnitTemplate = f.read() 69 with open(d.getVar("OVERLAYFS_ALL_OVERLAYS_TEMPLATE"), "r") as f: 70 AllOverlaysTemplate = f.read() 71 72 def prepareUnits(data, lower): 73 from oe.overlayfs import helperUnitName 74 75 args = { 76 'DATA_MOUNT_POINT': data, 77 'DATA_MOUNT_UNIT': mountUnitName(data), 78 'CREATE_DIRS_SERVICE': helperUnitName(lower), 79 'LOWERDIR': lower, 80 } 81 82 bb.debug(1, "Generate systemd unit %s" % mountUnitName(lower)) 83 with open(os.path.join(d.getVar('WORKDIR'), mountUnitName(lower)), 'w') as f: 84 f.write(MountUnitTemplate.format(**args)) 85 86 bb.debug(1, "Generate helper systemd unit %s" % helperUnitName(lower)) 87 with open(os.path.join(d.getVar('WORKDIR'), helperUnitName(lower)), 'w') as f: 88 f.write(CreateDirsUnitTemplate.format(**args)) 89 90 def prepareGlobalUnit(dependentUnits): 91 from oe.overlayfs import allOverlaysUnitName 92 args = { 93 'ALL_OVERLAYFS_UNITS': " ".join(dependentUnits), 94 'PN': d.getVar('PN') 95 } 96 97 bb.debug(1, "Generate systemd unit with all overlays %s" % allOverlaysUnitName(d)) 98 with open(os.path.join(d.getVar('WORKDIR'), allOverlaysUnitName(d)), 'w') as f: 99 f.write(AllOverlaysTemplate.format(**args)) 100 101 mountUnitList = [] 102 overlayMountPoints = d.getVarFlags("OVERLAYFS_MOUNT_POINT") 103 for mountPoint in overlayMountPoints: 104 bb.debug(1, "Process variable flag %s" % mountPoint) 105 lowerList = d.getVarFlag('OVERLAYFS_WRITABLE_PATHS', mountPoint) 106 if not lowerList: 107 bb.note("No mount points defined for %s flag, skipping" % (mountPoint)) 108 continue 109 for lower in lowerList.split(): 110 bb.debug(1, "Prepare mount unit for %s with data mount point %s" % 111 (lower, d.getVarFlag('OVERLAYFS_MOUNT_POINT', mountPoint))) 112 prepareUnits(d.getVarFlag('OVERLAYFS_MOUNT_POINT', mountPoint), lower) 113 mountUnitList.append(mountUnitName(lower)) 114 115 # set up one unit, which depends on all mount units, so users can set 116 # only one dependency in their units to make sure software starts 117 # when all overlays are mounted 118 prepareGlobalUnit(mountUnitList) 119} 120 121# we need to generate file names early during parsing stage 122python () { 123 from oe.overlayfs import strForBash, unitFileList 124 125 unitList = unitFileList(d) 126 for unit in unitList: 127 d.appendVar('SYSTEMD_SERVICE:' + d.getVar('PN'), ' ' + unit) 128 d.appendVar('FILES:' + d.getVar('PN'), ' ' + 129 d.getVar('systemd_system_unitdir') + '/' + strForBash(unit)) 130 131 d.setVar('OVERLAYFS_UNIT_LIST', ' '.join([strForBash(s) for s in unitList])) 132} 133 134do_install:append() { 135 install -d ${D}${systemd_system_unitdir} 136 for unit in ${OVERLAYFS_UNIT_LIST}; do 137 install -m 0444 ${WORKDIR}/${unit} ${D}${systemd_system_unitdir} 138 done 139} 140 141do_create_overlayfs_units[vardeps] += "OVERLAYFS_WRITABLE_PATHS" 142addtask create_overlayfs_units before do_install 143