Active Directory ID Mapping
This page helps you choose the ID Mapper mode before you join a QuantaStor system to an Active Directory domain. It explains what each mode does, the Unix user and group ID ranges each one produces, and why you need to settle the choice before any data is written to a Storage Pool.
Short answer: use Auto Relative ID (autorid), the default. Choose AD Managed Unix UID/GIDs (RFC2307) only if Linux or NFS clients outside QuantaStor need to see the same UIDs and GIDs as QuantaStor, and you are prepared to maintain Unix attributes on every AD user and group.
| Section | Purpose |
|---|---|
| Why the mode matters | What ID mapping does and why it has to stay fixed |
| The modes at a glance | All five modes side by side |
| Auto Relative ID (autorid) | The default, and its ID ranges |
| AD Managed Unix UID/GIDs (RFC2307) | When to use it, and the AD attributes it needs |
| Why tdb and rid are not recommended | How they give different UIDs on different nodes |
| Custom ranges | The range fields on the Advanced Settings tab |
| Decide before data lands on the pool | Why the choice is hard to undo, and a checklist |
Why the mode matters
Windows identifies users and groups by SID. The file systems under a Storage Pool record ownership and ACL entries as numeric Unix user and group IDs. Every time an AD account touches a file, QuantaStor has to translate the SID into a UID or GID, and the ID Mapper mode decides how.
The numbers the mode produces are written into every file's ownership and ACLs. The mode therefore has to give the same answer on every node that can serve the pool, and it has to give the same answer for the life of the data. If the mapping changes after files exist, the IDs stored on disk no longer belong to the accounts that own them, and users lose access to their own files. See Decide before data lands on the pool.
Where you set it
The ID Mapper field is on the AD Account Settings tab of the Join AD Domain dialog, in the Active Directory Settings box. The ID ranges are on the Advanced Settings tab under User/Group Range Settings. They default to Auto, which applies the ranges in the tables below.
The dialog applies the same settings to every Storage System selected on its first page, and it selects all eligible systems by default. For an HA pair, join both nodes in the same pass so they get identical settings.
From the CLI, the mode is the --idmap-mode argument of qs share-join-domain. It accepts autorid (the default), ad-rfc2307, rid, tdb and ad.
The modes at a glance
| ID Mapper (dialog label) | CLI value | Where the joined domain's IDs come from | Recommended for |
|---|---|---|---|
| Auto Relative ID (autorid) | autorid |
Calculated from each account's RID | Almost every deployment. The default. |
| AD Managed Unix UID/GIDs (RFC2307) | ad-rfc2307 |
Read from uidNumber and gidNumber in AD |
Sites where UIDs must match on non-QuantaStor Linux or NFS clients |
| Trivial DB (tdb - not recommended) | tdb |
Handed out in the order accounts are first seen, per node | Not recommended |
| Relative ID (rid - not recommended) | rid |
Calculated from the RID, with other accounts handed out in first-seen order | Not recommended |
| (not in the dialog) | ad |
Read from the older Services for UNIX (SFU) attributes in AD | Legacy domains that still carry SFU attributes; CLI only |
Two of these are AD schema variants and are separate modes. ad-rfc2307 reads the RFC2307 attributes that current Windows Server versions use. ad reads the SFU schema from the Windows Services for UNIX era. The dialog offers only RFC2307; SFU is reachable only with --idmap-mode=ad.
Auto Relative ID (autorid)
autorid is the default and the right choice unless you have a specific reason to pick RFC2307.
autorid divides its ID range into blocks of Domain Range Size IDs and gives each domain it meets its own block. Inside a block, an account's ID is the start of the block plus the account's RID, the last component of its SID. The ID is calculated, not handed out, so the same user gets the same number every time the system looks it up.
autorid is also the only mode that handles every account itself. BUILTIN groups, local accounts and accounts from trusted domains each get a block from the same range, so none of them falls through to a first-seen allocator. That is the main reason it is the default: the other modes all leave a TDB catch-all behind them (see Why tdb and rid are not recommended).
What it costs you: the UIDs are QuantaStor's own. A Linux or NFS client that resolves the same AD users through its own configuration will see different numbers unless it also runs autorid with the same range and range size.
| Setting | Default |
|---|---|
| ID range | 1000000 - 19999999 |
| Domain Range Size | 1000000 (19 blocks in the default range) |
| Fallback range for BUILTIN, local and trusted-domain accounts | none; they get blocks from the range above |
AD Managed Unix UID/GIDs (RFC2307)
In RFC2307 mode QuantaStor does not calculate IDs at all. It reads each user's uidNumber and gidNumber and each group's gidNumber from Active Directory, and uses the user's gidNumber as the primary group. Every system that reads the same attributes, QuantaStor or not, sees the same IDs.
That is the only reason to choose it: pick RFC2307 if you need UIDs to match on Linux servers or NFS clients that are not QuantaStor, for example when the same files are reached over both SMB and NFS and the NFS clients take their IDs from AD. If every client is a Windows SMB client, RFC2307 buys you nothing that autorid does not, and it adds work that never ends.
What the extra configuration means
RFC2307 depends on attributes that AD does not fill in for you:
- Every user that needs access must have a
uidNumberand agidNumber. - Every group used in a share permission or ACL must have a
gidNumber. - You allocate those numbers yourself, keep them unique, and set them on every new user and group for as long as the system is in service.
An account without these attributes is not mapped at all. It gets no UID, so it gets no access to the shares, and nothing on the Windows side tells the user why. If you try to make such an account a share owner, QuantaStor reports that the account has no Unix attributes rather than that it does not exist.
Microsoft removed the UNIX Attributes tab from Active Directory Users and Computers in Windows Server 2016. Set the attributes on the Attribute Editor tab instead (enable View → Advanced Features to see it), or with PowerShell:
Set-ADUser jsmith -Replace @{uidNumber=1000101; gidNumber=1000100}
Set-ADGroup "Engineering" -Replace @{gidNumber=1000100}
The range has to cover your numbers
In RFC2307 mode the ID range is a filter: QuantaStor accepts an ID read from AD only if it falls inside the range, and ignores the account otherwise. With Auto the range is 1000000 - 1500000. Either number your users and groups inside that range, or choose Custom on the Advanced Settings page and set Min User/Group ID and Max User/Group ID to cover the numbers already in your directory.
| Setting | Default |
|---|---|
Accepted range for AD uidNumber / gidNumber |
1000000 - 1500000 |
| Fallback range (TDB) for BUILTIN, local and trusted-domain accounts | 500000 - 4999999 |
Keep the two ranges apart. An AD-assigned number that falls inside the fallback range can collide with an ID that the fallback handed to a different account.
Why tdb and rid are not recommended
The dialog labels both not recommended. The reason is the same for both.
Trivial DB (tdb) hands out IDs from 500000 - 4999999 in the order accounts are first seen, and records the result in a local database on each node. Two nodes that see users in a different order give the same user different UIDs. In an HA pair, a file created on one node can belong to someone else after the pool fails over to the other.
Relative ID (rid) calculates IDs for the joined domain the way autorid does: UID = 5000000 + RID, over the range 5000000 - 19999999. Those numbers are consistent between nodes. Everything else is not. BUILTIN groups, local accounts and accounts from trusted domains fall through to a TDB catch-all and are handed out in first-seen order, exactly as in tdb mode.
RFC2307 and the CLI-only ad mode have the same TDB catch-all behind them, but there it covers only accounts outside the joined domain.
Allow Trusted Domain is ticked by default in the dialog, so in rid mode accounts from trusted domains reach the first-seen allocator from the day you join. autorid avoids the problem because it gives trusted domains their own calculated blocks.
| Mode | Joined domain | BUILTIN, local and trusted-domain accounts |
|---|---|---|
| tdb | 500000 - 4999999, first-seen order | same range, first-seen order |
| rid | 5000000 - 19999999, 5000000 + RID | 500000 - 4999999, first-seen order |
ad (SFU, CLI only) |
SFU attributes from AD, accepted within 5000000 - 19999999 | 500000 - 4999999, first-seen order |
Custom ranges
Leave User/Group Range Settings on Auto unless you need a specific range. Custom enables the fields that apply to the selected mode and fills them with suggested values:
| Field | Applies to | Purpose |
|---|---|---|
| Joined Domain User/Group Range: Min User/Group ID, Max User/Group ID | every mode | The range for accounts from the joined domain. For autorid this is the whole range blocks are cut from; for RFC2307 it bounds which AD values are accepted; for tdb it is the single range everything is allocated from. |
| Domain Range Size | autorid only | The number of IDs in each domain's block. |
| Local User/Group Range: Min User/Group ID, Max User/Group ID | rid and RFC2307 | The shared TDB fallback range for BUILTIN, local and trusted-domain accounts. It is not a per-domain setting. |
The dialog accepts IDs from 1000 to 4294967294. The same values are available from the CLI as --min-uid, --max-uid, --range-size, --min-def-uid and --max-def-uid.
SSSD+Winbind join mode
The AD Join Mode field next to ID Mapper defaults to Winbind, and everything above describes that mode. If you choose SSSD+Winbind, SSSD supplies the IDs for the joined domain over 200000 - 2147483647, with a TDB fallback over 10000 - 199999. With RFC2307 selected, SSSD reads the uidNumber and gidNumber attributes from AD; with any other selection it uses its own automatic ID mapping instead.
Decide before data lands on the pool
Choose the mode, and the ranges, before you create shares and copy data onto the pool.
The mode is set when the system joins the domain, and the only way to change it is to leave the domain with Active Directory Leave and join again. That changes the configuration only. It does not touch the files: every file keeps the numeric owner, group and ACL entries it was written with. After a change, those numbers either belong to nobody or belong to a different account, and access breaks across the whole pool. Correcting it means re-owning and re-permissioning the data.
Before you join, check:
- Mode. autorid, unless non-QuantaStor Linux or NFS clients must see the same UIDs, in which case RFC2307.
- Every node. Join both nodes of an HA pair, and every system that can import the pool, with the same mode and ranges.
- RFC2307 attributes. Every user has
uidNumberandgidNumber, every group hasgidNumber, and all of them fall inside the accepted range. - Trusted domains. If you leave Allow Trusted Domain ticked, use autorid so trusted-domain accounts get calculated IDs.
Related pages
- Join AD Domain -- the join dialog, field by field
- Active Directory Configuration
- Active Directory Leave
- AD User & Group Information Caching for Large Environments
- Network Shares
- NFS Configuration
- Setup Guide for Clustered HA Storage Pools
- qs share-join-domain
Verified against QuantaStor 6.9.0.