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

INFO-DIR-SECTION Kerberos V5
START-INFO-DIR-ENTRY
* Admin Guide: (krb5-admin).            Kerberos V5 System Admin's Guide
END-INFO-DIR-ENTRY



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

Attributes
..........

To retrieve a listing of the attributes and/or policies associated with
a principal, use the `kadmin' `get_principal' command, which requires
the "inquire" administrative privilege.  The syntax is:

     get_principal principal

The `get_principal' command has the alias `getprinc'.

For example, suppose you wanted to view the attributes of the principals
`jennifer/root@ATHENA.MIT.EDU' and `systest@ATHENA.MIT.EDU'.  You would
type:

     shell% kadmin
     kadmin: getprinc jennifer/root
     Principal: jennifer/root@ATHENA.MIT.EDU
     Key version: 3
     Maximum life: 1 day 00:00:00
     Maximum renewable life: 7 days 00:00:00
     Master key version: 1
     Expires: Mon Jan 18 22:14:07 EDT 2038
     Password expires: Mon Sep 19 14:40:00 EDT 1996
     Password last changed: Mon Jan 31 02:06:40 EDT 1996
     Last modified: by joeadmin/admin@ATHENA.MIT.EDU
     	on Wed Jul 13 18:27:08 EDT 1996
     Attributes: DISALLOW_FORWARDABLE, DISALLOW_PROXIABLE,
     	REQUIRES_HW_AUTH
     Salt type: DEFAULT
     kadmin:

The `get_principal' command has a `-terse' option, which lists the
fields as a quoted, tab-separated string.  For example:

     kadmin: getprinc -terse systest
     systest@ATHENA.MIT.EDU	3	86400	604800	1
     785926535	753241234	785900000
     joeadmin/admin@ATHENA.MIT.EDU	786100034	0
     0
     kadmin:


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 alias
`listprincs'.  For example:

     kadmin: listprincs test*
     test3@mit.edu
     test2@mit.edu
     test1@mit.edu
     testuser@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'.  Each line of the file contains a principal, the
privileges that principal has, and optionally the target to which those
permissions apply.  The privileges 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.

*
     All privileges (admcil).

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

Principals in this file can include the * wildcard.  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
     jennifer/root@ATHENA.MIT.EDU  cil  */root@ATHENA.MIT.EDU
     */*@ATHENA.MIT.EDU  i

In the above file, any principal 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).  He has inquire
and list permissions with any other instance (matches the third line).
When `jennifer' is using her `root' instance,
`jennifer/root@ATHENA.MIT.EDU', she has change password, inquire, and
list privileges for any other principal that has the instance `root'.
Finally, any principal in the realm `ATHENA.MIT.EDU' (except for
`joeadmin@ATHENA.MIT.EDU', as mentioned above) has inquire privileges.


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 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)

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

-salt salttype
     Uses the specified salt for generating the key.  The valid salt
     types are:

        * full_name (aliases "v5_salt" and "normal"; this is the
          default)

        * name_only

        * realm_only

        * no_salt (alias "v4_salt")

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

-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.

-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.

{-|+}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.

