Australian cloud for business software — built and run in Sydney since 2003

+61 2 8282 5656
support@netleverage.com
Talk to an engineer
Talk to an engineer
NetLeverage
NetLeverage

Recovering a Samba file server: smb.conf, the TDB databases and consistent ID mapping

Technical article
Backup & Recovery

Originally published:

About this article: AI-assisted writing, reviewed against the cited sources. This is source research, not a lab validation of the procedures. Check the stated versions and your own recovery requirements before making changes.

Restoring Samba share contents can leave users with wrong permissions if configuration and identity mappings are missing. A successful file copy is only one part of server recovery.

One possible cause lies outside the file contents. Samba keeps state of its own beside the shares: its configuration, a set of small databases in a format called TDB (trivial database), a machine identity, and the table that connects Windows security identifiers (SIDs) to the numeric user and group IDs that Linux stores on every file. This guide works through that state from the Samba manuals, separates what must be kept from what can be discarded, and explains why the ID mapping choice made on the day the server was built decides how hard a rebuild will be.

It covers Samba file servers that are Active Directory domain members, and standalone servers with local accounts. Samba as a domain controller is mentioned only where the manuals draw a line.

Why it matters

Linux stores ownership and POSIX permissions on files as numbers. Windows thinks in SIDs. Samba translates between the two in both directions, and where Windows permissions are stored natively they are stored as SIDs. If the translation table is not the same after a rebuild as it was before, the numbers on disk and the SIDs on disk no longer describe the same people.

The vfs_acl_xattr manual page is explicit about the second half of this. That module keeps Windows (NT) ACLs in the security.NTACL extended attribute "in a form containing the Windows SID representing the users and groups in the ACL." It goes on: "This is different from the uid and gids stored in local filesystem ACLs and the mapping from users and groups to Windows SIDs must be consistent in order to maintain the meaning of the stored NT ACL".

So a Samba share can carry two sets of permissions for the same file: the Linux owner, group and ACL entries as numbers, and the NT ACL as SIDs. A restore that brings both back intact can still produce a server where they disagree, because the mapping that ties them together lives somewhere else.

The same manual page adds a detail that catches people checking their backups: the attribute "is not listed by the Linux command getfattr -d filename". It has to be asked for by name. A spot check that dumps attributes and sees nothing Samba-related has not proved the NT ACLs are missing.

How it works

The configuration: a file, or the registry

Most Samba servers are configured by smb.conf. The smb.conf manual describes a second option, config backend, which "controls the backend for storing the configuration. Possible values are file (the default) and registry." When registry configuration is switched on, "the configuration read so far is dropped and the global options are read from registry instead." Share definitions can also live in the registry: the registry shares option "defaults to no, but it is set to yes when config backend is set to registry."

The point for recovery is that the shares and global settings of a registry-configured server are not in the text file. A backup that copies smb.conf and nothing else may capture a few lines that switch to the registry and none of the real settings. The first recovery question is therefore which backend the server uses.

Where Samba keeps its databases

The smb.conf manual names several directories, and its descriptions sort the contents by how much they matter.

The private dir is "the directory smbd will use for storing such files as smbpasswd and secrets.tdb." On a domain member, secrets.tdb holds the machine account password; the net manual notes that a keytab "can be created only when machine password is available in secrets.tdb". On a standalone server with local accounts, the private directory also holds the password database.

The state directory is where "TDB files containing important persistent data will be stored." Since Samba 3.4.0 the configuration distinguishes persistent state from caches.

The cache directory stores "TDB files containing non-persistent data that will be kept across service restarts." It "should be placed on persistent storage, but the data can be safely deleted by an administrator."

The lock directory holds lock files, and "The files placed in this directory are not required across service restarts and can be safely placed on volatile storage (e.g. tmpfs in Linux)".

That gives a ready-made backup priority, in the manual's own words: the private directory and the state directory carry what the server needs to be itself; the cache directory can be rebuilt; runtime lock files do not need restoration after a clean service stop (our reading of the four descriptions together). Record the effective paths and build configuration, including any overlapping directory locations. Do not skip an entire physical directory merely because one option calls it a cache or lock directory.

TDB files need a consistent copy

TDB files are databases, and the usual caution applies: copying a database file while the service writes to it can give a copy that is internally inconsistent. Samba ships a tool for this. The tdbbackup manual page says "tdbbackup is a tool that may be used to backup samba .tdb files. This tool may also be used to verify the integrity of the .tdb files prior to samba startup or during normal operation. If it finds file damage and it finds a prior backup the backup file will be restored."

The same page lists the files it considers important: "secrets.tdb - usual location is in the /usr/local/samba/private directory, or on some systems in /etc/samba." and "passdb.tdb", plus "*.tdb located in the /usr/local/samba/var directory or on some systems in the /var/cache or /var/lib/samba directories." That page states it "is correct for version 3 of the Samba suite", so its location list is old; the principle, a tool that makes and checks TDB copies, is the useful part. We did not find a current samba.org copy of the page, and readers should check the tdbbackup page shipped with their own release.

