Use fsmount API to avoid PAGE_SIZE limit for erofs by ChengyuZhu6 · Pull Request #12783 · containerd/containerd

ChengyuZhu6 · 2026-01-14T04:18:00Z

The traditional mount() syscall has a PAGE_SIZE (typically 4KB) limit for mount options. Use the new mount API (fsopen/fsconfig/fsmount/ move_mount) introduced in Linux 5.2 to bypass this limitation.

Fixed: #12662

hsiangkao · 2026-01-15T05:27:23Z

Try to cc @halaney @rata @azr for visibility and the common part for the new mount apis

fuweid · 2026-01-16T04:30:43Z

+	optionsBuilder.WriteString("ro")
+
+	for i := 0; i < 100; i++ {
+		fakeDevice := filepath.Join(tempDir, strings.Repeat("x", 50), "fake_device_"+strings.Repeat("0", 10))


The idea looks good.

Just sharing some context: there is still a limitation here

I tried using fsopen 2–3 years ago for OverlayFS mounting, but ran into a restriction with key=value parsing in the kernel (see: https://elixir.bootlin.com/linux/v6.12.6/source/fs/fsopen.c#L429). When setting a string option, both the key and the value must be less than 256 bytes. However, OverlayFS options like lowerdir=xx:yy:zz:... can easily exceed this limit.

Maybe I used it incorrectly, but it does look like there is a hard limit on the key/value length.

hi @fuweid , overlayfs introduces a new representation for new mount APIs on the issue you mentioned, you could check out the latest overlayfs kernel doc.

especially this part

Since kernel version v6.8, directory names containing colons can also be configured as lower layer using the “lowerdir+” mount options and the fsconfig syscall from new mount api. For example: fsconfig(fs_fd, FSCONFIG_SET_STRING, "lowerdir+", "/a:lower::dir", 0);

although I agree it needs more recent kernel versions.

As for erofs, we pass multiple devices in multiple device= arguments rather than overlayfs way splited in : so it won't have a hard issue (although 256 is shorter than PATH_MAX.)

even newer versions support fd passing, as I said in #11354 (comment).
It could be resolved with mount manager expression like {{ overlay 0 n-1 }} {{mountpoint 0}} for example.

EROFS doesn't have the passing fd feature, I could form one later.

Since kernel version v6.8, directory names containing colons can also be configured as lower layer using the “lowerdir+” mount options and the fsconfig syscall from new mount api. For example:

Nice!. When I try this API, the latest kernel is still starting from 5.X 😂

As for erofs, we pass multiple devices in multiple device= arguments rather than overlayfs way splited in :

👍 +1 for this api

@fuweid besides what @hsiangkao said, there is also another way to go around that, I think: overlayfs supports since 6.15 to use fds for lower dirs. See https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=0ff053b98a0f039e52c2bd8d0cb38f2831edfaf5.

So the path length is not an issue if we use fds. It can definitely help in the idmap case too, as we don't need to mount the idmapped lower layers :)

I am not sure if we can skip idmapped lower layers here. But it's good move to use open_tree to handle 4096 case without changing chdir in go runtime.

Thank you both for the review. As @hsiangkao mentioned, erofs use multiple 'device=' options individually rather than one long string. Since each path is well under 256 bytes, we avoid the limit while successfully bypassing the original PAGE_SIZE restriction.

fuweid · 2026-01-16T04:39:29Z

+}
+
+// Fsopen opens a filesystem context for configuration.
+func Fsopen(fsName string, flags int) (*os.File, error) {


Side note: once we use Fsopen, we should use mount.Umount to umount that mountpoint. just in case that fd is hold by some new process - REF: f40bfc4

Thanks. erofsMountHandler.Unmount is indeed using mount.Unmount

fuweid · 2026-01-17T02:25:48Z

Suggestion: we can move this API into pkg/internal first. Eventually, we can export fsmount via core/mount.

fuweid · 2026-01-17T02:26:24Z

+		// Handle key=value options
+		if key, val, ok := strings.Cut(o, "="); ok {
+			if err := unix.FsconfigSetString(int(fsctx.Fd()), key, val); err != nil {
+				return fmt.Errorf("failed to set option %s=%s: %w", key, val, err)


Suggested change

return fmt.Errorf("failed to set option %s=%s: %w", key, val, err)

return fmt.Errorf("failed to set string option %s=%s: %w", key, val, err)

fuweid · 2026-01-17T02:34:32Z

+	optionsBuilder.WriteString("ro")
+
+	for i := 0; i < 100; i++ {
+		fakeDevice := filepath.Join(tempDir, strings.Repeat("x", 50), "fake_device_"+strings.Repeat("0", 10))


I am not sure if we can skip idmapped lower layers here. But it's good move to use open_tree to handle 4096 case without changing chdir in go runtime.

The traditional mount() syscall has a PAGE_SIZE (typically 4KB) limit for mount options. Use the new mount API (fsopen/fsconfig/fsmount/ move_mount) introduced in Linux 5.2 to bypass this limitation. Fixed: containerd#12662 Signed-off-by: ChengyuZhu6 <[email protected]>

hsiangkao · 2026-01-20T15:01:36Z

@containerd/committers ... merge this? cc @fuweid

github-project-automation Bot added this to Pull Request Review Jan 14, 2026

github-project-automation Bot moved this to Needs Triage in Pull Request Review Jan 14, 2026

k8s-ci-robot added the size/L label Jan 14, 2026

dosubot Bot added the area/runtime Runtime label Jan 14, 2026

hsiangkao reviewed Jan 14, 2026

View reviewed changes

Comment thread plugins/mount/erofs/plugin_linux.go Outdated

Comment thread plugins/mount/erofs/plugin_linux.go Outdated

Comment thread plugins/mount/erofs/plugin_linux.go Outdated

ChengyuZhu6 force-pushed the mount branch from 1bcf23d to 9304dcf Compare January 15, 2026 02:50

fuweid reviewed Jan 16, 2026

View reviewed changes

ChengyuZhu6 moved this from Needs Triage to Needs Reviewers in Pull Request Review Jan 16, 2026

fuweid reviewed Jan 17, 2026

View reviewed changes

ChengyuZhu6 force-pushed the mount branch from 9304dcf to f873e4d Compare January 17, 2026 08:03

fuweid approved these changes Jan 19, 2026

View reviewed changes

hsiangkao approved these changes Jan 20, 2026

View reviewed changes

github-project-automation Bot moved this from Needs Reviewers to Review In Progress in Pull Request Review Jan 20, 2026

azr approved these changes Jan 20, 2026

View reviewed changes

fuweid added this pull request to the merge queue Jan 20, 2026

Merged via the queue into containerd:main with commit 4fb4c9d Jan 20, 2026
52 checks passed

github-project-automation Bot moved this from Review In Progress to Done in Pull Request Review Jan 20, 2026

dmcgowan changed the title ~~plugins/mount/erofs: use fsmount API to avoid PAGE_SIZE limit~~ Use fsmount API to avoid PAGE_SIZE limit for erofs Mar 17, 2026

dmcgowan added impact/changelog area/snapshotters Snapshotters area/storage Image Storage and removed area/snapshotters Snapshotters area/runtime Runtime labels Mar 17, 2026

dmcgowan mentioned this pull request Mar 17, 2026

Prepare release notes for v2.3.0-beta.0 #13048

Merged

dmcgowan mentioned this pull request Apr 27, 2026

Prepare release notes for v2.3.0-rc.0 #13302

Merged

dmcgowan mentioned this pull request Apr 30, 2026

Prepare release notes for v2.3.0 #13325

Merged

BrewTestBot mentioned this pull request Apr 30, 2026

containerd 2.3.0 Homebrew/homebrew-core#280287

Merged

	return fmt.Errorf("failed to set option %s=%s: %w", key, val, err)
	return fmt.Errorf("failed to set string option %s=%s: %w", key, val, err)

Conversation

ChengyuZhu6 commented Jan 14, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

hsiangkao commented Jan 15, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hsiangkao Jan 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

fuweid Jan 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hsiangkao commented Jan 20, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

hsiangkao Jan 16, 2026 •

edited

Loading

fuweid Jan 16, 2026 •

edited

Loading