This is krb5-admin.info, produced by makeinfo version 4.5 from
admin.texinfo.

Copyright (C) 1985-2010 by the Massachusetts Institute of Technology.
INFO-DIR-SECTION Kerberos
START-INFO-DIR-ENTRY
* krb5-admin: (krb5-admin).             Kerberos V5 Administrator's Guide
END-INFO-DIR-ENTRY


File: krb5-admin.info,  Node: Retrieving a List of Principals,  Prev: Attributes,  Up: Retrieving Information About a Principal

Retrieving a List of Principals
...............................

To generate a listing of principals, use the `kadmin' `list_principals'
command, which requires the "list" privilege.  The syntax is:

     list_principals [expression]

where expression is a shell-style glob expression that can contain the
characters `*', `?', `[', and `]'.  All policy names matching the
expression are displayed.  The `list_principals' command has the
aliases `listprincs', `get_principals', and `getprincs'.  For example:

     kadmin: listprincs test*
     test3@ATHENA.MIT.EDU
     test2@ATHENA.MIT.EDU
     test1@ATHENA.MIT.EDU
     testuser@ATHENA.MIT.EDU
     kadmin:

If no expression is provided, all principals are printed.


File: krb5-admin.info,  Node: Privileges,  Next: Adding or Modifying Principals,  Prev: Retrieving Information About a Principal,  Up: Principals

Privileges
----------

Administrative privileges for the Kerberos database are stored in the
file `kadm5.acl'.

The format of the file is:

     Kerberos_principal      permissions     [target_principal]	[restrictions]

The Kerberos principal (and optional target principal) can include the
"*" wildcard, so if you want any principal with the instance "admin" to
have full permissions on the database, you could use the principal
"`*/admin@REALM'" where "REALM" is your Kerberos realm.
`target_principal' can also include backreferences to
`Kerberos_principal', in which "*number" matches the component number
in the `Kerberos_principal'.

Note:  a common use of an admin instance is so you can grant separate
permissions (such as administrator access to the Kerberos database) to
a separate Kerberos principal.  For example, the user `joeadmin' might
have a principal for his administrative use, called `joeadmin/admin'.
This way, `joeadmin' would obtain `joeadmin/admin' tickets only when he
actually needs to use those permissions.

The permissions are represented by single letters; UPPER-CASE letters
represent negative permissions.  The permissions are:

a
     allows the addition of principals or policies in the database.

A
     disallows the addition of principals or policies in the database.

d
     allows the deletion of principals or policies in the database.

D
     disallows the deletion of principals or policies in the database.

m
     allows the modification of principals or policies in the database.

M
     disallows the modification of principals or policies in the
     database.

c
     allows the changing of passwords for principals in the database.

C
     disallows the changing of passwords for principals in the database.

i
     allows inquiries to the database.

I
     disallows inquiries to the database.

l
     allows the listing of principals or policies in the database.

L
     disallows the listing of principals or policies in the database.

s
     allows the explicit setting of the key for a principal

S
     disallows the explicit setting of the key for a principal

*
     All privileges (admcil).

x
     All privileges (admcil); identical to "*".

The restrictions are a string of flags.  Allowed restrictions are:

[+ -]flagname
     flag is forced to indicated value.  The permissible flags are the
     same as the `+' and `-' flags for the `kadmin addprinc' and
     `modprinc' commands.

-clearpolicy
     policy is forced to clear

-policy pol
     policy is forced to be pol

expire time
pwexpire time
maxlife time
maxrenewlife time
     associated value will be forced to MIN(time, requested value)

The above flags act as restrictions on any add or modify operation
which is allowed due to that ACL line.

Here is an example of a `kadm5.acl' file.  Note that order is
important; permissions are determined by the first matching entry.

     */admin@ATHENA.MIT.EDU  *
     joeadmin@ATHENA.MIT.EDU  ADMCIL
     joeadmin/*@ATHENA.MIT.EDU il */root@ATHENA.MIT.EDU
     *@ATHENA.MIT.EDU cil *1/admin@ATHENA.MIT.EDU
     */*@ATHENA.MIT.EDU  i
     */admin@EXAMPLE.COM * -maxlife 9h -postdateable

In the above file, any principal in the ATHENA.MIT.EDU realm with an
`admin' instance has all administrative privileges.  The user `joeadmin'
has all permissions with his `admin' instance,
`joeadmin/admin@ATHENA.MIT.EDU' (matches the first line).  He has no
permissions at all with his `null' instance, `joeadmin@ATHENA.MIT.EDU'
(matches the second line).  His root instance has inquire and list
permissions with any other principal that has the instance `root'.  Any
principal in ATHENA.MIT.EDU can inquire, list, or change the password of
their `admin' instance, but not any other `admin' instance.  Any
principal in the realm `ATHENA.MIT.EDU' (except for
`joeadmin@ATHENA.MIT.EDU', as mentioned above) has inquire privileges.
Finally, any principal with an admin instance in EXAMPLE.COM has all
permissions, but any principal that they create or modify will not be
able to get postdateable tickets or tickets with a life of longer than
9 hours.


File: krb5-admin.info,  Node: Adding or Modifying Principals,  Next: Deleting Principals,  Prev: Privileges,  Up: Principals

Adding or Modifying Principals
------------------------------

To add a principal to the database, use the kadmin `add_principal'
command, which requires the "add" administrative privilege.  This
function creates the new principal, prompting twice for a password, and,
if neither the -policy nor -clearpolicy options are specified and the
policy "default" exists, assigns it that policy.  The syntax is:

     kadmin: add_principal [options] principal

To modify attributes of a principal, use the kadmin `modify_principal'
command, which requires the "modify" administrative privilege.  The
syntax is:

     kadmin: modify_principal [options] principal

`add_principal' has the aliases `addprinc' and `ank'(1).
`modify_principal' has the alias `modprinc'.

