If the question you have isn't answered here, try posting it to the Fuse4X group.

1. Introductory Questions

Q 1.1. What is Fuse4X? Is it the same as FUSE on Linux?

Fuse4X is software that allows you to write arbitrary file systems as user-space programs. You can think of it as a library for easily developing Mac OS X file systems. Another crude way to look at this would be to think of Fuse4X as something that makes Mac OS X work like a microkernel for the purpose of writing/running file systems. Fuse4X has two major components: an in-kernel loadable file system and a user-space library (libfuse4x). The in-kernel file system is specific to Mac OS X and is not based on Linux FUSE. (Some of its code is based on the FreeBSD implementation of FUSE.) The user-space library (libfuse4x), which provides the developer-visible FUSE API, that is Linux FUSE with a few Mac OS X specific extensions and features.

Q 1.2. What is "Fuse4X-x.y.z.dmg"?

A: Fuse4X-x.y.z.dmg (where x, y, and z constitute the Fuse4X version number) is the installation package containing the official distribution of fundamental Fuse4X software you need to use other software built atop Fuse4X. The core Fuse4X software consists of the following components when installed on your system:

Q 1.3. I'm experiencing serious problems (fill in details of serious problems here) right after I installed Fuse4X. What can I do?

A: Circumstantial evidence such as "right after I installed Fuse4X" is unfortunately not enough to go on. To realize why Fuse4X cannot cause the kind of problems people sometimes ascribe to it, you need to understand what Fuse4X is, and just as importantly, what it's not.

Fuse4X is not an application. It's not a background process. It does not configure, reconfigure, or modify the normal working of OS X by itself. It does not alter settings of any OS X components.

