kadmin: Add add_alias, del_alias

kadmin/kadmin.1

@@ -140,6 +140,37 @@ The only policy supported by Heimdal servers is
 .Ql default .
 .Ed
 .Pp
+.Nm add_alias
+.Ar principal
+.Ar alias...
+.Bd -ragged -offset indent
+Adds one or more aliases to the given principal.
+.Pp
+When a client requests a service ticket for a service principal
+name that is an alias of a principal in a different realm, the
+TGS will return a referral to that realm.
+This compares favorably to using
+.Ar [domain_realm]
+entries in the KDC's
+.Ar krb5.conf ,
+but may be managed via the
+.Nm kadmin
+command and its
+.Nm add_alias
+and
+.Nm del_alias
+sub-commands rather than having to edit the KDC's configuration
+file and having to restart the KDC.
+.Pp
+However, there is currently no way to alias namespaces via HDB
+entry aliases.
+To issue referrals for entire namespaces use the
+.Ar [domain_realm]
+section of the KDC's
+.Ar krb5.conf
+file.
+.Ed
+.Pp
 .Nm add_namespace
 .Ar Fl Fl key-rotation-epoch= Ns Ar time
 .Ar Fl Fl key-rotation-period= Ns Ar time
@@ -202,6 +233,19 @@ supported.
 .Ar principal...
 .Bd -ragged -offset indent
 Removes a principal.
+It is an error to delete an alias.
+To remove a principal's alias or aliases, use the
+.Nm del_alias
+command.
+To remove a principal given an alias, first
+.Nm get
+the principal to get its canonical name and then delete that.
+.Ed
+.Pp
+.Nm del_alias
+.Ar alias...
+.Bd -ragged -offset indent
+Deletes the given aliases, but not their canonical principals.
 .Ed
 .Pp
 .Nm del_enctype
@@ -320,6 +364,7 @@ and
 .Op Fl Fl pw-expiration-time= Ns Ar time
 .Op Fl Fl kvno= Ns Ar number
 .Op Fl Fl policy= Ns Ar policy-name
+.Op Fl Fl alias= Ns Ar alias-name
 .Op Fl C Ar path | Fl Fl krb5-config-file= Ns Ar path
 .Ar principal...
 .Bd -ragged -offset indent
@@ -327,6 +372,23 @@ Modifies certain attributes of a principal. If run without command
 line options, you will be prompted. With command line options, it will
 only change the ones specified.
 .Pp
+The
+.Fl Fl alias= Ns Ar alias-name
+option may be given multiple times, which will set the complete
+list of aliases for the principal.
+Use the
+.Nm add_alias
+command instead to add an alias without having to list all
+existing aliases to keep.
+.Pp
+The
+.Fl Fl alias=
+option without a value allows the user to set an empty list of
+aliases.
+Use the
+.Nm del_alias
+command to delete one or more aliases.
+.Pp
 The only policy supported by Heimdal is
 .Ql default .
 .Pp