mountfd 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 75db1001630a8a9cc58592f3daa3c263fe50f3c356de527f4f693d1c34ae7e1f
+  data.tar.gz: be9d690de9dae6234faeb83b7f5c712b73690fb703769ad12adba3298dfccedd
+SHA512:
+  metadata.gz: a305df091fee137702cc27adc98e1ab4537ce3d1b9dd7580a3a98a81e2943fd65753a79a2713009f50d8271f0c99cfb52d333b6d502a59f4efccf691445ea5cd
+  data.tar.gz: e60033d763131eed72f6bf3dd5c2d323dbe2c450614865e53933384ee7d9a155ecbc19391fb222ad3eac3c61ed40dee8727272b9f29907143c4bc698ecb53f19

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Yudai Takada
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,225 @@
+# Mountfd
+
+Mountfd exposes Linux's file-descriptor-based mount API to Ruby. It builds a
+mount while detached, applies its final attributes, and only then attaches it
+to the mount namespace. This avoids the visibility and option-string problems
+of the legacy `mount(2)` API.
+
+```text
+FsContext (fsopen) -> superblock (fsconfig) -> DetachedMount (fsmount)
+                                                    |
+existing mount ---------------- open_tree(CLONE) ---+
+                                                    |
+                                             move_mount
+                                                    v
+                                             mounted path
+```
+
+The native extension calls `fsopen`, `fsconfig`, `fsmount`, `fspick`,
+`open_tree`, `move_mount`, `mount_setattr`, `statmount`, `listmount`, and
+`umount2` directly. It does not use Fiddle or FFI.
+
+## Requirements
+
+- Ruby 3.2 or newer
+- Linux 5.2 or newer for the new mount API
+- Linux 5.12 or newer for `mount_setattr` and idmapped mounts
+- Linux 6.8 or newer for `statmount`/`listmount`; older kernels use
+  `/proc/self/mountinfo`
+- `CAP_SYS_ADMIN` in the owning user namespace, normally obtained through an
+  unprivileged user namespace or a privileged container
+
+`require "mountfd"` succeeds on unsupported platforms so applications can use
+feature detection:
+
+```ruby
+Mountfd.supported? # false on macOS or a kernel older than 5.2
+Mountfd.features   # [:new_mount_api, :mount_setattr, :idmap, ...]
+```
+
+Known unsupported or restricted environments:
+
+| Environment | Result |
+|---|---|
+| macOS and Windows | The gem builds and loads, but mount operations raise `UnsupportedError`. |
+| WSL2 with a kernel older than 5.2 | The new mount syscalls are unavailable. |
+| Docker Desktop | Operations affect the Linux VM/container namespace, never the host filesystem. |
+| Unprivileged Docker | The default seccomp/capability policy commonly rejects mount and user-namespace operations. |
+| Ubuntu 24.04+ | AppArmor may block unprivileged user namespaces via `kernel.apparmor_restrict_unprivileged_userns=1`. |
+| GitHub-hosted runners | Unit tests work; system tests depend on the runner's user-namespace policy. |
+
+Filesystem support for idmapped mounts is kernel-dependent. The safe,
+source-free probe produced:
+
+| kernel | tmpfs | ramfs | hugetlbfs |
+|---|---|---|---|
+| 5.10 | no/unavailable | no/unavailable | no/unavailable |
+| 5.15 | no/unavailable | no/unavailable | no/unavailable |
+| 6.1 | no/unavailable | no/unavailable | no/unavailable |
+| 6.6 | yes | no/unavailable | no/unavailable |
+| 6.8 | yes | no/unavailable | no/unavailable |
+| 6.12 | yes | no/unavailable | no/unavailable |
+
+Run `rake research:idmap_support` in the target environment. Filesystems that
+need a block device or mount options are deliberately excluded from this safe
+probe; the system suite separately verifies ext4 on a loop device on Linux
+5.15 and 6.8.
+
+## Installation
+
+```sh
+bundle add mountfd
+```
+
+Or install it directly with `gem install mountfd`.
+
+## Create and attach a mount
+
+The block form closes the filesystem context while returning ownership of the
+detached mount:
+
+```ruby
+mount = Mountfd::FsContext.open("tmpfs") do |context|
+  context.set("size", "64M")
+  context.set_flag("noswap")
+  context.create!
+  context.mount(attrs: {nosuid: true, nodev: true})
+end
+
+mount.attach("/mnt/tmp")
+```
+
+Configuration failures include diagnostics read from the filesystem context:
+
+```ruby
+context = Mountfd::FsContext.new("tmpfs")
+context.set("sizee", "64M")
+# Mountfd::ConfigError: fsconfig: Invalid argument
+# error: tmpfs: Unknown parameter 'sizee'
+```
+
+The high-level form performs the same lifecycle:
+
+```ruby
+Mountfd.mount(
+  "tmpfs", "/mnt/tmp",
+  options: {size: "64M"},
+  attrs: {nosuid: true, nodev: true, atime: :noatime}
+)
+Mountfd.umount("/mnt/tmp")
+```
+
+## Bind and idmapped mounts
+
+`bind` uses `open_tree(OPEN_TREE_CLONE)`. Recursive attributes are applied to
+the detached tree before it becomes visible:
+
+```ruby
+Mountfd.bind("/src", "/dst", recursive: true, attrs: {rdonly: true})
+```
+
+Pass an existing user namespace or a mapping. Mapping ranges may use a hash or
+an array of `[inside, outside, length]` triples:
+
+```ruby
+Mountfd.bind(
+  "/data", "/container/data", recursive: true,
+  idmap: {
+    uid: {0 => [100_000, 65_536]},
+    gid: {0 => [100_000, 65_536]},
+    helper: :auto
+  }
+)
+```
+
+The triples are written to `uid_map`/`gid_map` in kernel order. When the caller
+uses the initial user namespace, mapping an on-disk UID 100000 so it is reported
+as UID 0 uses `{100_000 => [0, 1]}`. A container that itself maps root to host
+UID 100000 normally uses `{0 => [100_000, 65_536]}` for both its user namespace
+and mount.
+
+`:auto` uses `newuidmap` and `newgidmap` for non-root callers when both are
+installed. Requested ranges must also be delegated in `/etc/subuid` and
+`/etc/subgid`.
+
+## Mount discovery
+
+```ruby
+Mountfd.mounts                 # Array<Mountfd::MountInfo>
+Mountfd.mount_at("/home")      # MountInfo or nil
+Mountfd.mounts_backend         # :statmount or :mountinfo
+Mountfd.mounts(ns: 1234)       # parses /proc/1234/mountinfo
+File.open("/proc/1234/ns/mnt") { Mountfd.mounts(ns: _1) } # statmount, Linux 6.11+
+```
+
+The mountinfo fallback decodes octal path escapes and handles the variable
+optional-field section. A disappearing mount during `statmount` enumeration is
+ignored as a normal race. An open mount namespace descriptor can be passed on
+Linux 6.11 or newer; an integer namespace argument remains a process ID.
+Generic attributes and propagation are normalized across both backends.
+`source` or filesystem-specific `options` may be nil or empty when the running
+kernel does not return the corresponding statmount field.
+
+## Namespace helpers
+
+Namespace changes affect the calling OS thread and are intended for a
+single-threaded setup phase:
+
+```ruby
+Mountfd::Namespace.reexec_user! # robust entry path, including Ruby 3.4+
+Mountfd::Namespace.unshare_user!(map_root: true)
+Mountfd::Namespace.unshare_mount!(propagation: :private)
+Mountfd.pivot_root(new_root, put_old)
+```
+
+`reexec_user!` restarts the current command through `unshare -Ur`; use it before
+creating threads. The in-process `unshare_user!` is available when the Ruby
+process has only one OS thread.
+
+See `examples/` for an overlay mini-container, idmapped volume, read-only
+sandbox with a writable tmpfs at `/tmp`, and `MOVE_MOUNT_BENEATH` atomic swap.
+Set `MOUNTFD_LANDLOCK=1` when running `readonly_sandbox.rb` with the optional
+`landlock` gem installed to restrict filesystem writes to `/tmp` (plus `/dev/null`)
+as defense in depth. The exec-based examples use a supervising parent so their
+temporary mount trees are removed after the command exits, including on a
+nonzero exit status.
+
+## Development
+
+```sh
+bundle install
+bundle exec rake test:unit
+bundle exec rbs -I sig validate
+```
+
+System tests change mount namespaces and must run on Linux with user namespaces
+enabled:
+
+```sh
+bundle exec rake test:system
+bundle exec rake test:adversarial # 270-mount pagination and long statmount data
+bundle exec rake test:ext4       # root plus loop-device access
+```
+
+For kernel-matrix testing, install `virtme-ng` and run:
+
+```sh
+make -C tools/vm KVER=6.12.20
+```
+
+The source-free idmap probe prints a Markdown table for the current kernel:
+
+```sh
+bundle exec rake research:idmap_support
+bundle exec rake benchmark:mounts # defaults to a namespace with 1000 mounts
+```
+
+## Scope
+
+Mountfd intentionally does not wrap legacy `mount(2)`, FUSE mount helpers, or
+systemd `.mount` units. Filesystem-specific `fsconfig` keys are passed to the
+kernel without duplicating kernel validation.
+
+## License
+
+Mountfd is available under the MIT License.

