feat(fuse): Expose MFS as FUSE mount point (#10781)

* Add MFS command line options, extend existing mount functions for MFS, set defaults.

* Directory listing and file stat.

* Add a read-only MFS view.

* Add mkdir and interface checks.

* Add remove and rename functionality.

* Implement all required write interfaces.

* Adjust mount  functions for other architechtures.

* Merge branch 'master' into feat/10710-mfs-fuse-mount

* Write a basic read/write test.

* Write more basic tests, add a mutex to the file object, fix modtime.

* Add a concurrency test, remove mutexes from file and directory structures.

* Refactor naming(mfdir -> mfsdir) and add documentation.

* Add CID retrieval through ipfs_cid xattr.

* Add docs, add xattr listing, fix bugs for mv and stat, refactor.

* Add MFS command line options, extend existing mount functions for MFS, set defaults.

* docs phrasing

* docs: Mounts.MFS

* docs: warn about lazy-loaded DAGs

* test: TEST_FUSE=1 ./t0030-mount.sh -v

---------

Co-authored-by: Guillaume Michel <guillaumemichel@users.noreply.github.com>
Co-authored-by: guillaumemichel <guillaume@michel.id>
Co-authored-by: Marcin Rataj <lidel@lidel.org>

Author: 3 people

cmd/ipfs/kubo/daemon.go

@@ -56,6 +56,7 @@ const (
 	initProfileOptionKwd       = "init-profile"
 	ipfsMountKwd               = "mount-ipfs"
 	ipnsMountKwd               = "mount-ipns"
+	mfsMountKwd                = "mount-mfs"
 	migrateKwd                 = "migrate"
 	mountKwd                   = "mount"
 	offlineKwd                 = "offline" // global option
@@ -173,6 +174,7 @@ Headers.
 		cmds.BoolOption(mountKwd, "Mounts IPFS to the filesystem using FUSE (experimental)"),
 		cmds.StringOption(ipfsMountKwd, "Path to the mountpoint for IPFS (if using --mount). Defaults to config setting."),
 		cmds.StringOption(ipnsMountKwd, "Path to the mountpoint for IPNS (if using --mount). Defaults to config setting."),
+		cmds.StringOption(mfsMountKwd, "Path to the mountpoint for MFS (if using --mount). Defaults to config setting."),
 		cmds.BoolOption(unrestrictedAPIAccessKwd, "Allow RPC API access to unlisted hashes"),
 		cmds.BoolOption(unencryptTransportKwd, "Disable transport encryption (for debugging protocols)"),
 		cmds.BoolOption(enableGCKwd, "Enable automatic periodic repo garbage collection"),
@@ -1062,17 +1064,23 @@ func mountFuse(req *cmds.Request, cctx *oldcmds.Context) error {
 		nsdir = cfg.Mounts.IPNS
 	}
 
+	mfsdir, found := req.Options[mfsMountKwd].(string)
+	if !found {
+		mfsdir = cfg.Mounts.MFS
+	}
+
 	node, err := cctx.ConstructNode()
 	if err != nil {
 		return fmt.Errorf("mountFuse: ConstructNode() failed: %s", err)
 	}
 
-	err = nodeMount.Mount(node, fsdir, nsdir)
+	err = nodeMount.Mount(node, fsdir, nsdir, mfsdir)
 	if err != nil {
 		return err
 	}
 	fmt.Printf("IPFS mounted at: %s\n", fsdir)
 	fmt.Printf("IPNS mounted at: %s\n", nsdir)
+	fmt.Printf("MFS mounted at: %s\n", mfsdir)
 	return nil
 }
 

config/init.go

@@ -52,6 +52,7 @@ func InitWithIdentity(identity Identity) (*Config, error) {
 		Mounts: Mounts{
 			IPFS: "/ipfs",
 			IPNS: "/ipns",
+			MFS:  "/mfs",
 		},
 
 		Ipns: Ipns{

config/mounts.go

@@ -4,5 +4,6 @@ package config
 type Mounts struct {
 	IPFS           string
 	IPNS           string
+	MFS            string
 	FuseAllowOther bool
 }

core/commands/mount_nofuse.go

@@ -14,10 +14,11 @@ var MountCmd = &cmds.Command{
 		ShortDescription: `
 This version of ipfs is compiled without fuse support, which is required
 for mounting. If you'd like to be able to mount, please use a version of
-ipfs compiled with fuse.
+Kubo compiled with fuse.
 
 For the latest instructions, please check the project's repository:
-  https://github.com/ipfs/go-ipfs
+  https://github.com/ipfs/kubo
+  https://github.com/ipfs/kubo/blob/master/docs/fuse.md
 `,
 	},
 }

core/commands/mount_unix.go

@@ -18,21 +18,22 @@ import (
 const (
 	mountIPFSPathOptionName = "ipfs-path"
 	mountIPNSPathOptionName = "ipns-path"
+	mountMFSPathOptionName  = "mfs-path"
 )
 
 var MountCmd = &cmds.Command{
 	Status: cmds.Experimental,
 	Helptext: cmds.HelpText{
 		Tagline: "Mounts IPFS to the filesystem (read-only).",
 		ShortDescription: `
-Mount IPFS at a read-only mountpoint on the OS (default: /ipfs and /ipns).
+Mount IPFS at a read-only mountpoint on the OS (default: /ipfs, /ipns, /mfs).
 All IPFS objects will be accessible under that directory. Note that the
 root will not be listable, as it is virtual. Access known paths directly.
 
 You may have to create /ipfs and /ipns before using 'ipfs mount':
 
-> sudo mkdir /ipfs /ipns
-> sudo chown $(whoami) /ipfs /ipns
+> sudo mkdir /ipfs /ipns /mfs
+> sudo chown $(whoami) /ipfs /ipns /mfs
 > ipfs daemon &
 > ipfs mount
 `,
@@ -44,8 +45,8 @@ root will not be listable, as it is virtual. Access known paths directly.
 
 You may have to create /ipfs and /ipns before using 'ipfs mount':
 
-> sudo mkdir /ipfs /ipns
-> sudo chown $(whoami) /ipfs /ipns
+> sudo mkdir /ipfs /ipns /mfs
+> sudo chown $(whoami) /ipfs /ipns /mfs
 > ipfs daemon &
 > ipfs mount
 
@@ -67,6 +68,7 @@ baz
 > ipfs mount
 IPFS mounted at: /ipfs
 IPNS mounted at: /ipns
+MFS  mounted at: /mfs
 > cd /ipfs/QmSh5e7S6fdcu75LAbXNZAFY2nGyZUJXyLCJDvn2zRkWyC
 > ls
 bar
@@ -81,6 +83,7 @@ baz
 	Options: []cmds.Option{
 		cmds.StringOption(mountIPFSPathOptionName, "f", "The path where IPFS should be mounted."),
 		cmds.StringOption(mountIPNSPathOptionName, "n", "The path where IPNS should be mounted."),
+		cmds.StringOption(mountMFSPathOptionName, "m", "The path where MFS should be mounted."),
 	},
 	Run: func(req *cmds.Request, res cmds.ResponseEmitter, env cmds.Environment) error {
 		cfg, err := env.(*oldcmds.Context).GetConfig()
@@ -109,21 +112,28 @@ baz
 			nsdir = cfg.Mounts.IPNS // NB: be sure to not redeclare!
 		}
 
-		err = nodeMount.Mount(nd, fsdir, nsdir)
+		mfsdir, found := req.Options[mountMFSPathOptionName].(string)
+		if !found {
+			mfsdir = cfg.Mounts.MFS
+		}
+
+		err = nodeMount.Mount(nd, fsdir, nsdir, mfsdir)
 		if err != nil {
 			return err
 		}
 
 		var output config.Mounts
 		output.IPFS = fsdir
 		output.IPNS = nsdir
+		output.MFS = mfsdir
 		return cmds.EmitOnce(res, &output)
 	},
 	Type: config.Mounts{},
 	Encoders: cmds.EncoderMap{
 		cmds.Text: cmds.MakeTypedEncoder(func(req *cmds.Request, w io.Writer, mounts *config.Mounts) error {
 			fmt.Fprintf(w, "IPFS mounted at: %s\n", cmdenv.EscNonPrint(mounts.IPFS))
 			fmt.Fprintf(w, "IPNS mounted at: %s\n", cmdenv.EscNonPrint(mounts.IPNS))
+			fmt.Fprintf(w, "MFS mounted at: %s\n", cmdenv.EscNonPrint(mounts.MFS))
 
 			return nil
 		}),

core/core.go

@@ -134,6 +134,7 @@ type IpfsNode struct {
 type Mounts struct {
 	Ipfs mount.Mount
 	Ipns mount.Mount
+	Mfs  mount.Mount
 }
 
 // Close calls Close() on the App object

docs/changelogs/v0.35.md

@@ -12,6 +12,7 @@ This release  was brought to you by the [Shipyard](http://ipshipyard.com/) team.
 - [🔦 Highlights](#-highlights)
   - [Opt-in HTTP Retrieval client](#opt-in-http-retrieval-client)
   - [Dedicated `Reprovider.Strategy` for MFS](#dedicated-reproviderstrategy-for-mfs)
+  - [Experimental support for MFS as a FUSE mount point](#experimental-support-for-mfs-as-a-fuse-mount-point)
   - [Grid view in WebUI](#grid-view-in-webui)
   - [Enhanced DAG-Shaping Controls](#enhanced-dag-shaping-controls)
     - [New DAG-Shaping `ipfs add` Options](#new-dag-shaping-ipfs-add-options)
@@ -64,6 +65,14 @@ Users relying on the `pinned` strategy can switch to `pinned+mfs` and use MFS al
 
 See [`Reprovider.Strategy`](https://github.com/ipfs/kubo/blob/master/docs/config.md#reproviderstrategy) for more details.
 
+#### Experimental support for MFS as a FUSE mount point
+
+The MFS root (filesystem behind the `ipfs files` API) is now available as a read/write FUSE mount point at `Mounts.MFS`. This filesystem is mounted in the same way as `Mounts.IPFS` and `Mounts.IPNS` when running `ipfs mount` or `ipfs daemon --mount`.
+
+Note that the operations supported by the MFS FUSE mountpoint are limited, since MFS doesn't store file attributes.
+
+See [`Mounts`](https://github.com/ipfs/kubo/blob/master/docs/config.md#mounts) and [`docs/fuse.md`](https://github.com/ipfs/kubo/blob/master/docs/fuse.md) for more details.
+
 #### Grid view in WebUI
 
 The WebUI, accessible at http://127.0.0.1:5001/webui/, now includes support for the grid view on the _Files_ screen:

docs/config.md

@@ -97,6 +97,7 @@ config file at runtime.
   - [`Mounts`](#mounts)
     - [`Mounts.IPFS`](#mountsipfs)
     - [`Mounts.IPNS`](#mountsipns)
+    - [`Mounts.MFS`](#mountsmfs)
     - [`Mounts.FuseAllowOther`](#mountsfuseallowother)
   - [`Pinning`](#pinning)
     - [`Pinning.RemoteServices`](#pinningremoteservices)
@@ -1368,7 +1369,8 @@ Default: `cache`
 
 ## `Mounts`
 
-**EXPERIMENTAL:** read about current limitations at [fuse.md](./fuse.md).
+> [!CAUTION]
+> **EXPERIMENTAL:** read about current limitations at [fuse.md](./fuse.md).
 
 FUSE mount point configuration options.
 
@@ -1388,6 +1390,18 @@ Default: `/ipns`
 
 Type: `string` (filesystem path)
 
+### `Mounts.MFS`
+
+Mountpoint for Mutable File System (MFS) behind the `ipfs files` API.
+
+> [!CAUTION]
+> - Write support is highly experimental and not recommended for mission-critical deployments.
+> - Avoid storing lazy-loaded datasets in MFS. Exposing a partially local, lazy-loaded DAG risks operating system search indexers crawling it, which may trigger unintended network prefetching of non-local DAG components.
+
+Default: `/mfs`
+
+Type: `string` (filesystem path)
+
 ### `Mounts.FuseAllowOther`
 
 Sets the 'FUSE allow other'-option on the mount point.

docs/experimental-features.md

@@ -404,7 +404,7 @@ We also support the use of protocol names of the form /x/$NAME/http where $NAME
 
 ## FUSE
 
-FUSE makes it possible to mount `/ipfs` and `/ipns` namespaces in your OS,
+FUSE makes it possible to mount `/ipfs`, `/ipns` and `/mfs` namespaces in your OS,
 allowing arbitrary apps access to IPFS using a subset of filesystem abstractions.
 
 It is considered  EXPERIMENTAL due to limited (and buggy) support on some platforms.

docs/fuse.md

@@ -2,7 +2,7 @@
 
 **EXPERIMENTAL:** FUSE support is limited, YMMV.
 
-Kubo makes it possible to mount `/ipfs` and `/ipns` namespaces in your OS,
+Kubo makes it possible to mount `/ipfs`, `/ipns` and `/mfs` namespaces in your OS,
 allowing arbitrary apps access to IPFS.
 
 ## Install FUSE
@@ -50,18 +50,20 @@ speak with us, or if you figure something new out, please add to this document!
 
 ## Prepare mountpoints
 
-By default ipfs uses `/ipfs` and `/ipns` directories for mounting, this can be
-changed in config. You will have to create the `/ipfs` and `/ipns` directories
+By default ipfs uses `/ipfs`, `/ipns` and `/mfs` directories for mounting, this can be
+changed in config. You will have to create the `/ipfs`, `/ipns` and `/mfs` directories
 explicitly. Note that modifying root requires sudo permissions.
 
 ```sh
 # make the directories
 sudo mkdir /ipfs
 sudo mkdir /ipns
+sudo mkdir /mfs
 
 # chown them so ipfs can use them without root permissions
 sudo chown <username> /ipfs
 sudo chown <username> /ipns
+sudo chown <username> /mfs
 ```
 
 Depending on whether you are using OSX or Linux, follow the proceeding instructions. 
@@ -105,6 +107,25 @@ ipfs config --json Mounts.FuseAllowOther true
 ipfs daemon --mount
 ```
 
+## MFS mountpoint
+
+Kubo v0.35.0 and later supports mounting the MFS (Mutable File System) root as
+a FUSE filesystem, enabling manipulation of content-addressed data like regular
+files. The CID for any file or directory is retrievable via the `ipfs_cid`
+extended attribute.
+
+```sh
+getfattr -n ipfs_cid /mfs/welcome-to-IPFS.jpg 
+getfattr: Removing leading '/' from absolute path names
+# file: mfs/welcome-to-IPFS.jpg
+ipfs_cid="QmaeXDdwpUeKQcMy7d5SFBfVB4y7LtREbhm5KizawPsBSH"
+```
+
+Please note that the operations supported by the MFS FUSE mountpoint are
+limited. Since the MFS wasn't designed to store file attributes like ownership
+information, permissions and creation date, some applications like `vim` and
+`sed` may misbehave due to missing functionality.
+
 ## Troubleshooting
 
 #### `Permission denied` or `fusermount: user has no write access to mountpoint` error in Linux
@@ -145,6 +166,7 @@ set for user running `ipfs mount` command.
 ```
 sudo umount /ipfs
 sudo umount /ipns
+sudo umount /mfs
 ```
 
 #### Mounting fails with "error mounting: could not resolve name"