[Samba] Man page for idmap_rid

[Michael Adam]

On 2016-08-08 at 16:31 -0300, francis picabia wrote:
> I'm reading the man page for idmap_rid over and over and I can't understand
> it.  I think it needs a rewrite so a normal user can understand.  Using a
> practical example.

I admit it is a little terse.
But in principle, assuming a little bit of
general knowledge about how idmap backends are configured
(see man smb.conf), it's all there.

Before proposing a patch that will elaborate the manpage
a bit, let me explain here:

> Step 1: determine the highest UID in use for your /etc/passwd file
> (can we assume everyone has a passwd file?)
> Step 2: I don't know...
> 
> Optionally at this point, document how to plug that into the formula
> 
> RID = ID + BASE_RID - LOW_RANGE_ID
> 
> and then show how we set the lines:
> 
> range = low - high

This 'low' here is the LOW_RANGE_ID referenced above
in the formula. More concretely, this config would be

   idmap config DOMAIN : backend = rid
   idmap config DOMAIN : range = low-high

> base_rid = INTEGER

My suggestion: Forget about the 'base_rid' value. This optional parameter
is only needed for corner cases, where you are very limited in the amount
of unix ids available. It allows you to filter out the lower part of the
rids in your domain. I have never seen it used. (i.e. use the default
value of 0.)

> The man page examples do not line up with any numbers practical outside of
> smb.conf

So in order to decribe how the rid module works for a given
config, you need to describe how unix-id-->sid and sid-->unix-id
mappings are calculated. The manpage offers this:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
THE MAPPING FORMULAS
  The Unix ID for a RID is calculated this way:

     ID = RID - BASE_RID + LOW_RANGE_ID.

  Correspondingly, the formula for calculating the RID
  for a given Unix ID is this:

     RID = ID + BASE_RID - LOW_RANGE_ID.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

As said above, here LOW_RANGE_ID is the id that is the lower
number of the configured range. Now for the sake of simplicity,
say that we did not configure the base rid, so BASE_RID is 0 in
the above formulas and they simplify to:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    ID  = RID + LOW_RANGE_ID
    RID = ID  - LOW_RANGE_ID
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

More concretely, assume that you have a domain MYDOM
and a config

   idmap config MYDOM : backend = rid
   idmap config MYDOM : range   = 100000-200000

Now calculate a few examples:

- The administrator of MYDOM has rid=500 (the admin
  of each domain has). So it's unix ID would be

  500 + 100000 = 100500

- The Domain Users group has rid 513.
  So the associated unix group id would be

  513 + 100000 = 100513

- A Unix group of GID = 100512 would
  map to the SID with the rid of

  100512 - 100000 = 512

  i.e. the domain admins group.

- A unix user of UID = 123456 would be associated
  to a sid with the rid of

  123456 - 10000 = 23456

- A unix ID of 200001 would be bigger than
  the high id of the range and hence NOT be
  treated by this idmap module.

- A SID with a rid of 100001 would be calculated
  to yield a unix id of

  100001 + 100000 = 200001

  but this is bigger than the high upper limit of
  the configured range, hence the sid would be
  'filtered', i.e. this object would not be mapped.

Do these examples make it more clear?

The low id of the range determines where the unix IDs of
your domain will start, and the high id of the range
determines how big the rids can get. More concretely,
the largest mapped rid would be

  high id - low id


> Say my UID on the Linux side would never exceed 70000.  How do
> I configure range and base_rid?

The only important thing here is that the low id in the range is
LARGER than the largest unix id used otherwise in your system.
(That does not only mean passwd or group file, but also other
possible nsswitch sources like ldap or nis...)
So if you know you won't have unix user or group ids above 10000,
then you could start your idmap rid range at 10001; this would
be the lowes possible start of a range. But you could as
well start it at 20000 or 100000 or 1000000. And so on.

Also note that all other idmap ranges you configure must
be disjoint from this idmap range. More generally, all
configured idmap ranges must be mutually disjoint.

See the example in the manpage for complete example
idmap configs.

Hope this helps at least a bit..

Michael

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 181 bytes
Desc: not available
URL: <http://lists.samba.org/pipermail/samba/attachments/20160808/ee68930b/signature.sig>