TrueNAS Mirror Dataset Visible But Can’t Extract Files

If your TrueNAS mirror dataset is visible but you cannot extract files from it, the most common cause is a permissions or ownership mismatch between the dataset and the user or application trying to read the files, not data corruption. This article explains why this happens and provides step-by-step fixes to regain access to your data.

Background: How TrueNAS Mirrors and Datasets Work

TrueNAS uses ZFS as its filesystem, which handles both the storage pool and the datasets within it. A mirror is a type of virtual device (vdev) that stores identical copies of data on two or more disks. The mirror protects against a single disk failure, but it does not change how permissions or file access work. Datasets are separate filesystems within a pool, each with its own permissions, quotas, and settings. When you create a dataset, TrueNAS applies default permissions based on the pool’s configuration, often using the root user or a specific service account. If those permissions are too restrictive, or if you’re accessing the data through a different user, you may see the dataset and its contents but be unable to open or extract files.

Why You Can See Files but Not Extract Them

There are several reasons why a dataset appears normal but refuses to let you extract files. The most frequent causes are:

• Incorrect ownership: The files are owned by a user (e.g., root or a service account) that your current user does not match, and the permissions (read/write/execute) are not set for “others.”
• Permissions misconfiguration: The dataset’s ACL (Access Control List) may have explicit deny entries or missing read permissions for your user or group.
• Read-only dataset or pool: The dataset or the entire pool may be mounted read-only, often due to a previous error or an explicit setting.
• Encryption or lock: If the dataset is encrypted and the key is not loaded, you may see the dataset name but cannot access the data.
• Corrupted file system metadata: While rare, ZFS can have corrupted metadata that makes files appear but unreadable. This is less common but possible.

How to Diagnose the Problem

Before making changes, it’s important to confirm the exact cause. Follow these steps in order:

1. Check the pool status: Go to Storage → Pools in the TrueNAS web interface. Look for any warnings or errors. Ensure the pool is healthy (status ONLINE) and not degraded or read-only.
2. Check dataset mount point: Under Storage → Pools → (your pool) → (your dataset), verify the mount point is set correctly. If it’s not mounted, the dataset won’t be accessible at all.
3. Inspect permissions via shell: Use the TrueNAS shell (or SSH) to run ls -la /mnt/poolname/datasetname. This shows the ownership and permission bits. Also run getfacl if available to see the full ACL.
4. Test as root: Try to read the file as the root user (e.g., cat /mnt/poolname/datasetname/file). If root can read it, the issue is definitely permissions for your user.
5. Check encryption status: If the dataset is encrypted, go to Storage → Pools → (dataset) → Encryption and confirm the key is loaded. If not, load it.

Fixing Permissions and Ownership

Once you’ve confirmed it’s a permissions issue, the fix is straightforward. You can do this via the TrueNAS web interface or the shell.

Using the Web Interface:

1. Go to Storage → Pools, find your dataset, and click the three-dot menu → Edit Permissions.
2. Set the owner user and group to the user that needs access (e.g., your login user or a service account).
3. Set the permission bits. For a typical user, you want the owner to have Read and Write, and possibly Execute for directories.
4. If you have complex ACLs, you can use the Apply User and Apply Group checkboxes to recursively change ownership.

Using the Shell:

Run the following commands as root (adjust paths and usernames):

chown -R username:group /mnt/poolname/datasetname
chmod -R u+rwX /mnt/poolname/datasetname

The X (capital) only adds execute permission for directories, which is safe for files. If you need to give access to a group, add g+rwX as well.

Common Mistakes and Misconceptions

One common mistake is assuming that because the mirror is healthy, the data is automatically accessible. That’s not true—ZFS still enforces permissions. Another misconception is that you need to “repair” the mirror to fix access issues. A mirror only protects against disk failure; it does not affect file permissions. Also, some users try to change permissions on the entire pool, which can break system services. Always change permissions on the specific dataset, not the pool root.

Another frequent error is using chmod 777 to give everyone access. This is a security risk and should be avoided. Instead, set proper ownership and group permissions.

When the Data Is Actually Corrupted

If permissions are correct but you still cannot extract files, it may be a ZFS corruption issue. Check the pool status for checksum errors: zpool status -v. If you see errors, the mirror may have a bad copy. In a mirror, ZFS can often self-heal if one copy is good. If both copies are bad, recovery is difficult. You can try to roll back to a previous snapshot if you have one. If you have a snapshot, go to Storage → Pools → (dataset) → Snapshots and roll back to a point before the corruption. Always make a backup of any important data before attempting repairs.

Frequently Asked Questions

Q: Why can I see the dataset but not open it in Windows Explorer?
A: This usually means the SMB share permissions are misconfigured. Check the share’s ACL in TrueNAS under Shares → Windows (SMB). Ensure the share allows your user and that the dataset permissions also allow access. Also, check that the Windows user is mapped correctly to a TrueNAS user.

Q: Can I extract files using the TrueNAS shell if I can’t via SMB?
A: Yes, if you have root access to the shell, you can read the files directly from the mounted dataset. This bypasses SMB permission checks, but you still need filesystem permissions. If root can read them, the issue is with the SMB share configuration, not the dataset.

Q: How do I give a specific user access to a dataset without making everything world-readable?
A: In the dataset’s Edit Permissions, set the owner to that user, or add the user to a group that has read access. Then set the group permissions to read/execute. Do not use the “Others” permissions unless you want everyone to have access.

Q: What if the dataset is encrypted and I forgot the passphrase?
A: Without the passphrase or a recovery key, the data is unrecoverable. TrueNAS does not have a backdoor. If you have a recovery key, you can load it via the web interface or zfs load-key command. If not, the data is lost.

Q: Does a mirror protect against accidental deletion?
A: No. A mirror only protects against disk failure. If you delete a file, it is deleted from both copies immediately. For protection against deletion, you need snapshots or backups.

Q: Why does the dataset show as read-only?
A: The pool may have been imported read-only due to a previous error. Check zpool get readonly. If it’s on, export the pool and re-import it normally. Also, check the dataset’s readonly property with zfs get readonly pool/dataset. If set to on, turn it off with zfs set readonly=off.

Related

• Anker Recalls Five More Power Banks: What to Know
• DIY Pokémon Piñata Poké Ball Cake
• Google AI Outfit Images: How the Virtual Try-On Works