Note the restore behaviour in the description: when the tool finds damage and a prior backup exists, the backup is restored. That is an automatic overwrite, and it should be understood before the tool is placed in a startup script.

ID mapping: the heart of the problem

When a domain user touches a file on a domain member, winbindd has to give that user a Linux UID, and each group a GID. The smb.conf manual groups the ID mapping backends by how they work: tdb and its relatives "create mappings of their own using internal unixid counters and store the mappings in a database." By contrast, "The rid and hash backends use a pure algorithmic calculation to determine the unixid for a SID." Then: "The autorid module is a mixture of the tdb and rid backend." And: "The ad backend uses unix ids stored in Active Directory via the standard schema extensions."

Those three families behave very differently in a rebuild.

Allocating backends (tdb). The idmap_tdb page says it "is the default backend used by winbindd for storing SID/uid/gid mapping tables." It "is an allocating backend: This means that it needs to allocate new user and group IDs in order to create new mappings." The IDs are handed out in the order identities are first seen. A rebuilt server with an empty database will hand them out again in whatever order users happen to arrive, so the same person can receive a different number. Preserving the allocating map is essential; a suitable consistent database copy or a supported complete mapping export can provide that record. The net manual describes IDMAP DUMP, which "Dumps the mappings contained in the local tdb file specified" and is "useful to dump only the mappings produced by the idmap_tdb backend", and IDMAP RESTORE, which will "Restore the mappings from the specified file or stdin." We name them only; restoring mappings changes the server's identity table and should be planned and rehearsed.

Algorithmic backends (rid). The idmap_rid page says it uses "an algorithmic mapping scheme" and "No database is required in this case as the mapping is deterministic." The UID is calculated from the last part of the SID, the relative identifier: "ID = RID - BASE_RID + LOW_RANGE_ID." The Samba domain-member guide draws the practical conclusion: "If you use the 'rid' idmap backend and the same [global] section of the smb.conf on every Unix domain member, you will get the same IDs." For recovery, this means the configuration file is the mapping. Restore the same idmap lines with the same ranges and the same numbers come back. There is one limit: the rid backend "can NOT be used as the default backend." The manual says one usually needs "a writeable default idmap range, using a backend like tdb or ldap that can create unix ids, in order to be able to map the BUILTIN sids and other domains". So even an rid-based server normally has a small allocating database for the default range, and that database still matters.

Mixed (autorid). The idmap_autorid page describes a backend "more deterministic than idmap_tdb and easier to configure than idmap_rid." It assigns a range to each domain automatically. The catch is where those assignments go: "The mappings of which domain is mapped to which range is stored in autorid.tdb, thus you should backup this database regularly." If the database is lost and domains are seen in a different order, ranges can be handed out differently. The manual's own advice to back it up is the clearest instruction in this whole area.

Directory-held IDs (ad). The idmap_ad page says it reads ID mappings "from an AD server that uses RFC2307/SFU schema extensions", and the module "is READONLY. Mappings must be provided in advance by the administrator by adding the uidNumber attributes for users and gidNumber attributes for groups in the AD." The Samba Wiki ad guide lists the recovery advantage: "IDs are only cached locally, they are stored in the AD database on DC's. This means that if the local cache becomes corrupt the file ownerships are not lost." The cost is administrative: the same page warns "You have to manualy track ID values to avoid duplicates." [sic].

Ranges must stay the same and must not overlap

Every backend is configured with a range. The Idmap config ad wiki page says "The ID ranges of the * default domain and all other domains configured in the smb.conf file must not overlap." In a rebuild, the ranges are part of what must be restored exactly: changing the low boundary changes rid calculations, while other changes can filter mappings out. With ad, the range filters directory-held IDs rather than recalculating them. The idmap_autorid page adds that the range "acts as a filter. If algorithmically determined UID or GID fall outside the range, they are ignored".

Domain controllers are different

The Samba Wiki is blunt: "ID mapping back ends are not supported in the smb.conf file on a Samba Active Directory (AD) domain controller (DC)." It continues: "Do not add any idmap config lines to a Samba Active Directory (AD) domain controller (DC) smb.conf". A recovery runbook written for file servers must not be applied to a domain controller, and copying a file server's idmap lines into a DC's configuration during a hurried rebuild is a mistake the wiki explicitly warns against.

Machine identity

A domain member has a computer account in Active Directory and a password for it in secrets.tdb. The net manual includes a command, CHANGESECRETPW, that sets that stored password from outside, and it warns: "DO NOT USE this command unless you know exactly what you are doing." It adds that it "will overwrite a legitimate machine password without warning." We mention it only as a warning: it is not a recovery shortcut. Whether to restore secrets.tdb or simply rejoin the domain is a decision for the domain administrators; a rejoin creates fresh machine credentials but does not by itself bring back an allocating ID map.

