idmap(1M) observability [PSARC/2008/167 FastTrack timeout 03/12/2008]

[Nicolas Williams]

Template Version: @(#)sac_nextcase 1.64 07/13/07 SMI
This information is Copyright 2008 Sun Microsystems
1. Introduction
    1.1. Project/Component Working Name:
	 idmap(1M) observability
    1.2. Name of Document Author/Supplier:
	 Author:  Nicolas Williams
    1.3  Date of This Document:
	03 March, 2008
4. Technical Description

I'm sponsoring this case for Julian Pullen.  I've set the timer to
expire on Wednesday, March 12th, 2008.

The requested release binding is micro/patch (note: the base ARC case
has minor release binding, so "micro/patch" here is not meaningfully
different from minor).

BACKGROUND
----------

PSARC/2006/315 introduced a facility for mapping between Windows and
Solaris user/group identities.

idmap(1M) is the primary user interface for the Solaris ID mapping
facility.  It allows the administrator to specify rules for ID mapping,
as well as to observe what identities have been mapped, and to request
mappings for specific IDs.

idmap now supports the following mapping methods
	1) Hardcoded mappings for _some_ Well-Known SIDs
	2) Directory-based name mapping using AD only (soon also using
	   native LDAP, and a mixed mode; see PSARC/2007/663)
	3) Name-based rule mapping
	4) Ephemeral mapping
	5) Local SID mapping

PROBLEM
-------

The idmap(1M) utility provides no information as to how any one mapping
was performed, nor what conditions led to failure to produce a requested
mapping.

SOLUTION
--------

This case enhances idmap to enable it to display how the the identifiers
were mapped.  The "idmap show" and "idmap dump" commands will be
extended with a -v flag to display this information.  The "idmap show"
command will also display whether the ID mapping was just generated as a
result of the command or whether it had been cached.

The information displayed will include the type of mapping.  For
directory-based name mapping it will include if the Directory is AD or
Native LDAP, the Distinguished name of the entry and the mapping
attribute and value.  For name-based rule mapping it will include the
matching rule.

Man page diffs will be added to the case directory.

INTERFACE STABILITY
-------------------

The new -v option to 'idmap dump' and 'idmap show' will be Committed.

The output of 'idmap dump' and 'idmap show' is hereby declared to be Not
an Interface.  A future case may introduce stable output formats
suitable for scripting.

PHASED DELIVERY
---------------

We may deliver this case in two phases: one that adds observability for
success cases, and one that adds observability for failure cases.

We expect this provision to be non-controversial given the Not-an-
Interface nature of idmap(1M)'s output at this time.

OUTPUT
------

[Remember, idmap(1M) output remains Not an Interface, thus we reserve
the right to change the output formats shown below.]

Success cases:

% idmap show ...
<mapping>
% idmap show -v ...
<mapping>
New: yes | cached
Method: <method-name>
[DN:    <LDAP DN>]
[Attribute: <LDAP attribute name> = <value>]
[Rule: <rule>]

Where:

 - <mapping> is the output that idmap produces today.

 - <method-name> is one of: AD Directory, Native LDAP Directory, Name
   Rule, Ephemeral, Local SID, Well-Known mapping.

 - <LDAP DN> is the DN of an AD or native LDAP object (if ds-based name
   mapping was used).

 - <LDAP attribute name> and <value> are the name and value of the
   attribute used for directory-based name mapping (if ds-based name
   mapping was used).

 - <rule> is the matching name-based rule, if any, using the same format
   as used by "idmap list" today.

Output for "idmap dump" will be the same as "show -v" but it will not
contain "New: ..." (all dumped entries must be in the cache).


Error cases:

% idmap show ...
[<mapping>]
Failed Method: <method-name>
Error: <error message>



6. Resources and Schedule
    6.4. Steering Committee requested information
   	6.4.1. Consolidation C-team Name:
		ON
    6.5. ARC review type: FastTrack
    6.6. ARC Exposure: open