-
Notifications
You must be signed in to change notification settings - Fork 6
/
faq.html
156 lines (140 loc) · 19.7 KB
/
faq.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
---
layout: default
title: Fuse4X – FAQ
---
<p>If the question you have isn't answered here, try posting it to the <a href="https://groups.google.com/forum/#!forum/fuse4x">Fuse4X</a> group.</p>
<h1>1. Introductory Questions</h1>
<p><a name="Q.1.1" href="#Q.1.1" class="faqitem">Q 1.1. What is Fuse4X? Is it the same as FUSE on Linux?</a></p>
<p>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 <i>microkernel</i> for the purpose of writing/running file systems. Fuse4X has two major components: an in-kernel loadable file system and a user-space library (<tt>libfuse4x</tt>). The in-kernel file system is specific to Mac OS X and is <strong>not</strong> based on Linux FUSE. (Some of its code is based on the FreeBSD implementation of FUSE.) The user-space library (<tt>libfuse4x</tt>), which provides the developer-visible FUSE API, that is <a href="http://fuse.sourceforge.net">Linux FUSE</a> with a few Mac OS X specific extensions and features.</p>
<p><a name="Q.1.2" href="#Q.1.2" class="faqitem">Q 1.2. What is "Fuse4X-x.y.z.dmg"?</a></p>
<p>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 <strong>when installed</strong> on your system:</p>
<ul>
<li>Fuse4X kernel extension (<tt>/Library/Extensions/fuse4x.kext</tt>)</li>
<li>Fuse4X C-based libraries (<tt>/usr/local/lib/libfuse4x*.dylib</tt>) and headers (<tt>/usr/local/include/fuse*</tt>)</li>
<li>Fuse4X Objective-C framework (<tt>/Library/Frameworks/Fuse4X.framework</tt>)</li>
<li>Utility tools (<tt>/Library/Filesystems/fuse4x.fs/Contents/Executables</tt>) for easier package update/uninstallation</li>
<!-- <li>Fuse4X project templates for Xcode (<tt>/Library/Application Support/Developer/Shared/Xcode/Project Templates/Fuse4X</tt>)</li> -->
</ul>
<p><a name="Q.1.3" href="#Q.1.3" class="faqitem">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></p>
<p>A: Circumstantial evidence such as "right after I installed Fuse4X" is unfortunately not enough to go on. To realize why Fuse4X <strong>cannot</strong> cause the kind of problems people sometimes ascribe to it, you need to understand <strong>what</strong> Fuse4X is, and just as importantly, what it's <strong>not</strong>.</p>
<p>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.</p>
<p>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?)</p>
<p>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:</p>
<ul>
<li>Affect the display</li>
<li>Affect wireless networking</li>
<li>Slow down the computer</li>
<li>Affect the computer's sleep or hibernate cycles</li>
<li>Prevent the computer from booting</li>
<li>Affect Finder settings, or any other program's settings</li>
<li>Do anything to your computer's firmware</li>
<li>Do anything to your computer's optical drive</li>
<li>Cause HFS+ corruption or any other non-Fuse4X-based file system's corruption</li>
<li>Cause car trouble</li>
</ul>
<p>If you remain convinced that your woes are Fuse4X's fault, please provide more information than circumstantial evidence.</p>
<p><a name="Q.1.4" href="#Q.1.4" class="faqitem">Q 1.4. How Fuse4X relates to MacFUSE?</a></p>
<p>Fuse4X is a fork of <a href="http://code.google.com/p/macfuse/">MacFUSE</a> started in June 2011. At that time MacFUSE project has been abandoned by the original author, the last release has been made in 2008.</p>
<p>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 <a href="https://groups.google.com/forum/#!forum/fuse4x">project forum</a>.</p>
<p>It is safe to have both Fuse4X and MacFUSE installed on the same computer. They use different names for extensions, libraries.</p>
<h1>2. Install/Uninstall Questions</h1>
<p><a name="Q.2.1" href="#Q.2.1" class="faqitem">Q 2.1. What is the preferred way to install Fuse4X?</a></p>
<p>A: The preferred way is to install the <tt>Fuse4X.pkg</tt> from the latest <tt>Fuse4X-<version>.dmg</tt> available from:</p>
<p><a href="https://github.com/fuse4x/fuse4x/archives/master">https://github.com/fuse4x/fuse4x/archives/master</a></p>
<p><a name="Q.2.2" href="#Q.2.2" class="faqitem">Q 2.2. How can I keep Fuse4X up-to-date?</a></p>
<p>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
<pre class="terminal"><span class="prompt">$ </span><span class="input">/Library/Filesystems/fuse4x.fs/Contents/Executables/autoupdater</span></pre></p>
<p><a name="Q.2.3" href="#Q.2.3" class="faqitem">Q 2.3. How can I uninstall Fuse4X?</a></p>
<p>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
<pre class="terminal"><span class="prompt">$ </span><span class="input">sudo /Library/Filesystems/fuse4x.fs/Contents/Executables/uninstall.sh</span></pre>
or
<pre class="terminal"><span class="prompt">$ </span><span class="input">sudo /System/Library/Filesystems/fuse4x.fs/Contents/Executables/uninstall.sh</span></pre>
for earlier versions of Fuse4X
</p>
<p><a name="Q.2.4" href="#Q.2.4" class="faqitem">Q 2.4. Why installer asks me to reboot my computer?</a></p>
<p>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.</p>
<p><a name="Q.2.5" href="#Q.2.5" class="faqitem">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></p>
<p>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.</p>
<p><a name="Q.2.6" href="#Q.2.6" class="faqitem">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</a></p>
<p>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.
<pre class="terminal">
<span class="prompt">$ </span><span class="input">sudo kextunload -b org.fuse4x.kext.fuse4x</span>
<span class="prompt">$ </span><span class="input">kextstat -l -b org.fuse4x.kext.fuse4x</span>
</pre>
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:
<pre class="terminal">
<span class="prompt">$ </span><span class="input">mount -t fuse4x</span>
</pre>
It gives you a list of filesystems that still use it. You need to unmount all of them by using "umount" command:
<pre class="terminal">
<span class="prompt">$ </span><span class="input">umount FS_DIRECTORY</span>
</pre>
And then unload the kernel extension one more time.
</p>
<h1>3. File System Specific Questions</h1>
<p><a name="Q.3.1" href="#Q.3.1" class="faqitem">Q 3.1. I just installed Fuse4X. How to mount my ext4/ntfs/fat32/... partition?</a></p>
<p>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.</p>
<p><a name="Q.3.2" href="#Q.3.2" class="faqitem">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></p>
<p>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 <i>replace</i> 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.</p>
<p>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 <tt>-o auto_cache</tt> 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.</p>
<p>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 <tt>-o cache</tt> options in sshfs, in particular, <tt>-o cache=no</tt>). Then, additionally, you need to tell Fuse4X not to cache things on its end too. You can use the <tt>-o nolocalcaches</tt> 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 <tt>auto_cache</tt> is vastly preferred over this approach.</p>
<p>An example command line for this mode of operation could look like the following:</p>
<pre class="terminal">
<span class="prompt">$ </span><span class="input">sshfs user@host:/dir /tmp/ssh -ocache=no -onolocalcaches -ovolname=ssh</span>
</pre>
<p>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 <tt>auto_cache</tt> option.</p>
<p><a name="Q.3.4" href="#Q.3.4" class="faqitem">Q 3.4. Who uses fuse?</a></p>
<p>Fuse is a widely known technology that is supported on several platforms (Linux,BSD,MacOSX). There are many filesystems use it, among them:
<ul>
<li><a href="http://sourceforge.net/apps/mediawiki/fuse/index.php?title=FileSystems">A huge list of filesystems</a> at fuse wiki. Any of these filesystems can be compiled with Fuse4X.</li>
<li><a href="https://github.com/fuse4x/sshfs">SSHFS for MacOSX</a></li>
<li><a href="http://www.lisanet.de/blog/dnl/Encfs-1.7.4.dmg">EncFS for MacOSX</a></li>
<li><a href="https://github.com/gerard/ext4fuse">ext4</a></li>
</ul>
</p>
<h1>4. Other Usage Questions</h1>
<p><a name="Q.4.1" href="#Q.4.1" class="faqitem">Q 4.1. Why do Fuse4X volumes show up with "server" (or "network volume") icons?</a></p>
<p>A: To be precise, by default Fuse4X volumes show up as <i>nonlocal</i> 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 <i>must</i> tag the volume as local. Well, let us see.</p>
<p>For a vfs to be local on Mac OS X, you need a "real" disk device – a <tt>/dev/disk*</tt> style node. Such a real disk device node in Fuse4X's case is problematic: at mount time, for a local volume, the kernel would <i>itself</i> 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 <i>also</i> want to (exclusively) open the disk device.</p>
<p>Moreover, Disk Arbitration also gets involved in mounting and unmounting "local" volumes – this may be undesirable in some cases.</p>
<p>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.</p>
<p>One way to think of Fuse4X user-space file systems is indeed as "servers" – in the microkernel sense.</p>
<p>All this said, it <i>is</i> possible to tag a specific mount point as "local" at mount time. If you wish to do so, you can use the <tt>-o local</tt> 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 <tt>.Trashes</tt> directory created on your volume. (It may not even be possible to create that directory in the case of certain file systems.) <strong>Make sure</strong> you read the description of <tt>-o local</tt> on the <a href="/options.html">options</a> page.</p>
<p><a name="Q.4.2" href="#Q.4.2" class="faqitem">Q 4.2. I mounted a Fuse4X volume but I don't see a volume icon on the Desktop. Why?</a></p>
<p>A: Check if the Finder preference for showing mounted servers on the Desktop is enabled. (Also see <strong>Q 4.1</strong> to understand why we are talking about "servers" here.) On Mac OS X "Leopard", this preference is <i>not</i> enabled by default. You can either check if <tt>Finder->Preferences->General->Connected servers</tt> is checked, or you can use the <tt>defaults</tt> command from a shell:</p>
<pre class="terminal">
<span class="prompt">$ </span><span class="input">defaults read com.apple.finder ShowMountedServersOnDesktop</span>
0</pre>
<p>If the preference is unchecked, you can check it within the GUI or use <tt>defaults</tt> to set its value to 1:</p>
<pre class="terminal">
<span class="prompt">$ </span><span class="input">defaults write com.apple.finder ShowMountedServersOnDesktop 1</span>
</pre>
<p>Alternatively, you can use the <tt>-o local</tt> 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.</p>
<p><a name="Q.4.3" href="#Q.4.3" class="faqitem">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></p>
<p>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 <tt>-o local</tt> Fuse4X mount-time option. Also see <strong>Q 4.1</strong> and <strong>Q 4.2</strong>.</p>
<p><a name="Q.4.5" href="#Q.4.5" class="faqitem">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></p>
<p>A: For several reasons, by default, Fuse4X allows access to a volume <i>only</i> to the user who mounted the volume. All other users, <i>including</i> the superuser is denied access. You can change this behavior if you need to. Refer to the <tt>allow_other</tt> and <tt>allow_root</tt> mount-time options in the <a href="/options.html">options</a> document.</p>
<p><a name="Q.4.6" href="#Q.4.6" class="faqitem">Q 4.6. Can I enable Spotlight on a Fuse4X file system?</a></p>
<p>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.</p>
<p><a name="Q.4.8" href="#Q.4.8" class="faqitem">Q 4.8. How should I unmount my Fuse4X file system? I can't find the <tt>fusermount</tt> program anywhere.</a></p>
<p>A: Just use the standard <tt>umount</tt> command in Mac OS X. You don't need the Linux-specific <tt>fusermount</tt> with Fuse4X.</p>
<p><a name="Q.4.9" href="#Q.4.9" class="faqitem">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></p>
<p>A: Use the <tt>volname</tt> command-line option. See <a href="/options.html">options</a> for details.</p>
<p><a name="Q.4.10" href="#Q.4.10" class="faqitem">Q 4.10. How to build Fuse4X?</a></p>
<p>
<ol>
<li>Install all required development tools. You need to have XCode with MacOSX SDK.<br>
Additionally you need to have <tt>autotools,gettext,iconv,pkg-config</tt> installed. The most easiest way to do it - use a package manager such as <a href="http://macports.org">MacPorts</a> or <a href="http://mxcl.github.com/homebrew/">Homebrew</a>. For macports instructions are following:
<pre class="terminal">
<span class="prompt">$ </span><span class="input">sudo port install libtool autoconf automake gettext pkgconfig libiconv</span>
</pre>
</li>
<li>Go to the <a href="https://github.com/fuse4x">github page</a> and clone module you are interested in. If you want to build the final *.pkg file - clone all modules like this:
<pre class="terminal">
<span class="prompt">$ </span><span class="input">for p in kext fuse framework support fuse4x sshfs; do git clone git://github.com/fuse4x/$p.git; done</span>
</pre>
</li>
<li>Go to the module directory and run its build script <tt>./build.rb</tt>. It builds the binaries; for a <tt>kext,fuse,sshfs</tt> modules it also installs the binaries to your local computer. If you want to build the final *.dmg file - run <tt>./build.rb</tt> from fuse4x module, *.dmg file can be found in fuse4x/build directory.</li>
</ol>
</p>