Linux rsync Permissions Error on WSL2 Ubuntu to Windows Filesystem

Troubleshoot 'rsync permission denied' errors when syncing files from WSL2 Ubuntu to your Windows host filesystem. Understand and resolve common ACL and metadata issues.

When working in a hybrid development environment leveraging the power of WSL2 for Linux tools and Windows for its native applications, rsync is an indispensable utility for synchronizing files. However, a common frustration arises when attempting to rsync files from a WSL2 Ubuntu instance to a Windows host filesystem (e.g., C: or D: drives). The process often terminates with "Permission denied" errors, indicating that rsync cannot properly transfer files due to underlying differences in how Linux and Windows handle file permissions and metadata. This guide will delve into the intricacies of WSL2's interaction with the Windows filesystem (DrvFS) and provide robust solutions to overcome these rsync permission issues.

Symptom & Error Signature

The most common symptom is rsync failing to complete, reporting errors that clearly indicate a permission problem on the destination side. You might see messages like this in your terminal:

# Example rsync command attempting to copy a directory from WSL to Windows
rsync -avz /path/to/source/project/ /mnt/c/Users/YourUser/Documents/destination/

Typical error output:

sending incremental file list
rsync: [sender] set_file_attributes: rsync: [sender] utime(/mnt/c/Users/YourUser/Documents/destination/.idea/dataSources/c0142e03-0c48-436f-b040-cfc3a702b37c.xml): Permission denied (13)
rsync: [sender] set_file_attributes: rsync: [sender] utime(/mnt/c/Users/YourUser/Documents/destination/src/main/resources/application.properties): Permission denied (13)
rsync: [sender] set_file_attributes: rsync: [sender] utime(/mnt/c/Users/YourUser/Documents/destination/target/classes/com/example/MyApp.class): Permission denied (13)
rsync error: some files could not be transferred (code 23) at main.c(1338) [sender=3.2.3]

Other variations may include Input/output error (5) or Operation not permitted (1) when attempting to set specific attributes like ownership or group.

Root Cause Analysis

The core of the problem lies in the fundamental architectural differences between Linux (POSIX) file permissions and Windows (NTFS) Access Control Lists (ACLs), and how WSL2's DrvFS (Drive File System) attempts to bridge this gap.

1. POSIX vs. NTFS Permissions Mismatch:

   • Linux (POSIX) uses a simple owner/group/other triad with read, write, execute bits, along with extended attributes like sticky bits, SUID, SGID.
   • Windows (NTFS) employs a more complex ACL system, where permissions are granted to specific user accounts or groups, defining granular access rights.
   • rsync's default behavior, especially with the -a (archive) flag, attempts to preserve full POSIX permissions, ownership (UID/GID), and timestamps. When rsync tries to apply these Linux-specific attributes to files on a Windows NTFS filesystem mounted via DrvFS, the underlying system often cannot reconcile them directly, leading to "Permission denied" errors.

2. WSL2 DrvFS Metadata Handling:

   • When a Windows drive (e.g., C:) is mounted into WSL2 as /mnt/c, it uses DrvFS. By default, DrvFS tries to map basic file attributes.
   • The metadata mount option in DrvFS allows WSL2 to store POSIX metadata (permissions, owner, group) as extended attributes (reparse points) on the NTFS file system. While this sounds ideal, it can be problematic when writing files via rsync because:
     • The Windows user account executing the WSL2 instance (and thus the rsync process) might not have the necessary NTFS permissions to create/modify these extended attributes for all files or directories.
     • rsync might attempt to set ownership/group to UIDs/GIDs that don't have a direct, privileged mapping to the underlying Windows user, triggering a denial.
     • The overhead or specific implementation of metadata can sometimes conflict with rsync's efficient attribute-setting mechanisms.

3. Default Mount Options and User Context:

   • Without explicit /etc/fstab configuration, DrvFS mounts usually assign files to the current WSL user (based on the init process). umask defaults might also be restrictive.
   • If the source files within WSL2 have different ownerships than the user executing rsync on the target Windows drive, rsync -a will attempt to preserve this, leading to errors.

