ntfs-3g.usermap

ntfs-3g.usermap [options] <ntfs-source> [<mapping-file-path>]
ntfs-3g.usermap [options] - [<mapping-file-path>]

<ntfs-source>
    The NTFS device (e.g., /dev/sdb1), mount point (e.g., /mnt/ntfs), or - to read SIDs from standard input.

<mapping-file-path>
    Optional. The path to the mapping file to be created or updated. If omitted, the output is printed to standard output.

-h, --help
    Displays a help message and exits.

-v, --version
    Shows version information and exits.

-c, --create-mapping
    Creates a new mapping file, overwriting any existing one at the specified path.

-a, --append
    Appends new mappings to an existing mapping file. This is the default behavior if -c is not used and the file exists.

-p, --permissions
    Includes full permission mapping, allowing for a more accurate translation of NTFS permissions. This option often requires root privileges.

-u, --user-mapping
    Includes user mapping. This option is implied by -p.

-g, --group-mapping
    Includes group mapping. This option is implied by -p.

-e, --everyone
    Adds a mapping for the Windows 'Everyone' SID to a specified Linux UID/GID. Useful for general access.

-o, --owner
    Maps the owner of the NTFS device (the user who mounted it) to a specific Windows SID. This is useful for consistent ownership.

-s SID, --sid SID
    Specifies a particular Windows SID to be mapped.

-U UID, --uid UID
    Specifies a particular Linux UID to map to a given SID or to be included in the mapping.

-G GID, --gid GID
    Specifies a particular Linux GID to map to a given SID or to be included in the mapping.

The ntfs-3g.usermap command is a utility provided by the ntfs-3g project, designed to facilitate proper file ownership and permissions when interacting with NTFS filesystems from Linux. Its primary function is to create and manage a mapping file that translates Windows Security Identifiers (SIDs) to Linux User IDs (UIDs) and Group IDs (GIDs).

This mapping is crucial for ntfs-3g to correctly interpret and enforce file access controls. When an NTFS partition is mounted with options like permissions or acl, ntfs-3g relies on this mapping file to present NTFS file ownership and permissions in a way that is understandable and manageable by the Linux kernel and userland tools. Without a proper mapping, all files might appear to be owned by a single user (e.g., root) or the user mounting the filesystem, losing granular permission control. The command can read SIDs from an NTFS device or a specific file, generate a new mapping file, append to an existing one, or manage individual SID-UID/GID entries.

Using ntfs-3g.usermap effectively often requires a good understanding of both Windows SIDs and Linux UIDs/GIDs. Generating a comprehensive mapping can be complex, especially in environments with many users or dynamically changing SIDs. Incorrect mappings can lead to unexpected permission issues. For accurate permission translation, the command often needs to be run with root privileges. The generated mapping file must be placed in a location where ntfs-3g can find it (e.g., /etc/ntfs-3g.usermap or specified via the usermap= mount option) and must be consistent with the actual users/groups on the Linux system.

The mapping file generated by ntfs-3g.usermap is a plain text file, typically located at /etc/ntfs-3g.usermap, though its path can be specified during mounting using the usermap= option. Each line in the file represents a mapping, usually in the format 'SID:UID:GID' or 'SID:UID' or 'SID:GID'. It is crucial for ntfs-3g to find this file during the mount process to correctly apply permissions and ownership to files and directories on the NTFS filesystem.

The full power of ntfs-3g.usermap is realized when mounting an NTFS partition with specific options in ntfs-3g. The most relevant options are permissions (or acl), which instructs ntfs-3g to honor NTFS permissions and use the mapping file, and usermap=path/to/usermap, which explicitly points to the mapping file. Without these options, ntfs-3g often defaults to simpler ownership rules (e.g., all files owned by the mounting user), making the usermap less critical.

The ntfs-3g.usermap utility is an integral part of the ntfs-3g project, which began development around 2006. ntfs-3g aimed to provide a robust, reliable, and performant read-write NTFS driver for Linux, a significant improvement over earlier, often experimental, NTFS support. As the project matured, features like accurate permission handling became essential, leading to the creation of utilities like ntfs-3g.usermap to bridge the inherent differences between Windows and Linux security models. Its development has been driven by the need for seamless interoperability between the two operating systems, particularly in dual-boot or shared storage environments.

ntfs-3g(8), mount(8), fstab(5)