data/Rakefile

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/extensiontask"
+require "rspec/core/rake_task"
+require "yard"
+
+Rake::ExtensionTask.new("mountfd") do |extension|
+  extension.lib_dir = "lib/mountfd"
+end
+
+RSpec::Core::RakeTask.new(:spec) do |task|
+  task.pattern = "spec/mountfd_spec.rb"
+end
+
+RSpec::Core::RakeTask.new("spec:system") do |task|
+  task.pattern = "spec/system/**/*_spec.rb"
+end
+
+RSpec::Core::RakeTask.new("spec:ext4") do |task|
+  task.pattern = "spec/ext4/**/*_spec.rb"
+end
+
+YARD::Rake::YardocTask.new(:yard)
+
+desc "Validate RBS signatures"
+task :rbs do
+  sh "rbs", "-I", "sig", "validate"
+end
+
+namespace :test do
+  task unit: :spec
+  task system: :compile do
+    ENV["MOUNTFD_SYSTEM"] = "1"
+    Rake::Task["spec:system"].invoke
+  end
+  task adversarial: :compile do
+    ENV["MOUNTFD_SYSTEM"] = ENV["MOUNTFD_EXTENSIVE"] = "1"
+    Rake::Task["spec:system"].invoke
+  end
+  task ext4: :compile do
+    ENV["MOUNTFD_EXT4"] = "1"
+    Rake::Task["spec:ext4"].invoke
+  end
+end
+
+namespace :research do
+  desc "Probe idmapped-mount support for source-free filesystems"
+  task idmap_support: :compile do
+    ruby "-Ilib", "tools/research_idmap.rb"
+  end
+end
+
+namespace :benchmark do
+  desc "Compare statmount with mountinfo parsing in a 1000-mount namespace"
+  task mounts: :compile do
+    ruby "-Ilib", "benchmark/mounts.rb"
+  end
+end
+
+namespace :gen do
+  desc "Generate mount constants from the installed Linux UAPI headers"
+  task :constants do
+    ruby "tools/generate_constants.rb"
+  end
+end
+
+task spec: :compile
+task default: "test:unit"