The `add_principal' and `modify_principal' commands take the following
switches:

-x db_princ_args
     Denotes the database specific options.

     The options for LDAP database are:
    -x dn=<dn>
          Specifies the  LDAP object that will contain the Kerberos
          principal being created.

    -x linkdn=<dn>
          Specifies the LDAP object  to which the newly created
          Kerberos principal object will point to.

    -x containerdn=<container_dn>
          Specifies the  container object under which the Kerberos
          principal is to be created.

    -x tktpolicy=<policy>
          Associates a ticket policy to the Kerberos principal.
          Specifying an empty string value clears the ticket policy
          associated with the principal.

          Note:

          * dn and containerdn options are not valid while modifying
          the principal.

          * containerdn and linkdn options cannot be specified with dn
          option.

          *  If dn or containerdn options are not specified while
          adding the principal, the principals are created    under the
          prinicipal container configured in the realm or the realm
          container.  * dn and containerdn should be within the
          subtrees or principal container configured in the realm.

-expire date
     Sets the expiration date of the principal to date.

-pwexpire date
     Sets the expiration date of the password to date.

-maxlife maxlife
     Sets the maximum ticket life of the principal to maxlife.

-maxrenewlife maxrenewlife
     Sets the maximum renewable life of tickets for the principal to
     maxrenewlife.

-kvno number
     Explicity sets the key version number to number.  MIT does not
     recommend doing this unless there is a specific reason.

-policy policy
     Sets the policy used by this principal.  (*Note Policies::.)  With
     `modify_principal', the current policy assigned to the principal is
     set or changed.  With `add_principal', if this option is not
     supplied, the -clearpolicy is not specified, and the policy
     "default" exists, that policy is assigned.  If a principal is
     created with no policy, `kadmin' will print a warning message.

-clearpolicy
     For `modify_principal', removes the current policy from a
     principal.  For `add_principal', suppresses the automatic
     assignment of the policy "default".

{-|+}allow_postdated
     The "-allow_postdated" option prohibits this principal from
     obtaining postdated tickets.  "+allow_postdated" clears this flag.
     In effect, "-allow_postdated" sets the
     KRB5_KDB_DISALLOW_POSTDATED flag on the principal in the database.

{-|+}allow_forwardable
     The "-allow_forwardable" option prohibits this principal from
     obtaining forwardable tickets.  "+allow_forwardable" clears this
     flag.  In effect, "-allow_forwardable" sets the
     KRB5_KDB_DISALLOW_FORWARDABLE flag on the principal in the
     database.

{-|+}allow_renewable
     The "-allow_renewable" option prohibits this principal from
     obtaining renewable tickets.  "+allow_renewable" clears this flag.
     In effect, "-allow_renewable" sets the
     KRB5_KDB_DISALLOW_RENEWABLE flag on the principal in the database.

{-|+}allow_proxiable
     The "-allow_proxiable" option prohibits this principal from
     obtaining proxiable tickets.  "+allow_proxiable" clears this flag.
     In effect, "-allow_proxiable" sets the
     KRB5_KDB_DISALLOW_PROXIABLE flag. on the principal in the database.

{-|+}allow_dup_skey
     The "-allow_dup_skey" option disables user-to-user authentication
     for this principal by prohibiting this principal from obtaining a
     session key for another user.  "+allow_dup_skey" clears this flag.
     In effect, "-allow_dup_skey" sets the
     KRB5_KDB_DISALLOW_DUP_SKEY flag on the principal in the database.

{-|+}requires_preauth
     The "+requires_preauth" option requires this principal to
     preauthenticate before being allowed to kinit.  -requires_preauth
     clears this flag.  In effect, +requires_preauth sets the
     KRB5_KDB_REQUIRES_PRE_AUTH flag on the principal in the database.

{-|+}requires_hwauth
     The "+requires_hwauth" flag requires the principal to
     preauthenticate using a hardware device before being allowed to
     kinit.  "-requires_hwauth" clears this flag.  In effect,
     "+requires_hwauth" sets the KRB5_KDB_REQUIRES_HW_AUTH flag on the
     principal in the database.

{-|+}allow_svr
     The "-allow_svr" flag prohibits the issuance of service tickets for
     this principal.  "+allow_svr" clears this flag.  In effect,
     "-allow_svr" sets the
     KRB5_KDB_DISALLOW_SVR flag on the principal in the database.

{-|+}allow_tgs_req
     The "-allow_tgs_req" option specifies that a Ticket-Granting
     Service (TGS) request for a service ticket for this principal is
     not permitted.  You will probably never need to use this option.
     "+allow_tgs_req" clears this flag.  The default is
     "+allow_tgs_req".  In effect, "-allow_tgs_req" sets the
     KRB5_KDB_DISALLOW_TGT_BASED flag on the principal in the database.

{-|+}allow_tix
     The "-allow_tix" option forbids the issuance of any tickets for
     this principal.  "+allow_tix" clears this flag.  The default is
     "+allow_tix".  In effect, "-allow_tix" sets the
     KRB5_KDB_DISALLOW_ALL_TIX flag on the principal in the database.

{-|+}needchange
     The "+needchange" option sets a flag in attributes field to force a
     password change; "-needchange" clears it.  The default is
     "-needchange".  In effect, "+needchange" sets the
     KRB5_KDB_REQUIRES_PWCHANGE flag on the principal in the database.

{-|+}password_changing_service
     The "+password_changing_service" option sets a flag in the
     attributes field marking this principal as a password change
     service. (Again, you will probably never need to use this option.)
     "-password_changing_service" clears the flag.  The default is
     "-password_changing_service".  In effect, the
     "+password_changing_service" option sets the
     KRB5_KDB_PWCHANGE_SERVICE flag on the principal in the database.

{-|+}ok_as_delegate
     The "+ok_as_delegate" option sets a flag in tickets issued for the
     service principal.  Some client programs may recognize this flag as
     indicating that it is okay to delegate credentials to the service.
     If ok_as_delegate is set on a cross-realm TGT, it indicates that
     the foreign realm's ok_as_delegate flags should be honored by
     clients in the local realm.  The default is "-ok_as_delegate".

-randkey
     Sets the key for the principal to a random value (`add_principal'
     only).  MIT recommends using this option for host keys.

