blob: a82763ec102ccf8f61d99c499a3485c4046c75ba [file] [log] [blame]
Patrick Williams92b42cb2022-09-03 06:53:57 -05001#
2# Copyright OpenEmbedded Contributors
3#
4# SPDX-License-Identifier: MIT
5#
6
Patrick Williams0ca19cc2021-08-16 14:03:13 -05007# 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#
Andrew Geisslerd5838332022-05-27 11:33:10 -050025# 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.
Patrick Williams0ca19cc2021-08-16 14:03:13 -050028#
Andrew Geisslerd5838332022-05-27 11:33:10 -050029# 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:
Patrick Williams0ca19cc2021-08-16 14:03:13 -050037#
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#
Andrew Geisslerd5838332022-05-27 11:33:10 -050047# 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#
Patrick Williams0ca19cc2021-08-16 14:03:13 -050051# Note: the class does not support /etc directory itself, because systemd depends on it
Andrew Geissler595f6302022-01-24 19:11:47 +000052# For /etc directory use overlayfs-etc class
Patrick Williams0ca19cc2021-08-16 14:03:13 -050053
54REQUIRED_DISTRO_FEATURES += "systemd overlayfs"
55
56inherit systemd features_check
57
Andrew Geissler595f6302022-01-24 19:11:47 +000058OVERLAYFS_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
Patrick Williams0ca19cc2021-08-16 14:03:13 -050062python do_create_overlayfs_units() {
Andrew Geissler595f6302022-01-24 19:11:47 +000063 from oe.overlayfs import mountUnitName
Patrick Williams0ca19cc2021-08-16 14:03:13 -050064
Andrew Geissler595f6302022-01-24 19:11:47 +000065 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()
Patrick Williams0ca19cc2021-08-16 14:03:13 -050071
72 def prepareUnits(data, lower):
Andrew Geissler595f6302022-01-24 19:11:47 +000073 from oe.overlayfs import helperUnitName
Patrick Williams0ca19cc2021-08-16 14:03:13 -050074
75 args = {
76 'DATA_MOUNT_POINT': data,
77 'DATA_MOUNT_UNIT': mountUnitName(data),
78 'CREATE_DIRS_SERVICE': helperUnitName(lower),
79 'LOWERDIR': lower,
80 }
81
Andrew Geissler595f6302022-01-24 19:11:47 +000082 bb.debug(1, "Generate systemd unit %s" % mountUnitName(lower))
Patrick Williams0ca19cc2021-08-16 14:03:13 -050083 with open(os.path.join(d.getVar('WORKDIR'), mountUnitName(lower)), 'w') as f:
84 f.write(MountUnitTemplate.format(**args))
85
Andrew Geissler595f6302022-01-24 19:11:47 +000086 bb.debug(1, "Generate helper systemd unit %s" % helperUnitName(lower))
Patrick Williams0ca19cc2021-08-16 14:03:13 -050087 with open(os.path.join(d.getVar('WORKDIR'), helperUnitName(lower)), 'w') as f:
88 f.write(CreateDirsUnitTemplate.format(**args))
89
Andrew Geissler595f6302022-01-24 19:11:47 +000090 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 = []
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500102 overlayMountPoints = d.getVarFlags("OVERLAYFS_MOUNT_POINT")
103 for mountPoint in overlayMountPoints:
Andrew Geissler595f6302022-01-24 19:11:47 +0000104 bb.debug(1, "Process variable flag %s" % mountPoint)
Patrick Williams2390b1b2022-11-03 13:47:49 -0500105 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():
Andrew Geissler595f6302022-01-24 19:11:47 +0000110 bb.debug(1, "Prepare mount unit for %s with data mount point %s" %
111 (lower, d.getVarFlag('OVERLAYFS_MOUNT_POINT', mountPoint)))
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500112 prepareUnits(d.getVarFlag('OVERLAYFS_MOUNT_POINT', mountPoint), lower)
Andrew Geissler595f6302022-01-24 19:11:47 +0000113 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)
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500119}
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:
Andrew Geissler595f6302022-01-24 19:11:47 +0000127 d.appendVar('SYSTEMD_SERVICE:' + d.getVar('PN'), ' ' + unit)
Andrew Geissler9aee5002022-03-30 16:27:02 +0000128 d.appendVar('FILES:' + d.getVar('PN'), ' ' +
129 d.getVar('systemd_system_unitdir') + '/' + strForBash(unit))
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500130
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
Patrick Williams39653562024-03-01 08:54:02 -0600141do_create_overlayfs_units[vardeps] += "OVERLAYFS_WRITABLE_PATHS"
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500142addtask create_overlayfs_units before do_install