FAQ
If the question you have is not answered here, try posting it to the "FUSE for OS X" Google Group.
"FUSE for OS X" is software that allows you to write arbitrary file systems as user space applications. You can think of it as a library for easily developing OS X file systems. Another crude way to look at this would be to think of "FUSE for OS X" as something that makes OS X work like a microkernel for the purpose of writing/running file systems.
"FUSE for OS X" is a fully backwards compatible sucessor to MacFUSE. MacFUSE is used by many applications but has not seen an official update since 2008. The latest release does not fully support Mac OS X 10.6 and will not work at all on OS X 10.7 and later versions. The OSXFUSE project has sprung from the MacFUSE Google Group in order to continue the work on FUSE for OS X. See question 1.3 for information about the "MacFUSE Compatibility Layer".
"FUSE for OS X" has two major components: an in-kernel loadable file system and a user-space library (libosxfuse). The in-kernel file system is specific to 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 (libosxfuse), which provides the developer-visible FUSE API, has numerous OS X specific extensions and features.
The OSXFUSE software package is compatible with Mac OS X 10.5 and later versions. It supports Intel and PowerPC Macs.
"OSXFUSE-{version}.dmg" is the disk image containing the official distribution of fundamental "FUSE for OS X" software you need to use other software built atop "FUSE for OS X" or MacFUSE. The core "FUSE for OS X" software consists of the following components when installed on your Mac:
- OSXFUSE file system bundle
/Library/Filesystems/osxfusefs.fs - OSXFUSE Objective-C framework
/Library/Frameworks/OSXFUSE.framework - OSXFUSE C-based libraries
/usr/local/lib/libosxfuse*.dyliband headers/usr/local/include/osxfuse* - "FUSE for OS X" preference pane
/Library/PreferencePanes/OSXFUSE.prefPane
The osxfusefs.fs bundle in turn contains most of the core "FUSE for OS X" software. Besides bundle metadata, its components include:
- OSXFUSE kernel extension
osxfusefs.kext - OSXFUSE mount program
mount_osxfusefs - OSXFUSE kernel extension loader
load_osxfusefs - OSXFUSE auto-update mechanism
autoinstall-osxfuse-core - OSXFUSE uninstall script
uninstall-osxfuse-core
See question 2.3 for instructions on how to unistall "FUSE for OS X".
The "FUSE for OS X" software contains a compatibility layer for file systems that have been built for MacFUSE. You will need this compatibility layer, if you plan on using MacFUSE file systems like "NTFS-3G for Mac OS X" or TrueCrypt with "FUSE for OS X".
By default the MacFUSE compatibility layer is not installed. To install it, select the option "MacFUSE Compatibility Layer" in section "Installation Type" when installing "FUSE for OS X". If "FUSE for OS X" has been installed without the compatibility layer, run the installer again. As a result of installing the compatibility layer, MacFUSE will automaticall be uninstalled - in case it is installed.
The "MacFUSE Compatibility layer" consists of the following components when installed on your Mac:
- MacFUSE Objective-C framework
/Library/Frameworks/MacFUSE.framework - MacFUSE C-based libraries
/usr/local/lib/libfuse*.dyliband headers/usr/local/include/macfuse*
1.4. I am experiencing serious problems (fill in details of serious problems here) right after I installed "FUSE for OS X". What can I do?
Circumstantial evidence such as "right after I installed 'FUSE for OSX'" is unfortunately not enough to go on. To realize why "FUSE for OS X" cannot cause the kind of problems people sometimes ascribe to it, you need to understand what "FUSE for OS X" is, and just as importantly, what it is not.
"FUSE for OS X" is not an application. It is not a background process. It is not something that launches automatically at boot time or any other time. 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 besides placing its preference pane for System Preferences to use.
"FUSE for OS X" is a bunch of libraries and headers along with a kernel extension. Developers use OSXFUSE 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, "FUSE for OS X" is not either.
The OSXFUSE kernel extension is not loaded automatically at boot time or any other time. It is dynamically loaded when a "FUSE for OS X"-based application runs. Even when loaded, the kernel extension just occupies some memory - its code does not kick in until you actually mount a "FUSE for OS X"-based file system.
The "FUSE for OS X" updater runs only when explicitly asked by the user, say, by going to the "FUSE for OS X" preference pane.
With this context, even if "it happened right after/only when you installed 'FUSE for OS X'", "FUSE for OS X" cannot do things such as the following:
- Affect the display
- Affect wireless networking
- Affect the computer's sleep or hibernate cycles
- Prevent the computer from booting
- Affect Finder settings, or any other program's settings
- Do anything to your computer's firmware
- Do anything to your computer's optical drive
- Cause HFS+ corruption or any other non-"FUSE for OS X"-based file system's corruption
- ...
If you remain convinced that your woes are "FUSE for OS X"'s fault, please provide more information.
Note: "FUSE for OS X" refers to the official version that can be downloaded from this web site. Everything here should generally apply to other repackagings/redistributions of "FUSE for OS X", but they are not officially supported.
The recommended way to install "FUSE for OS X" is to download the latest "OSXFUSE-{version}.dmg" available from http://osxfuse.github.com/ and double-clicking on "Install OSXFUSE {version}".
The tools to keep "FUSE for OS X" up-to-date (query the installed version, query for available updates, download and install updates, and so on) are built into "FUSE for OS X". Simply launch the "System Preferences" application and go to the "FUSE for OS X" preference pane. It should tell you if there is and update and if so, will also let you download and install it.
Launch the "System Preferences" application and go to the "FUSE for OS X" preference pane. Click on the "Remove OSXFUSE" button. This will uninstall all "FUSE for OS X" components except the preference pane itself.
You can keep the "FUSE for OS X" preference pane around should you decide to install "FUSE for OS X" again in the future. If you do wish to remove it, you do it just like how you would remove any other non-Apple preference pane:
In System Preferences, control-click (right-click) on the "FUSE for OS X" icon and you will see "Remove ..." as an action.
Note: If you had the "Show Beta Versions" button checked in the "FUSE for OS X" preference pane, you will have a property list file remaining at: /Library/Preferences/com.github.osxfuse.plist. To remove it, you should uncheck the button before you remove the preference pane as described above.
No, you are not required but highly recommended to do so. See this blog post about MacFUSE that applys to "FUSE for OS X", too, for more details.
2.5. I am using some software that needs an old/deprecated version of "FUSE for OS X". I do not see that version available on the web site. What to do?
Please do not use old/deprecated versions of "FUSE for OS X". The only "good" version of "FUSE for OS X" is the latest one. Older versions become obsolete/unsupported as soon as a new release is out. It is an important goal of "FUSE for OS X" to not break existing applications written atop it. Developers are encouraged to test their software against pre-release versions of "FUSE for OS X" to help meet this goal.
-
NTFS-3G: For more information about NTFS-3G see NTFS-3G for Mac OS X.
-
SSHFS: For more information about SSHFS see SSHFS.
To be precise, by default "FUSE for OS X" volumes show up as non-local volumes, which the Finder unfortunately treats the same as "servers". It is a good question as to why "FUSE for OS X" normally tags its volumes as non-local. Some people think that in the case of disk-based file systems such as NTFS-3G, "FUSE for OS X" must tag the volume as local.
For a VFS to be local on Mac OS X, you need a "real" disk device - a /dev/disk{number} style node. Such a real disk device node in "FUSE for OS X"'s case is problematic: at mount time, for a local volume, the kernel would
itself open the device node and pass it to "FUSE for OS X". 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 "FUSE for OS X" and mounting can proceed. This would have been fine if the entire file system lived in the kernel, but in "FUSE for OS X"'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 "FUSE for OS X" volumes are, in fact, "remote". (The semantics of "local" and "remote" are debatable, but that is another discussion.) As far as the "FUSE for OS X" 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. "FUSE for OS X" does not 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 "FUSE for OS X" 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 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)
Check if the Finder preference for showing mounted servers on the Desktop is enabled. (Also see question 4.1 to understand why we are talking about "servers" here) You can either check if Finder > Preferences > General > Connected servers is checked, or you can use the defaults command from Terminal:
defaults read com.apple.finder ShowMountedServersOnDesktop
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 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.
4.3. I mounted a "FUSE for OS X" volume but I do not see a volume icon in the Finder's sidebar. I have looked at all relevant Finder preferences, but still nothing. What is happening?
The Finder by default will not show a "FUSE for OS X" volume under the "DEVICES" section of the sidebar because the volume is not "local". The Finder will not show the volume under "SHARED" (even though it is "non-local") because it apparently thinks that non-local 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 mount-time option. Also see questions 4.1 and 4.2.
To show all mounted volumes (including "FUSE for OS X" volumes) in Finder click on Go > Computer in Finder's menu bar.
4.4. I tried to use file system (fill in file system here) with "FUSE for OS X" and I am not happy because of (fill in reason here). What to do?
"FUSE for OS X" is like a programming library. Individual file systems (like NTFS-3G, procfs, SSHFS, etc.) are programs written using that library. The quality and behavior of individual programs - of any kind - can vary wildly, and may or may not be an issue with the underlying library. If you have poor experience with an individual "FUSE for OS X" file system, please determine (or help determine) if it is an issue specific to that file system or if it is a general issue with "FUSE for OS X". File systems are complex. "FUSE for OS X" does simplify their implementation enormously, but nontrivial user space file systems can still be complex, and their performance/behavior can depend upon numerous factors besides "FUSE for OS X" itself. When in doubt, feel free to post your questions on the "FUSE for OS X" Google Group.
4.5. I am trying to access a "FUSE for OS X" volume but I keep getting access/permission denied errors. I am doing this as root - what is going on? Is not everything allowed as root?
For several reasons, by default, "FUSE for OS X" allows access to a volume only to the user who mounted the volume. All other users, including the superuser are denied access. You can change this behavior if you need to. Refer to the allow_other and allow_root mount-time options.
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.
4.7. I tried to run gdb on an executable residing on a "FUSE for OS X" file system but I got an "operation not permitted" error. What is going on?
gdb is a setgid executable on Mac OS X (see /usr/libexec/*gdb*). Therefore, under "FUSE for OS X"'s default mode of operation, it will not have access to "FUSE for OS X" volumes. See the previous questions.
4.8. How should I unmount my "FUSE for OS X" file system? I cannot find the fusermount program anywhere.
Just use the standard umount command in OS X. You do not need the Linux-specific fusermount with "FUSE for OS X".
4.9. All my file systems are showing up in the Finder as "OSXFUSE Volume {number} ({type})". What should I do?
Use the volname command-line mount-time option.
5.1. I am having problem (fill in problem here) compiling a FUSE file system in the "FUSE for OS X" environment. What to do?
Besides any other file-system-specific compile- or configure-time options, you may need to have -D_FILE_OFFSET_BITS=64 -D_DARWIN_USE_64_BIT_INODE in CFLAGS unless it is already there (-D_DARWIN_USE_64_BIT_INODE is only needed when targeting Mac OS X 10.5). Try something like:
CFLAGS="-D_FILE_OFFSET_BITS=64 -D_DARWIN_USE_64_BIT_INODE" ./configure --prefix=/usr/local
"FUSE for OS X" installs a fuse.pc file in /usr/local/lib/pkgconfig/. This, in conjunction with the pkg-config program, will automatically cause -D_FILE_OFFSET_BITS=64 -D_DARWIN_USE_64_BIT_INODE to be included in CFLAGS. If your particular installation of pkg-config (say, through MacPorts) does not look under /usr/local/lib/pkgconfig/ by default, you can set the environment variable PKG_CONFIG_PATH to /usr/local/lib/pkgconfig.