-pw password
     Sets the key of the principal to the specified string and does not
     prompt for a password (`add_principal' only).  MIT does not
     recommend using this option.

-e enc:salt...
     Uses the specified list of enctype-salttype pairs for setting the
     key of the principal.  The quotes are necessary if there are
     multiple enctype-salttype pairs.  This will not function against
     kadmin daemons earlier than krb5-1.2.  See *Note Supported
     Encryption Types:: and *Note Salts:: for available types.

If you want to just use the default values, all you need to do is:

     kadmin: addprinc jennifer
     WARNING: no policy specified for "jennifer@ATHENA.MIT.EDU";
     defaulting to no policy.
     Enter password for principal jennifer@ATHENA.MIT.EDU:  <= Type the password.
     Re-enter password for principal jennifer@ATHENA.MIT.EDU:  <=Type it again.
     Principal "jennifer@ATHENA.MIT.EDU" created.
     kadmin:

If you want to create a principal which is contained by a  LDAP object,
all you need to do is:

     kadmin: addprinc -x dn=cn=jennifer,dc=example,dc=com jennifer
     WARNING: no policy specified for "jennifer@ATHENA.MIT.EDU";
     defaulting to no policy.
     Enter password for principal jennifer@ATHENA.MIT.EDU:  <= Type the password.
     Re-enter password for principal jennifer@ATHENA.MIT.EDU:  <=Type it again.
     Principal "jennifer@ATHENA.MIT.EDU" created.
     kadmin:

If you want to create a principal under a specific LDAP container and
link to an existing LDAP object, all you need to do is:

     kadmin: addprinc -x containerdn=dc=example,dc=com -x linkdn=cn=david,dc=example,dc=com david
     WARNING: no policy specified for "david@ATHENA.MIT.EDU";
     defaulting to no policy.
     Enter password for principal david@ATHENA.MIT.EDU:  <= Type the password.
     Re-enter password for principal david@ATHENA.MIT.EDU:  <=Type it again.
     Principal "david@ATHENA.MIT.EDU" created.
     kadmin:

If you want to associate a ticket policy to a principal, all you need
to do is:

     kadmin: modprinc -x tktpolicy=userpolicy david
     Principal "david@ATHENA.MIT.EDU" modified.
     kadmin:

If, on the other hand, you want to set up an account that expires on
January 1, 2000, that uses a policy called "stduser", with a temporary
password (which you want the user to change immediately), you would type
the following.  (Note:  each line beginning with => is a continuation
of the previous line.)


     kadmin: addprinc david -expire "1/1/2000 12:01am EST" -policy stduser
     =>  +needchange
     Enter password for principal david@ATHENA.MIT.EDU:  <= Type the password.
     Re-enter password for principal
     david@ATHENA.MIT.EDU:  <= Type it again.
     Principal "david@ATHENA.MIT.EDU" created.
     kadmin:

If you will need cross-realm authentication, you need to add principals
for the other realm's TGT to each realm.  For example, if you need to
do cross-realm authentication between the realms ATHENA.MIT.EDU and
EXAMPLE.COM, you would need to add the principals
`krbtgt/EXAMPLE.COM@ATHENA.MIT.EDU' and
`krbtgt/ATHENA.MIT.EDU@EXAMPLE.COM' to both databases.  You need to be
sure the passwords and the key version numbers (kvno) are the same in
both databases.  This may require explicitly setting the kvno with the
`-kvno' option.  See *Note Cross-realm Authentication:: for more
details.

---------- Footnotes ----------

(1) `ank' was the short form of the equivalent command using the
deprecated `kadmin5' database administrative tool.  It has been kept


File: krb5-admin.info,  Node: Deleting Principals,  Next: Changing Passwords,  Prev: Adding or Modifying Principals,  Up: Principals

Deleting Principals
-------------------

To delete a principal, use the kadmin `delete_principal' command, which
requires the "delete" administrative privilege.  The syntax is:

     delete_principal [-force] principal

`delete_principal' has the alias `delprinc'.  The `-force' option
causes `delete_principal' not to ask if you're sure.  For example:

     kadmin: delprinc jennifer
     Are you sure you want to delete the principal
     "jennifer@ATHENA.MIT.EDU"? (yes/no): yes
     Principal "jennifer@ATHENA.MIT.EDU" deleted.
     Make sure that you have removed this principal from
     all ACLs before reusing.
     kadmin:


File: krb5-admin.info,  Node: Changing Passwords,  Prev: Deleting Principals,  Up: Principals

Changing Passwords
------------------

To change a principal's password use the kadmin `change_password'
command, which requires the "modify" administrative privilege (unless
the principal is changing his/her own password).  The syntax is:

     change_password [options] principal

The `change_password' option has the alias `cpw'.  `change_password'
takes the following options:

-randkey
     Sets the key of the principal to a random value.

-pw password
     Sets the password to the string password.  MIT does not recommend
     using this option.

-e "enc:salt..."
     Uses the specified list of enctype-salttype pairs for setting the
     key of the principal.  The quotes are necessary if there are
     multiple enctype-salttype pairs.  This will not function against
     kadmin daemons earlier than krb5-1.2.  See *Note Supported
     Encryption Types:: and *Note Salts:: for possible values.

-keepold
     Keeps the previous kvno's keys around.  This flag is usually not
     necessary except perhaps for TGS keys.  Don't use this flag unless
     you know what you're doing. This option is not supported for the
     LDAP database


For example:

     kadmin: cpw david
     Enter password for principal david@ATHENA.MIT.EDU:  <= Type the new password.
     Re-enter password for principal david@ATHENA.MIT.EDU:  <= Type it again.
     Password for david@ATHENA.MIT.EDU changed.
     kadmin:

Note that `change_password' will not let you change the password to one
that is in the principal's password history.


File: krb5-admin.info,  Node: Policies,  Next: Global Operations on the Kerberos Database,  Prev: Principals,  Up: Administrating the Kerberos Database

Policies
========

A policy is a set of rules governing passwords.  Policies can dictate
minimum and maximum password lifetimes, minimum number of characters and
character classes a password must contain, and the number of old
passwords kept in the database.

* Menu:

* Retrieving Policies::
* Retrieving the List of Policies::
* Adding or Modifying Policies::
* Deleting Policies::
* Updating the History Key::


File: krb5-admin.info,  Node: Retrieving Policies,  Next: Retrieving the List of Policies,  Prev: Policies,  Up: Policies

Retrieving Policies
-------------------

To retrieve a policy, use the kadmin `get_policy' command, which
requires the "inquire" administrative privilege.  The syntax is:

     get_policy [-terse] policy

The `get_policy' command has the alias `getpol'.  For example:

     kadmin: get_policy admin
     Policy: admin
     Maximum password life: 180 days 00:00:00
     Minimum password life: 00:00:00
     Minimum password length: 6
     Minimum number of password character classes: 2
     Number of old keys kept: 5
     Reference count: 17
     kadmin:

The "reference count" is the number of principals using that policy.

The `get_policy' command has a `-terse' option, which lists each field
as a quoted, tab-separated string.  For example:

     kadmin: get_policy -terse admin
     admin   15552000        0       6       2       5       17
     kadmin:


File: krb5-admin.info,  Node: Retrieving the List of Policies,  Next: Adding or Modifying Policies,  Prev: Retrieving Policies,  Up: Policies

Retrieving the List of Policies
-------------------------------

You can retrieve the list of policies with the kadmin `list_policies'
command, which requires the "list" privilege.  The syntax is:

     list_policies [expression]

where expression is a shell-style glob expression that can contain the
characters *, ?, and [].  All policy names matching the expression are
displayed.  The `list_policies' command has the aliases `listpols',
`get_policies', and `getpols'.  For example:

     kadmin:  listpols
     test-pol
     dict-only
     once-a-min
     test-pol-nopw
     
     kadmin:  listpols t*
     test-pol
     test-pol-nopw
     kadmin:


File: krb5-admin.info,  Node: Adding or Modifying Policies,  Next: Deleting Policies,  Prev: Retrieving the List of Policies,  Up: Policies

Adding or Modifying Policies
----------------------------

To add a new policy, use the kadmin `add_policy' command, which
requires the "add" administrative privilege.  The syntax is:

     add_policy [options] policy_name

To modify attributes of a principal, use the kadmin `modify_policy'
command, which requires the "modify" administrative privilege.  The
syntax is:

     modify_policy [options] policy_name

`add_policy' has the alias `addpol'.  `modify_poilcy' has the alias
`modpol'.

The `add_policy' and `modify_policy' commands take the following
switches:

-maxlife time
     Sets the maximum lifetime of a password to time.

-minlife time
     Sets the minimum lifetime of a password to time.

-minlength length
     Sets the minimum length of a password to length characters.

-minclasses number
     Requires at least number of character classes in a password.

-history number
     Sets the number of past keys kept for a principal to number. This
     option is not supported for LDAP database.

Note: The policies are created under realm container in the LDAP
database.


File: krb5-admin.info,  Node: Deleting Policies,  Next: Updating the History Key,  Prev: Adding or Modifying Policies,  Up: Policies

Deleting Policies
-----------------

To delete a policy, use the `kadmin' `delete_policy' command, which
requires the "delete" administrative privilege.  The syntax is:

     delete_policy [-force] policy_name

The `delete_policy' command has the alias `delpol'.  It prompts for
confirmation before deletion.  For example:

     kadmin: delete_policy guests
     Are you sure you want to delete the policy "guests"?
     (yes/no): yes
     kadmin:

Note that you must cancel the policy from all principals before deleting
it.  The `delete_policy' command will fail if it is in use by any
principals.


File: krb5-admin.info,  Node: Updating the History Key,  Prev: Deleting Policies,  Up: Policies

Updating the History Key
------------------------

If a policy specifies a number of old keys kept of two or more, the
stored old keys are encrypted in a history key, which is found in the
key data of the kadmin/history principal.

Currently there is no support for proper rollover of the history key,
but you can change the history key (for example, to use a better
encryption type) at the cost of invalidating currently stored old keys.
To change the history key, run:

     kadmin: change_password -randkey kadmin/history

This command will fail if you specify the -keepold flag.  Only one new
history key will be created, even if you specify multiple key/salt
combinations.

In the future, we plan to migrate towards encrypting old keys in the
master key instead of the history key, and implementing proper rollover
support for stored old keys.


File: krb5-admin.info,  Node: Global Operations on the Kerberos Database,  Next: Global Operations on the Kerberos LDAP Database,  Prev: Policies,  Up: Administrating the Kerberos Database

Global Operations on the Kerberos Database
==========================================

* Menu:

* Dumping a Kerberos Database to a File::
* Restoring a Kerberos Database from a Dump File::
* Creating a Stash File::
* Creating and Destroying a Kerberos Database::

The `kdb5_util' command is the primary tool for administrating the
Kerberos database.  The syntax is:

     kdb5_util command [kdb5_util_options] [command_options]

The `kdb5_util' command takes the following options, which override the
defaults specified in the configuration files:

-r realm
     specifies the the Kerberos realm of the database.

-d database_name
     specifies the name under which the principal database is stored.

-k master_key_type
     specifies the key type of the master key in the database.

-M master_key_name
     specifies the principal name of the master key in the database.

-m
     indicates that the master database password should be read from
     the TTY rather than fetched from a file on disk.

-sf stash_file
     specifies the stash file of the master database password

-P password
     specifies the master database password.  MIT does not recommend
     using this option.



File: krb5-admin.info,  Node: Dumping a Kerberos Database to a File,  Next: Restoring a Kerberos Database from a Dump File,  Prev: Global Operations on the Kerberos Database,  Up: Global Operations on the Kerberos Database

Dumping a Kerberos Database to a File
-------------------------------------

To dump a Kerberos database into a file, use the `kdb5_util' `dump'
command on one of the KDCs.  The syntax is:

     kdb5_util dump [-old] [-b6] [-b7] [-ov]
     [-verbose] [-mkey_convert] [-new_mkey_file] [filename
     [principals...]]

The `kdb5_util dump' command takes the following options:

-old
     causes the dump to be in the Kerberos 5 Beta 5 and earlier dump
     format ("kdb5_edit load_dump version 2.0").

-b6
     causes the dump to be in the Kerberos 5 Beta 6 format ("kdb5_edit
     load_dump version 3.0").

-b7
     causes the dump to be in the Kerberos 5 Beta 7 format ("kdbt_edit
     load_dump version 4").

-ov
     causes the dump to be in ovsec_adm_export format.  Currently, the
     only way to preserve per-principal policy information is to use
     this in conjunction with a normal dump.

-verbose
     causes the name of each principal and policy to be printed as it is
     dumped.

-mkey_convert
     prompts for a new master password, and then dumps the database with
     all keys reencrypted in this new master key

-new_mkey_file
     reads a new key from the default keytab and then dumps the database
     with all keys reencrypted in this new master key

For example:

     shell% kdb5_util dump dumpfile
     shell%

     shell% kbd5_util dump -verbose dumpfile
     kadmin/admin@ATHENA.MIT.EDU
     krbtgt/ATHENA.MIT.EDU@ATHENA.MIT.EDU
     kadmin/history@ATHENA.MIT.EDU
     K/M@ATHENA.MIT.EDU
     kadmin/changepw@ATHENA.MIT.EDU
     shell%

If you specify which principals to dump, you must use the full
principal, as in the following example.  (The line beginning with => is
a continuation of the previous line.):

     shell% kdb5_util dump -verbose dumpfile K/M@ATHENA.MIT.EDU
     => kadmin/admin@ATHENA.MIT.EDU
     kadmin/admin@ATHENA.MIT.EDU
     K/M@ATHENA.MIT.EDU
     shell%

Otherwise, the principals will not match those in the database and will
not be dumped:

     shell% kdb5_util dump -verbose dumpfile K/M kadmin/admin
     shell%

If you do not specify a dump file, `kdb5_util' will dump the database
to the standard output.

There is currently a bug where the default dump format omits the
per-principal policy information.  In order to dump all the data
contained in the Kerberos database, you must perform a normal dump (with
no option flags) and an additional dump using the "-ov" flag to a
different file.


File: krb5-admin.info,  Node: Restoring a Kerberos Database from a Dump File,  Next: Creating a Stash File,  Prev: Dumping a Kerberos Database to a File,  Up: Global Operations on the Kerberos Database

Restoring a Kerberos Database from a Dump File
----------------------------------------------

To restore a Kerberos database dump from a file, use the `kdb5_util'
`load' command on one of the KDCs.  The syntax is:

     kdb5_util load [-old] [-b6] [-b7] [-ov] [-verbose]
     [-update] [-hash] dumpfilename dbname [admin_dbname]

The `kdb5_util load' command takes the following options:

-old
     requires the dump to be in the Kerberos 5 Beta 5 and earlier dump
     format ("kdb5_edit load_dump version 2.0").

-b6
     requires the dump to be in the Kerberos 5 Beta 6 format ("kdb5_edit
     load_dump version 3.0").

-b7
     requires the dump to be in the Kerberos 5 Beta 7 format ("kdb5_edit
     load_dump version 4").

-ov
     requires the dump to be in ovsec_adm_export format.

-verbose
     causes the name of each principal and policy to be printed as it is
     loaded.

-update
     causes records from the dump file to be updated in or added to the
     existing database.  This is useful in conjunction with an
     ovsec_adm_export format dump if you want to preserve per-principal
     policy information, since the current default format does not
     contain this data.

-hash
     causes the database to be stored as a hash rather than a binary
     tree.

For example:

     shell% kdb5_util load dumpfile principal
     shell%

     shell% kdb5_util load -update dumpfile principal
     shell%

If the database file exists, and the -update flag was not given,
`kdb5_util' will overwrite the existing database.


File: krb5-admin.info,  Node: Creating a Stash File,  Next: Creating and Destroying a Kerberos Database,  Prev: Restoring a Kerberos Database from a Dump File,  Up: Global Operations on the Kerberos Database

Creating a Stash File
---------------------

A stash file allows a KDC to authenticate itself to the database
utilities, such as `kadmin', `kadmind', `krb5kdc', and `kdb5_util'.

To create a stash file, use the `kdb5_util' `stash' command.  The
syntax is:

     kdb5_util stash [-f keyfile]

For example:

     shell% kdb5_util stash
     kdb5_util: Cannot find/read stored master key while reading master key
     kdb5_util: Warning: proceeding without master key
     Enter KDC database master key:  <= Type the KDC database master password.
     shell%

If you do not specify a stash file, `kdb5_util' will stash the key in
the file specified in your `kdc.conf' file.


File: krb5-admin.info,  Node: Creating and Destroying a Kerberos Database,  Prev: Creating a Stash File,  Up: Global Operations on the Kerberos Database

Creating and Destroying a Kerberos Database
-------------------------------------------

If you need to create a new Kerberos database, use the `kdb5_util'
`create' command.  The syntax is:

     kdb5_util create [-s]

If you specify the `-s' option, `kdb5_util' will stash a copy of the
master key in a stash file.  (*Note Creating a Stash File::.)  For
example:

     shell% /usr/local/sbin/kdb5_util -r ATHENA.MIT.EDU create -s
     kdb5_util: No such file or directory while setting active database to
     => '/usr/local/var/krb5kdc/principal'
     Initializing database '/usr/local/var/krb5kdc/principal' for
     => realm 'ATHENA.MIT.EDU',
     master key name 'K/M@ATHENA.MIT.EDU'
     You will be prompted for the database Master Password.
     It is important that you NOT FORGET this password.
     Enter KDC database master key:  <= Type the master password.
     Re-enter KDC database master key to verify:  <= Type it again.
     shell%

If you need to destroy the current Kerberos database, use the
`kdb5_util' `destroy' command.  The syntax is:

     kdb5_util destroy [-f]

The `destroy' command destroys the database, first overwriting the disk
sectors and then unlinking the files.  If you specify the `-f' option,
`kdb5_util' will not prompt you for a confirmation before destroying
the database.

     shell% /usr/local/sbin/kdb5_util -r ATHENA.MIT.EDU destroy
     kdb5_util: Deleting KDC database stored in /usr/local/var/krb5kdc/principal, are you sure
     (type yes to confirm)? <== yes
     OK, deleting database '/usr/local/var/krb5kdc/principal'...
     
     shell%


File: krb5-admin.info,  Node: Global Operations on the Kerberos LDAP Database,  Next: Cross-realm Authentication,  Prev: Global Operations on the Kerberos Database,  Up: Administrating the Kerberos Database

Global Operations on the Kerberos LDAP Database
===============================================

The `kdb5_ldap_util' is the primary tool for administrating the
Kerberos LDAP database. It allows an administrator to manage realms,
Kerberos services ( KDC and Admin Server) and ticket policies.

The syntax is:
     kdb5_ldap_util [-D user_dn [-w passwd]] [-H ldap_uri] command [command_options]

-D user_dn
     Specifies the Distinguished Name (DN) of the user who has
     sufficient rights to perform the operation on the LDAP server.

-w passwd
     Specifies the password of user_dn. This option is not recommended.

-H ldap_uri
     Specifies the URI of the LDAP server. It is recommended to use
     ldapi:// or ldaps:// to connect to the LDAP server.

* Menu:

* Creating a Kerberos Realm::
* Modifying a Kerberos Realm::
* Retrieving Information about a Kerberos Realm::
* Destroying a Kerberos Realm::
* Listing available Kerberos Realms::
* Stashing Service Object's Password::
* Creating and Modifying a Ticket Policy::
* Retrieving Information About a Ticket Policy::
* Destroying a Ticket Policy::
* Listing available Ticket Policies::
* Creating a Service Object (eDirectory)::
* Modifying a Service Object (eDirectory)::
* Retrieving Service Object Information (eDirectory)::
* Destroying a Service Object (eDirectory)::
* Listing Available Service Objects (eDirectory)::
* Passwords for Service Objects (eDirectory)::


File: krb5-admin.info,  Node: Creating a Kerberos Realm,  Next: Modifying a Kerberos Realm,  Prev: Global Operations on the Kerberos LDAP Database,  Up: Global Operations on the Kerberos LDAP Database

Creating a Kerberos Realm
-------------------------

If you need to create a new realm, use the command as follows:

     create  [-r realm]  [-subtrees subtree_dn_list] [-sscope search_scope] [-containerref container_reference_dn]
     [-k  mkeytype] [-m|-P password][-sf stashlename] [-s] [-maxtktlife max_ticket_life]
     [-maxrenewlife  max_renewable_ticket_life] [ticket_flags]

Options to create realm in directory are as follows:

-r realm
     Specifies the Kerberos realm of the database; by default the realm
     returned by `krb5_default_local_realm' (3) is used.

-subtrees subtree_dn_list
     Specifies the list of subtrees containing principals of a realm.
     The list contains the DN of the subtree objects separated by
     colon(:).

-sscope search_scope
     Specifies the scope for searching the principals under the
     subtree. The possible values are 1 or one (one level), 2 or sub
     (subtree).

-containerref container_reference_dn
     Specfies the DN of the container object in which the principals of
     a realm will be created. If the container reference is not
     configured for a realm, the principals will be created in the
     realm container.

-k mkeytype
     Specifies the key type of the master key in the database; the
     default is that given in `kdc.conf'.

-m
     Specifies that the master database password should be read from
     the TTY rather than fetched from a file on disk.

-p password
     Specifies the master database password. This option is not
     recommended.

-sf stashfilename
     Specifies the stash file of the master database password.

-s
     Specifies that the stash file is to be created.

-maxtktlife max_ticket_life
     Specifies maximum ticket life for principals in this realm. This
     value is used, if it is not set on the principal.

-maxrenewlife max_renewable_ticket_life
     Specifies maximum renewable life of tickets for principals in this
     realm. This value is used, if it is not set on the principal.

ticket_flags
     Specifies the ticket flags. If this option is not specified, by
     default, none of the flags are set. This means all the ticket
     options will be allowed and no restriction will be set. This value
     is used, if it is not set on the principal.

     The various flags are:
    {-|+}allow_postdated
          `-allow_postdated' prohibits principals from obtaining
          postdated tickets. (Sets the `KRB5_KDB_DISALLOW_POSTDATED'
          flag.).`+allow_postdated' clears this flag.

    {-|+}allow_forwardable
          `-allow_forwardable' prohibits principals from obtaining
          forwardable tickets. (Sets the
          `KRB5_KDB_DISALLOW_FORWARDABLE' flag.) `+allow_forwardable'
          clears this flag.

    {-|+}allow_renewable
          `-allow_renewable' prohibits principals from obtaining
          renewable tickets. (Sets the `KRB5_KDB_DISALLOW_RENEWABLE'
          flag.) `+allow_renewable' clears this flag.

    {-|+}allow_proxiable
          `-allow_proxiable' prohibits principals from obtaining
          proxiable tickets. (Sets the `KRB5_KDB_DISALLOW_PROXABLE'
          flag.) `+allow_proxiable' clears this flag.

    {-|+}allow_dup_skey
          `-allow_dup_skey' disables user-to-user authentication for
          principals by prohibiting principals from obtaining a
          sessions key for another user.  (Sets the
          `KRB5_KDB_DISALLOW_DUP_SKEY' flag.)  `+allow_dup_skey' clears
          this flag.

    {-|+}requires_preauth
          `+requires_preauth' requires principals to preauthenticate
          before being allowed to kinit. (Sets the
          `KRB5_KDB_REQURES_PRE_AUTH' flag.) `-requires_preauth' clears
          this flag.

    {-|+}requires_hwauth
          `+requires_hwauth' requires principals to preauthenticate
          using a hardware device before being allowed to kinit. (Sets
          the `KRB5_KDB_REQURES_HW_AUTH' flag.)  `-requires_hwauth'
          clears this flag.

    {-|+}ok_as_delegate
          `+ok_as_delegate' sets the OK-AS-DELEGATE flag on tickets
          issued for use with this principal as the service, which
          clients may use as a hint that credentials can and should be
          delegated when authenticating to the service.  (Sets the
          `KRB5_KDB_OK_AS_DELEGATE' flag.) `-ok_as_delegate' clears
          this flag.

    {-|+}allow_svr
          `-allow_svr' prohibits the issuance of service tickets for
          principals. (Sets the `KRB5_KDB_DISALLOW_SVR' flag.)
          `+allow_svr' clears this flag.

    {-|+}allow_tgs_req
          `-allow_tgs_req' specifies that a "Ticket-Granting Service
          (TGS)" request for a service ticket for principals is not
          permitted. This option is useless for most
          things.`+allow_tgs_req' clears this flag.  The default is
          `+allow_tgs_req'. In effect, `-allow_tgs_req' sets the
          `KRB5_KDB_DISALLOW_TGT_BASED' flag on principals in the
          database.

    {-|+}allow_tix
          `-allow_tix' forbids the issuance of any tickets for
          principals. `+allow_tix' clears this flag. The default is
          `+allow_tix'.  In effect, `-allow_tix' sets the
          `KRB5_KDB_DISALLOW_ALL_TIX' flag on principals in the
          database.

    {-|+}needchange
          `+needchange' sets a flag in attributes field to force a
          password change; `-needchange' clears it. The default is
          `-needchange'. In effect, `+needchange' sets the
          `KRB5_KDB_REQURES_PWCHANGE' flag on principals in the
          database.

    {-|+}password_changing_service
          `+password_changing_service' sets a flag in the attributes
          field marking principal as a password change service
          principal (useless for most things).
          `-password_changing_service' clears the flag. This flag
          intentionally has a long name. The default is
          `-password_changing_service'. In effect,
          `+password_changing_service' sets the
          `KRB5_KDB_PWCHANGE_SERVICE' flag on principals in the
          database.



     shell% kdb5_ldap_util -D cn=admin,dc=example,dc=com -H ldaps://ldap-server1.mit.edu create -sscope 2
     -subtree ou=users,dc=example,dc=com -r ATHENA.MIT.EDU
     Password for "cn=admin,dc=example,dc=com":
     Initializing database for realm 'ATHENA.MIT.EDU'
     You will be prompted for the database Master Password.
     It is important that you NOT FORGET this password.
     Enter KDC database master key:
     Re-enter KDC database master key to verify:
     shell%

* Menu:

* eDirectory Options (Creating a Kerberos Realm)::


File: krb5-admin.info,  Node: eDirectory Options (Creating a Kerberos Realm),  Prev: Creating a Kerberos Realm,  Up: Creating a Kerberos Realm

eDirectory Options
..................

-kdcdn kdc_servce_list
     Specifies the list of KDC service objects serving the realm. The
     list contains the DNs of the KDC service objects separated by
     colon(:).

-admindn admin_service_list
     Specifies the  list of Administration service objects serving the
     realm. The list contains the DNs of the Administration service
     objects separated by colon(:).

     shell% kdb5_ldap_util -D cn=admin,dc=example,dc=com -H ldaps://ldap-server1.mit.edu create -sscope 2
     -subtree ou=users,dc=example,dc=com -kdcdn cn=krbkdc,dc=example,dc=com -admindn cn=krbadmin,dc=example,dc=com -r ATHENA.MIT.EDU
     Password for "cn=admin,dc=example,dc=com":
     Initializing database for realm 'ATHENA.MIT.EDU'
     You will be prompted for the database Master Password.
     It is important that you NOT FORGET this password.
     Enter KDC database master key:
     Re-enter KDC database master key to verify:
     shell%


File: krb5-admin.info,  Node: Modifying a Kerberos Realm,  Next: Retrieving Information about a Kerberos Realm,  Prev: Creating a Kerberos Realm,  Up: Global Operations on the Kerberos LDAP Database

Modifying a Kerberos Realm
--------------------------

If you need to modify a realm, use the command as follows:


     modify  [-r realm] [-subtrees subtree_dn] [-sscope search_scope][-containerref container_reference_dn]
     [-maxtktlifemax_ticket_life][-maxrenewlife max_renewable_ticket_life] [-ticket_flags]
Options to modify realm in directory are as follows:

-r realm
     Specifies the Kerberos realm of the database; by default the realm
     returned by krb5_default_local_realm (3) is used.

-subtrees subtree_dn_list
     Specifies the list of subtrees containing principal objects in the
     realm.The list contains the DN of the subtree objects separated by
     colon(:). This list replaces the existing list.

-sscope search_scope
     Specifies the scope for searching the principals under the
     subtrees. The possible values are 1 or one (one level), 2 or sub
     (subtrees).

-containerref container_reference_dn
     Specifies the Distinguished Name (DN) of the container object in
     which the principals of a realm will be created.

-maxtktlife max_ticket_life
     Specifies maximum ticket life for principals in this realm. This
     value is used, if it is not set on the principal.

-maxrenewlife max_renewable_ticket_life
     Specifies maximum renewable life of tickets for principals in this
     realm.  This value is used, if it is not set on the principal.

-ticket_flags
     Specifies the ticket flags. If this option is not specified, by
     default, none of the flags are set. This means all the ticket
     options will be allowed and no restriction will be set.  This
     value is used, if it is not set on the principal.

     The various flags are:
    {-|+}allow_postdated
          `-allow_postdated' prohibits principals from obtaining
          postdated tickets. (Sets the `KRB5_KDB_DISALLOW_POSTDATED'
          flag.).`+allow_postdated' clears this flag.

    {-|+}allow_forwardable
          `-allow_forwardable' prohibits principals from obtaining
          forwardable tickets.  (Sets the
          `KRB5_KDB_DISALLOW_FORWARDABLE' flag.) `+allow_forwardable'
          clears this flag.

    {-|+}allow_renewable
          `-allow_renewable' prohibits principals from obtaining
          renewable tickets. (Sets the `KRB5_KDB_DISALLOW_RENEWABLE'
          flag.) `+allow_renewable' clears this flag.

    {-|+}allow_proxiable
          `-allow_proxiable' prohibits principals from obtaining
          proxiable tickets. (Sets the `KRB5_KDB_DISALLOW_PROXABLE'
          flag.) `+allow_proxiable' clears this flag.

    {-|+}allow_dup_skey
          `-allow_dup_skey' Disables user-to-user authentication for
          principals by prohibiting principals from obtaining a
          sessions key for another user. (Sets the
          `KRB5_KDB_DISALLOW_DUP_SKEY' flag.). `+allow_dup_skey' clears
          This flag.

    {-|+}requires_preauth
          `+requires_preauth' requires principals to preauthenticate
          before being allowed to kinit. Sets the
          `KRB5_KDB_REQURES_PRE_AUTH' flag.`-requires_preauth' clears
          this flag.

    {-|+}requires_hwauth
          `+requires_hwauth' requires principals to preauthenticate
          using a hardware device before being allowed to kinit. (Sets
          the `KRB5_KDB_REQURES_HW_AUTH' flag.)`-requires_hwauth'
          clears this flag.

    {-|+}allow_svr
          `-allow_svr' prohibits the issuance of service tickets for
          principals. (Sets the `KRB5_KDB_DISALLOW_SVR' flag.)
          `+allow_svr' clears This flag.

    {-|+}allow_tgs_req
          `-allow_tgs_req' specifies that a "Ticket-Granting Service
          (TGS)" request for a service ticket for principals is not
          permitted. This option is useless for most
          things.`+allow_tgs_req' clears this flag.  The default is.
          `+allow_tgs_req'.  In effect, `-allow_tgs_req' sets the
          `KRB5_KDB_DISALLOW_TGT_BASED' flag on principals in the
          database.

    {-|+}allow_tix
          `-allow_tix' forbids the issuance of any tickets for
          principals. `+allow_tix' clears this flag. The default is
          `+allow_tix'.  In effect, `-allow_tix' sets the
          `KRB5_KDB_DISALLOW_ALL_TIX' flag on principals in the
          database.

    {-|+}needchange
          `+needchange' sets a flag in attributes field to force a
          password change; `-needchange' clears it.  The default is
          `-needchange'.  In effect,`+needchange' sets the
          `KRB5_KDB_REQURES_PWCHANGE' flag on principals in the
          database.

    {-|+}password_changing_service
          `+password_changing_service' sets a flag in the attributes
          field marking principal as a password change service
          principal (useless for most
          things).`-password_changing_service' clears the flag. This
          flag intentionally has a long name. The default is
          `-password_changing_service' In effect,
          `+password_changing_service' sets the
          `KRB5_KDB_PWCHANGE_SERVICE' flag on principals in the
          database.


     For example:
          shell% kdb5_ldap_util -D cn=admin,dc=example,dc=com -H ldaps://ldap-server1.mit.edu
          modify -r ATHENA.MIT.EDU +requires_preauth
          Password for "cn=admin,dc=example,dc=com":
          shell%

     * Menu:
     
     * eDirectory Options (Modifying a Kerberos Realm)::



File: krb5-admin.info,  Node: eDirectory Options (Modifying a Kerberos Realm),  Prev: Modifying a Kerberos Realm,  Up: Modifying a Kerberos Realm

eDirectory Options
..................

-kdcdn kdc_service_list
     Specifies the list of KDC service objects serving the realm. The
     list contains the DNs of the KDC service objects separated by a
     colon (:). This list replaces the existing list.

-clearkdcdn kdc_service_list
     Specifies the list of KDC service objects that need to be removed
     from the existing list. The list contains the DNs of the KDC
     service objects separated by a colon (:).

-addkdcdn kdc_service_list
     Specifies the list of KDC service objects that need to be added to
     the existing list. The list contains the DNs of the KDC service
     objects separated by a colon (:).

-admindn admin_service_list
     Specifies the list of Administration service objects serving the
     realm. The list contains the DNs of the Administration service
     objects separated by a colon (:). This list replaces the existing
     list.

-clearadmindn admin_service_list
     Specifies the list of Administration service objects that need to
     be removed from the existing list. The list contains the DNs of
     the Administration service objects separated by a colon (:).

-addadmindn admin_service_list
     Specifies the list of Administration service objects that need to
     be added to the existing list. The list contains the DNs of the
     Administration service objects separated by a colon (:).


