freebsd-ports/sysutils/fusefs-ntfs/files

==============================================================================
NTFS-3G README for the FreeBSD port
==============================================================================

1. Introduction
2. Port specific notes
3. Mounting at startup with /etc/fstab
4. Ublio configuration
5. Known issues
6. Reporting bugs

==============================================================================
1. Introduction
==============================================================================

The NTFS-3G project provides a read/write filesystem driver for NTFS. It uses
the FUSE library (a OS independent library to create filesystem drivers), more
precisely FUSE's library with fuse4bsd's kernel module (port of the kernel
dependent part of FUSE). For more information see:

NTFS-3G site:	http://ntfs-3g.org/
FUSE site:	http://fuse.sourceforge.net/
fuse4bsd site:	http://fuse4bsd.creo.hu/

==============================================================================
2. Port specific notes
==============================================================================

The port has a patch to align read/write operations to the media block size
(required on FreeBSD).

The port has 2 options: LOCK (to prevent access to the device by external
programs than NTFS-3G once mounted, default on Linux), and UBLIO (use a user
space cache library, see devel/libublio, not required on Linux).

The reason for using UBLIO is that FreeBSD removed support for block devices,
being them now character devices. The former ones had a cache, and NTFS-3G was
optimized for it (Linux still uses them). The same happens on Mac OS X (based
on FreeBSD 5). So using UBLIO both improves performance (~10 times faster),
and reduces disk load.

==============================================================================
3. Mounting at startup with /etc/fstab
==============================================================================

To mount at startup you need to have the following line in /etc/rc.conf:

fusefs_enable="YES"

And add the appropiate line to /etc/fstab: the filesystem should be "ntfs-3g"
instead of "ntfs", and the additional "late" parameter is required. Example:

/dev/ad4s1		/wxp		ntfs-3g	rw,late		0	0

Note that in FreeBSD 7.x, mount(8) has a fixed (hard coded) list of external
mount_XXX programs that can be called, so to make this work you have to do one
of the following:

1. Rename /sbin/mount_ntfs, symlink ntfs-3g as the former, and use just "ntfs"
   as the type in /etc/fstab.
   $ mv /sbin/mount_ntfs /sbin/mount_ntfs-kern
   $ ln -s /usr/sbin/mount_ntfs-3g /usr/sbin/mount_ntfs
2. Apply a patch to src/sbin/mount/mount.c to add "ntfs-3g" as a valid type.
3. Apply a patch to src/sbin/mount/mount.c to make it work like in 6.x (better
   than the previous one as will allow any external type). It can be found at:
   http://people.freebsd.org/~alepulver/current-7.0-mount.diff

==============================================================================
4. Ublio configuration
==============================================================================

The UBLIO layer is configured through environment variables, which are read
when mounting the filesystem. The following are available:

NTFS_USE_UBLIO	- Enable the UBLIO cache.
UBLIO_BLOCKSIZE	- Actual reads/writes will be multiples of this quantity.
UBLIO_ITEMS	- Number of cache entries, each of UBLIO_BLOCKSIZE length.
UBLIO_GRACE	- Number of times a cache entry will refuse being recycled.
UBLIO_SYNC_IO	- If enabled, all writes will be immediatly executed.

To give an idea about tuning, here are the default values with some notes
(they are only based on some simple benchmarks, and may be wrong):

NTFS_USE_UBLIO	- 1. Disabling it drastically decreases performance.
UBLIO_BLOCKSIZE	- 262144 (256KB). Larger improves reading/writing speed of
		  large files, and smaller makes filesystem operations
		  (creation, deletion, moving, find(1)) perform faster.
		  Try 2/4MB and 512/256KB for the different approaches. Note
		  that after that points performance descreases again.
UBLIO_ITEMS	- 64. Higher increases speed of filesystem operations. Try 128.
UBLIO_GRACE	- 32. Makes the cache items have more chances to be reused.
UBLIO_SYNC_IO	- 0. If enabled, highly decreases writing speed, but the data
		  is immediatly written to the disk.

For example (improves performance over large files, but read below):

# env UBLIO_BLOCKSIZE=2097152 ntfs-3g /dev/ad0s1 /mnt

Alternatively these variables could be set in the shell startup file. For
example if you are using it in /etc/fstab add them to /etc/profile. If you use
it as a user, instead, editing the shell startup in HOME is enough.

Note that higher values for UBLIO_BLOCKSIZE and UBLIO_ITEMS increase the
memory usage by their product in bytes. For example, if you set it to 1MB it
would consume 64MB. To decrease it to 16MB you could set UBLIO_BLOCKSIZE to
256KB (currently this is the default). Small values like 4096 can be used and
also perform fine.

It is also possible to enforce block aligned I/O on regular files by setting
the FORCE_ALIGNED_IO variable (it will be set to 512 bytes), but this is only
useful for testing purposes and in practice has no use.

==============================================================================
5. Known issues
==============================================================================

When reading/writting the same file repeatedly while doing many simultaneous
operations on different files sometimes the former one fails: read(2) returns
-1 and sets errno to EAGAIN. This is because of a difference between the FUSE
kernel implementation in Linux and FreeBSD, and is being worked on. An example
scenario would be playing a song in XMMS, while building many ports, which
could cause XMMS skip the song. Another observed problem is the current
directory not being found, but entering again would work. The details are
described in fuse4bsd (sysutils/fusefs-kmod) documentation (Linux access is
path based while FreeBSD is vnode based, which may be reused).

==============================================================================
6. Reporting bugs
==============================================================================

About the port itself, you can ask the maintainer (preferable) and/or in the
ports@FreeBSD.org mailing list.

About general NTFS problems (corruptions, etc) ask in the NTFS-3G forum (see
below).

But often (even on Linux, 50% of the issues are related to these) the problems
reside on the FUSE implementation (the library itself, or fuse4bsd portion).

For reporting kernel panics, see:

http://fuse.sourceforge.net/wiki/index.php/DebugFreeBSDPanicsHowto

And you can report them to the fuse4bsd author (preferable), or here:

NTFS-3G forum:	http://forum.ntfs-3g.org/
FreeBSD PRs:	http://www.freebsd.org/send-pr.html

==============================================================================