Problem: Samba4 Backup fails during sysvol ntacl backup with NT_STATUS_INVALID_PARAMETER

[fdavid]

Problem

Nightly Samba4 backups (typically scheduled at 3:00 AM) are failing consistently. Affected backups are labeled as INCOMPLETE within the backup directory (e.g., /var/univention-backup/samba/).

When attempting to run the backup manually using the following command:

samba-tool domain backup offline --targetdir=/var/univention-backup/samba

The process terminates with a Python traceback and the following error message:

running offline ntacl backup of sysvol
py_smbd_create_file: init_files_struct failed: NT_STATUS_INVALID_PARAMETER
ERROR(runtime): uncaught exception - (3221225485, 'An invalid parameter was passed to a service or function.')
  File "/usr/lib/python3/dist-packages/samba/netcmd/__init__.py", line 353, in _run
    return self.run(*args, **kwargs)
  File "/usr/lib/python3/dist-packages/samba/netcmd/domain/backup.py", line 1189, in run
    backup_offline(paths.sysvol, sysvol_tar, samdb, paths.smbconf)
  File "/usr/lib/python3/dist-packages/samba/ntacls.py", line 592, in backup_offline
    smbd.create_file(dst, session_info, service)
univention-samba4-backup: ERROR: samba-tool domain backup failed

---

Investigation

The standard traceback does not specify which file within the Sysvol directory is triggering the NT_STATUS_INVALID_PARAMETER error. To identify the culprit, we modified the Samba library file responsible for handling NT ACLs during backups.

1. Adding Debugging to ntacls.py

We added temporary print statements to /usr/lib/python3/dist-packages/samba/ntacls.py around line 590 to log the source and destination of every file being processed:

for filename in filenames:
    src = os.path.join(dirpath, filename)
    dst = os.path.join(dst_dirpath, filename)
    
    # --- DEBUG SECTION START ---
    print(f"DEBUG: Attempting to initialize file:")
    print(f"DEBUG:   Source: {src}")
    print(f"DEBUG:   Target: {dst}")
    import sys; sys.stdout.flush()
    # --- DEBUG SECTION END ---

    # handle symlinks
    if os.path.islink(src):
        os.symlink(os.readlink(src), dst)
        continue
    
    # create an empty file with metadata
    smbd.create_file(dst, session_info, service)

2. Identifying the Problematic File

After running the manual backup again, the debug output revealed exactly where the process crashed:

DEBUG:   Source: /var/lib/samba/sysvol/domain.de/Policies/{A3848355-78C0-44C2-8206-AD1805743F9C}/User.NTACL
DEBUG:   Target: /tmp/tmpyv4ocv9h/domain.de/Policies/{A3848355-78C0-44C2-8206-AD1805743F9C}/User.NTACL
py_smbd_create_file: init_files_struct failed: NT_STATUS_INVALID_PARAMETER
ERROR(runtime): uncaught exception - (3221225485, 'An invalid parameter was passed to a service or function.')

The log shows that the backup fails specifically when it encounters a file named User.NTACL inside a Group Policy Object (GPO) folder.

3. Correlation with Active Directory

Checking the metadata of this specific GPO in the Active Directory showed the following:

• DN: CN={A3848355-78C0-44C2-8206-AD1805743F9C},CN=Policies,CN=System,DC=domain,DC=de
• Display Name: “C Windows Profile Settings”
• Creation Date: Dec 4, 2025, at 09:32 AM

The GPO was created on December 4th. The very next scheduled backup on December 5th at 3:00 AM was the first to fail:

# ls -lhart /var/univention-backup/samba/ | grep INCOMPLETE | head -n1
drwx------  2 root root 4,0K  Dec 5 03:00 INCOMPLETEsambabackupfileurc8af27

---

Root Cause

The backup failure is caused by the presence of .NTACL sidecar files within the live Sysvol directory structure.

What are .NTACL files?

Samba stores Windows-specific permissions (NT ACLs) as Extended Attributes (XATTR) on Linux filesystems (like ext4 or xfs). However, when creating a backup, Samba cannot guarantee that the target (like a .tar archive) supports these attributes. To solve this, Samba creates “sidecar” files—metadata files ending in .NTACL (e.g., GPT.INI.NTACL )—to store the security descriptors during the backup process.

The Conflict

These .NTACL files are strictly for backup and migration purposes. If they are accidentally left in or copied into the active (live) Sysvol, the samba-tool backup utility gets confused. When it tries to create a backup of a file that is itself a backup metadata file, the internal smbd function fails with NT_STATUS_INVALID_PARAMETER, crashing the entire backup routine.

---

Solution

To resolve this, you must identify and remove the .NTACL files from your Sysvol.

1. Locate the problematic files:

find /var/lib/samba/sysvol -name "*.NTACL"

2. Create a backup of the files:

find /var/lib/samba/sysvol -name "*.NTACL" | tar -czf <destination>.tar.gz -T -

3. Remove the files:

find /var/lib/samba/sysvol -name "*.NTACL" -delete

4. Test the backup:

samba-tool domain backup offline --targetdir=/var/univention-backup/samba

Once the .NTACL files are removed, the backup should return to SUCCESS status.