-clearpolicy policyname
     Removes the policy policyname from the principal
     (`modify_principal' only).

-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.

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, 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
FUBAR.ORG, you would need to add the principals
`krbtgt/FUBAR.ORG@ATHENA.MIT.EDU' and `krbtgt/ATHENA.MIT.EDU@FUBAR.ORG'
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.

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

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


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:

-salt salttype
     Uses the specified salt for generating the key.  Salt types are
     the same as for the `add_principal' command (*note Adding or
     Modifying Principals::).

-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.

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: Dumping a Kerberos Database to a File,  Prev: Principals,  Up: Administrating Kerberos Database Entries

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::


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 alias `listpols'.  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.


File: krb5-admin.info,  Node: Deleting Policies,  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 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
     Policy "guests" deleted.
     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: Dumping a Kerberos Database to a File,  Next: Restoring a Kerberos Database from a Dump File,  Prev: Policies,  Up: Administrating Kerberos Database Entries

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]
     [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 ("kdb5_util
     load_dump version 4").  This was the dump format produced on
     releases prior to 1.2.2.

-ov
     causes the dump to be in ovsec_adm_export format.

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

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.


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: Administrating Kerberos Database Entries

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] 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_util
     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
     dumped.

-update
     causes records from the dump file to be updated in or added to the
     existing database.

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: Administrating Kerberos Database Entries

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: Administrating Kerberos Database Entries

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%


File: krb5-admin.info,  Node: Application Servers,  Next: Backups of Secure Hosts,  Prev: Administrating Kerberos Database Entries,  Up: Top

Application Servers
*******************

If you need to install the Kerberos V5 programs on an application
server, please refer to the Kerberos V5 Installation Guide.  Once you
have installed the software, you need to add that host to the Kerberos
database (*note Adding or Modifying Principals::), and generate a
"keytab" for that host, that contains the host's key.  You also need to
make sure the host's clock is within your maximum clock skew of the
KDCs.

* Menu:

* Keytabs::
* Clock Skew::
* Getting DNS Information Correct::
* Configuring Your Firewall to Work With Kerberos V5::


File: krb5-admin.info,  Node: Keytabs,  Next: Clock Skew,  Prev: Application Servers,  Up: Application Servers

Keytabs
=======

A "keytab" is a host's copy of its own keylist, which is analogous to a
user's password.  An application server that needs to authenticate
itself to the KDC has to have a keytab that contains its own principal
and key.  Just as it is important for users to protect their passwords,
it is equally important for hosts to protect their keytabs.  You should
always store keytab files on local disk, and make them readable only by
root, and you should never send a keytab file over a network in the
clear.  Ideally, you should run the `kadmin' command to extract a
keytab on the host on which the keytab is to reside.

* Menu:

* Adding Principals to Keytabs::
* Removing Principals from Keytabs::


File: krb5-admin.info,  Node: Adding Principals to Keytabs,  Next: Removing Principals from Keytabs,  Prev: Keytabs,  Up: Keytabs

Adding Principals to Keytabs
----------------------------

To generate a keytab, or to add a principal to an existing keytab, use
the `ktadd' command from `kadmin', which requires the "inquire"
administrative privilege.  (If you use the -glob princ_exp option, it
also requires the "list" administrative privilege.)  The syntax is:

     ktadd [-k keytab] [-q] [principal | -glob princ_exp] [...]

The `ktadd' command takes the following switches:

-k keytab
     use keytab as the keytab file.  Otherwise, `ktadd' will use the
     default keytab file (`/etc/krb5.keytab').

-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.

-q
     run in quiet mode.  This causes `ktadd' to display less verbose
     information.

principal | -glob principal expression
     add principal, or all principals matching principal expression to
     the keytab.  The rules for principal expression are the same as
     for the kadmin `list_principals' (*note Retrieving a List of
     Principals::) command.

Here is a sample session, using configuration files that enable only
`des-cbc-crc' encryption. (The line beginning with => is a continuation
of the previous line.)

     kadmin: ktadd host/daffodil.mit.edu@ATHENA.MIT.EDU
     kadmin: Entry for principal host/daffodil.mit.edu@ATHENA.MIT.EDU with
          kvno 2, encryption type DES-CBC-CRC added to keytab
          WRFILE:/etc/krb5.keytab.
     kadmin:

     kadmin: ktadd -k /usr/local/var/krb5kdc/kadmind.keytab
     => kadmin/admin kadmin/changepw
     kadmin: Entry for principal kadmin/admin@ATHENA.MIT.EDU with
          kvno 3, encryption type DES-CBC-CRC added to keytab
          WRFILE:/usr/local/var/krb5kdc/kadmind.keytab.
     kadmin:


File: krb5-admin.info,  Node: Removing Principals from Keytabs,  Prev: Adding Principals to Keytabs,  Up: Keytabs

Removing Principals from Keytabs
--------------------------------

To remove a principal to an existing keytab, use the kadmin `ktremove'
command.  The syntax is:

     ktremove [-k keytab] [-q] principal [kvno | all | old]

The `ktremove' command takes the following switches:

-k keytab
     use keytab as the keytab file.  Otherwise, `ktremove' will use the
     default keytab file (`/etc/krb5.keytab').

-q
     run in quiet mode.  This causes `ktremove' to display less verbose
     information.

principal
     the principal to remove from the keytab.  (Required.)

kvno
     remove all entries for the specified principal whose Key Version
     Numbers match kvno.

all
     remove all entries for the specified principal

old
     remove all entries for the specified principal except those with
     the highest kvno.

For example:

     kadmin: ktremove -k /usr/local/var/krb5kdc/kadmind.keytab kadmin/admin
     kadmin: Entry for principal kadmin/admin with kvno 3 removed
          from keytab WRFILE:/usr/local/var/krb5kdc/kadmind.keytab.
     kadmin:


File: krb5-admin.info,  Node: Clock Skew,  Next: Getting DNS Information Correct,  Prev: Keytabs,  Up: Application Servers

Clock Skew
==========

In order to prevent intruders from resetting their system clocks in
order to continue to use expired tickets, Kerberos V5 is set up to
reject ticket requests from any host whose clock is not within the
specified maximum clock skew of the KDC (as specified in the `kdc.conf'
file).  Similarly, hosts are configured to reject responses from any
KDC whose clock is not within the specified maximum clock skew of the
host (as specified in the `krb5.conf' file).  The default value for
maximum clock skew is 300 seconds (five minutes).

MIT suggests that you add a line to client machines' `/etc/rc' files to
synchronize the machine's clock to your KDC at boot time.  On UNIX
hosts, assuming you had a kdc called `kerberos' in your realm, this
would be:

     gettime -s kerberos

If the host is not likely to be rebooted frequently, you may also want
to set up a cron job that adjusts the time on a regular basis.


File: krb5-admin.info,  Node: Getting DNS Information Correct,  Next: Configuring Your Firewall to Work With Kerberos V5,  Prev: Clock Skew,  Up: Application Servers

Getting DNS Information Correct
===============================

Several aspects of Kerberos rely on name service.  In order for Kerberos
to provide its high level of security, it is less forgiving of name
service problems than some other parts of your network.  It is important
that your Domain Name System (DNS) entries and your hosts have the
correct information.

Each host's canonical name must be the fully-qualified host name
(including the domain), and each host's IP address must reverse-resolve
to the canonical name.

Other than the `localhost' entry, make all entries in each machine's
`/etc/hosts' file in the following form:

     IP address      fully-qualified hostname        aliases

Here is a sample `/etc/hosts' file:

     # this is a comment
     127.0.0.1       localhost localhost@mit.edu
     10.0.0.6       daffodil.mit.edu trillium wake-robin

Additionally, on Solaris machines, you need to be sure the "hosts"
entry in the file
`/etc/nsswitch.conf' includes the source "dns" as well as "file".

Finally, each host's keytab file must include a host/key pair for the
host's canonical name.  You can list the keys in a keytab file by
issuing the command `klist -k'.  For example:

     viola# klist -k
     Keytab name: /etc/krb5.keytab
     KVNO Principal
     ---- ------------------------------------------------------------
        1 host/daffodil.mit.edu@ATHENA.MIT.EDU

If you telnet to the host with a fresh credentials cache (ticket file),
and then `klist', the host's service principal should be
host/fully-qualified-hostname@REALM_NAME.


File: krb5-admin.info,  Node: Configuring Your Firewall to Work With Kerberos V5,  Prev: Getting DNS Information Correct,  Up: Application Servers

Configuring Your Firewall to Work With Kerberos V5
==================================================

If you need off-site users to be able to get Kerberos tickets in your
realm, they must be able to get to your KDC.  This requires either that
you have a slave KDC outside your firewall, or you configure your
firewall to allow UDP requests into to at least one of your KDCs, on
whichever port the KDC is running.  (The default is port 88; other ports
may be specified in the KDC's kdc.conf file.)  Similarly, if you need
off-site users to be able to change their passwords in your realm, they
must be able to get to your Kerberos admin server.  The default port for
the admin server is 749.

If your on-site users inside your firewall will need to get to KDCs in
other realms, you will also need to configure your firewall to allow
outgoing TCP and UDP requests to port 88.  Additionally, if they will
need to get to any Kerberos V4 KDCs, you may also need to allow TCP and
UDP requests to port 750.  If your on-site users inside your firewall
will need to get to Kerberos admin servers in other realms, you will
also need to allow outgoing TCP and UDP requests to port 749.

If any of your KDCs is outside your firewall, you will need to allow
`kprop' requests to get through to the remote KDC.  `Kprop' uses the
krb5_prop service on port 754 (tcp).

If you need your off-site users to have access to machines inside your
firewall, you need to allow TCP connections from their off-site hosts on
the appropriate ports for the programs they will be using.  The
following lines from `/etc/services' show the default port numbers for
the Kerberos V5 programs:

     ftp           21/tcp           # Kerberos ftp and telnet use the
     telnet        23/tcp           # default ports
     kerberos      88/udp    kdc    # Kerberos V5 KDC
     kerberos      88/tcp    kdc    # Kerberos V5 KDC
     klogin        543/tcp          # Kerberos authenticated rlogin
     kshell        544/tcp   cmd    # and remote shell
     kerberos-adm  749/tcp          # Kerberos 5 admin/changepw
     kerberos-adm  749/udp          # Kerberos 5 admin/changepw
     krb5_prop     754/tcp          # Kerberos slave propagation
     eklogin       2105/tcp         # Kerberos auth. & encrypted rlogin
     krb524        4444/tcp         # Kerberos 5 to 4 ticket translator

By default, Kerberos V5 `telnet' and `ftp' use the same ports as the
standard `telnet' and `ftp' programs, so if you already allow telnet
and ftp connections through your firewall, the Kerberos V5 versions
will get through as well.  If you do not already allow telnet and ftp
connections through your firewall, but need your users to be able to
use Kerberos V5 telnet and ftp, you can either allow ftp and telnet
connections on the standard ports, or switch these programs to
non-default port numbers and allow ftp and telnet connections on those
ports to get through.

Kerberos V5 `rlogin' uses the `klogin' service, which by default uses
port 543.  Encrypted Kerberos V5 rlogin uses uses the `eklogin'
service, which by default uses port 2105.

Kerberos V5 `rsh' uses the `kshell' service, which by default uses port
544.  However, the server must be able to make a TCP connection from
the kshell port to an arbitrary port on the client, so if your users
are to be able to use `rsh' from outside your firewall, the server they
connect to must be able to send outgoing packets to arbitrary port
numbers.  Similarly, if your users need to run `rsh' from inside your
firewall to hosts outside your firewall, the outside server needs to be
able to connect to an arbitrary port on the machine inside your
firewall.  Because Kerberos V5 `rcp' uses `rsh', the same issues apply.
If you need to use `rsh' (or `rcp') through your firewall and are
concerned with the security implications of allowing connections to
arbitrary ports, MIT suggests that you have rules that specifically
name these applications and, if possible, list the allowed hosts.

A reasonably good cookbook for configuring firewalls is available by FTP
from
`ftp.livingston.com', in the location:
`/pub/firewall/firewall-1.1.ps.Z'.  The book `UNIX System Security', by
David Curry, is also a good starting point.


File: krb5-admin.info,  Node: Backups of Secure Hosts,  Next: Bug Reporting,  Prev: Application Servers,  Up: Top

Backups of Secure Hosts
***********************

When you back up a secure host, you should exclude the host's keytab
file from the backup.  If someone obtained a copy of the keytab from a
backup, that person could make any host masquerade as the host whose
keytab was compromised.  This could be particularly dangerous if the
compromised keytab was from one of your KDCs.  If the machine has a disk
crash and the keytab file is lost, it is easy to generate another keytab
file.  (*Note Adding Principals to Keytabs::.)  If you are unable to
exclude particular files from backups, you should ensure that the
backups are kept as secure as the host's root password.

* Menu:

* Backing Up the Kerberos Database::


File: krb5-admin.info,  Node: Backing Up the Kerberos Database,  Prev: Backups of Secure Hosts,  Up: Backups of Secure Hosts

Backing Up the Kerberos Database
================================

As with any file, it is possible that your Kerberos database could
become corrupted.  If this happens on one of the slave KDCs, you might
never notice, since the next automatic propagation of the database would
install a fresh copy.  However, if it happens to the master KDC, the
corrupted database would be propagated to all of the slaves during the
next propagation.  For this reason, MIT recommends that you back up
your Kerberos database regularly.  Because the master KDC is
continuously dumping the database to a file in order to propagate it to
the slave KDCs, it is a simple matter to have a cron job periodically
copy the dump file to a secure machine elsewhere on your network.  (Of
course, it is important to make the host where these backups are stored
as secure as your KDCs, and to encrypt its transmission across your
network.)  Then if your database becomes corrupted, you can load the
most recent dump onto the master KDC.  (*Note Restoring a Kerberos
Database from a Dump File::.)


File: krb5-admin.info,  Node: Bug Reporting,  Next: Appendix,  Prev: Backups of Secure Hosts,  Up: Top

Bug Reporting
*************

In any complex software, there will be bugs.  If you have successfully
built and installed Kerberos V5, please use the `krb5-send-pr' program
to fill out a Problem Report.

Bug reports that include proposed fixes are especially welcome.  If you
do include fixes, please send them using either context diffs or unified
diffs (using `diff -c' or `diff -u', respectively).  Please be careful
when using "cut and paste" or other such means to copy a patch into a
bug report; depending on the system being used, that can result in
converting TAB characters into spaces, which makes applying the patches
more difficult.

