Skip to content
mountfd

A Ruby gem for the Linux mount API

Prepare first.
Mount when ready.

Build a filesystem, set its attributes, and attach it in one atomic step. Mountfd brings Linux’s file-descriptor-based mount API to Ruby.

Get started Read the docs

Ruby 3.2+   /   Linux 5.2+   /   MIT licensed

A mount, before it’s mounted Ruby 
require "mountfd"

mount = Mountfd::FsContext.open("tmpfs") do |fs|
  fs.set("size", "64M")
  fs.create!
  fs.mount(attrs: {nosuid: true})
end

# Ready. Now make it visible.
mount.attach("/mnt/tmp")

Invisible to the namespace until you attach it.

Configure off-tree. Expose only the finished mount.

A mount is a handle.
Until you give it a home.

The legacy mount API exposes a mount before later attribute changes. Mountfd lets you prepare it while detached, then attach the finished tree with move_mount. Close the descriptor to discard an unattached mount.

  1. 01 / Create

    Open a filesystem context

    Pass options directly to the kernel. Get structured diagnostics when a configuration fails.

    fsopen · fsconfig

  2. 02 / Prepare

    Keep it detached

    Create a new mount or clone an existing tree. Apply attributes before the mount becomes visible.

    fsmount · open_tree · mount_setattr

  3. 03 / Attach

    Put it in place, atomically

    Attach the prepared mount at its destination. No intermediate configuration is exposed.

    move_mount

Small building blocks.
Real filesystem work.

For Ruby tools that manage containers, sandboxes, and storage. A native C extension calls the kernel directly.

Explore runnable examples

Read-only trees, ready before attach

Clone a bind mount and apply recursive attributes while it is still detached.

Mountfd.bind("/src", "/dst",
  recursive: true, attrs: {rdonly: true})

Map ownership at the mount

Use idmapped mounts to present different user and group IDs without recursively changing file ownership. Requires Linux 5.12+ and filesystem support.

View the idmapped volume example

Ask the system what’s mounted

Discover mounts with statmount and listmount, with a mountinfo fallback for older kernels.

Mountfd.mounts
Mountfd.mount_at("/home")

Your next mount starts here.

Add Mountfd to your Ruby project, then start with a small tmpfs mount in a Linux environment.

bundle add mountfd
Follow the quick start View on RubyGems

Check your environment

Ruby
3.2 or newer
Linux mount API
5.2 or newer
Idmapped mounts
5.12 or newer
statmount / listmount
6.8 or newer

Mount operations need CAP_SYS_ADMIN in the owning user namespace. Container and host policies may restrict access.

The gem also loads on macOS and Windows for feature detection; mount operations remain Linux-only. Check Mountfd.supported? before use.

Read compatibility notes