krb5.conf auth_to_local rules

[Jen Selby]

I am attempting to document the tag auth_to_local in the realms
section of krb5.conf.

The DB:<filename> and DEFAULT values for this tag are fairly
self-explanatory, but I'd like to provide more of an explanation for
the RULE:<exp> value.

As far as I can tell from the code, the syntax for exp is
[n:$d..](s/regexp/substitute/g), where n is the number of components
that the target principal[s] will have, and each $d specifies the
individual components, so that you can choose the order that they will
be in in the string that will be processed by the substitution
expression.  The trailing g in the is option and will make the
substitution global for the string.

So if I have
[realms]
	MYREALM = {
		auth_to_local = {
			RULE:[2:$1](s/lucifer/lucifer/)
			RULE:[2:$2](s/admin/root/)
			DEFAULT
		}
	}

Then lucifer/admin at MYREALM would be translated to the local user
lucifer and any other principal with an admin instance will be
translated to root.  Every principal with a null instance will be
translated to their principal name (without the realm), and everyone
else will produce an error.

Has anyone who has actually used this tell me if my interpretation is
correct (and maybe also send me examples of your krb5.conf)?

Thanks.

Jen