data/benchmark/mounts.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "mountfd"
+require "tmpdir"
+
+abort "Linux statmount support is required" unless Mountfd.features.include?(:statmount)
+
+Mountfd::Namespace.reexec_user!
+Mountfd::Namespace.unshare_mount!
+count = Integer(ENV.fetch("MOUNTFD_BENCH_MOUNTS", "1000"))
+iterations = Integer(ENV.fetch("MOUNTFD_BENCH_ITERATIONS", "10"))
+
+measure = lambda do |label, &work|
+  started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  work.call
+  puts format("%-20s %8.3f ms", label, (Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1_000)
+end
+
+Dir.mktmpdir do |directory|
+  targets = count.times.map { File.join(directory, _1.to_s) }
+  targets.each { Dir.mkdir(_1); Mountfd.mount("tmpfs", _1) }
+  puts "#{Mountfd.mounts(backend: :statmount).length} visible mounts (#{count} created)"
+  measure.call("statmount/listmount") { iterations.times { Mountfd.mounts(backend: :statmount) } }
+  measure.call("parse mountinfo") do
+    iterations.times { Mountfd::MountInfoParser.parse(File.read("/proc/self/mountinfo")) }
+  end
+ensure
+  targets&.reverse_each do |target|
+    Mountfd.umount(target)
+  rescue Errno::EINVAL, Errno::ENOENT
+    nil
+  end
+end

data/docs/kernel-notes.md

@@ -0,0 +1,48 @@
+# Kernel notes
+
+Results recorded on 2026-08-25 and 2026-08-26 while implementing the initial release.
+
+| Environment | Result |
+|---|---|
+| macOS arm64, Ruby 4.0 | Native extension builds; `require` and unit tests pass; feature detection returns unsupported. |
+| Linux arm64 container, Ruby 3.2/3.3/3.4 | Native extension builds; unit tests and RBS validation pass on every version. |
+| Privileged Linux container | `fsopen(tmpfs)` → `fsconfig` → `fsmount` → `move_mount`, file I/O, and `umount2` pass in a private mount namespace. |
+| Privileged Linux container | A misspelled tmpfs option returns `error: tmpfs: Unknown parameter 'sizee'`. |
+| Privileged Linux container | `open_tree(CLONE)` plus `mount_setattr(MOUNT_ATTR_RDONLY)` rejects writes with `EROFS`. |
+| Privileged Linux container | C-level user-namespace keeper returns a usable namespace fd and releases the keeper process. |
+| Privileged Linux container | A tmpfs file owned by UID 100000 is reported as UID 0 through an idmapped bind using `100000 0 1`. |
+| Linux 6.8.0-64 arm64 | `statmount` and mountinfo return the same visible mounts, including overmount filtering. |
+| Linux 6.8.0-64 arm64 | `listmount` pagination passes with 270 new mounts; `statmount` buffer growth passes with more than 4 KiB of path data. |
+| Linux 6.8.0-64 arm64 | 1000 explicit fd closes and `GC.stress` leave `/proc/self/fd` unchanged. |
+| Linux 6.8.0-64 arm64 | Recursive read-only, attribute set/clear, propagation, detached discard, and atomic replacement tests pass. |
+| Linux 6.8.0-64 arm64 | `MOVE_MOUNT_SET_GROUP`, close-error fd reuse, compacting-GC syscall arguments, and native binary-length validation pass. |
+| Linux 6.8.0-64 arm64 | Invalid idmap fd/flag pairs are rejected before the syscall; the helper path passes through `posix_spawnp`. |
+| Linux 6.8.0-64 arm64 | An ext4 loopback file owned by UID 1000 is UID 0 through an idmapped bind; an unmapped UID is 65534. |
+| Linux 6.8.0-64 arm64, non-root | `newuidmap`/`newgidmap` create a namespace fd with delegated `100000:65536` sub-ID ranges. |
+| Linux 6.8.0-64 arm64 | Safe source-free idmap probe: tmpfs yes; ramfs and hugetlbfs no/unavailable. |
+| Linux 6.8.0-64 arm64 | 1000-mount benchmark, 10 iterations: statmount/listmount 30 ms; mountinfo parse 37 ms. |
+| Linux 6.8.0-64 arm64, Ruby 3.4 | Adversarial suite: 24 examples, 0 failures, 2 expected pending. |
+| Linux 6.8.0-64 arm64, Ruby 3.4, ASan/UBSan | Unit and system suites plus repeated syscall/GC-compaction stress pass without sanitizer findings. The intentional SIGSTOP helper test runs separately because ASan cannot supervise the stopped fork child. |
+| Linux 5.10.0 arm64, virtme-ng/QEMU | System suite: 21 examples, 0 failures, 13 expected pending; `mount_setattr` and exclusive creation report `UnsupportedError`. |
+| Linux 5.15.0 arm64, virtme-ng/QEMU | System suite: 21 examples, 0 failures, 8 expected pending; `MOVE_MOUNT_SET_GROUP` and ext4 loopback idmap pass. |
+| Linux 6.1.0 arm64, virtme-ng/QEMU | System suite: 17 examples, 0 failures, 8 expected pending. |
+| Linux 6.6.0 arm64, virtme-ng/QEMU | System suite: 17 examples, 0 failures, 6 expected pending; exclusive filesystem-context creation passes. |
+| Linux 6.12.20 arm64, virtme-ng/QEMU | System suite: 17 examples, 0 failures, 4 expected pending; namespace-selected `listmount`/`statmount` pass. |
+| Linux 5.10/5.15/6.1 arm64 | Source-free idmap probe: tmpfs, ramfs, and hugetlbfs no/unavailable. |
+| Linux 6.6/6.12.20 arm64 | Source-free idmap probe: tmpfs yes; ramfs and hugetlbfs no/unavailable. |
+| Linux 6.12.0 arm64, QEMU/TCG | A static initramfs probe passes `NS_GET_MNTNS_ID`, namespace-selected `listmount`, and namespace-selected `statmount`. |
+| Linux 6.8.0-64 arm64 | The read-only sandbox preserves command status and removes its temporary tree; the idmapped-volume and overlay-container examples pass on ext4-backed test data. |
+
+The checked-in VM harness remains the source of truth for older-kernel
+regressions. The tested Ubuntu 6.12.0 image panics in netfs/9p before userspace,
+so its new namespace ABI was isolated with a static initramfs; the full Ruby
+suite passes on the 6.12.20 stable update. The harness disables PSI only for
+5.10 because that kernel panics while current Ubuntu userspace initializes PSI.
+Re-run the matrix before publishing a release.
+
+```sh
+make -C tools/vm KVER=5.15
+make -C tools/vm KVER=6.1
+make -C tools/vm KVER=6.6
+make -C tools/vm KVER=6.12.20
+```

data/examples/atomic_swap.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "mountfd"
+
+target = File.expand_path(ARGV.fetch(0) { abort "usage: #{$PROGRAM_NAME} TARGET" })
+Mountfd.replace(target) do
+  Mountfd::FsContext.open("tmpfs") do |context|
+    context.set("size", "64M")
+    context.create!
+    context.mount(attrs: {nosuid: true, nodev: true})
+  end
+end

data/examples/idmapped_volume.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "mountfd"
+
+source, target, outside = ARGV
+abort "usage: #{$PROGRAM_NAME} SOURCE TARGET OUTSIDE_UID" unless outside
+outside = Integer(outside)
+FileUtils.mkdir_p(target)
+
+Mountfd.bind(
+  File.expand_path(source), File.expand_path(target), recursive: true,
+  idmap: {
+    uid: {outside => [0, 65_536]},
+    gid: {outside => [0, 65_536]}
+  }
+)

data/examples/mini_container.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "mountfd"
+require "rbconfig"
+require "tmpdir"
+
+lower = File.expand_path(ARGV.fetch(0) { abort "usage: #{$PROGRAM_NAME} ROOTFS [COMMAND ...]" })
+command = ARGV.drop(1)
+command = ["/bin/sh"] if command.empty?
+
+Mountfd::Namespace.reexec_user!
+directory = ENV["MOUNTFD_CONTAINER_ROOT"]
+unless directory
+  status = Dir.mktmpdir("mountfd-container") do |root|
+    command = begin
+      File.binread("/proc/self/cmdline").split("\0")
+    rescue Errno::EACCES, Errno::ENOENT
+      [RbConfig.ruby, $PROGRAM_NAME, *ARGV]
+    end
+    command = [RbConfig.ruby, $PROGRAM_NAME, *ARGV] if command.empty?
+    pid = Process.spawn({"MOUNTFD_CONTAINER_ROOT" => root}, *command)
+    Process.wait2(pid).last
+  end
+  exit(status.exitstatus || 128 + status.termsig)
+end
+
+Mountfd::Namespace.unshare_mount!
+upper, work, root = %w[upper work root].map { |name| File.join(directory, name) }
+FileUtils.mkdir_p([upper, work, root])
+Mountfd.mount(
+  "overlay", root,
+  options: {lowerdir: lower, upperdir: upper, workdir: work},
+  attrs: {nosuid: true, nodev: true}
+)
+Dir.chdir(root)
+Mountfd.pivot_root(".", ".")
+Mountfd.umount(".")
+Dir.chdir("/")
+exec(*command)

data/examples/readonly_sandbox.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "mountfd"
+require "rbconfig"
+require "tmpdir"
+require "landlock" if ENV["MOUNTFD_LANDLOCK"] == "1"
+
+rootfs = File.expand_path(ARGV.fetch(0) { abort "usage: #{$PROGRAM_NAME} ROOTFS [COMMAND ...]" })
+command = ARGV.drop(1)
+command = ["/bin/sh"] if command.empty?
+abort "#{rootfs}/tmp must exist" unless File.directory?(File.join(rootfs, "tmp"))
+
+Mountfd::Namespace.reexec_user!
+root = ENV["MOUNTFD_SANDBOX_ROOT"]
+unless root
+  status = Dir.mktmpdir("mountfd-sandbox") do |directory|
+    command = begin
+      File.binread("/proc/self/cmdline").split("\0")
+    rescue Errno::EACCES, Errno::ENOENT
+      [RbConfig.ruby, $PROGRAM_NAME, *ARGV]
+    end
+    command = [RbConfig.ruby, $PROGRAM_NAME, *ARGV] if command.empty?
+    pid = Process.spawn({"MOUNTFD_SANDBOX_ROOT" => directory}, *command)
+    Process.wait2(pid).last
+  end
+  exit(status.exitstatus || 128 + status.termsig)
+end
+
+Mountfd::Namespace.unshare_mount!
+Mountfd.bind(rootfs, root, recursive: true, attrs: {rdonly: true})
+Mountfd.mount("tmpfs", File.join(root, "tmp"), attrs: {nosuid: true, nodev: true})
+Dir.chdir(root)
+Mountfd.pivot_root(".", ".")
+Mountfd.umount(".")
+Dir.chdir("/")
+if ENV["MOUNTFD_LANDLOCK"] == "1"
+  Landlock.restrict!(read: ["/"], write: ["/tmp", "/dev/null"], execute: ["/"], allow_all_known: true)
+end
+exec(*command)