The `krb5-send-pr' program is installed in the directory
`/usr/local/sbin'.

The `krb5-send-pr' program enters the problem report into our Problem
Report Management System (PRMS), which automatically assigns it to the
engineer best able to help you with problems in the assigned category.

The `krb5-send-pr' program will try to intelligently fill in as many
fields as it can.  You need to choose the "category", "class",
"severity", and "priority" of the problem, as well as giving us as much
information as you can about its exact nature.

The PR category will be one of:

     krb5-admin   krb5-appl    krb5-build   krb5-clients
     krb5-doc     krb5-kdc     krb5-libs    krb5-misc
     pty          telnet       test

Choose the category that best describes the area under which your
problem falls.

The class can be "sw-bug", "doc-bug", "change-request", or "support".
The first two are exactly as their names imply.  Use change-request
when the software is behaving according to specifications, but you want
to request changes in some feature or behavior.  The support class is
intended for more general questions about building or using Kerberos V5.

The severity of the problem indicates the problem's impact on the
usability of Kerberos V5.  If a problem is "critical", that means the
product, component or concept is completely non-operational, or some
essential functionality is missing, and no workaround is known.  A
"serious" problem is one in which the product, component or concept is
not working properly or significant functionality is missing.  Problems
that would otherwise be considered critical are rated serious when a
workaround is known.  A "non-critical" problem is one that is indeed a
problem, but one that is having a minimal effect on your ability to use
Kerberos V5.  E.g., The product, component or concept is working in
general, but lacks features, has irritating behavior, does something
wrong, or doesn't match its documentation.  The default severity is
serious.

