Why my NAS lost all share permissions after a migration and the UID/GID remap script that repaired access control

After spending an entire weekend migrating my network-attached storage (NAS) setup from an aging box to a shiny new system, I thought the hardest part was over. Fresh OS, upgraded hardware, and a clean, organized disk layout—it should have been smooth sailing. But as soon as I reconnected the NAS to the network and tried to access my shared folders, something was immediately wrong: no one could access anything. All share permissions seemed to have vanished into thin air. My carefully set read, write, and execute permissions were now a tangled mess of access denied errors. What went wrong during this seamless migration?

TL;DR (Too long; didn’t read)

During my NAS migration, all file and folder permissions disappeared because the user IDs (UIDs) and group IDs (GIDs) on the new system didn’t match those on the old setup. These numeric identifiers are how Linux-based systems enforce access control regardless of the visible user names. I used a UID/GID remapping script to realign ownership on the new system to match what was originally set. This script saved hours of manual effort and fully restored my access control configuration.

Why Permissions Matter—and How They Work

In Unix-like systems (which most NAS OS platforms are based on), the access rights for files and folders don’t rely on usernames alone. Instead, ownership is enforced using UIDs (User IDs) and GIDs (Group IDs). This allows the system to operate with numeric precision behind the scenes, even if usernames look identical across systems.

For example, let’s say your user “alex” had UID 1003 on the old NAS. On the new NAS, after reinstalling the OS, “alex” could now be assigned UID 1001—if the user was re-added in a different order or from a different base image. As a result, even though ‘alex’ appears to have the proper username, the underlying UID no longer matches the files created previously.

Symptoms of Broken Permissions After a Migration

Here are the warning signs that your NAS might have suffered a mismatch of UID/GIDs during a migration:

Previously accessible shares now throw “Access Denied” errors
Files show up as owned by “nobody” or “unknown” when viewed via shell
Users can no longer write or modify files they created in the old NAS
Samba or NFS shares log permission-related errors

The moment I saw “owner: nobody” and chmod wouldn’t work easily, I knew I wasn’t dealing with corrupted data—it was a mapping mismatch.

What’s Actually Happening Behind the Scenes

Preserving filenames and directory trees is one thing. But unless you properly migrate or replicate the /etc/passwd and /etc/group information—or more extreme still, the numeric UIDs/GIDs—from one machine to another, the files stored on the disk will no longer “connect” to the users as you expect.

This comes from the static way Unix assigns ownership metadata to files:

Each file has a UID and GID associated with it
The system maps these IDs to usernames using a local lookup
If the UID is not associated with a user on the new machine, it will appear as “nobody”

Each time you copy files across disks, especially if using a tool like rsync or cp, this numeric ownership is preserved—which is good. But it only helps if those IDs still relate to something meaningful on the destination system.

The Script That Saved My NAS Access Control

I opted not to manually recreate the old users with their specific UIDs because that’s prone to error and not future-proof. Instead, I wrote a Python-based UID/GID remap script that scans the file system, identifies inconsistencies, and updates ownerships accordingly.

Here’s how the script works:

It accepts a mapping dictionary of old UID to new UID pairs
Recursively walks through directories and files under a specified root
Whenever it finds a file or folder owned by the old UID/GID, it updates it to the new one using os.chown()

Key Principles I Followed

Non-destructive: the script doesn’t delete or overwrite data, only updates inode metadata
Dry-run Feature: simulate changes to preview which files will be affected
Verbose Logging: keeps track of every file changed for review and rollback if needed

This meant I could test the script first without modifying anything. Once I saw that it correctly mapped old UID 1003 to new UID 1001 for all of “alex’s” files, I ran it for all users.

And it worked. The shares magically became accessible again right after. Windows clients no longer reported authentication issues, and media servers located in those directories started indexing without any complaints.

The Script in Simplified Form

import os

# Mapping of old UID to new UID
uid_map = {
    1003: 1001,
    1004: 1002,
    # Add more as needed
}

# Same for groups (if needed)
gid_map = {
    1003: 1001,
    1004: 1002,
}

def remap_ids(target_dir):
    for root, dirs, files in os.walk(target_dir):
        for name in dirs + files:
            path = os.path.join(root, name)
            stat_info = os.lstat(path)
            uid = uid_map.get(stat_info.st_uid, stat_info.st_uid)
            gid = gid_map.get(stat_info.st_gid, stat_info.st_gid)
            os.lchown(path, uid, gid)
            print(f"Updated: {path} to UID:{uid} GID:{gid}")

# Example usage
remap_ids("/mnt/nas_storage")

This simple but powerful script became an indispensable tool. And it’s easy to expand to multiple directories, user validation, or even integrate with Samba or NFS hooks.

Lessons Learned and Preventative Strategies

If you’re ever planning to migrate a Linux-based NAS, learn from my experience and consider the following preventative measures:

Record UIDs and GIDs of all users before the migration. Save the contents of /etc/passwd and /etc/group.
Create users in the same order or manually set their UIDs during user creation using tools like useradd -u UID
Use rsync with -a to preserve UID/GID during transfer
Use remapping scripts to patch things if all else fails

While this problem might seem obscure, it’s more common than you’d think—especially for self-built NAS systems or migrations across Linux distributions. The key is knowing that the system cares about numbers, not names.

Final Thoughts

In the end, my lost NAS permissions turned out to be a UID/GID mismatch—not a corrupted filesystem or botched migration tool. A small Python script was all it took to realign my file ownership landscape and restore the access control I had meticulously configured. Sometimes, it’s not about how advanced the technology is, but how well you understand the fundamentals behind it.

If you’re setting up or migrating a NAS, take a few extra minutes to consider how ownership identifiers are managed. Future-you will thank you when your shares continue to work like nothing ever changed.

Jonathan Dough