mirror of
https://git.freebsd.org/ports.git
synced 2025-05-14 16:21:50 -04:00
fbf944ca9e
- Mention the necessity of fusefs(5) support in the kernel and how to enable it at the system startup time - Remove outdated URLs and references from the FreeBSD-specific README file; drop the ``Reporting bugs'' section completely as most of it does not reflect modern reality or is simply banal PR: 264478, 264479
126 lines
5.8 KiB
Text
126 lines
5.8 KiB
Text
==============================================================================
|
|
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
|
|
|
|
==============================================================================
|
|
1. Introduction
|
|
==============================================================================
|
|
|
|
The NTFS-3G project provides a read/write filesystem driver for NTFS. It uses
|
|
the FUSE library (an OS-independent library to create filesystem drivers) and
|
|
FreeBSD fusefs(5) kernel module (port of the kernel-dependent part of FUSE).
|
|
For more information see:
|
|
|
|
NTFS-3G site: https://github.com/tuxera/ntfs-3g
|
|
FUSE site: https://github.com/libfuse/libfuse
|
|
|
|
==============================================================================
|
|
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 /boot/loader.conf:
|
|
|
|
fusefs_load="YES"
|
|
|
|
or have "fusefs" added to the "kld_list" in the /etc/rc.conf.
|
|
|
|
Then create the following symlink:
|
|
|
|
$ ln -s `which ntfs-3g` /usr/sbin/mount_ntfs-3g
|
|
|
|
And add the appropriate 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
|
|
|
|
==============================================================================
|
|
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 immediately 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 decreases 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 immediately 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
|
|
==============================================================================
|
|
|
|
- For mkntfs(8) -F must be used to allow non-block device to be processed.
|
|
|
|
- Current implementation does not properly work with partitions of size which
|
|
is not a multiply of UBLIO_BLOCKSIZE (cannot read/write last cluster). For
|
|
instance, you may not be able to create ntfs filesystem because of this with
|
|
|
|
Initializing device with zeroes: 99%Failed to complete writing to
|
|
/dev/ada0s1 after three retries.
|
|
|
|
- When reading/writing 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 (Linux access is
|
|
path-based while FreeBSD is vnode-based, which may be reused).
|
|
|
|
==============================================================================
|