The priority indicates how urgent this particular problem is in
relation to your work.  Note that low priority does not imply low
importance.  A priority of "high" means a solution is needed as soon as
possible.  A priority of "medium" means the problem should be solved no
later than the next release.  A priority of "low" means the problem
should be solved in a future release, but it is not important to your
work how soon this happens.  The default priority is medium.

Note that a given severity does not necessarily imply a given priority.
For example, a non-critical problem might still have a high priority if
you are faced with a hard deadline.  Conversely, a serious problem might
have a low priority if the feature it is disabling is one that you do
not need.

It is important that you fill in the release field and tell us what
changes you have made, if any.

Bug reports that include proposed fixes are especially welcome.  If you
include proposed fixes, please send them using either context diffs
(`diff -c') or unified diffs (`diff -u').

A sample filled-out form from a company named "Toasters, Inc." might
look like this:

     To: krb5-bugs@mit.edu
     Subject: misspelled "Kerberos" in title of installation guide
     From: jcb
     Reply-To: jcb
     Cc:
     X-send-pr-version: 3.99
     
     
     >Submitter-Id:	mit
     >Originator:	Jeffrey C. Gilman Bigler
     >Organization:
     mit
     >Confidential:	no
     >Synopsis:	Misspelled "Kerberos" in title of installation guide
     >Severity:	non-critical
     >Priority:	low
     >Category:	krb5-doc
     >Class:		doc-bug
     >Release:	1.0-development
     >Environment:
     	<machine, os, target, libraries (multiple lines)>
     System: ULTRIX imbrium 4.2 0 RISC
     Machine: mips
     >Description:
             Misspelled "Kerberos" in title of "Kerboros V5 Installation Guide"
     >How-To-Repeat:
             N/A
     >Fix:
             Correct the spelling.

If the `krb5-send-pr' program does not work for you, or if you did not
get far enough in the process to have an installed and working
`krb5-send-pr', you can generate your own form, using the above as an
example.


File: krb5-admin.info,  Node: Appendix,  Prev: Bug Reporting,  Up: Top

Appendix
********

* Menu:

* Errors::
* kadmin Time Zones::


File: krb5-admin.info,  Node: Errors,  Next: kadmin Time Zones,  Prev: Appendix,  Up: Appendix

Kerberos Error Messages
=======================

* Menu:

* Kerberos V5 Library Error Codes::
* Kerberos V5 Database Library Error Codes::
* Kerberos V5 Magic Numbers Error Codes::
* ASN.1 Error Codes::
* GSSAPI Error Codes::