4. Windows Security Software:

   • Occasionally, antivirus software or Windows Defender might interfere with file operations, especially if they involve large numbers of files or modifications of extended attributes, mistakenly flagging them as suspicious.

Step-by-Step Resolution

The most effective resolution involves a combination of configuring DrvFS mount options and adjusting rsync behavior.

1. Configure DrvFS Mount Options in /etc/fstab

This is the most critical step. For rsync operations from WSL2 to Windows, where the primary goal is file synchronization for Windows applications, it's often counter-productive to try and preserve full Linux metadata. Instead, we want the files to inherit standard Windows permissions associated with your Windows user. This typically means disabling the metadata option and explicitly setting default POSIX permissions and ownership.

1. Edit your WSL2 /etc/fstab: Open a terminal in your WSL2 Ubuntu instance and edit the fstab file:

   sudo nano /etc/fstab
   

2. Add/Modify DrvFS entries: Add or modify the entry for your Windows drive (e.g., C: or D:) to include specific fmask, dmask, uid, and gid options. These options control the default file and directory permissions and ownership that DrvFS applies when creating or modifying files on the Windows filesystem.

   For most rsync scenarios to Windows, you should avoid the metadata option on DrvFS mounts if you're encountering permission issues. While metadata helps preserve Linux attributes, it's often the source of these rsync permission problems when writing to Windows. The uid and gid should match your default user inside WSL2. You can find these with id -u and id -g.

   A recommended entry for /mnt/c might look like this (replace 1000 with your actual UID/GID if different):

   # /etc/fstab entry for Windows C: drive for rsync compatibility
   C: /mnt/c drvfs defaults,noatime,uid=1000,gid=1000,umask=022,fmask=111,dmask=000 0 0
   

   Let's break down these options:

   • C: /mnt/c drvfs: Specifies mounting the Windows C drive at /mnt/c using the DrvFS filesystem.
   • defaults: Standard mount options.
   • noatime: Disables writing access times to files, which can improve performance.
   • uid=1000, gid=1000: Sets the default user and group ID for all files and directories on this mount point. Replace 1000 with your actual WSL2 user's UID/GID (id -u and id -g). This ensures that files appear to be owned by your WSL2 user, simplifying permissions.
   • umask=022: A common umask setting. When creating files, it results in 644 (rw-r–r–) and directories 755 (rwxr-xr-x).
   • fmask=111: Applies an OR mask of 0111 (execute permissions for group/other) to files, effectively removing execute permissions (chmod 666). For files, (target_permissions & ~fmask) is applied. fmask=111 means files will not have execute permissions (e.g., 666 or 644).
   • dmask=000: Applies an OR mask of 0000 to directories, allowing full permissions (chmod 777 or 755). For directories, (target_permissions & ~dmask) is applied. dmask=000 means directories will retain their requested execute permissions (e.g., 777 or 755).

   If you already have metadata in your fstab entry, remove it and restart WSL2. metadata is usually the antagonist for permission errors when rsyncing to Windows.

3. Apply changes and remount: First, unmount the drive:

   sudo umount /mnt/c
   

   Then, mount all entries listed in fstab:

   sudo mount -a
   

   If this causes issues or doesn't seem to take effect, a full WSL2 restart is recommended:

   # From a Windows Command Prompt or PowerShell (as administrator is safest)
   wsl --shutdown
   

   Then, reopen your WSL2 terminal.

2. Adjust rsync Options to Skip Permission/Ownership Preservation

Once DrvFS is configured to not expect or accept full Linux metadata, you must tell rsync not to try and set these attributes. The -a (archive) flag implies --perms, --owner, and --group, which are the primary culprits.