A standalone server has a different identity problem. The net manual's GETLOCALSID "Prints the SID of the specified domain, or if the parameter is omitted, the SID of the local server." Local accounts on a standalone server have SIDs built from that local SID. A rebuilt server with a new local SID would give the same user names new SIDs, and NT ACLs stored as SIDs would no longer match them. Recording the local SID before a failure is cheap; the manual's SETLOCALSID exists, but changing a server's SID is an identity change to be planned, not improvised.

A worked example

This is an illustration, not a measured case.

A firm runs one Samba server as a member of its Active Directory domain. It shares a projects folder to 120 staff. When it was built, the administrator left the default domain on the tdb backend and added an rid range for the company domain. Windows permissions are stored with vfs_acl_xattr.

The server's system disk fails. The data volume is intact on separate storage, and nightly backups of the system disk exist.

Version one. A new machine is built from scratch. Samba is installed, smb.conf is written again from memory, and the machine rejoins the domain. The administrator picks a new rid range because the old one cannot be recalled. Staff connect. Linux ownership on the data volume still carries the old numbers, which now translate to different SIDs or to none. The NT ACLs, stored as SIDs, still name the right people, but the Linux-side permissions on the same files disagree with them. With the default acl_xattr setting, Samba evaluates both system and NT ACLs; disagreement can cause unexpected access results. The ignore-system-ACL option changes that relationship and must be recorded. Fixing it means either finding the old range or reworking ownership across the volume.

Version two. In an isolated rehearsal, the administrator first inventories and validates the system backup, including the smb.conf file (and confirms it is a file configuration, not registry); the idmap lines and ranges exactly as they were; the state directory, which holds the database for the default tdb range; and a copy of the private directory, kept aside while the domain administrators decide between restoring the machine account secrets and rejoining. Regenerable caches and runtime locks are distinguished from persistent files using the effective directory layout. The expected result is unchanged rid-derived IDs and preserved allocating mappings; compare actual UID/SID results and effective permissions before allowing users to connect.

The recovery depends on the complete configuration, applicable identity databases, directory-held IDs and file metadata remaining mutually consistent.

A planning checklist

These are our recommendations, drawn from the manuals above.

  1. Record which configuration backend the server uses. If it is the registry, make sure the backup captures the registry configuration, not only smb.conf.
  2. Keep a copy of the full smb.conf, and write down every idmap line: backend, range and domain. Treat a range change as a migration, never as a rebuild detail.
  3. Read the private dir, state directory and cache directory from the running server and record them. Back up the private and state directories; the cache directory may be skipped.
  4. Plan a coherent recovery set across configuration and persistent databases. A consistent copy of one TDB does not prove several separately captured databases agree. Use a supported coordinated method or an approved service stop. Check the tdbbackup page for your release and understand its automatic restore behaviour before scheduling it.
  5. Preserve allocating maps through supported consistent database backups or a complete supported export. The autorid manual specifically requires its range-assignment database; a fresh allocation is not equivalent.
  6. Choose a mapping model for new domain members according to directory administration and cross-system requirements. rid needs stable ranges; ad needs valid, unique directory attributes. Preserve any allocating default range as well. Do not change the backend during an emergency rebuild.
  7. On standalone servers, record the local SID alongside the configuration.
  8. Keep domain controller recovery in a separate runbook. Never copy file server idmap lines into a DC.
  9. Test the restore by comparing, for a sample of users, the UID and SID before and after on a test server, and by checking NT ACLs by attribute name rather than by listing all attributes.
  10. Decide in advance, with the domain administrators, whether a rebuilt member restores its machine secrets or rejoins.

Risks and limits

Nothing described here was executed. These are source-researched planning points; validate the exact release and rehearse on an isolated server before an approved recovery.

  • Partial restores. Restoring the share data without the identity state is the failure scenario considered here. It produces a server that runs and looks normal.
  • Old secrets. A restored secrets.tdb holds a machine password that may since have changed in Active Directory. Whether it still works depends on how long ago the copy was taken and the domain's password rules; we did not research this behaviour, and it is a point for the domain administrators.
  • Automatic tool behaviour. tdbbackup can restore a prior backup over a damaged file by itself. Understand that before placing it in automation.
  • Commands named, not given. IDMAP RESTORE, CHANGESECRETPW and SETLOCALSID change a server's identity. This guide names them so the manuals can be read; it gives no procedures.
  • Version drift. The tdbbackup page read is for an old Samba version, and Samba directory defaults differ between builds and distributions.
  • Scope. We did not research the ldap, nss or hash backends in depth, clustered Samba (CTDB), or vendor NAS products that embed Samba and manage these files for you.

Sources

This article was originally published on .