Fuse4X is a bunch of libraries and headers along with a kernel extension. Developers use Fuse4X APIs to write applications – just like how developers use Apple's Cocoa APIs to write applications. Just as Cocoa is not a user-tangible entity, Fuse4X isn't either. (As an end user, you don't "run" or "launch" Cocoa, do you?)

With this context, no matter how convinced you are that "it happened right after/only when you installed Fuse4X", keep in mind that Fuse4X cannot do things such as the following:

If you remain convinced that your woes are Fuse4X's fault, please provide more information than circumstantial evidence.

Q 1.4. How Fuse4X relates to MacFUSE?

Fuse4X is a fork of MacFUSE started in June 2011. At that time MacFUSE project has been abandoned by the original author, the last release has been made in 2008.

Both Fuse4X and MacFuse provide similar API. If you are software developer and want to migrate your application from MacFUSE to Fuse4X – just recompile it against Fuse4X.framework. In most cases it is enough. If you have problems during migration, please contact Fuse4X project forum.

It is safe to have both Fuse4X and MacFUSE installed on the same computer. They use different names for extensions, libraries.

2. Install/Uninstall Questions

Q 2.1. What is the preferred way to install Fuse4X?

A: The preferred way is to install the Fuse4X.pkg from the latest Fuse4X-<version>.dmg available from:

https://github.com/fuse4x/fuse4x/archives/master

Q 2.2. How can I keep Fuse4X up-to-date?

A: Fuse4X distribution contains tool that automatically checks whether a new version of Fuse4X is available. It periodically run as a background process. In case if there is a new version you'll see a dialog that offer you to choose whether you want to update Fuse4X. You can also run the autoupdater tool manually by 

$ /Library/Filesystems/fuse4x.fs/Contents/Executables/autoupdater

Q 2.3. How can I uninstall Fuse4X?

A: MacOSX does not provide any convenient uninstaller tool. That is why Fuse4X has a script that completely uninstalls the package. If you want to do it, run 

$ sudo /Library/Filesystems/fuse4x.fs/Contents/Executables/uninstall.sh
or 
$ sudo /System/Library/Filesystems/fuse4x.fs/Contents/Executables/uninstall.sh
for earlier versions of Fuse4X

Q 2.4. Why installer asks me to reboot my computer?

Fuse4X installer asks to reboot computer only in case if it was not able to reload the kernel extension. It might happen in case if fuse4x filesystem still in use by some process. You need to "stop" all such processes and the easiest way to do it – reboot the computer.

Q 2.5. I'm using some software that needs an old/deprecated version of Fuse4X. I don't see that version available from your web site. What to do?

A: Please don't use old/deprecated versions of Fuse4X. The only "good" version of Fuse4X is the latest one. Older versions become obsolete/unsupported as soon as a new release is out. It's an important goal of Fuse4X to not break existing applications written atop it. Developers are encouraged to test their software against prerelease versions of Fuse4X to help meet this goal.

Q 2.6. I've upgraded fuse4x and when try to use a filesystem (e.g. sshfs) I have "client library version is incompatible with the kernel extension" error

This message means that user-space library does not match running fuse4x kernel extension. Sometimes the easiest way to fix this issue is to restart your computer. In this case all kernel extensions will be unloaded and the correct one will be loaded next time. If you don't want to restart you computer then you need to unload the currently running kernel extension manually. 

$ sudo kextunload -b org.fuse4x.kext.fuse4x
$ kextstat -l -b org.fuse4x.kext.fuse4x
If the second command shows a record it means that kext was not unloaded. It usually happens when it is still in use by some filesystems. Let's find such filesystems: 
$ mount -t fuse4x
It gives you a list of filesystems that still use it. You need to unmount all of them by using "umount" command: 
$ umount FS_DIRECTORY
And then unload the kernel extension one more time.

3. File System Specific Questions

Q 3.1. I just installed Fuse4X. How to mount my ext4/ntfs/fat32/... partition?

First thing you should remember is that Fuse4X itself does not provide any filesystem, neither ext4 nor ntfs or any other. Fuse4X is a library, is a building block that helps developers to create a filesystem for you. So the short answer is "Fuse4X itself cannot mount any of your partitions". See section 3.4 for the list of existing filesystems that might help you.

Q 3.2. I'm using sshfs and changed a file "externally" (not through sshfs/Fuse4X) on the server, but in the sshfs volume, I'm not seeing the changes. In fact, when I copy the file through sshfs, I get the old content, etc.

A: Fuse4X itself isn't a distributed remote file system! It's a mechanism for building arbitrary file systems. If you change things "externally" to Fuse4X (like, a file on the remote server in the case of sshfs), in general, things need to be done proactively to tell Fuse4X that something has changed, otherwise you'll get such "incorrect" behavior. In particular, sshfs isn't meant to replace things such as NFS, AFP, and SMB – it's meant to be a substitute when you don't have any remote file sharing access to a computer, but you do have sftp access. When you use sshfs, from the server's standpoint, you are just accessing it using sftp. It's not as if the server is going to notify an sshfs client of modifications by other clients.

To make sshfs (or any other file system) "catch up" better with "remote" changes, there are a few things you can do. You can use the -o auto_cache option. This would make Fuse4X purge a file's in-kernel buffer cache if a change in the file's size or modification time is detected.

A worse way to have this mode of operation (where you can change things remotely at any time) is to disable caching in sshfs (look at the various -o cache options in sshfs, in particular, -o cache=no). Then, additionally, you need to tell Fuse4X not to cache things on its end too. You can use the -o nolocalcaches option, which turns off readaheads, the unified buffer cache, and the pathname resolution cache (all in the kernel). At the cost of some overhead, which could be substantial in certain cases, this will give you the behavior where most requests will have to go to the server and will therefore have more up-to-date information. Note that auto_cache is vastly preferred over this approach.

An example command line for this mode of operation could look like the following:

$ sshfs user@host:/dir /tmp/ssh -ocache=no -onolocalcaches -ovolname=ssh

If you are developing a Fuse4X file system and you want to handle such scenarios better within your file system, you should consider mounting your file system with the auto_cache option.

Q 3.4. Who uses fuse?

Fuse is a widely known technology that is supported on several platforms (Linux,BSD,MacOSX). There are many filesystems use it, among them:

4. Other Usage Questions

Q 4.1. Why do Fuse4X volumes show up with "server" (or "network volume") icons?

A: To be precise, by default Fuse4X volumes show up as nonlocal volumes, which the Finder unfortunately treats the same as "servers". It's a good question as to why Fuse4X normally tags its volumes as nonlocal. Some people think that in the case of disk-based file systems, Fuse4X must tag the volume as local. Well, let us see.

For a vfs to be local on Mac OS X, you need a "real" disk device – a /dev/disk* style node. Such a real disk device node in Fuse4X's case is problematic: at mount time, for a local volume, the kernel would itself open the device node and pass it to Fuse4X. In doing so, the kernel would make sure that the device is not currently in use (for one, to disallow multiple mounts of the same device). This happens before control passes to Fuse4X and mounting can proceed. This would have been fine if the entire file system lived in the kernel, but in Fuse4X's case, the user-space file system program would also want to (exclusively) open the disk device.

Moreover, Disk Arbitration also gets involved in mounting and unmounting "local" volumes – this may be undesirable in some cases.

Technical reasons aside, there are arguments to justify that all Fuse4X volumes are, in fact, "remote". (The semantics of "local" and "remote" are debatable, but that's another discussion.) As far as the Fuse4X vfs is concerned, any and all volumes are remote in that their backing store lives across the kernel-user boundary, in a program that encapsulates backing store knowledge. Fuse4X doesn't care about where the real backing store is – across the network, in the user program's memory, or on a "local" disk device.

One way to think of Fuse4X user-space file systems is indeed as "servers" – in the microkernel sense.

All this said, it is possible to tag a specific mount point as "local" at mount time. If you wish to do so, you can use the -o local Fuse4X mount-time option. This has caveats though: the Finder (and the operating system in general) may try to do things differently with local volumes. Some of these different things may not be what you want – for example, you may not want a .Trashes directory created on your volume. (It may not even be possible to create that directory in the case of certain file systems.) Make sure you read the description of -o local on the options page.

Q 4.2. I mounted a Fuse4X volume but I don't see a volume icon on the Desktop. Why?

A: Check if the Finder preference for showing mounted servers on the Desktop is enabled. (Also see Q 4.1 to understand why we are talking about "servers" here.) On Mac OS X "Leopard", this preference is not enabled by default. You can either check if Finder->Preferences->General->Connected servers is checked, or you can use the defaults command from a shell:

$ defaults read com.apple.finder ShowMountedServersOnDesktop
0

If the preference is unchecked, you can check it within the GUI or use defaults to set its value to 1:

$ defaults write com.apple.finder ShowMountedServersOnDesktop 1

Alternatively, you can use the -o local Fuse4X mount-time option to tag the volume being mounted as "local", in which case it would show up on the Desktop unless you have disabled "external disks" from showing up on the Desktop.

Q 4.3. On Mac OS X "Leopard", I mounted a Fuse4X volume but I don't see a volume icon in the Finder's sidebar. I've looked at all relevant Finder preferences, but still nothing. What's happening?

A: Ah the Finder and its infinite wisdom. On "Leopard", the Finder by default won't show a Fuse4X volume under the "DEVICES" section of the sidebar because the volume isn't "local". The Finder won't show the volume under "SHARED" (even though it's "nonlocal") because it apparently thinks that nonlocal volumes must be of types such as AFP, NFS, SMB, and such. If you really want the volume to show up in the sidebar, you can use the -o local Fuse4X mount-time option. Also see Q 4.1 and Q 4.2.

Q 4.5. I'm trying to access a Fuse4X volume but I keep getting access/permission denied errors. I'm doing this as root – what's going on? Isn't everything allowed as root?

A: For several reasons, by default, Fuse4X allows access to a volume only to the user who mounted the volume. All other users, including the superuser is denied access. You can change this behavior if you need to. Refer to the allow_other and allow_root mount-time options in the options document.

Q 4.6. Can I enable Spotlight on a Fuse4X file system?

A: Yes, but by default, Spotlight processes running as root would not be able to access the volume, so you have to use certain mount-time options. See the answer to the previous question.

Q 4.8. How should I unmount my Fuse4X file system? I can't find the fusermount program anywhere.

A: Just use the standard umount command in Mac OS X. You don't need the Linux-specific fusermount with Fuse4X.

Q 4.9. All my file systems are showing up in the Finder as "Fuse4X Volume n (X)" for some number n and some file system type X. What should I do?

A: Use the volname command-line option. See options for details.

Q 4.10. How to build Fuse4X?

  1. Install all required development tools. You need to have XCode with MacOSX SDK.
    Additionally you need to have autotools,gettext,iconv,pkg-config installed. The most easiest way to do it - use a package manager such as MacPorts or Homebrew. For macports instructions are following: 
    $ sudo port install libtool autoconf automake gettext pkgconfig libiconv
  2. Go to the github page and clone module you are interested in. If you want to build the final *.pkg file - clone all modules like this: 
    $ for p in kext fuse framework support fuse4x sshfs; do git clone git://github.com/fuse4x/$p.git; done
  3. Go to the module directory and run its build script ./build.rb. It builds the binaries; for a kext,fuse,sshfs modules it also installs the binaries to your local computer. If you want to build the final *.dmg file - run ./build.rb from fuse4x module, *.dmg file can be found in fuse4x/build directory.