1. Use specific flags instead of -a: Replace -a with a combination of flags that don't attempt to preserve permissions, ownership, or group.

   rsync -rltDv --no-perms --no-owner --no-group /path/to/source/project/ /mnt/c/Users/YourUser/Documents/destination/
   

   Breakdown of flags:

   • -r (recursive): Needed for directories.
   • -l (links): Copies symlinks as symlinks (within the WSL context, these might be converted to files on Windows).
   • -t (times): Preserves modification times. This is generally safe and useful.
   • -D (devices + specials): Copies device files and special files.
   • -v (verbose): Shows what rsync is doing.
   • --no-perms: Crucially prevents rsync from setting permissions on the destination. Files will inherit permissions based on the fmask/dmask/umask settings in your fstab and underlying Windows ACLs.
   • --no-owner: Prevents rsync from setting file ownership.
   • --no-group: Prevents rsync from setting file group.

   Alternatively, you can start with -a and explicitly override the problem options:

   rsync -avz --no-perms --no-owner --no-group /path/to/source/project/ /mnt/c/Users/YourUser/Documents/destination/
   

   This is often a cleaner way to specify intent.

3. Run WSL2 Terminal as Administrator

Sometimes, even with correct fstab settings, the underlying Windows user context lacks sufficient permissions to write certain attributes, especially if the target directory is in a protected area (like Program Files) or inherited ACLs are restrictive.

1. Close all WSL2 terminals.

2. Open Windows Terminal or PowerShell as an administrator.

3. Launch your WSL2 distribution from the administrator terminal (e.g., ubuntu or wsl).

4. Try the rsync command again.

   While running as administrator might solve the problem, routinely running rsync to sensitive Windows directories as administrator might mask underlying permissions issues that should be addressed at the NTFS ACL level for better security practice. Use this as a diagnostic step if other solutions fail.

4. Verify Windows Folder Permissions (NTFS ACLs)

Ensure that the specific Windows folder you are syncing to has appropriate write permissions for your Windows user account.

1. Navigate to the destination folder in Windows File Explorer.

2. Right-click the folder -> Properties -> Security tab.

3. Check Permissions: Ensure your Windows user account has "Full Control" or at least "Modify" and "Write" permissions.

4. Adjust if necessary: Click "Edit", select your user, and grant the required permissions. You might need to click "Advanced" and "Change Permissions" to recursively apply permissions to subfolders and files.

   Be extremely cautious when modifying NTFS permissions on system-critical folders. Incorrect changes can lead to system instability or security vulnerabilities.

5. Exclude Problematic Files or Directories

If only a few specific files or directories consistently cause errors, they might be locked by a Windows process, have extremely restrictive ACLs, or be difficult for DrvFS to manage. You can exclude them using rsync's --exclude option.

rsync -avz --no-perms --no-owner --no-group --exclude='*.lock' --exclude='temp_folder/' /path/to/source/project/ /mnt/c/Users/YourUser/Documents/destination/

6. Disable Antivirus / Windows Defender (Temporary Test)

In rare cases, aggressive antivirus software, including Windows Defender, can interfere with rsync operations, especially when many files are being written or modified, or when extended attributes are being handled.

Temporarily disabling your antivirus software or Windows Defender is a diagnostic step only. Re-enable it immediately after testing. Running your system without active protection is a significant security risk.

1. Disable your antivirus or Windows Defender's real-time protection.
2. Attempt the rsync command.
3. Re-enable your antivirus/Windows Defender immediately.
4. If rsync works, consider adding an exclusion for the target directory in your antivirus software, or investigate specific security settings.

7. Review dmesg for DrvFS-Specific Errors

Sometimes, the underlying DrvFS driver itself reports errors that can give clues. Check the kernel messages for DrvFS-related issues:

dmesg | grep -i drvfs

Look for any entries marked as "error" or "fail" related to file operations on /mnt/c.

By systematically applying these steps, starting with DrvFS configuration and rsync flag adjustments, you should be able to resolve most "Permission denied" errors when syncing files from your WSL2 Ubuntu environment to your Windows host filesystem.