<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Database administration — MIT Kerberos Documentation</title>
<link rel="stylesheet" href="../_static/agogo.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<link rel="stylesheet" type="text/css" href="../_static/kerb.css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/language_data.js"></script>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="Database types" href="dbtypes.html" />
<link rel="prev" title="Realm configuration decisions" href="realm_config.html" />
</head><body>
<div class="header-wrapper">
<div class="header">
<h1><a href="../index.html">MIT Kerberos Documentation</a></h1>
<div class="rel">
<a href="../index.html" title="Full Table of Contents"
accesskey="C">Contents</a> |
<a href="realm_config.html" title="Realm configuration decisions"
accesskey="P">previous</a> |
<a href="dbtypes.html" title="Database types"
accesskey="N">next</a> |
<a href="../genindex.html" title="General Index"
accesskey="I">index</a> |
<a href="../search.html" title="Enter search criteria"
accesskey="S">Search</a> |
<a href="mailto:krb5-bugs@mit.edu?subject=Documentation__Database administration">feedback</a>
</div>
</div>
</div>
<div class="content-wrapper">
<div class="content">
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="database-administration">
<h1>Database administration<a class="headerlink" href="#database-administration" title="Permalink to this headline">¶</a></h1>
<p>A Kerberos database contains all of a realm’s Kerberos principals,
their passwords, and other administrative information about each
principal. For the most part, you will use the <a class="reference internal" href="admin_commands/kdb5_util.html#kdb5-util-8"><span class="std std-ref">kdb5_util</span></a>
program to manipulate the Kerberos database as a whole, and the
<a class="reference internal" href="admin_commands/kadmin_local.html#kadmin-1"><span class="std std-ref">kadmin</span></a> program to make changes to the entries in the
database. (One notable exception is that users will use the
<a class="reference internal" href="../user/user_commands/kpasswd.html#kpasswd-1"><span class="std std-ref">kpasswd</span></a> program to change their own passwords.) The kadmin
program has its own command-line interface, to which you type the
database administrating commands.</p>
<p><a class="reference internal" href="admin_commands/kdb5_util.html#kdb5-util-8"><span class="std std-ref">kdb5_util</span></a> provides a means to create, delete, load, or dump
a Kerberos database. It also contains commands to roll over the
database master key, and to stash a copy of the key so that the
<a class="reference internal" href="admin_commands/kadmind.html#kadmind-8"><span class="std std-ref">kadmind</span></a> and <a class="reference internal" href="admin_commands/krb5kdc.html#krb5kdc-8"><span class="std std-ref">krb5kdc</span></a> daemons can use the database
without manual input.</p>
<p><a class="reference internal" href="admin_commands/kadmin_local.html#kadmin-1"><span class="std std-ref">kadmin</span></a> provides for the maintenance of Kerberos principals,
password policies, and service key tables (keytabs). Normally it
operates as a network client using Kerberos authentication to
communicate with <a class="reference internal" href="admin_commands/kadmind.html#kadmind-8"><span class="std std-ref">kadmind</span></a>, but there is also a variant, named
kadmin.local, which directly accesses the Kerberos database on the
local filesystem (or through LDAP). kadmin.local is necessary to set
up enough of the database to be able to use the remote version.</p>
<p>kadmin can authenticate to the admin server using the service
principal <code class="docutils literal notranslate"><span class="pre">kadmin/HOST</span></code> (where <em>HOST</em> is the hostname of the admin
server) or <code class="docutils literal notranslate"><span class="pre">kadmin/admin</span></code>. If the credentials cache contains a
ticket for either service principal and the <strong>-c</strong> ccache option is
specified, that ticket is used to authenticate to KADM5. Otherwise,
the <strong>-p</strong> and <strong>-k</strong> options are used to specify the client Kerberos
principal name used to authenticate. Once kadmin has determined the
principal name, it requests a <code class="docutils literal notranslate"><span class="pre">kadmin/admin</span></code> Kerberos service ticket
from the KDC, and uses that service ticket to authenticate to KADM5.</p>
<p>See <a class="reference internal" href="admin_commands/kadmin_local.html#kadmin-1"><span class="std std-ref">kadmin</span></a> for the available kadmin and kadmin.local
commands and options.</p>
<div class="section" id="kadmin-options">
<h2>kadmin options<a class="headerlink" href="#kadmin-options" title="Permalink to this headline">¶</a></h2>
<p>You can invoke <a class="reference internal" href="admin_commands/kadmin_local.html#kadmin-1"><span class="std std-ref">kadmin</span></a> or kadmin.local with any of the
following options:</p>
<p><strong>kadmin</strong>
[<strong>-O</strong>|<strong>-N</strong>]
[<strong>-r</strong> <em>realm</em>]
[<strong>-p</strong> <em>principal</em>]
[<strong>-q</strong> <em>query</em>]
[[<strong>-c</strong> <em>cache_name</em>]|[<strong>-k</strong> [<strong>-t</strong> <em>keytab</em>]]|<strong>-n</strong>]
[<strong>-w</strong> <em>password</em>]
[<strong>-s</strong> <em>admin_server</em>[:<em>port</em>]]
[command args…]</p>
<p><strong>kadmin.local</strong>
[<strong>-r</strong> <em>realm</em>]
[<strong>-p</strong> <em>principal</em>]
[<strong>-q</strong> <em>query</em>]
[<strong>-d</strong> <em>dbname</em>]
[<strong>-e</strong> <em>enc</em>:<em>salt</em> …]
[<strong>-m</strong>]
[<strong>-x</strong> <em>db_args</em>]
[command args…]</p>
<p><strong>OPTIONS</strong></p>
<dl class="docutils">
<dt><strong>-r</strong> <em>realm</em></dt>
<dd>Use <em>realm</em> as the default database realm.</dd>
<dt><strong>-p</strong> <em>principal</em></dt>
<dd>Use <em>principal</em> to authenticate. Otherwise, kadmin will append
<code class="docutils literal notranslate"><span class="pre">/admin</span></code> to the primary principal name of the default ccache,
the value of the <strong>USER</strong> environment variable, or the username as
obtained with getpwuid, in order of preference.</dd>
<dt><strong>-k</strong></dt>
<dd>Use a keytab to decrypt the KDC response instead of prompting for
a password. In this case, the default principal will be
<code class="docutils literal notranslate"><span class="pre">host/hostname</span></code>. If there is no keytab specified with the
<strong>-t</strong> option, then the default keytab will be used.</dd>
<dt><strong>-t</strong> <em>keytab</em></dt>
<dd>Use <em>keytab</em> to decrypt the KDC response. This can only be used
with the <strong>-k</strong> option.</dd>
<dt><strong>-n</strong></dt>
<dd>Requests anonymous processing. Two types of anonymous principals
are supported. For fully anonymous Kerberos, configure PKINIT on
the KDC and configure <strong>pkinit_anchors</strong> in the client’s
<a class="reference internal" href="conf_files/krb5_conf.html#krb5-conf-5"><span class="std std-ref">krb5.conf</span></a>. Then use the <strong>-n</strong> option with a principal
of the form <code class="docutils literal notranslate"><span class="pre">@REALM</span></code> (an empty principal name followed by the
at-sign and a realm name). If permitted by the KDC, an anonymous
ticket will be returned. A second form of anonymous tickets is
supported; these realm-exposed tickets hide the identity of the
client but not the client’s realm. For this mode, use <code class="docutils literal notranslate"><span class="pre">kinit</span>
<span class="pre">-n</span></code> with a normal principal name. If supported by the KDC, the
principal (but not realm) will be replaced by the anonymous
principal. As of release 1.8, the MIT Kerberos KDC only supports
fully anonymous operation.</dd>
<dt><strong>-c</strong> <em>credentials_cache</em></dt>
<dd>Use <em>credentials_cache</em> as the credentials cache. The
cache should contain a service ticket for the <code class="docutils literal notranslate"><span class="pre">kadmin/ADMINHOST</span></code>
(where <em>ADMINHOST</em> is the fully-qualified hostname of the admin
server) or <code class="docutils literal notranslate"><span class="pre">kadmin/admin</span></code> service; it can be acquired with the
<a class="reference internal" href="../user/user_commands/kinit.html#kinit-1"><span class="std std-ref">kinit</span></a> program. If this option is not specified, kadmin
requests a new service ticket from the KDC, and stores it in its
own temporary ccache.</dd>
<dt><strong>-w</strong> <em>password</em></dt>
<dd>Use <em>password</em> instead of prompting for one. Use this option with
care, as it may expose the password to other users on the system
via the process list.</dd>
<dt><strong>-q</strong> <em>query</em></dt>
<dd>Perform the specified query and then exit.</dd>
<dt><strong>-d</strong> <em>dbname</em></dt>
<dd>Specifies the name of the KDC database. This option does not
apply to the LDAP database module.</dd>
<dt><strong>-s</strong> <em>admin_server</em>[:<em>port</em>]</dt>
<dd>Specifies the admin server which kadmin should contact.</dd>
<dt><strong>-m</strong></dt>
<dd>If using kadmin.local, prompt for the database master password
instead of reading it from a stash file.</dd>
<dt><strong>-e</strong> “<em>enc</em>:<em>salt</em> …”</dt>
<dd>Sets the keysalt list to be used for any new keys created. See
<a class="reference internal" href="conf_files/kdc_conf.html#keysalt-lists"><span class="std std-ref">Keysalt lists</span></a> in <a class="reference internal" href="conf_files/kdc_conf.html#kdc-conf-5"><span class="std std-ref">kdc.conf</span></a> for a list of possible
values.</dd>
<dt><strong>-O</strong></dt>
<dd>Force use of old AUTH_GSSAPI authentication flavor.</dd>
<dt><strong>-N</strong></dt>
<dd>Prevent fallback to AUTH_GSSAPI authentication flavor.</dd>
<dt><strong>-x</strong> <em>db_args</em></dt>
<dd>Specifies the database specific arguments. See the next section
for supported options.</dd>
</dl>
</div>
<div class="section" id="date-format">
<h2>Date Format<a class="headerlink" href="#date-format" title="Permalink to this headline">¶</a></h2>
<p>For the supported date-time formats see <a class="reference internal" href="../basic/date_format.html#getdate"><span class="std std-ref">getdate time</span></a> section
in <a class="reference internal" href="../basic/date_format.html#datetime"><span class="std std-ref">Supported date and time formats</span></a>.</p>
</div>
<div class="section" id="principals">
<h2>Principals<a class="headerlink" href="#principals" title="Permalink to this headline">¶</a></h2>
<p>Each entry in the Kerberos database contains a Kerberos principal and
the attributes and policies associated with that principal.</p>
<div class="section" id="adding-modifying-and-deleting-principals">
<span id="add-mod-del-princs"></span><h3>Adding, modifying and deleting principals<a class="headerlink" href="#adding-modifying-and-deleting-principals" title="Permalink to this headline">¶</a></h3>
<p>To add a principal to the database, use the <a class="reference internal" href="admin_commands/kadmin_local.html#kadmin-1"><span class="std std-ref">kadmin</span></a>
<strong>add_principal</strong> command.</p>
<p>To modify attributes of a principal, use the kadmin
<strong>modify_principal</strong> command.</p>
<p>To delete a principal, use the kadmin <strong>delete_principal</strong> command.</p>
</div>
<div class="section" id="add-principal">
<h3>add_principal<a class="headerlink" href="#add-principal" title="Permalink to this headline">¶</a></h3>
<blockquote>
<div><strong>add_principal</strong> [<em>options</em>] <em>newprinc</em></div></blockquote>
<p>Creates the principal <em>newprinc</em>, prompting twice for a password. If
no password policy is specified with the <strong>-policy</strong> option, and the
policy named <code class="docutils literal notranslate"><span class="pre">default</span></code> is assigned to the principal if it exists.
However, creating a policy named <code class="docutils literal notranslate"><span class="pre">default</span></code> will not automatically
assign this policy to previously existing principals. This policy
assignment can be suppressed with the <strong>-clearpolicy</strong> option.</p>
<p>This command requires the <strong>add</strong> privilege.</p>
<p>Aliases: <strong>addprinc</strong>, <strong>ank</strong></p>
<p>Options:</p>
<dl class="docutils">
<dt><strong>-expire</strong> <em>expdate</em></dt>
<dd>(<a class="reference internal" href="../basic/date_format.html#getdate"><span class="std std-ref">getdate time</span></a> string) The expiration date of the principal.</dd>
<dt><strong>-pwexpire</strong> <em>pwexpdate</em></dt>
<dd>(<a class="reference internal" href="../basic/date_format.html#getdate"><span class="std std-ref">getdate time</span></a> string) The password expiration date.</dd>
<dt><strong>-maxlife</strong> <em>maxlife</em></dt>
<dd>(<a class="reference internal" href="../basic/date_format.html#duration"><span class="std std-ref">Time duration</span></a> or <a class="reference internal" href="../basic/date_format.html#getdate"><span class="std std-ref">getdate time</span></a> string) The maximum ticket life
for the principal.</dd>
<dt><strong>-maxrenewlife</strong> <em>maxrenewlife</em></dt>
<dd>(<a class="reference internal" href="../basic/date_format.html#duration"><span class="std std-ref">Time duration</span></a> or <a class="reference internal" href="../basic/date_format.html#getdate"><span class="std std-ref">getdate time</span></a> string) The maximum renewable
life of tickets for the principal.</dd>
<dt><strong>-kvno</strong> <em>kvno</em></dt>
<dd>The initial key version number.</dd>
<dt><strong>-policy</strong> <em>policy</em></dt>
<dd>The password policy used by this principal. If not specified, the
policy <code class="docutils literal notranslate"><span class="pre">default</span></code> is used if it exists (unless <strong>-clearpolicy</strong>
is specified).</dd>
<dt><strong>-clearpolicy</strong></dt>
<dd>Prevents any policy from being assigned when <strong>-policy</strong> is not
specified.</dd>
<dt>{-|+}<strong>allow_postdated</strong></dt>
<dd><strong>-allow_postdated</strong> prohibits this principal from obtaining
postdated tickets. <strong>+allow_postdated</strong> clears this flag.</dd>
<dt>{-|+}<strong>allow_forwardable</strong></dt>
<dd><strong>-allow_forwardable</strong> prohibits this principal from obtaining
forwardable tickets. <strong>+allow_forwardable</strong> clears this flag.</dd>
<dt>{-|+}<strong>allow_renewable</strong></dt>
<dd><strong>-allow_renewable</strong> prohibits this principal from obtaining
renewable tickets. <strong>+allow_renewable</strong> clears this flag.</dd>
<dt>{-|+}<strong>allow_proxiable</strong></dt>
<dd><strong>-allow_proxiable</strong> prohibits this principal from obtaining
proxiable tickets. <strong>+allow_proxiable</strong> clears this flag.</dd>
<dt>{-|+}<strong>allow_dup_skey</strong></dt>
<dd><strong>-allow_dup_skey</strong> disables user-to-user authentication for this
principal by prohibiting others from obtaining a service ticket
encrypted in this principal’s TGT session key.
<strong>+allow_dup_skey</strong> clears this flag.</dd>
<dt>{-|+}<strong>requires_preauth</strong></dt>
<dd><strong>+requires_preauth</strong> requires this principal to preauthenticate
before being allowed to kinit. <strong>-requires_preauth</strong> clears this
flag. When <strong>+requires_preauth</strong> is set on a service principal,
the KDC will only issue service tickets for that service principal
if the client’s initial authentication was performed using
preauthentication.</dd>
<dt>{-|+}<strong>requires_hwauth</strong></dt>
<dd><strong>+requires_hwauth</strong> requires this principal to preauthenticate
using a hardware device before being allowed to kinit.
<strong>-requires_hwauth</strong> clears this flag. When <strong>+requires_hwauth</strong> is
set on a service principal, the KDC will only issue service tickets
for that service principal if the client’s initial authentication was
performed using a hardware device to preauthenticate.</dd>
<dt>{-|+}<strong>ok_as_delegate</strong></dt>
<dd><strong>+ok_as_delegate</strong> sets the <strong>okay as delegate</strong> flag on tickets
issued with this principal as the service. Clients may use this
flag as a hint that credentials should be delegated when
authenticating to the service. <strong>-ok_as_delegate</strong> clears this
flag.</dd>
<dt>{-|+}<strong>allow_svr</strong></dt>
<dd><strong>-allow_svr</strong> prohibits the issuance of service tickets for this
principal. In release 1.17 and later, user-to-user service
tickets are still allowed unless the <strong>-allow_dup_skey</strong> flag is
also set. <strong>+allow_svr</strong> clears this flag.</dd>
<dt>{-|+}<strong>allow_tgs_req</strong></dt>
<dd><strong>-allow_tgs_req</strong> specifies that a Ticket-Granting Service (TGS)
request for a service ticket for this principal is not permitted.
<strong>+allow_tgs_req</strong> clears this flag.</dd>
<dt>{-|+}<strong>allow_tix</strong></dt>
<dd><strong>-allow_tix</strong> forbids the issuance of any tickets for this
principal. <strong>+allow_tix</strong> clears this flag.</dd>
<dt>{-|+}<strong>needchange</strong></dt>
<dd><strong>+needchange</strong> forces a password change on the next initial
authentication to this principal. <strong>-needchange</strong> clears this
flag.</dd>
<dt>{-|+}<strong>password_changing_service</strong></dt>
<dd><strong>+password_changing_service</strong> marks this principal as a password
change service principal.</dd>
<dt>{-|+}<strong>ok_to_auth_as_delegate</strong></dt>
<dd><strong>+ok_to_auth_as_delegate</strong> allows this principal to acquire
forwardable tickets to itself from arbitrary users, for use with
constrained delegation.</dd>
<dt>{-|+}<strong>no_auth_data_required</strong></dt>
<dd><strong>+no_auth_data_required</strong> prevents PAC or AD-SIGNEDPATH data from
being added to service tickets for the principal.</dd>
<dt>{-|+}<strong>lockdown_keys</strong></dt>
<dd><strong>+lockdown_keys</strong> prevents keys for this principal from leaving
the KDC via kadmind. The chpass and extract operations are denied
for a principal with this attribute. The chrand operation is
allowed, but will not return the new keys. The delete and rename
operations are also denied if this attribute is set, in order to
prevent a malicious administrator from replacing principals like
krbtgt/* or kadmin/* with new principals without the attribute.
This attribute can be set via the network protocol, but can only
be removed using kadmin.local.</dd>
<dt><strong>-randkey</strong></dt>
<dd>Sets the key of the principal to a random value.</dd>
<dt><strong>-nokey</strong></dt>
<dd>Causes the principal to be created with no key. New in release
1.12.</dd>
<dt><strong>-pw</strong> <em>password</em></dt>
<dd>Sets the password of the principal to the specified string and
does not prompt for a password. Note: using this option in a
shell script may expose the password to other users on the system
via the process list.</dd>
<dt><strong>-e</strong> <em>enc</em>:<em>salt</em>,…</dt>
<dd>Uses the specified keysalt list for setting the keys of the
principal. See <a class="reference internal" href="conf_files/kdc_conf.html#keysalt-lists"><span class="std std-ref">Keysalt lists</span></a> in <a class="reference internal" href="conf_files/kdc_conf.html#kdc-conf-5"><span class="std std-ref">kdc.conf</span></a> for a
list of possible values.</dd>
<dt><strong>-x</strong> <em>db_princ_args</em></dt>
<dd><p class="first">Indicates database-specific options. The options for the LDAP
database module are:</p>
<dl class="docutils">
<dt><strong>-x dn=</strong><em>dn</em></dt>
<dd>Specifies the LDAP object that will contain the Kerberos
principal being created.</dd>
<dt><strong>-x linkdn=</strong><em>dn</em></dt>
<dd>Specifies the LDAP object to which the newly created Kerberos
principal object will point.</dd>
<dt><strong>-x containerdn=</strong><em>container_dn</em></dt>
<dd>Specifies the container object under which the Kerberos
principal is to be created.</dd>
<dt><strong>-x tktpolicy=</strong><em>policy</em></dt>
<dd>Associates a ticket policy to the Kerberos principal.</dd>
</dl>
<div class="last admonition note">
<p class="first admonition-title">Note</p>
<ul class="last simple">
<li>The <strong>containerdn</strong> and <strong>linkdn</strong> options cannot be
specified with the <strong>dn</strong> option.</li>
<li>If the <em>dn</em> or <em>containerdn</em> options are not specified while
adding the principal, the principals are created under the
principal container configured in the realm or the realm
container.</li>
<li><em>dn</em> and <em>containerdn</em> should be within the subtrees or
principal container configured in the realm.</li>
</ul>
</div>
</dd>
</dl>
<p>Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">kadmin</span><span class="p">:</span> <span class="n">addprinc</span> <span class="n">jennifer</span>
<span class="n">WARNING</span><span class="p">:</span> <span class="n">no</span> <span class="n">policy</span> <span class="n">specified</span> <span class="k">for</span> <span class="s2">"jennifer@ATHENA.MIT.EDU"</span><span class="p">;</span>
<span class="n">defaulting</span> <span class="n">to</span> <span class="n">no</span> <span class="n">policy</span><span class="o">.</span>
<span class="n">Enter</span> <span class="n">password</span> <span class="k">for</span> <span class="n">principal</span> <span class="n">jennifer</span><span class="nd">@ATHENA</span><span class="o">.</span><span class="n">MIT</span><span class="o">.</span><span class="n">EDU</span><span class="p">:</span>
<span class="n">Re</span><span class="o">-</span><span class="n">enter</span> <span class="n">password</span> <span class="k">for</span> <span class="n">principal</span> <span class="n">jennifer</span><span class="nd">@ATHENA</span><span class="o">.</span><span class="n">MIT</span><span class="o">.</span><span class="n">EDU</span><span class="p">:</span>
<span class="n">Principal</span> <span class="s2">"jennifer@ATHENA.MIT.EDU"</span> <span class="n">created</span><span class="o">.</span>
<span class="n">kadmin</span><span class="p">:</span>
</pre></div>
</div>
</div>
<div class="section" id="modify-principal">
<h3>modify_principal<a class="headerlink" href="#modify-principal" title="Permalink to this headline">¶</a></h3>
<blockquote>
<div><strong>modify_principal</strong> [<em>options</em>] <em>principal</em></div></blockquote>
<p>Modifies the specified principal, changing the fields as specified.
The options to <strong>add_principal</strong> also apply to this command, except
for the <strong>-randkey</strong>, <strong>-pw</strong>, and <strong>-e</strong> options. In addition, the
option <strong>-clearpolicy</strong> will clear the current policy of a principal.</p>
<p>This command requires the <em>modify</em> privilege.</p>
<p>Alias: <strong>modprinc</strong></p>
<p>Options (in addition to the <strong>addprinc</strong> options):</p>
<dl class="docutils">
<dt><strong>-unlock</strong></dt>
<dd>Unlocks a locked principal (one which has received too many failed
authentication attempts without enough time between them according
to its password policy) so that it can successfully authenticate.</dd>
</dl>
</div>
<div class="section" id="delete-principal">
<h3>delete_principal<a class="headerlink" href="#delete-principal" title="Permalink to this headline">¶</a></h3>
<blockquote>
<div><strong>delete_principal</strong> [<strong>-force</strong>] <em>principal</em></div></blockquote>
<p>Deletes the specified <em>principal</em> from the database. This command
prompts for deletion, unless the <strong>-force</strong> option is given.</p>
<p>This command requires the <strong>delete</strong> privilege.</p>
<p>Alias: <strong>delprinc</strong></p>
<div class="section" id="examples">
<h4>Examples<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h4>
<p>If you want to create a principal which is contained by a LDAP object,
all you need to do is:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">kadmin</span><span class="p">:</span> <span class="n">addprinc</span> <span class="o">-</span><span class="n">x</span> <span class="n">dn</span><span class="o">=</span><span class="n">cn</span><span class="o">=</span><span class="n">jennifer</span><span class="p">,</span><span class="n">dc</span><span class="o">=</span><span class="n">example</span><span class="p">,</span><span class="n">dc</span><span class="o">=</span><span class="n">com</span> <span class="n">jennifer</span>
<span class="n">WARNING</span><span class="p">:</span> <span class="n">no</span> <span class="n">policy</span> <span class="n">specified</span> <span class="k">for</span> <span class="s2">"jennifer@ATHENA.MIT.EDU"</span><span class="p">;</span>
<span class="n">defaulting</span> <span class="n">to</span> <span class="n">no</span> <span class="n">policy</span><span class="o">.</span>
<span class="n">Enter</span> <span class="n">password</span> <span class="k">for</span> <span class="n">principal</span> <span class="n">jennifer</span><span class="nd">@ATHENA</span><span class="o">.</span><span class="n">MIT</span><span class="o">.</span><span class="n">EDU</span><span class="p">:</span> <span class="o"><=</span> <span class="n">Type</span> <span class="n">the</span> <span class="n">password</span><span class="o">.</span>
<span class="n">Re</span><span class="o">-</span><span class="n">enter</span> <span class="n">password</span> <span class="k">for</span> <span class="n">principal</span> <span class="n">jennifer</span><span class="nd">@ATHENA</span><span class="o">.</span><span class="n">MIT</span><span class="o">.</span><span class="n">EDU</span><span class="p">:</span> <span class="o"><=</span><span class="n">Type</span> <span class="n">it</span> <span class="n">again</span><span class="o">.</span>
<span class="n">Principal</span> <span class="s2">"jennifer@ATHENA.MIT.EDU"</span> <span class="n">created</span><span class="o">.</span>
<span class="n">kadmin</span><span class="p">:</span>
</pre></div>
</div>
<p>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:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">kadmin</span><span class="p">:</span> <span class="n">addprinc</span> <span class="o">-</span><span class="n">x</span> <span class="n">containerdn</span><span class="o">=</span><span class="n">dc</span><span class="o">=</span><span class="n">example</span><span class="p">,</span><span class="n">dc</span><span class="o">=</span><span class="n">com</span> <span class="o">-</span><span class="n">x</span> <span class="n">linkdn</span><span class="o">=</span><span class="n">cn</span><span class="o">=</span><span class="n">david</span><span class="p">,</span><span class="n">dc</span><span class="o">=</span><span class="n">example</span><span class="p">,</span><span class="n">dc</span><span class="o">=</span><span class="n">com</span> <span class="n">david</span>
<span class="n">WARNING</span><span class="p">:</span> <span class="n">no</span> <span class="n">policy</span> <span class="n">specified</span> <span class="k">for</span> <span class="s2">"david@ATHENA.MIT.EDU"</span><span class="p">;</span>
<span class="n">defaulting</span> <span class="n">to</span> <span class="n">no</span> <span class="n">policy</span><span class="o">.</span>
<span class="n">Enter</span> <span class="n">password</span> <span class="k">for</span> <span class="n">principal</span> <span class="n">david</span><span class="nd">@ATHENA</span><span class="o">.</span><span class="n">MIT</span><span class="o">.</span><span class="n">EDU</span><span class="p">:</span> <span class="o"><=</span> <span class="n">Type</span> <span class="n">the</span> <span class="n">password</span><span class="o">.</span>
<span class="n">Re</span><span class="o">-</span><span class="n">enter</span> <span class="n">password</span> <span class="k">for</span> <span class="n">principal</span> <span class="n">david</span><span class="nd">@ATHENA</span><span class="o">.</span><span class="n">MIT</span><span class="o">.</span><span class="n">EDU</span><span class="p">:</span> <span class="o"><=</span><span class="n">Type</span> <span class="n">it</span> <span class="n">again</span><span class="o">.</span>
<span class="n">Principal</span> <span class="s2">"david@ATHENA.MIT.EDU"</span> <span class="n">created</span><span class="o">.</span>
<span class="n">kadmin</span><span class="p">:</span>
</pre></div>
</div>
<p>If you want to associate a ticket policy to a principal, all you need
to do is:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">kadmin</span><span class="p">:</span> <span class="n">modprinc</span> <span class="o">-</span><span class="n">x</span> <span class="n">tktpolicy</span><span class="o">=</span><span class="n">userpolicy</span> <span class="n">david</span>
<span class="n">Principal</span> <span class="s2">"david@ATHENA.MIT.EDU"</span> <span class="n">modified</span><span class="o">.</span>
<span class="n">kadmin</span><span class="p">:</span>
</pre></div>
</div>
<p>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:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">kadmin</span><span class="p">:</span> <span class="n">addprinc</span> <span class="n">david</span> <span class="o">-</span><span class="n">expire</span> <span class="s2">"1/1/2000 12:01am EST"</span> <span class="o">-</span><span class="n">policy</span> <span class="n">stduser</span> <span class="o">+</span><span class="n">needchange</span>
<span class="n">Enter</span> <span class="n">password</span> <span class="k">for</span> <span class="n">principal</span> <span class="n">david</span><span class="nd">@ATHENA</span><span class="o">.</span><span class="n">MIT</span><span class="o">.</span><span class="n">EDU</span><span class="p">:</span> <span class="o"><=</span> <span class="n">Type</span> <span class="n">the</span> <span class="n">password</span><span class="o">.</span>
<span class="n">Re</span><span class="o">-</span><span class="n">enter</span> <span class="n">password</span> <span class="k">for</span> <span class="n">principal</span>
<span class="n">david</span><span class="nd">@ATHENA</span><span class="o">.</span><span class="n">MIT</span><span class="o">.</span><span class="n">EDU</span><span class="p">:</span> <span class="o"><=</span> <span class="n">Type</span> <span class="n">it</span> <span class="n">again</span><span class="o">.</span>
<span class="n">Principal</span> <span class="s2">"david@ATHENA.MIT.EDU"</span> <span class="n">created</span><span class="o">.</span>
<span class="n">kadmin</span><span class="p">:</span>
</pre></div>
</div>
<p>If you want to delete a principal:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>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:
</pre></div>
</div>
</div>
</div>
<div class="section" id="retrieving-information-about-a-principal">
<h3>Retrieving information about a principal<a class="headerlink" href="#retrieving-information-about-a-principal" title="Permalink to this headline">¶</a></h3>
<p>To retrieve a listing of the attributes and/or policies associated
with a principal, use the <a class="reference internal" href="admin_commands/kadmin_local.html#kadmin-1"><span class="std std-ref">kadmin</span></a> <strong>get_principal</strong> command.</p>
<p>To generate a listing of principals, use the kadmin
<strong>list_principals</strong> command.</p>
</div>
<div class="section" id="get-principal">
<h3>get_principal<a class="headerlink" href="#get-principal" title="Permalink to this headline">¶</a></h3>
<blockquote>
<div><strong>get_principal</strong> [<strong>-terse</strong>] <em>principal</em></div></blockquote>
<p>Gets the attributes of principal. With the <strong>-terse</strong> option, outputs
fields as quoted tab-separated strings.</p>
<p>This command requires the <strong>inquire</strong> privilege, or that the principal
running the the program to be the same as the one being listed.</p>
<p>Alias: <strong>getprinc</strong></p>
<p>Examples:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">kadmin</span><span class="p">:</span> <span class="n">getprinc</span> <span class="n">tlyu</span><span class="o">/</span><span class="n">admin</span>
<span class="n">Principal</span><span class="p">:</span> <span class="n">tlyu</span><span class="o">/</span><span class="n">admin</span><span class="nd">@BLEEP</span><span class="o">.</span><span class="n">COM</span>
<span class="n">Expiration</span> <span class="n">date</span><span class="p">:</span> <span class="p">[</span><span class="n">never</span><span class="p">]</span>
<span class="n">Last</span> <span class="n">password</span> <span class="n">change</span><span class="p">:</span> <span class="n">Mon</span> <span class="n">Aug</span> <span class="mi">12</span> <span class="mi">14</span><span class="p">:</span><span class="mi">16</span><span class="p">:</span><span class="mi">47</span> <span class="n">EDT</span> <span class="mi">1996</span>
<span class="n">Password</span> <span class="n">expiration</span> <span class="n">date</span><span class="p">:</span> <span class="p">[</span><span class="n">none</span><span class="p">]</span>
<span class="n">Maximum</span> <span class="n">ticket</span> <span class="n">life</span><span class="p">:</span> <span class="mi">0</span> <span class="n">days</span> <span class="mi">10</span><span class="p">:</span><span class="mi">00</span><span class="p">:</span><span class="mi">00</span>
<span class="n">Maximum</span> <span class="n">renewable</span> <span class="n">life</span><span class="p">:</span> <span class="mi">7</span> <span class="n">days</span> <span class="mi">00</span><span class="p">:</span><span class="mi">00</span><span class="p">:</span><span class="mi">00</span>
<span class="n">Last</span> <span class="n">modified</span><span class="p">:</span> <span class="n">Mon</span> <span class="n">Aug</span> <span class="mi">12</span> <span class="mi">14</span><span class="p">:</span><span class="mi">16</span><span class="p">:</span><span class="mi">47</span> <span class="n">EDT</span> <span class="mi">1996</span> <span class="p">(</span><span class="n">bjaspan</span><span class="o">/</span><span class="n">admin</span><span class="nd">@BLEEP</span><span class="o">.</span><span class="n">COM</span><span class="p">)</span>
<span class="n">Last</span> <span class="n">successful</span> <span class="n">authentication</span><span class="p">:</span> <span class="p">[</span><span class="n">never</span><span class="p">]</span>
<span class="n">Last</span> <span class="n">failed</span> <span class="n">authentication</span><span class="p">:</span> <span class="p">[</span><span class="n">never</span><span class="p">]</span>
<span class="n">Failed</span> <span class="n">password</span> <span class="n">attempts</span><span class="p">:</span> <span class="mi">0</span>
<span class="n">Number</span> <span class="n">of</span> <span class="n">keys</span><span class="p">:</span> <span class="mi">2</span>
<span class="n">Key</span><span class="p">:</span> <span class="n">vno</span> <span class="mi">1</span><span class="p">,</span> <span class="n">des</span><span class="o">-</span><span class="n">cbc</span><span class="o">-</span><span class="n">crc</span>
<span class="n">Key</span><span class="p">:</span> <span class="n">vno</span> <span class="mi">1</span><span class="p">,</span> <span class="n">des</span><span class="o">-</span><span class="n">cbc</span><span class="o">-</span><span class="n">crc</span><span class="p">:</span><span class="n">v4</span>
<span class="n">Attributes</span><span class="p">:</span>
<span class="n">Policy</span><span class="p">:</span> <span class="p">[</span><span class="n">none</span><span class="p">]</span>
<span class="n">kadmin</span><span class="p">:</span> <span class="n">getprinc</span> <span class="o">-</span><span class="n">terse</span> <span class="n">systest</span>
<span class="n">systest</span><span class="nd">@BLEEP</span><span class="o">.</span><span class="n">COM</span> <span class="mi">3</span> <span class="mi">86400</span> <span class="mi">604800</span> <span class="mi">1</span>
<span class="mi">785926535</span> <span class="mi">753241234</span> <span class="mi">785900000</span>
<span class="n">tlyu</span><span class="o">/</span><span class="n">admin</span><span class="nd">@BLEEP</span><span class="o">.</span><span class="n">COM</span> <span class="mi">786100034</span> <span class="mi">0</span> <span class="mi">0</span>
<span class="n">kadmin</span><span class="p">:</span>
</pre></div>
</div>
</div>
<div class="section" id="list-principals">
<h3>list_principals<a class="headerlink" href="#list-principals" title="Permalink to this headline">¶</a></h3>
<blockquote>
<div><strong>list_principals</strong> [<em>expression</em>]</div></blockquote>
<p>Retrieves all or some principal names. <em>expression</em> is a shell-style
glob expression that can contain the wild-card characters <code class="docutils literal notranslate"><span class="pre">?</span></code>,
<code class="docutils literal notranslate"><span class="pre">*</span></code>, and <code class="docutils literal notranslate"><span class="pre">[]</span></code>. All principal names matching the expression are
printed. If no expression is provided, all principal names are
printed. If the expression does not contain an <code class="docutils literal notranslate"><span class="pre">@</span></code> character, an
<code class="docutils literal notranslate"><span class="pre">@</span></code> character followed by the local realm is appended to the
expression.</p>
<p>This command requires the <strong>list</strong> privilege.</p>
<p>Alias: <strong>listprincs</strong>, <strong>get_principals</strong>, <strong>get_princs</strong></p>
<p>Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">kadmin</span><span class="p">:</span> <span class="n">listprincs</span> <span class="n">test</span><span class="o">*</span>
<span class="n">test3</span><span class="nd">@SECURE</span><span class="o">-</span><span class="n">TEST</span><span class="o">.</span><span class="n">OV</span><span class="o">.</span><span class="n">COM</span>
<span class="n">test2</span><span class="nd">@SECURE</span><span class="o">-</span><span class="n">TEST</span><span class="o">.</span><span class="n">OV</span><span class="o">.</span><span class="n">COM</span>
<span class="n">test1</span><span class="nd">@SECURE</span><span class="o">-</span><span class="n">TEST</span><span class="o">.</span><span class="n">OV</span><span class="o">.</span><span class="n">COM</span>
<span class="n">testuser</span><span class="nd">@SECURE</span><span class="o">-</span><span class="n">TEST</span><span class="o">.</span><span class="n">OV</span><span class="o">.</span><span class="n">COM</span>
<span class="n">kadmin</span><span class="p">:</span>
</pre></div>
</div>
</div>
<div class="section" id="changing-passwords">
<h3>Changing passwords<a class="headerlink" href="#changing-passwords" title="Permalink to this headline">¶</a></h3>
<p>To change a principal’s password use the <a class="reference internal" href="admin_commands/kadmin_local.html#kadmin-1"><span class="std std-ref">kadmin</span></a>
<strong>change_password</strong> command.</p>
</div>
<div class="section" id="change-password">
<h3>change_password<a class="headerlink" href="#change-password" title="Permalink to this headline">¶</a></h3>
<blockquote>
<div><strong>change_password</strong> [<em>options</em>] <em>principal</em></div></blockquote>
<p>Changes the password of <em>principal</em>. Prompts for a new password if
neither <strong>-randkey</strong> or <strong>-pw</strong> is specified.</p>
<p>This command requires the <strong>changepw</strong> privilege, or that the
principal running the program is the same as the principal being
changed.</p>
<p>Alias: <strong>cpw</strong></p>
<p>The following options are available:</p>
<dl class="docutils">
<dt><strong>-randkey</strong></dt>
<dd>Sets the key of the principal to a random value.</dd>
<dt><strong>-pw</strong> <em>password</em></dt>
<dd>Set the password to the specified string. Using this option in a
script may expose the password to other users on the system via
the process list.</dd>
<dt><strong>-e</strong> <em>enc</em>:<em>salt</em>,…</dt>
<dd>Uses the specified keysalt list for setting the keys of the
principal. See <a class="reference internal" href="conf_files/kdc_conf.html#keysalt-lists"><span class="std std-ref">Keysalt lists</span></a> in <a class="reference internal" href="conf_files/kdc_conf.html#kdc-conf-5"><span class="std std-ref">kdc.conf</span></a> for a
list of possible values.</dd>
<dt><strong>-keepold</strong></dt>
<dd>Keeps the existing keys in the database. This flag is usually not
necessary except perhaps for <code class="docutils literal notranslate"><span class="pre">krbtgt</span></code> principals.</dd>
</dl>
<p>Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">kadmin</span><span class="p">:</span> <span class="n">cpw</span> <span class="n">systest</span>
<span class="n">Enter</span> <span class="n">password</span> <span class="k">for</span> <span class="n">principal</span> <span class="n">systest</span><span class="nd">@BLEEP</span><span class="o">.</span><span class="n">COM</span><span class="p">:</span>
<span class="n">Re</span><span class="o">-</span><span class="n">enter</span> <span class="n">password</span> <span class="k">for</span> <span class="n">principal</span> <span class="n">systest</span><span class="nd">@BLEEP</span><span class="o">.</span><span class="n">COM</span><span class="p">:</span>
<span class="n">Password</span> <span class="k">for</span> <span class="n">systest</span><span class="nd">@BLEEP</span><span class="o">.</span><span class="n">COM</span> <span class="n">changed</span><span class="o">.</span>
<span class="n">kadmin</span><span class="p">:</span>
</pre></div>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Password changes through kadmin are subject to the same
password policies as would apply to password changes through
<a class="reference internal" href="../user/user_commands/kpasswd.html#kpasswd-1"><span class="std std-ref">kpasswd</span></a>.</p>
</div>
</div>
</div>
<div class="section" id="policies">
<span id="id1"></span><h2>Policies<a class="headerlink" href="#policies" title="Permalink to this headline">¶</a></h2>
<p>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.</p>
<div class="section" id="adding-modifying-and-deleting-policies">
<h3>Adding, modifying and deleting policies<a class="headerlink" href="#adding-modifying-and-deleting-policies" title="Permalink to this headline">¶</a></h3>
<p>To add a new policy, use the <a class="reference internal" href="admin_commands/kadmin_local.html#kadmin-1"><span class="std std-ref">kadmin</span></a> <strong>add_policy</strong> command.</p>
<p>To modify attributes of a principal, use the kadmin <strong>modify_policy</strong>
command.</p>
<p>To delete a policy, use the kadmin <strong>delete_policy</strong> command.</p>
</div>
<div class="section" id="add-policy">
<h3>add_policy<a class="headerlink" href="#add-policy" title="Permalink to this headline">¶</a></h3>
<blockquote>
<div><strong>add_policy</strong> [<em>options</em>] <em>policy</em></div></blockquote>
<p>Adds a password policy named <em>policy</em> to the database.</p>
<p>This command requires the <strong>add</strong> privilege.</p>
<p>Alias: <strong>addpol</strong></p>
<p>The following options are available:</p>
<dl class="docutils">
<dt><strong>-maxlife</strong> <em>time</em></dt>
<dd>(<a class="reference internal" href="../basic/date_format.html#duration"><span class="std std-ref">Time duration</span></a> or <a class="reference internal" href="../basic/date_format.html#getdate"><span class="std std-ref">getdate time</span></a> string) Sets the maximum
lifetime of a password.</dd>
<dt><strong>-minlife</strong> <em>time</em></dt>
<dd>(<a class="reference internal" href="../basic/date_format.html#duration"><span class="std std-ref">Time duration</span></a> or <a class="reference internal" href="../basic/date_format.html#getdate"><span class="std std-ref">getdate time</span></a> string) Sets the minimum
lifetime of a password.</dd>
<dt><strong>-minlength</strong> <em>length</em></dt>
<dd>Sets the minimum length of a password.</dd>
<dt><strong>-minclasses</strong> <em>number</em></dt>
<dd>Sets the minimum number of character classes required in a
password. The five character classes are lower case, upper case,
numbers, punctuation, and whitespace/unprintable characters.</dd>
<dt><strong>-history</strong> <em>number</em></dt>
<dd>Sets the number of past keys kept for a principal. This option is
not supported with the LDAP KDC database module.</dd>
</dl>
<dl class="docutils" id="policy-maxfailure">
<dt><strong>-maxfailure</strong> <em>maxnumber</em></dt>
<dd>Sets the number of authentication failures before the principal is
locked. Authentication failures are only tracked for principals
which require preauthentication. The counter of failed attempts
resets to 0 after a successful attempt to authenticate. A
<em>maxnumber</em> value of 0 (the default) disables lockout.</dd>
</dl>
<dl class="docutils" id="policy-failurecountinterval">
<dt><strong>-failurecountinterval</strong> <em>failuretime</em></dt>
<dd>(<a class="reference internal" href="../basic/date_format.html#duration"><span class="std std-ref">Time duration</span></a> or <a class="reference internal" href="../basic/date_format.html#getdate"><span class="std std-ref">getdate time</span></a> string) Sets the allowable time
between authentication failures. If an authentication failure
happens after <em>failuretime</em> has elapsed since the previous
failure, the number of authentication failures is reset to 1. A
<em>failuretime</em> value of 0 (the default) means forever.</dd>
</dl>
<dl class="docutils" id="policy-lockoutduration">
<dt><strong>-lockoutduration</strong> <em>lockouttime</em></dt>
<dd>(<a class="reference internal" href="../basic/date_format.html#duration"><span class="std std-ref">Time duration</span></a> or <a class="reference internal" href="../basic/date_format.html#getdate"><span class="std std-ref">getdate time</span></a> string) Sets the duration for
which the principal is locked from authenticating if too many
authentication failures occur without the specified failure count
interval elapsing. A duration of 0 (the default) means the
principal remains locked out until it is administratively unlocked
with <code class="docutils literal notranslate"><span class="pre">modprinc</span> <span class="pre">-unlock</span></code>.</dd>
<dt><strong>-allowedkeysalts</strong></dt>
<dd>Specifies the key/salt tuples supported for long-term keys when
setting or changing a principal’s password/keys. See
<a class="reference internal" href="conf_files/kdc_conf.html#keysalt-lists"><span class="std std-ref">Keysalt lists</span></a> in <a class="reference internal" href="conf_files/kdc_conf.html#kdc-conf-5"><span class="std std-ref">kdc.conf</span></a> for a list of the
accepted values, but note that key/salt tuples must be separated
with commas (‘,’) only. To clear the allowed key/salt policy use
a value of ‘-‘.</dd>
</dl>
<p>Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">kadmin</span><span class="p">:</span> <span class="n">add_policy</span> <span class="o">-</span><span class="n">maxlife</span> <span class="s2">"2 days"</span> <span class="o">-</span><span class="n">minlength</span> <span class="mi">5</span> <span class="n">guests</span>
<span class="n">kadmin</span><span class="p">:</span>
</pre></div>
</div>
</div>
<div class="section" id="modify-policy">
<h3>modify_policy<a class="headerlink" href="#modify-policy" title="Permalink to this headline">¶</a></h3>
<blockquote>
<div><strong>modify_policy</strong> [<em>options</em>] <em>policy</em></div></blockquote>
<p>Modifies the password policy named <em>policy</em>. Options are as described
for <strong>add_policy</strong>.</p>
<p>This command requires the <strong>modify</strong> privilege.</p>
<p>Alias: <strong>modpol</strong></p>
</div>
<div class="section" id="delete-policy">
<h3>delete_policy<a class="headerlink" href="#delete-policy" title="Permalink to this headline">¶</a></h3>
<blockquote>
<div><strong>delete_policy</strong> [<strong>-force</strong>] <em>policy</em></div></blockquote>
<p>Deletes the password policy named <em>policy</em>. Prompts for confirmation
before deletion. The command will fail if the policy is in use by any
principals.</p>
<p>This command requires the <strong>delete</strong> privilege.</p>
<p>Alias: <strong>delpol</strong></p>
<p>Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>kadmin: del_policy guests
Are you sure you want to delete the policy "guests"?
(yes/no): yes
kadmin:
</pre></div>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">You must cancel the policy from <em>all</em> principals before
deleting it. The <em>delete_policy</em> command will fail if the policy
is in use by any principals.</p>
</div>
</div>
<div class="section" id="retrieving-policies">
<h3>Retrieving policies<a class="headerlink" href="#retrieving-policies" title="Permalink to this headline">¶</a></h3>
<p>To retrieve a policy, use the <a class="reference internal" href="admin_commands/kadmin_local.html#kadmin-1"><span class="std std-ref">kadmin</span></a> <strong>get_policy</strong> command.</p>
<p>You can retrieve the list of policies with the kadmin
<strong>list_policies</strong> command.</p>
</div>
<div class="section" id="get-policy">
<h3>get_policy<a class="headerlink" href="#get-policy" title="Permalink to this headline">¶</a></h3>
<blockquote>
<div><strong>get_policy</strong> [ <strong>-terse</strong> ] <em>policy</em></div></blockquote>
<p>Displays the values of the password policy named <em>policy</em>. With the
<strong>-terse</strong> flag, outputs the fields as quoted strings separated by
tabs.</p>
<p>This command requires the <strong>inquire</strong> privilege.</p>
<p>Alias: getpol</p>
<p>Examples:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">kadmin</span><span class="p">:</span> <span class="n">get_policy</span> <span class="n">admin</span>
<span class="n">Policy</span><span class="p">:</span> <span class="n">admin</span>
<span class="n">Maximum</span> <span class="n">password</span> <span class="n">life</span><span class="p">:</span> <span class="mi">180</span> <span class="n">days</span> <span class="mi">00</span><span class="p">:</span><span class="mi">00</span><span class="p">:</span><span class="mi">00</span>
<span class="n">Minimum</span> <span class="n">password</span> <span class="n">life</span><span class="p">:</span> <span class="mi">00</span><span class="p">:</span><span class="mi">00</span><span class="p">:</span><span class="mi">00</span>
<span class="n">Minimum</span> <span class="n">password</span> <span class="n">length</span><span class="p">:</span> <span class="mi">6</span>
<span class="n">Minimum</span> <span class="n">number</span> <span class="n">of</span> <span class="n">password</span> <span class="n">character</span> <span class="n">classes</span><span class="p">:</span> <span class="mi">2</span>
<span class="n">Number</span> <span class="n">of</span> <span class="n">old</span> <span class="n">keys</span> <span class="n">kept</span><span class="p">:</span> <span class="mi">5</span>
<span class="n">Reference</span> <span class="n">count</span><span class="p">:</span> <span class="mi">17</span>
<span class="n">kadmin</span><span class="p">:</span> <span class="n">get_policy</span> <span class="o">-</span><span class="n">terse</span> <span class="n">admin</span>
<span class="n">admin</span> <span class="mi">15552000</span> <span class="mi">0</span> <span class="mi">6</span> <span class="mi">2</span> <span class="mi">5</span> <span class="mi">17</span>
<span class="n">kadmin</span><span class="p">:</span>
</pre></div>
</div>
<p>The “Reference count” is the number of principals using that policy.
With the LDAP KDC database module, the reference count field is not
meaningful.</p>
</div>
<div class="section" id="list-policies">
<h3>list_policies<a class="headerlink" href="#list-policies" title="Permalink to this headline">¶</a></h3>
<blockquote>
<div><strong>list_policies</strong> [<em>expression</em>]</div></blockquote>
<p>Retrieves all or some policy names. <em>expression</em> is a shell-style
glob expression that can contain the wild-card characters <code class="docutils literal notranslate"><span class="pre">?</span></code>,
<code class="docutils literal notranslate"><span class="pre">*</span></code>, and <code class="docutils literal notranslate"><span class="pre">[]</span></code>. All policy names matching the expression are
printed. If no expression is provided, all existing policy names are
printed.</p>
<p>This command requires the <strong>list</strong> privilege.</p>
<p>Aliases: <strong>listpols</strong>, <strong>get_policies</strong>, <strong>getpols</strong>.</p>
<p>Examples:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">kadmin</span><span class="p">:</span> <span class="n">listpols</span>
<span class="n">test</span><span class="o">-</span><span class="n">pol</span>
<span class="nb">dict</span><span class="o">-</span><span class="n">only</span>
<span class="n">once</span><span class="o">-</span><span class="n">a</span><span class="o">-</span><span class="nb">min</span>
<span class="n">test</span><span class="o">-</span><span class="n">pol</span><span class="o">-</span><span class="n">nopw</span>
<span class="n">kadmin</span><span class="p">:</span> <span class="n">listpols</span> <span class="n">t</span><span class="o">*</span>
<span class="n">test</span><span class="o">-</span><span class="n">pol</span>
<span class="n">test</span><span class="o">-</span><span class="n">pol</span><span class="o">-</span><span class="n">nopw</span>
<span class="n">kadmin</span><span class="p">:</span>
</pre></div>
</div>
</div>
<div class="section" id="policies-and-principals">
<h3>Policies and principals<a class="headerlink" href="#policies-and-principals" title="Permalink to this headline">¶</a></h3>
<p>Policies can be applied to principals as they are created by using
the <strong>-policy</strong> flag to <a class="reference internal" href="admin_commands/kadmin_local.html#add-principal"><span class="std std-ref">add_principal</span></a>. Existing principals can
be modified by using the <strong>-policy</strong> or <strong>-clearpolicy</strong> flag to
<a class="reference internal" href="admin_commands/kadmin_local.html#modify-principal"><span class="std std-ref">modify_principal</span></a>.</p>
</div>
<div class="section" id="updating-the-history-key">
<h3>Updating the history key<a class="headerlink" href="#updating-the-history-key" title="Permalink to this headline">¶</a></h3>
<p>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 <code class="docutils literal notranslate"><span class="pre">kadmin/history</span></code> principal.</p>
<p>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:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">kadmin</span><span class="p">:</span> <span class="n">change_password</span> <span class="o">-</span><span class="n">randkey</span> <span class="n">kadmin</span><span class="o">/</span><span class="n">history</span>
</pre></div>
</div>
<p>This command will fail if you specify the <strong>-keepold</strong> flag. Only one
new history key will be created, even if you specify multiple key/salt
combinations.</p>
<p>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.</p>
</div>
</div>
<div class="section" id="privileges">
<span id="id2"></span><h2>Privileges<a class="headerlink" href="#privileges" title="Permalink to this headline">¶</a></h2>
<p>Administrative privileges for the Kerberos database are stored in the
file <a class="reference internal" href="conf_files/kadm5_acl.html#kadm5-acl-5"><span class="std std-ref">kadm5.acl</span></a>.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">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 <code class="docutils literal notranslate"><span class="pre">joeadmin</span></code> might have a principal for
his administrative use, called <code class="docutils literal notranslate"><span class="pre">joeadmin/admin</span></code>. This
way, <code class="docutils literal notranslate"><span class="pre">joeadmin</span></code> would obtain <code class="docutils literal notranslate"><span class="pre">joeadmin/admin</span></code> tickets
only when he actually needs to use those permissions.</p>
</div>
</div>
<div class="section" id="operations-on-the-kerberos-database">
<span id="db-operations"></span><h2>Operations on the Kerberos database<a class="headerlink" href="#operations-on-the-kerberos-database" title="Permalink to this headline">¶</a></h2>
<p>The <a class="reference internal" href="admin_commands/kdb5_util.html#kdb5-util-8"><span class="std std-ref">kdb5_util</span></a> command is the primary tool for administrating
the Kerberos database.</p>
<p><strong>kdb5_util</strong>
[<strong>-r</strong> <em>realm</em>]
[<strong>-d</strong> <em>dbname</em>]
[<strong>-k</strong> <em>mkeytype</em>]
[<strong>-kv</strong> <em>mkeyVNO</em>]
[<strong>-M</strong> <em>mkeyname</em>]
[<strong>-m</strong>]
[<strong>-sf</strong> <em>stashfilename</em>]
[<strong>-P</strong> <em>password</em>]
[<strong>-x</strong> <em>db_args</em>]
<em>command</em> [<em>command_options</em>]</p>
<p><strong>OPTIONS</strong></p>
<dl class="docutils">
<dt><strong>-r</strong> <em>realm</em></dt>
<dd>specifies the Kerberos realm of the database.</dd>
<dt><strong>-d</strong> <em>dbname</em></dt>
<dd>specifies the name under which the principal database is stored;
by default the database is that listed in <a class="reference internal" href="conf_files/kdc_conf.html#kdc-conf-5"><span class="std std-ref">kdc.conf</span></a>. The
password policy database and lock files are also derived from this
value.</dd>
<dt><strong>-k</strong> <em>mkeytype</em></dt>
<dd>specifies the key type of the master key in the database. The
default is given by the <strong>master_key_type</strong> variable in
<a class="reference internal" href="conf_files/kdc_conf.html#kdc-conf-5"><span class="std std-ref">kdc.conf</span></a>.</dd>
<dt><strong>-kv</strong> <em>mkeyVNO</em></dt>
<dd>Specifies the version number of the master key in the database;
the default is 1. Note that 0 is not allowed.</dd>
<dt><strong>-M</strong> <em>mkeyname</em></dt>
<dd>principal name for the master key in the database. If not
specified, the name is determined by the <strong>master_key_name</strong>
variable in <a class="reference internal" href="conf_files/kdc_conf.html#kdc-conf-5"><span class="std std-ref">kdc.conf</span></a>.</dd>
<dt><strong>-m</strong></dt>
<dd>specifies that the master database password should be read from
the keyboard rather than fetched from a file on disk.</dd>
<dt><strong>-sf</strong> <em>stash_file</em></dt>
<dd>specifies the stash filename of the master database password. If
not specified, the filename is determined by the
<strong>key_stash_file</strong> variable in <a class="reference internal" href="conf_files/kdc_conf.html#kdc-conf-5"><span class="std std-ref">kdc.conf</span></a>.</dd>
<dt><strong>-P</strong> <em>password</em></dt>
<dd>specifies the master database password. Using this option may
expose the password to other users on the system via the process
list.</dd>
<dt><strong>-x</strong> <em>db_args</em></dt>
<dd>specifies database-specific options. See <a class="reference internal" href="admin_commands/kadmin_local.html#kadmin-1"><span class="std std-ref">kadmin</span></a> for
supported options.</dd>
</dl>
<div class="toctree-wrapper compound">
</div>
<div class="section" id="dumping-a-kerberos-database-to-a-file">
<h3>Dumping a Kerberos database to a file<a class="headerlink" href="#dumping-a-kerberos-database-to-a-file" title="Permalink to this headline">¶</a></h3>
<p>To dump a Kerberos database into a file, use the <a class="reference internal" href="admin_commands/kdb5_util.html#kdb5-util-8"><span class="std std-ref">kdb5_util</span></a>
<strong>dump</strong> command on one of the KDCs.</p>
<blockquote>
<div><strong>dump</strong> [<strong>-b7</strong>|<strong>-ov</strong>|<strong>-r13</strong>|<strong>-r18</strong>]
[<strong>-verbose</strong>] [<strong>-mkey_convert</strong>] [<strong>-new_mkey_file</strong>
<em>mkey_file</em>] [<strong>-rev</strong>] [<strong>-recurse</strong>] [<em>filename</em>
[<em>principals</em>…]]</div></blockquote>
<p>Dumps the current Kerberos and KADM5 database into an ASCII file. By
default, the database is dumped in current format, “kdb5_util
load_dump version 7”. If filename is not specified, or is the string
“-“, the dump is sent to standard output. Options:</p>
<dl class="docutils">
<dt><strong>-b7</strong></dt>
<dd>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.</dd>
<dt><strong>-ov</strong></dt>
<dd>causes the dump to be in “ovsec_adm_export” format.</dd>
<dt><strong>-r13</strong></dt>
<dd>causes the dump to be in the Kerberos 5 1.3 format (“kdb5_util
load_dump version 5”). This was the dump format produced on
releases prior to 1.8.</dd>
<dt><strong>-r18</strong></dt>
<dd>causes the dump to be in the Kerberos 5 1.8 format (“kdb5_util
load_dump version 6”). This was the dump format produced on
releases prior to 1.11.</dd>
<dt><strong>-verbose</strong></dt>
<dd>causes the name of each principal and policy to be printed as it
is dumped.</dd>
<dt><strong>-mkey_convert</strong></dt>
<dd>prompts for a new master key. This new master key will be used to
re-encrypt principal key data in the dumpfile. The principal keys
themselves will not be changed.</dd>
<dt><strong>-new_mkey_file</strong> <em>mkey_file</em></dt>
<dd>the filename of a stash file. The master key in this stash file
will be used to re-encrypt the key data in the dumpfile. The key
data in the database will not be changed.</dd>
<dt><strong>-rev</strong></dt>
<dd>dumps in reverse order. This may recover principals that do not
dump normally, in cases where database corruption has occurred.</dd>
<dt><strong>-recurse</strong></dt>
<dd><p class="first">causes the dump to walk the database recursively (btree only).
This may recover principals that do not dump normally, in cases
where database corruption has occurred. In cases of such
corruption, this option will probably retrieve more principals
than the <strong>-rev</strong> option will.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 1.15: </span>Release 1.15 restored the functionality of the <strong>-recurse</strong>
option.</p>
</div>
<div class="last versionchanged">
<p><span class="versionmodified">Changed in version 1.5: </span>The <strong>-recurse</strong> option ceased working until release 1.15,
doing a normal dump instead of a recursive traversal.</p>
</div>
</dd>
</dl>
<div class="section" id="id3">
<h4>Examples<a class="headerlink" href="#id3" title="Permalink to this headline">¶</a></h4>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">shell</span><span class="o">%</span> <span class="n">kdb5_util</span> <span class="n">dump</span> <span class="n">dumpfile</span>
<span class="n">shell</span><span class="o">%</span>
<span class="n">shell</span><span class="o">%</span> <span class="n">kbd5_util</span> <span class="n">dump</span> <span class="o">-</span><span class="n">verbose</span> <span class="n">dumpfile</span>
<span class="n">kadmin</span><span class="o">/</span><span class="n">admin</span><span class="nd">@ATHENA</span><span class="o">.</span><span class="n">MIT</span><span class="o">.</span><span class="n">EDU</span>
<span class="n">krbtgt</span><span class="o">/</span><span class="n">ATHENA</span><span class="o">.</span><span class="n">MIT</span><span class="o">.</span><span class="n">EDU</span><span class="nd">@ATHENA</span><span class="o">.</span><span class="n">MIT</span><span class="o">.</span><span class="n">EDU</span>
<span class="n">kadmin</span><span class="o">/</span><span class="n">history</span><span class="nd">@ATHENA</span><span class="o">.</span><span class="n">MIT</span><span class="o">.</span><span class="n">EDU</span>
<span class="n">K</span><span class="o">/</span><span class="n">M</span><span class="nd">@ATHENA</span><span class="o">.</span><span class="n">MIT</span><span class="o">.</span><span class="n">EDU</span>
<span class="n">kadmin</span><span class="o">/</span><span class="n">changepw</span><span class="nd">@ATHENA</span><span class="o">.</span><span class="n">MIT</span><span class="o">.</span><span class="n">EDU</span>
<span class="n">shell</span><span class="o">%</span>
</pre></div>
</div>
<p>If you specify which principals to dump, you must use the full
principal, as in the following example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">shell</span><span class="o">%</span> <span class="n">kdb5_util</span> <span class="n">dump</span> <span class="o">-</span><span class="n">verbose</span> <span class="n">dumpfile</span> <span class="n">K</span><span class="o">/</span><span class="n">M</span><span class="nd">@ATHENA</span><span class="o">.</span><span class="n">MIT</span><span class="o">.</span><span class="n">EDU</span> <span class="n">kadmin</span><span class="o">/</span><span class="n">admin</span><span class="nd">@ATHENA</span><span class="o">.</span><span class="n">MIT</span><span class="o">.</span><span class="n">EDU</span>
<span class="n">kadmin</span><span class="o">/</span><span class="n">admin</span><span class="nd">@ATHENA</span><span class="o">.</span><span class="n">MIT</span><span class="o">.</span><span class="n">EDU</span>
<span class="n">K</span><span class="o">/</span><span class="n">M</span><span class="nd">@ATHENA</span><span class="o">.</span><span class="n">MIT</span><span class="o">.</span><span class="n">EDU</span>
<span class="n">shell</span><span class="o">%</span>
</pre></div>
</div>
<p>Otherwise, the principals will not match those in the database and
will not be dumped:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">shell</span><span class="o">%</span> <span class="n">kdb5_util</span> <span class="n">dump</span> <span class="o">-</span><span class="n">verbose</span> <span class="n">dumpfile</span> <span class="n">K</span><span class="o">/</span><span class="n">M</span> <span class="n">kadmin</span><span class="o">/</span><span class="n">admin</span>
<span class="n">shell</span><span class="o">%</span>
</pre></div>
</div>
<p>If you do not specify a dump file, kdb5_util will dump the database to
the standard output.</p>
</div>
</div>
<div class="section" id="restoring-a-kerberos-database-from-a-dump-file">
<span id="restore-from-dump"></span><h3>Restoring a Kerberos database from a dump file<a class="headerlink" href="#restoring-a-kerberos-database-from-a-dump-file" title="Permalink to this headline">¶</a></h3>
<p>To restore a Kerberos database dump from a file, use the
<a class="reference internal" href="admin_commands/kdb5_util.html#kdb5-util-8"><span class="std std-ref">kdb5_util</span></a> <strong>load</strong> command on one of the KDCs.</p>
<blockquote>
<div><strong>load</strong> [<strong>-b7</strong>|<strong>-ov</strong>|<strong>-r13</strong>|<strong>-r18</strong>] [<strong>-hash</strong>]
[<strong>-verbose</strong>] [<strong>-update</strong>] <em>filename</em></div></blockquote>
<p>Loads a database dump from the named file into the named database. If
no option is given to determine the format of the dump file, the
format is detected automatically and handled as appropriate. Unless
the <strong>-update</strong> option is given, <strong>load</strong> creates a new database
containing only the data in the dump file, overwriting the contents of
any previously existing database. Note that when using the LDAP KDC
database module, the <strong>-update</strong> flag is required.</p>
<p>Options:</p>
<dl class="docutils">
<dt><strong>-b7</strong></dt>
<dd>requires the database 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.</dd>
<dt><strong>-ov</strong></dt>
<dd>requires the database to be in “ovsec_adm_import” format. Must be
used with the <strong>-update</strong> option.</dd>
<dt><strong>-r13</strong></dt>
<dd>requires the database to be in Kerberos 5 1.3 format (“kdb5_util
load_dump version 5”). This was the dump format produced on
releases prior to 1.8.</dd>
<dt><strong>-r18</strong></dt>
<dd>requires the database to be in Kerberos 5 1.8 format (“kdb5_util
load_dump version 6”). This was the dump format produced on
releases prior to 1.11.</dd>
<dt><strong>-hash</strong></dt>
<dd>stores the database in hash format, if using the DB2 database
type. If this option is not specified, the database will be
stored in btree format. This option is not recommended, as
databases stored in hash format are known to corrupt data and lose
principals.</dd>
<dt><strong>-verbose</strong></dt>
<dd>causes the name of each principal and policy to be printed as it
is dumped.</dd>
<dt><strong>-update</strong></dt>
<dd>records from the dump file are added to or updated in the existing
database. Otherwise, a new database is created containing only
what is in the dump file and the old one destroyed upon successful
completion.</dd>
</dl>
<div class="section" id="id4">
<h4>Examples<a class="headerlink" href="#id4" title="Permalink to this headline">¶</a></h4>
<p>To dump a single principal and later load it, updating the database:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">shell</span><span class="o">%</span> <span class="n">kdb5_util</span> <span class="n">dump</span> <span class="n">dumpfile</span> <span class="n">principal</span><span class="nd">@REALM</span>
<span class="n">shell</span><span class="o">%</span>
<span class="n">shell</span><span class="o">%</span> <span class="n">kdb5_util</span> <span class="n">load</span> <span class="o">-</span><span class="n">update</span> <span class="n">dumpfile</span>
<span class="n">shell</span><span class="o">%</span>
</pre></div>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">If the database file exists, and the <em>-update</em> flag was not
given, <em>kdb5_util</em> will overwrite the existing database.</p>
</div>
<p>Using kdb5_util to upgrade a master KDC from krb5 1.1.x:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">shell</span><span class="o">%</span> <span class="n">kdb5_util</span> <span class="n">dump</span> <span class="n">old</span><span class="o">-</span><span class="n">kdb</span><span class="o">-</span><span class="n">dump</span>
<span class="n">shell</span><span class="o">%</span> <span class="n">kdb5_util</span> <span class="n">dump</span> <span class="o">-</span><span class="n">ov</span> <span class="n">old</span><span class="o">-</span><span class="n">kdb</span><span class="o">-</span><span class="n">dump</span><span class="o">.</span><span class="n">ov</span>
<span class="p">[</span><span class="n">Create</span> <span class="n">a</span> <span class="n">new</span> <span class="n">KDC</span> <span class="n">installation</span><span class="p">,</span> <span class="n">using</span> <span class="n">the</span> <span class="n">old</span> <span class="n">stash</span> <span class="n">file</span><span class="o">/</span><span class="n">master</span> <span class="n">password</span><span class="p">]</span>
<span class="n">shell</span><span class="o">%</span> <span class="n">kdb5_util</span> <span class="n">load</span> <span class="n">old</span><span class="o">-</span><span class="n">kdb</span><span class="o">-</span><span class="n">dump</span>
<span class="n">shell</span><span class="o">%</span> <span class="n">kdb5_util</span> <span class="n">load</span> <span class="o">-</span><span class="n">update</span> <span class="n">old</span><span class="o">-</span><span class="n">kdb</span><span class="o">-</span><span class="n">dump</span><span class="o">.</span><span class="n">ov</span>
</pre></div>
</div>
<p>The use of old-kdb-dump.ov for an extra dump and load is necessary
to preserve per-principal policy information, which is not included in
the default dump format of krb5 1.1.x.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Using kdb5_util to dump and reload the principal database is
only necessary when upgrading from versions of krb5 prior
to 1.2.0—newer versions will use the existing database as-is.</p>
</div>
</div>
</div>
<div class="section" id="creating-a-stash-file">
<span id="create-stash"></span><h3>Creating a stash file<a class="headerlink" href="#creating-a-stash-file" title="Permalink to this headline">¶</a></h3>
<p>A stash file allows a KDC to authenticate itself to the database
utilities, such as <a class="reference internal" href="admin_commands/kadmind.html#kadmind-8"><span class="std std-ref">kadmind</span></a>, <a class="reference internal" href="admin_commands/krb5kdc.html#krb5kdc-8"><span class="std std-ref">krb5kdc</span></a>, and
<a class="reference internal" href="admin_commands/kdb5_util.html#kdb5-util-8"><span class="std std-ref">kdb5_util</span></a>.</p>
<p>To create a stash file, use the <a class="reference internal" href="admin_commands/kdb5_util.html#kdb5-util-8"><span class="std std-ref">kdb5_util</span></a> <strong>stash</strong> command.</p>
<blockquote>
<div><strong>stash</strong> [<strong>-f</strong> <em>keyfile</em>]</div></blockquote>
<p>Stores the master principal’s keys in a stash file. The <strong>-f</strong>
argument can be used to override the <em>keyfile</em> specified in
<a class="reference internal" href="conf_files/kdc_conf.html#kdc-conf-5"><span class="std std-ref">kdc.conf</span></a>.</p>
<div class="section" id="example">
<h4>Example<a class="headerlink" href="#example" title="Permalink to this headline">¶</a></h4>
<blockquote>
<div>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%</div></blockquote>
<p>If you do not specify a stash file, kdb5_util will stash the key in
the file specified in your <a class="reference internal" href="conf_files/kdc_conf.html#kdc-conf-5"><span class="std std-ref">kdc.conf</span></a> file.</p>
</div>
</div>
<div class="section" id="creating-and-destroying-a-kerberos-database">
<h3>Creating and destroying a Kerberos database<a class="headerlink" href="#creating-and-destroying-a-kerberos-database" title="Permalink to this headline">¶</a></h3>
<p>If you need to create a new Kerberos database, use the
<a class="reference internal" href="admin_commands/kdb5_util.html#kdb5-util-8"><span class="std std-ref">kdb5_util</span></a> <strong>create</strong> command.</p>
<blockquote>
<div><strong>create</strong> [<strong>-s</strong>]</div></blockquote>
<p>Creates a new database. If the <strong>-s</strong> option is specified, the stash
file is also created. This command fails if the database already
exists. If the command is successful, the database is opened just as
if it had already existed when the program was first run.</p>
<p>If you need to destroy the current Kerberos database, use the
<a class="reference internal" href="admin_commands/kdb5_util.html#kdb5-util-8"><span class="std std-ref">kdb5_util</span></a> <strong>destroy</strong> command.</p>
<blockquote>
<div><strong>destroy</strong> [<strong>-f</strong>]</div></blockquote>
<p>Destroys the database, first overwriting the disk sectors and then
unlinking the files, after prompting the user for confirmation. With
the <strong>-f</strong> argument, does not prompt the user.</p>
<div class="section" id="id5">
<h4>Examples<a class="headerlink" href="#id5" title="Permalink to this headline">¶</a></h4>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>shell% kdb5_util -r ATHENA.MIT.EDU create -s
Loading random data
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%
shell% kdb5_util -r ATHENA.MIT.EDU destroy
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'...
** Database '/usr/local/var/krb5kdc/principal' destroyed.
shell%
</pre></div>
</div>
</div>
</div>
<div class="section" id="updating-the-master-key">
<h3>Updating the master key<a class="headerlink" href="#updating-the-master-key" title="Permalink to this headline">¶</a></h3>
<p>Starting with release 1.7, <a class="reference internal" href="admin_commands/kdb5_util.html#kdb5-util-8"><span class="std std-ref">kdb5_util</span></a> allows the master key
to be changed using a rollover process, with minimal loss of
availability. To roll over the master key, follow these steps:</p>
<ol class="arabic">
<li><p class="first">On the master KDC, run <code class="docutils literal notranslate"><span class="pre">kdb5_util</span> <span class="pre">list_mkeys</span></code> to view the current
master key version number (KVNO). If you have never rolled over
the master key before, this will likely be version 1:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ kdb5_util list_mkeys
Master keys for Principal: K/M@KRBTEST.COM
KVNO: 1, Enctype: des-cbc-crc, Active on: Wed Dec 31 19:00:00 EST 1969 *
</pre></div>
</div>
</li>
<li><p class="first">On the master KDC, run <code class="docutils literal notranslate"><span class="pre">kdb5_util</span> <span class="pre">use_mkey</span> <span class="pre">1</span></code> to ensure that a
master key activation list is present in the database. This step
is unnecessary in release 1.11.4 or later, or if the database was
initially created with release 1.7 or later.</p>
</li>
<li><p class="first">On the master KDC, run <code class="docutils literal notranslate"><span class="pre">kdb5_util</span> <span class="pre">add_mkey</span> <span class="pre">-s</span></code> to create a new
master key and write it to the stash file. Enter a secure password
when prompted. If this is the first time you are changing the
master key, the new key will have version 2. The new master key
will not be used until you make it active.</p>
</li>
<li><p class="first">Propagate the database to all replica KDCs, either manually or by
waiting until the next scheduled propagation. If you do not have
any replica KDCs, you can skip this and the next step.</p>
</li>
<li><p class="first">On each replica KDC, run <code class="docutils literal notranslate"><span class="pre">kdb5_util</span> <span class="pre">list_mkeys</span></code> to verify that
the new master key is present, and then <code class="docutils literal notranslate"><span class="pre">kdb5_util</span> <span class="pre">stash</span></code> to
write the new master key to the replica KDC’s stash file.</p>
</li>
<li><p class="first">On the master KDC, run <code class="docutils literal notranslate"><span class="pre">kdb5_util</span> <span class="pre">use_mkey</span> <span class="pre">2</span></code> to begin using the
new master key. Replace <code class="docutils literal notranslate"><span class="pre">2</span></code> with the version of the new master
key, as appropriate. You can optionally specify a date for the new
master key to become active; by default, it will become active
immediately. Prior to release 1.12, <a class="reference internal" href="admin_commands/kadmind.html#kadmind-8"><span class="std std-ref">kadmind</span></a> must be
restarted for this change to take full effect.</p>
</li>
<li><p class="first">On the master KDC, run <code class="docutils literal notranslate"><span class="pre">kdb5_util</span> <span class="pre">update_princ_encryption</span></code>. This
command will iterate over the database and re-encrypt all keys in
the new master key. If the database is large and uses DB2, the
master KDC will become unavailable while this command runs, but
clients should fail over to replica KDCs (if any are present)
during this time period. In release 1.13 and later, you can
instead run <code class="docutils literal notranslate"><span class="pre">kdb5_util</span> <span class="pre">-x</span> <span class="pre">unlockiter</span> <span class="pre">update_princ_encryption</span></code> to
use unlocked iteration; this variant will take longer, but will
keep the database available to the KDC and kadmind while it runs.</p>
</li>
<li><p class="first">Wait until the above changes have propagated to all replica KDCs
and until all running KDC and kadmind processes have serviced
requests using updated principal entries.</p>
</li>
<li><p class="first">On the master KDC, run <code class="docutils literal notranslate"><span class="pre">kdb5_util</span> <span class="pre">purge_mkeys</span></code> to clean up the
old master key.</p>
</li>
</ol>
</div>
</div>
<div class="section" id="operations-on-the-ldap-database">
<span id="ops-on-ldap"></span><h2>Operations on the LDAP database<a class="headerlink" href="#operations-on-the-ldap-database" title="Permalink to this headline">¶</a></h2>
<p>The <a class="reference internal" href="admin_commands/kdb5_ldap_util.html#kdb5-ldap-util-8"><span class="std std-ref">kdb5_ldap_util</span></a> 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.</p>
<p><strong>kdb5_ldap_util</strong>
[<strong>-D</strong> <em>user_dn</em> [<strong>-w</strong> <em>passwd</em>]]
[<strong>-H</strong> <em>ldapuri</em>]
<strong>command</strong>
[<em>command_options</em>]</p>
<p><strong>OPTIONS</strong></p>
<dl class="docutils">
<dt><strong>-D</strong> <em>user_dn</em></dt>
<dd>Specifies the Distinguished Name (DN) of the user who has
sufficient rights to perform the operation on the LDAP server.</dd>
<dt><strong>-w</strong> <em>passwd</em></dt>
<dd>Specifies the password of <em>user_dn</em>. This option is not
recommended.</dd>
<dt><strong>-H</strong> <em>ldapuri</em></dt>
<dd>Specifies the URI of the LDAP server. It is recommended to use
<code class="docutils literal notranslate"><span class="pre">ldapi://</span></code> or <code class="docutils literal notranslate"><span class="pre">ldaps://</span></code> to connect to the LDAP server.</dd>
</dl>
<div class="section" id="creating-a-kerberos-realm">
<span id="ldap-create-realm"></span><h3>Creating a Kerberos realm<a class="headerlink" href="#creating-a-kerberos-realm" title="Permalink to this headline">¶</a></h3>
<p>If you need to create a new realm, use the <a class="reference internal" href="admin_commands/kdb5_ldap_util.html#kdb5-ldap-util-8"><span class="std std-ref">kdb5_ldap_util</span></a>
<strong>create</strong> command as follows.</p>
<blockquote>
<div><strong>create</strong>
[<strong>-subtrees</strong> <em>subtree_dn_list</em>]
[<strong>-sscope</strong> <em>search_scope</em>]
[<strong>-containerref</strong> <em>container_reference_dn</em>]
[<strong>-k</strong> <em>mkeytype</em>]
[<strong>-kv</strong> <em>mkeyVNO</em>]
[<strong>-m|-P</strong> <em>password</em>|<strong>-sf</strong> <em>stashfilename</em>]
[<strong>-s</strong>]
[<strong>-r</strong> <em>realm</em>]
[<strong>-maxtktlife</strong> <em>max_ticket_life</em>]
[<strong>-maxrenewlife</strong> <em>max_renewable_ticket_life</em>]
[<em>ticket_flags</em>]</div></blockquote>
<p>Creates realm in directory. Options:</p>
<dl class="docutils">
<dt><strong>-subtrees</strong> <em>subtree_dn_list</em></dt>
<dd>Specifies the list of subtrees containing the principals of a
realm. The list contains the DNs of the subtree objects separated
by colon (<code class="docutils literal notranslate"><span class="pre">:</span></code>).</dd>
<dt><strong>-sscope</strong> <em>search_scope</em></dt>
<dd>Specifies the scope for searching the principals under the
subtree. The possible values are 1 or one (one level), 2 or sub
(subtrees).</dd>
<dt><strong>-containerref</strong> <em>container_reference_dn</em></dt>
<dd>Specifies 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.</dd>
<dt><strong>-k</strong> <em>mkeytype</em></dt>
<dd>Specifies the key type of the master key in the database. The
default is given by the <strong>master_key_type</strong> variable in
<a class="reference internal" href="conf_files/kdc_conf.html#kdc-conf-5"><span class="std std-ref">kdc.conf</span></a>.</dd>
<dt><strong>-kv</strong> <em>mkeyVNO</em></dt>
<dd>Specifies the version number of the master key in the database;
the default is 1. Note that 0 is not allowed.</dd>
<dt><strong>-m</strong></dt>
<dd>Specifies that the master database password should be read from
the TTY rather than fetched from a file on the disk.</dd>
<dt><strong>-P</strong> <em>password</em></dt>
<dd>Specifies the master database password. This option is not
recommended.</dd>
<dt><strong>-r</strong> <em>realm</em></dt>
<dd>Specifies the Kerberos realm of the database.</dd>
<dt><strong>-sf</strong> <em>stashfilename</em></dt>
<dd>Specifies the stash file of the master database password.</dd>
<dt><strong>-s</strong></dt>
<dd>Specifies that the stash file is to be created.</dd>
<dt><strong>-maxtktlife</strong> <em>max_ticket_life</em></dt>
<dd>(<a class="reference internal" href="../basic/date_format.html#getdate"><span class="std std-ref">getdate time</span></a> string) Specifies maximum ticket life for
principals in this realm.</dd>
<dt><strong>-maxrenewlife</strong> <em>max_renewable_ticket_life</em></dt>
<dd>(<a class="reference internal" href="../basic/date_format.html#getdate"><span class="std std-ref">getdate time</span></a> string) Specifies maximum renewable life of
tickets for principals in this realm.</dd>
<dt><em>ticket_flags</em></dt>
<dd>Specifies global ticket flags for the realm. Allowable flags are
documented in the description of the <strong>add_principal</strong> command in
<a class="reference internal" href="admin_commands/kadmin_local.html#kadmin-1"><span class="std std-ref">kadmin</span></a>.</dd>
</dl>
<p>Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">kdb5_ldap_util</span> <span class="o">-</span><span class="n">D</span> <span class="n">cn</span><span class="o">=</span><span class="n">admin</span><span class="p">,</span><span class="n">o</span><span class="o">=</span><span class="n">org</span> <span class="o">-</span><span class="n">H</span> <span class="n">ldaps</span><span class="p">:</span><span class="o">//</span><span class="n">ldap</span><span class="o">-</span><span class="n">server1</span><span class="o">.</span><span class="n">mit</span><span class="o">.</span><span class="n">edu</span>
<span class="n">create</span> <span class="o">-</span><span class="n">subtrees</span> <span class="n">o</span><span class="o">=</span><span class="n">org</span> <span class="o">-</span><span class="n">sscope</span> <span class="n">SUB</span> <span class="o">-</span><span class="n">r</span> <span class="n">ATHENA</span><span class="o">.</span><span class="n">MIT</span><span class="o">.</span><span class="n">EDU</span>
<span class="n">Password</span> <span class="k">for</span> <span class="s2">"cn=admin,o=org"</span><span class="p">:</span>
<span class="n">Initializing</span> <span class="n">database</span> <span class="k">for</span> <span class="n">realm</span> <span class="s1">'ATHENA.MIT.EDU'</span>
<span class="n">You</span> <span class="n">will</span> <span class="n">be</span> <span class="n">prompted</span> <span class="k">for</span> <span class="n">the</span> <span class="n">database</span> <span class="n">Master</span> <span class="n">Password</span><span class="o">.</span>
<span class="n">It</span> <span class="ow">is</span> <span class="n">important</span> <span class="n">that</span> <span class="n">you</span> <span class="n">NOT</span> <span class="n">FORGET</span> <span class="n">this</span> <span class="n">password</span><span class="o">.</span>
<span class="n">Enter</span> <span class="n">KDC</span> <span class="n">database</span> <span class="n">master</span> <span class="n">key</span><span class="p">:</span>
<span class="n">Re</span><span class="o">-</span><span class="n">enter</span> <span class="n">KDC</span> <span class="n">database</span> <span class="n">master</span> <span class="n">key</span> <span class="n">to</span> <span class="n">verify</span><span class="p">:</span>
</pre></div>
</div>
</div>
<div class="section" id="modifying-a-kerberos-realm">
<span id="ldap-mod-realm"></span><h3>Modifying a Kerberos realm<a class="headerlink" href="#modifying-a-kerberos-realm" title="Permalink to this headline">¶</a></h3>
<p>If you need to modify a realm, use the <a class="reference internal" href="admin_commands/kdb5_ldap_util.html#kdb5-ldap-util-8"><span class="std std-ref">kdb5_ldap_util</span></a>
<strong>modify</strong> command as follows.</p>
<blockquote>
<div><strong>modify</strong>
[<strong>-subtrees</strong> <em>subtree_dn_list</em>]
[<strong>-sscope</strong> <em>search_scope</em>]
[<strong>-containerref</strong> <em>container_reference_dn</em>]
[<strong>-r</strong> <em>realm</em>]
[<strong>-maxtktlife</strong> <em>max_ticket_life</em>]
[<strong>-maxrenewlife</strong> <em>max_renewable_ticket_life</em>]
[<em>ticket_flags</em>]</div></blockquote>
<p>Modifies the attributes of a realm. Options:</p>
<dl class="docutils">
<dt><strong>-subtrees</strong> <em>subtree_dn_list</em></dt>
<dd>Specifies the list of subtrees containing the principals of a
realm. The list contains the DNs of the subtree objects separated
by colon (<code class="docutils literal notranslate"><span class="pre">:</span></code>). This list replaces the existing list.</dd>
<dt><strong>-sscope</strong> <em>search_scope</em></dt>
<dd>Specifies the scope for searching the principals under the
subtrees. The possible values are 1 or one (one level), 2 or sub
(subtrees).</dd>
<dt><strong>-containerref</strong> <em>container_reference_dn</em> Specifies the DN of the</dt>
<dd>container object in which the principals of a realm will be
created.</dd>
<dt><strong>-r</strong> <em>realm</em></dt>
<dd>Specifies the Kerberos realm of the database.</dd>
<dt><strong>-maxtktlife</strong> <em>max_ticket_life</em></dt>
<dd>(<a class="reference internal" href="../basic/date_format.html#getdate"><span class="std std-ref">getdate time</span></a> string) Specifies maximum ticket life for
principals in this realm.</dd>
<dt><strong>-maxrenewlife</strong> <em>max_renewable_ticket_life</em></dt>
<dd>(<a class="reference internal" href="../basic/date_format.html#getdate"><span class="std std-ref">getdate time</span></a> string) Specifies maximum renewable life of
tickets for principals in this realm.</dd>
<dt><em>ticket_flags</em></dt>
<dd>Specifies global ticket flags for the realm. Allowable flags are
documented in the description of the <strong>add_principal</strong> command in
<a class="reference internal" href="admin_commands/kadmin_local.html#kadmin-1"><span class="std std-ref">kadmin</span></a>.</dd>
</dl>
<p>Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">shell</span><span class="o">%</span> <span class="n">kdb5_ldap_util</span> <span class="o">-</span><span class="n">D</span> <span class="n">cn</span><span class="o">=</span><span class="n">admin</span><span class="p">,</span><span class="n">o</span><span class="o">=</span><span class="n">org</span> <span class="o">-</span><span class="n">H</span>
<span class="n">ldaps</span><span class="p">:</span><span class="o">//</span><span class="n">ldap</span><span class="o">-</span><span class="n">server1</span><span class="o">.</span><span class="n">mit</span><span class="o">.</span><span class="n">edu</span> <span class="n">modify</span> <span class="o">+</span><span class="n">requires_preauth</span> <span class="o">-</span><span class="n">r</span>
<span class="n">ATHENA</span><span class="o">.</span><span class="n">MIT</span><span class="o">.</span><span class="n">EDU</span>
<span class="n">Password</span> <span class="k">for</span> <span class="s2">"cn=admin,o=org"</span><span class="p">:</span>
<span class="n">shell</span><span class="o">%</span>
</pre></div>
</div>
</div>
<div class="section" id="destroying-a-kerberos-realm">
<h3>Destroying a Kerberos realm<a class="headerlink" href="#destroying-a-kerberos-realm" title="Permalink to this headline">¶</a></h3>
<p>If you need to destroy a Kerberos realm, use the
<a class="reference internal" href="admin_commands/kdb5_ldap_util.html#kdb5-ldap-util-8"><span class="std std-ref">kdb5_ldap_util</span></a> <strong>destroy</strong> command as follows.</p>
<blockquote>
<div><strong>destroy</strong> [<strong>-f</strong>] [<strong>-r</strong> <em>realm</em>]</div></blockquote>
<p>Destroys an existing realm. Options:</p>
<dl class="docutils">
<dt><strong>-f</strong></dt>
<dd>If specified, will not prompt the user for confirmation.</dd>
<dt><strong>-r</strong> <em>realm</em></dt>
<dd>Specifies the Kerberos realm of the database.</dd>
</dl>
<p>Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>shell% kdb5_ldap_util -D cn=admin,o=org -H
ldaps://ldap-server1.mit.edu destroy -r ATHENA.MIT.EDU
Password for "cn=admin,o=org":
Deleting KDC database of 'ATHENA.MIT.EDU', are you sure?
(type 'yes' to confirm)? yes
OK, deleting database of 'ATHENA.MIT.EDU'...
shell%
</pre></div>
</div>
</div>
<div class="section" id="retrieving-information-about-a-kerberos-realm">
<h3>Retrieving information about a Kerberos realm<a class="headerlink" href="#retrieving-information-about-a-kerberos-realm" title="Permalink to this headline">¶</a></h3>
<p>If you need to display the attributes of a realm, use the
<a class="reference internal" href="admin_commands/kdb5_ldap_util.html#kdb5-ldap-util-8"><span class="std std-ref">kdb5_ldap_util</span></a> <strong>view</strong> command as follows.</p>
<blockquote>
<div><strong>view</strong> [<strong>-r</strong> <em>realm</em>]</div></blockquote>
<p>Displays the attributes of a realm. Options:</p>
<dl class="docutils">
<dt><strong>-r</strong> <em>realm</em></dt>
<dd>Specifies the Kerberos realm of the database.</dd>
</dl>
<p>Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">kdb5_ldap_util</span> <span class="o">-</span><span class="n">D</span> <span class="n">cn</span><span class="o">=</span><span class="n">admin</span><span class="p">,</span><span class="n">o</span><span class="o">=</span><span class="n">org</span> <span class="o">-</span><span class="n">H</span> <span class="n">ldaps</span><span class="p">:</span><span class="o">//</span><span class="n">ldap</span><span class="o">-</span><span class="n">server1</span><span class="o">.</span><span class="n">mit</span><span class="o">.</span><span class="n">edu</span>
<span class="n">view</span> <span class="o">-</span><span class="n">r</span> <span class="n">ATHENA</span><span class="o">.</span><span class="n">MIT</span><span class="o">.</span><span class="n">EDU</span>
<span class="n">Password</span> <span class="k">for</span> <span class="s2">"cn=admin,o=org"</span><span class="p">:</span>
<span class="n">Realm</span> <span class="n">Name</span><span class="p">:</span> <span class="n">ATHENA</span><span class="o">.</span><span class="n">MIT</span><span class="o">.</span><span class="n">EDU</span>
<span class="n">Subtree</span><span class="p">:</span> <span class="n">ou</span><span class="o">=</span><span class="n">users</span><span class="p">,</span><span class="n">o</span><span class="o">=</span><span class="n">org</span>
<span class="n">Subtree</span><span class="p">:</span> <span class="n">ou</span><span class="o">=</span><span class="n">servers</span><span class="p">,</span><span class="n">o</span><span class="o">=</span><span class="n">org</span>
<span class="n">SearchScope</span><span class="p">:</span> <span class="n">ONE</span>
<span class="n">Maximum</span> <span class="n">ticket</span> <span class="n">life</span><span class="p">:</span> <span class="mi">0</span> <span class="n">days</span> <span class="mi">01</span><span class="p">:</span><span class="mi">00</span><span class="p">:</span><span class="mi">00</span>
<span class="n">Maximum</span> <span class="n">renewable</span> <span class="n">life</span><span class="p">:</span> <span class="mi">0</span> <span class="n">days</span> <span class="mi">10</span><span class="p">:</span><span class="mi">00</span><span class="p">:</span><span class="mi">00</span>
<span class="n">Ticket</span> <span class="n">flags</span><span class="p">:</span> <span class="n">DISALLOW_FORWARDABLE</span> <span class="n">REQUIRES_PWCHANGE</span>
</pre></div>
</div>
</div>
<div class="section" id="listing-available-kerberos-realms">
<h3>Listing available Kerberos realms<a class="headerlink" href="#listing-available-kerberos-realms" title="Permalink to this headline">¶</a></h3>
<p>If you need to display the list of the realms, use the
<a class="reference internal" href="admin_commands/kdb5_ldap_util.html#kdb5-ldap-util-8"><span class="std std-ref">kdb5_ldap_util</span></a> <strong>list</strong> command as follows.</p>
<blockquote>
<div><strong>list</strong></div></blockquote>
<p>Lists the name of realms.</p>
<p>Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">shell</span><span class="o">%</span> <span class="n">kdb5_ldap_util</span> <span class="o">-</span><span class="n">D</span> <span class="n">cn</span><span class="o">=</span><span class="n">admin</span><span class="p">,</span><span class="n">o</span><span class="o">=</span><span class="n">org</span> <span class="o">-</span><span class="n">H</span>
<span class="n">ldaps</span><span class="p">:</span><span class="o">//</span><span class="n">ldap</span><span class="o">-</span><span class="n">server1</span><span class="o">.</span><span class="n">mit</span><span class="o">.</span><span class="n">edu</span> <span class="nb">list</span>
<span class="n">Password</span> <span class="k">for</span> <span class="s2">"cn=admin,o=org"</span><span class="p">:</span>
<span class="n">ATHENA</span><span class="o">.</span><span class="n">MIT</span><span class="o">.</span><span class="n">EDU</span>
<span class="n">OPENLDAP</span><span class="o">.</span><span class="n">MIT</span><span class="o">.</span><span class="n">EDU</span>
<span class="n">MEDIA</span><span class="o">-</span><span class="n">LAB</span><span class="o">.</span><span class="n">MIT</span><span class="o">.</span><span class="n">EDU</span>
<span class="n">shell</span><span class="o">%</span>
</pre></div>
</div>
</div>
<div class="section" id="stashing-service-object-s-password">
<span id="stash-ldap"></span><h3>Stashing service object’s password<a class="headerlink" href="#stashing-service-object-s-password" title="Permalink to this headline">¶</a></h3>
<p>The <a class="reference internal" href="admin_commands/kdb5_ldap_util.html#kdb5-ldap-util-8"><span class="std std-ref">kdb5_ldap_util</span></a> <strong>stashsrvpw</strong> command allows an
administrator to store the password of service object in a file. The
KDC and Administration server uses this password to authenticate to
the LDAP server.</p>
<blockquote>
<div><strong>stashsrvpw</strong>
[<strong>-f</strong> <em>filename</em>]
<em>name</em></div></blockquote>
<p>Allows an administrator to store the password for service object in a
file so that KDC and Administration server can use it to authenticate
to the LDAP server. Options:</p>
<dl class="docutils">
<dt><strong>-f</strong> <em>filename</em></dt>
<dd>Specifies the complete path of the service password file. By
default, <code class="docutils literal notranslate"><span class="pre">/usr/local/var/service_passwd</span></code> is used.</dd>
<dt><em>name</em></dt>
<dd>Specifies the name of the object whose password is to be stored.
If <a class="reference internal" href="admin_commands/krb5kdc.html#krb5kdc-8"><span class="std std-ref">krb5kdc</span></a> or <a class="reference internal" href="admin_commands/kadmind.html#kadmind-8"><span class="std std-ref">kadmind</span></a> are configured for
simple binding, this should be the distinguished name it will
use as given by the <strong>ldap_kdc_dn</strong> or <strong>ldap_kadmind_dn</strong>
variable in <a class="reference internal" href="conf_files/kdc_conf.html#kdc-conf-5"><span class="std std-ref">kdc.conf</span></a>. If the KDC or kadmind is
configured for SASL binding, this should be the authentication
name it will use as given by the <strong>ldap_kdc_sasl_authcid</strong> or
<strong>ldap_kadmind_sasl_authcid</strong> variable.</dd>
</dl>
<p>Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">kdb5_ldap_util</span> <span class="n">stashsrvpw</span> <span class="o">-</span><span class="n">f</span> <span class="o">/</span><span class="n">home</span><span class="o">/</span><span class="n">andrew</span><span class="o">/</span><span class="n">conf_keyfile</span>
<span class="n">cn</span><span class="o">=</span><span class="n">service</span><span class="o">-</span><span class="n">kdc</span><span class="p">,</span><span class="n">o</span><span class="o">=</span><span class="n">org</span>
<span class="n">Password</span> <span class="k">for</span> <span class="s2">"cn=service-kdc,o=org"</span><span class="p">:</span>
<span class="n">Re</span><span class="o">-</span><span class="n">enter</span> <span class="n">password</span> <span class="k">for</span> <span class="s2">"cn=service-kdc,o=org"</span><span class="p">:</span>
</pre></div>
</div>
</div>
<div class="section" id="ticket-policy-operations">
<h3>Ticket Policy operations<a class="headerlink" href="#ticket-policy-operations" title="Permalink to this headline">¶</a></h3>
<div class="section" id="creating-a-ticket-policy">
<h4>Creating a Ticket Policy<a class="headerlink" href="#creating-a-ticket-policy" title="Permalink to this headline">¶</a></h4>
<p>To create a new ticket policy in directory , use the
<a class="reference internal" href="admin_commands/kdb5_ldap_util.html#kdb5-ldap-util-8"><span class="std std-ref">kdb5_ldap_util</span></a> <strong>create_policy</strong> command. Ticket policy
objects are created under the realm container.</p>
<blockquote>
<div><strong>create_policy</strong>
[<strong>-r</strong> <em>realm</em>]
[<strong>-maxtktlife</strong> <em>max_ticket_life</em>]
[<strong>-maxrenewlife</strong> <em>max_renewable_ticket_life</em>]
[<em>ticket_flags</em>]
<em>policy_name</em></div></blockquote>
<p>Creates a ticket policy in the directory. Options:</p>
<dl class="docutils">
<dt><strong>-r</strong> <em>realm</em></dt>
<dd>Specifies the Kerberos realm of the database.</dd>
<dt><strong>-maxtktlife</strong> <em>max_ticket_life</em></dt>
<dd>(<a class="reference internal" href="../basic/date_format.html#getdate"><span class="std std-ref">getdate time</span></a> string) Specifies maximum ticket life for
principals.</dd>
<dt><strong>-maxrenewlife</strong> <em>max_renewable_ticket_life</em></dt>
<dd>(<a class="reference internal" href="../basic/date_format.html#getdate"><span class="std std-ref">getdate time</span></a> string) Specifies maximum renewable life of
tickets for principals.</dd>
<dt><em>ticket_flags</em></dt>
<dd>Specifies the ticket flags. If this option is not specified, by
default, no restriction will be set by the policy. Allowable
flags are documented in the description of the <strong>add_principal</strong>
command in <a class="reference internal" href="admin_commands/kadmin_local.html#kadmin-1"><span class="std std-ref">kadmin</span></a>.</dd>
<dt><em>policy_name</em></dt>
<dd>Specifies the name of the ticket policy.</dd>
</dl>
<p>Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">kdb5_ldap_util</span> <span class="o">-</span><span class="n">D</span> <span class="n">cn</span><span class="o">=</span><span class="n">admin</span><span class="p">,</span><span class="n">o</span><span class="o">=</span><span class="n">org</span> <span class="o">-</span><span class="n">H</span> <span class="n">ldaps</span><span class="p">:</span><span class="o">//</span><span class="n">ldap</span><span class="o">-</span><span class="n">server1</span><span class="o">.</span><span class="n">mit</span><span class="o">.</span><span class="n">edu</span>
<span class="n">create_policy</span> <span class="o">-</span><span class="n">r</span> <span class="n">ATHENA</span><span class="o">.</span><span class="n">MIT</span><span class="o">.</span><span class="n">EDU</span> <span class="o">-</span><span class="n">maxtktlife</span> <span class="s2">"1 day"</span>
<span class="o">-</span><span class="n">maxrenewlife</span> <span class="s2">"1 week"</span> <span class="o">-</span><span class="n">allow_postdated</span> <span class="o">+</span><span class="n">needchange</span>
<span class="o">-</span><span class="n">allow_forwardable</span> <span class="n">tktpolicy</span>
<span class="n">Password</span> <span class="k">for</span> <span class="s2">"cn=admin,o=org"</span><span class="p">:</span>
</pre></div>
</div>
</div>
<div class="section" id="modifying-a-ticket-policy">
<h4>Modifying a Ticket Policy<a class="headerlink" href="#modifying-a-ticket-policy" title="Permalink to this headline">¶</a></h4>
<p>To modify a ticket policy in directory, use the
<a class="reference internal" href="admin_commands/kdb5_ldap_util.html#kdb5-ldap-util-8"><span class="std std-ref">kdb5_ldap_util</span></a> <strong>modify_policy</strong> command.</p>
<blockquote>
<div><strong>modify_policy</strong>
[<strong>-r</strong> <em>realm</em>]
[<strong>-maxtktlife</strong> <em>max_ticket_life</em>]
[<strong>-maxrenewlife</strong> <em>max_renewable_ticket_life</em>]
[<em>ticket_flags</em>]
<em>policy_name</em></div></blockquote>
<p>Modifies the attributes of a ticket policy. Options are same as for
<strong>create_policy</strong>.</p>
<p>Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">kdb5_ldap_util</span> <span class="o">-</span><span class="n">D</span> <span class="n">cn</span><span class="o">=</span><span class="n">admin</span><span class="p">,</span><span class="n">o</span><span class="o">=</span><span class="n">org</span> <span class="o">-</span><span class="n">H</span>
<span class="n">ldaps</span><span class="p">:</span><span class="o">//</span><span class="n">ldap</span><span class="o">-</span><span class="n">server1</span><span class="o">.</span><span class="n">mit</span><span class="o">.</span><span class="n">edu</span> <span class="n">modify_policy</span> <span class="o">-</span><span class="n">r</span> <span class="n">ATHENA</span><span class="o">.</span><span class="n">MIT</span><span class="o">.</span><span class="n">EDU</span>
<span class="o">-</span><span class="n">maxtktlife</span> <span class="s2">"60 minutes"</span> <span class="o">-</span><span class="n">maxrenewlife</span> <span class="s2">"10 hours"</span>
<span class="o">+</span><span class="n">allow_postdated</span> <span class="o">-</span><span class="n">requires_preauth</span> <span class="n">tktpolicy</span>
<span class="n">Password</span> <span class="k">for</span> <span class="s2">"cn=admin,o=org"</span><span class="p">:</span>
</pre></div>
</div>
</div>
<div class="section" id="retrieving-information-about-a-ticket-policy">
<h4>Retrieving Information About a Ticket Policy<a class="headerlink" href="#retrieving-information-about-a-ticket-policy" title="Permalink to this headline">¶</a></h4>
<p>To display the attributes of a ticket policy, use the
<a class="reference internal" href="admin_commands/kdb5_ldap_util.html#kdb5-ldap-util-8"><span class="std std-ref">kdb5_ldap_util</span></a> <strong>view_policy</strong> command.</p>
<blockquote>
<div><strong>view_policy</strong>
[<strong>-r</strong> <em>realm</em>]
<em>policy_name</em></div></blockquote>
<p>Displays the attributes of a ticket policy. Options:</p>
<dl class="docutils">
<dt><em>policy_name</em></dt>
<dd>Specifies the name of the ticket policy.</dd>
</dl>
<p>Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">kdb5_ldap_util</span> <span class="o">-</span><span class="n">D</span> <span class="n">cn</span><span class="o">=</span><span class="n">admin</span><span class="p">,</span><span class="n">o</span><span class="o">=</span><span class="n">org</span> <span class="o">-</span><span class="n">H</span> <span class="n">ldaps</span><span class="p">:</span><span class="o">//</span><span class="n">ldap</span><span class="o">-</span><span class="n">server1</span><span class="o">.</span><span class="n">mit</span><span class="o">.</span><span class="n">edu</span>
<span class="n">view_policy</span> <span class="o">-</span><span class="n">r</span> <span class="n">ATHENA</span><span class="o">.</span><span class="n">MIT</span><span class="o">.</span><span class="n">EDU</span> <span class="n">tktpolicy</span>
<span class="n">Password</span> <span class="k">for</span> <span class="s2">"cn=admin,o=org"</span><span class="p">:</span>
<span class="n">Ticket</span> <span class="n">policy</span><span class="p">:</span> <span class="n">tktpolicy</span>
<span class="n">Maximum</span> <span class="n">ticket</span> <span class="n">life</span><span class="p">:</span> <span class="mi">0</span> <span class="n">days</span> <span class="mi">01</span><span class="p">:</span><span class="mi">00</span><span class="p">:</span><span class="mi">00</span>
<span class="n">Maximum</span> <span class="n">renewable</span> <span class="n">life</span><span class="p">:</span> <span class="mi">0</span> <span class="n">days</span> <span class="mi">10</span><span class="p">:</span><span class="mi">00</span><span class="p">:</span><span class="mi">00</span>
<span class="n">Ticket</span> <span class="n">flags</span><span class="p">:</span> <span class="n">DISALLOW_FORWARDABLE</span> <span class="n">REQUIRES_PWCHANGE</span>
</pre></div>
</div>
</div>
<div class="section" id="destroying-a-ticket-policy">
<h4>Destroying a Ticket Policy<a class="headerlink" href="#destroying-a-ticket-policy" title="Permalink to this headline">¶</a></h4>
<p>To destroy an existing ticket policy, use the <a class="reference internal" href="admin_commands/kdb5_ldap_util.html#kdb5-ldap-util-8"><span class="std std-ref">kdb5_ldap_util</span></a>
<strong>destroy_policy</strong> command.</p>
<blockquote>
<div><strong>destroy_policy</strong>
[<strong>-r</strong> <em>realm</em>]
[<strong>-force</strong>]
<em>policy_name</em></div></blockquote>
<p>Destroys an existing ticket policy. Options:</p>
<dl class="docutils">
<dt><strong>-r</strong> <em>realm</em></dt>
<dd>Specifies the Kerberos realm of the database.</dd>
<dt><strong>-force</strong></dt>
<dd>Forces the deletion of the policy object. If not specified, the
user will be prompted for confirmation before deleting the policy.</dd>
<dt><em>policy_name</em></dt>
<dd>Specifies the name of the ticket policy.</dd>
</dl>
<p>Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>kdb5_ldap_util -D cn=admin,o=org -H ldaps://ldap-server1.mit.edu
destroy_policy -r ATHENA.MIT.EDU tktpolicy
Password for "cn=admin,o=org":
This will delete the policy object 'tktpolicy', are you sure?
(type 'yes' to confirm)? yes
** policy object 'tktpolicy' deleted.
</pre></div>
</div>
</div>
<div class="section" id="listing-available-ticket-policies">
<h4>Listing available Ticket Policies<a class="headerlink" href="#listing-available-ticket-policies" title="Permalink to this headline">¶</a></h4>
<p>To list the name of ticket policies in a realm, use the
<a class="reference internal" href="admin_commands/kdb5_ldap_util.html#kdb5-ldap-util-8"><span class="std std-ref">kdb5_ldap_util</span></a> <strong>list_policy</strong> command.</p>
<blockquote>
<div><strong>list_policy</strong>
[<strong>-r</strong> <em>realm</em>]</div></blockquote>
<p>Lists the ticket policies in realm if specified or in the default
realm. Options:</p>
<dl class="docutils">
<dt><strong>-r</strong> <em>realm</em></dt>
<dd>Specifies the Kerberos realm of the database.</dd>
</dl>
<p>Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">kdb5_ldap_util</span> <span class="o">-</span><span class="n">D</span> <span class="n">cn</span><span class="o">=</span><span class="n">admin</span><span class="p">,</span><span class="n">o</span><span class="o">=</span><span class="n">org</span> <span class="o">-</span><span class="n">H</span> <span class="n">ldaps</span><span class="p">:</span><span class="o">//</span><span class="n">ldap</span><span class="o">-</span><span class="n">server1</span><span class="o">.</span><span class="n">mit</span><span class="o">.</span><span class="n">edu</span>
<span class="n">list_policy</span> <span class="o">-</span><span class="n">r</span> <span class="n">ATHENA</span><span class="o">.</span><span class="n">MIT</span><span class="o">.</span><span class="n">EDU</span>
<span class="n">Password</span> <span class="k">for</span> <span class="s2">"cn=admin,o=org"</span><span class="p">:</span>
<span class="n">tktpolicy</span>
<span class="n">tmppolicy</span>
<span class="n">userpolicy</span>
</pre></div>
</div>
</div>
</div>
</div>
<div class="section" id="cross-realm-authentication">
<span id="xrealm-authn"></span><h2>Cross-realm authentication<a class="headerlink" href="#cross-realm-authentication" title="Permalink to this headline">¶</a></h2>
<p>In order for a KDC in one realm to authenticate Kerberos users in a
different realm, it must share a key with the KDC in the other realm.
In both databases, there must be krbtgt service principals for both realms.
For example, if you need to do cross-realm authentication between the realms
<code class="docutils literal notranslate"><span class="pre">ATHENA.MIT.EDU</span></code> and <code class="docutils literal notranslate"><span class="pre">EXAMPLE.COM</span></code>, you would need to add the
principals <code class="docutils literal notranslate"><span class="pre">krbtgt/EXAMPLE.COM@ATHENA.MIT.EDU</span></code> and
<code class="docutils literal notranslate"><span class="pre">krbtgt/ATHENA.MIT.EDU@EXAMPLE.COM</span></code> to both databases.
These principals must all have the same passwords, key version
numbers, and encryption types; this may require explicitly setting
the key version number with the <strong>-kvno</strong> option.</p>
<p>In the ATHENA.MIT.EDU and EXAMPLE.COM cross-realm case, the administrators
would run the following commands on the KDCs in both realms:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">shell</span><span class="o">%</span><span class="p">:</span> <span class="n">kadmin</span><span class="o">.</span><span class="n">local</span> <span class="o">-</span><span class="n">e</span> <span class="s2">"aes256-cts:normal"</span>
<span class="n">kadmin</span><span class="p">:</span> <span class="n">addprinc</span> <span class="o">-</span><span class="n">requires_preauth</span> <span class="n">krbtgt</span><span class="o">/</span><span class="n">ATHENA</span><span class="o">.</span><span class="n">MIT</span><span class="o">.</span><span class="n">EDU</span><span class="nd">@EXAMPLE</span><span class="o">.</span><span class="n">COM</span>
<span class="n">Enter</span> <span class="n">password</span> <span class="k">for</span> <span class="n">principal</span> <span class="n">krbtgt</span><span class="o">/</span><span class="n">ATHENA</span><span class="o">.</span><span class="n">MIT</span><span class="o">.</span><span class="n">EDU</span><span class="nd">@EXAMPLE</span><span class="o">.</span><span class="n">COM</span><span class="p">:</span>
<span class="n">Re</span><span class="o">-</span><span class="n">enter</span> <span class="n">password</span> <span class="k">for</span> <span class="n">principal</span> <span class="n">krbtgt</span><span class="o">/</span><span class="n">ATHENA</span><span class="o">.</span><span class="n">MIT</span><span class="o">.</span><span class="n">EDU</span><span class="nd">@EXAMPLE</span><span class="o">.</span><span class="n">COM</span><span class="p">:</span>
<span class="n">kadmin</span><span class="p">:</span> <span class="n">addprinc</span> <span class="o">-</span><span class="n">requires_preauth</span> <span class="n">krbtgt</span><span class="o">/</span><span class="n">EXAMPLE</span><span class="o">.</span><span class="n">COM</span><span class="nd">@ATHENA</span><span class="o">.</span><span class="n">MIT</span><span class="o">.</span><span class="n">EDU</span>
<span class="n">Enter</span> <span class="n">password</span> <span class="k">for</span> <span class="n">principal</span> <span class="n">krbtgt</span><span class="o">/</span><span class="n">EXAMPLE</span><span class="o">.</span><span class="n">COM</span><span class="nd">@ATHENA</span><span class="o">.</span><span class="n">MIT</span><span class="o">.</span><span class="n">EDU</span><span class="p">:</span>
<span class="n">Enter</span> <span class="n">password</span> <span class="k">for</span> <span class="n">principal</span> <span class="n">krbtgt</span><span class="o">/</span><span class="n">EXAMPLE</span><span class="o">.</span><span class="n">COM</span><span class="nd">@ATHENA</span><span class="o">.</span><span class="n">MIT</span><span class="o">.</span><span class="n">EDU</span><span class="p">:</span>
<span class="n">kadmin</span><span class="p">:</span>
</pre></div>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Even if most principals in a realm are generally created
with the <strong>requires_preauth</strong> flag enabled, this flag is not
desirable on cross-realm authentication keys because doing
so makes it impossible to disable preauthentication on a
service-by-service basis. Disabling it as in the example
above is recommended.</p>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">It is very important that these principals have good
passwords. MIT recommends that TGT principal passwords be
at least 26 characters of random ASCII text.</p>
</div>
</div>
<div class="section" id="changing-the-krbtgt-key">
<span id="changing-krbtgt-key"></span><h2>Changing the krbtgt key<a class="headerlink" href="#changing-the-krbtgt-key" title="Permalink to this headline">¶</a></h2>
<p>A Kerberos Ticket Granting Ticket (TGT) is a service ticket for the
principal <code class="docutils literal notranslate"><span class="pre">krbtgt/REALM</span></code>. The key for this principal is created
when the Kerberos database is initialized and need not be changed.
However, it will only have the encryption types supported by the KDC
at the time of the initial database creation. To allow use of newer
encryption types for the TGT, this key has to be changed.</p>
<p>Changing this key using the normal <a class="reference internal" href="admin_commands/kadmin_local.html#kadmin-1"><span class="std std-ref">kadmin</span></a>
<strong>change_password</strong> command would invalidate any previously issued
TGTs. Therefore, when changing this key, normally one should use the
<strong>-keepold</strong> flag to change_password to retain the previous key in the
database as well as the new key. For example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">kadmin</span><span class="p">:</span> <span class="n">change_password</span> <span class="o">-</span><span class="n">randkey</span> <span class="o">-</span><span class="n">keepold</span> <span class="n">krbtgt</span><span class="o">/</span><span class="n">ATHENA</span><span class="o">.</span><span class="n">MIT</span><span class="o">.</span><span class="n">EDU</span><span class="nd">@ATHENA</span><span class="o">.</span><span class="n">MIT</span><span class="o">.</span><span class="n">EDU</span>
</pre></div>
</div>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">After issuing this command, the old key is still valid
and is still vulnerable to (for instance) brute force
attacks. To completely retire an old key or encryption
type, run the kadmin <strong>purgekeys</strong> command to delete keys
with older kvnos, ideally first making sure that all
tickets issued with the old keys have expired.</p>
</div>
<p>Only the first krbtgt key of the newest key version is used to encrypt
ticket-granting tickets. However, the set of encryption types present
in the krbtgt keys is used by default to determine the session key
types supported by the krbtgt service (see
<a class="reference internal" href="enctypes.html#session-key-selection"><span class="std std-ref">Session key selection</span></a>). Because non-MIT Kerberos clients
sometimes send a limited set of encryption types when making AS
requests, it can be important to for the krbtgt service to support
multiple encryption types. This can be accomplished by giving the
krbtgt principal multiple keys, which is usually as simple as not
specifying any <strong>-e</strong> option when changing the krbtgt key, or by
setting the <strong>session_enctypes</strong> string attribute on the krbtgt
principal (see <a class="reference internal" href="admin_commands/kadmin_local.html#set-string"><span class="std std-ref">set_string</span></a>).</p>
<p>Due to a bug in releases 1.8 through 1.13, renewed and forwarded
tickets may not work if the original ticket was obtained prior to a
krbtgt key change and the modified ticket is obtained afterwards.
Upgrading the KDC to release 1.14 or later will correct this bug.</p>
</div>
<div class="section" id="incremental-database-propagation">
<span id="incr-db-prop"></span><h2>Incremental database propagation<a class="headerlink" href="#incremental-database-propagation" title="Permalink to this headline">¶</a></h2>
<div class="section" id="overview">
<h3>Overview<a class="headerlink" href="#overview" title="Permalink to this headline">¶</a></h3>
<p>At some very large sites, dumping and transmitting the database can
take more time than is desirable for changes to propagate from the
master KDC to the replica KDCs. The incremental propagation support
added in the 1.7 release is intended to address this.</p>
<p>With incremental propagation enabled, all programs on the master KDC
that change the database also write information about the changes to
an “update log” file, maintained as a circular buffer of a certain
size. A process on each replica KDC connects to a service on the
master KDC (currently implemented in the <a class="reference internal" href="admin_commands/kadmind.html#kadmind-8"><span class="std std-ref">kadmind</span></a> server) and
periodically requests the changes that have been made since the last
check. By default, this check is done every two minutes. If the
database has just been modified in the previous several seconds
(currently the threshold is hard-coded at 10 seconds), the replica
will not retrieve updates, but instead will pause and try again soon
after. This reduces the likelihood that incremental update queries
will cause delays for an administrator trying to make a bunch of
changes to the database at the same time.</p>
<p>Incremental propagation uses the following entries in the per-realm
data in the KDC config file (See <a class="reference internal" href="conf_files/kdc_conf.html#kdc-conf-5"><span class="std std-ref">kdc.conf</span></a>):</p>
<table border="1" class="docutils">
<colgroup>
<col width="4%" />
<col width="3%" />
<col width="94%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd"><td>iprop_enable</td>
<td><em>boolean</em></td>
<td>If <em>true</em>, then incremental propagation is enabled, and (as noted below) normal kprop propagation is disabled. The default is <em>false</em>.</td>
</tr>
<tr class="row-even"><td>iprop_master_ulogsize</td>
<td><em>integer</em></td>
<td>Indicates the number of entries that should be retained in the update log. The default is 1000; the maximum number is 2500.</td>
</tr>
<tr class="row-odd"><td>iprop_replica_poll</td>
<td><em>time interval</em></td>
<td>Indicates how often the replica should poll the master KDC for changes to the database. The default is two minutes.</td>
</tr>
<tr class="row-even"><td>iprop_port</td>
<td><em>integer</em></td>
<td>Specifies the port number to be used for incremental propagation. This is required in both master and replica configuration files.</td>
</tr>
<tr class="row-odd"><td>iprop_resync_timeout</td>
<td><em>integer</em></td>
<td>Specifies the number of seconds to wait for a full propagation to complete. This is optional on replica configurations. Defaults to 300 seconds (5 minutes).</td>
</tr>
<tr class="row-even"><td>iprop_logfile</td>
<td><em>file name</em></td>
<td>Specifies where the update log file for the realm database is to be stored. The default is to use the <em>database_name</em> entry from the realms section of the config file <a class="reference internal" href="conf_files/kdc_conf.html#kdc-conf-5"><span class="std std-ref">kdc.conf</span></a>, with <em>.ulog</em> appended. (NOTE: If database_name isn’t specified in the realms section, perhaps because the LDAP database back end is being used, or the file name is specified in the <em>dbmodules</em> section, then the hard-coded default for <em>database_name</em> is used. Determination of the <em>iprop_logfile</em> default value will not use values from the <em>dbmodules</em> section.)</td>
</tr>
</tbody>
</table>
<p>Both master and replica sides must have a principal named
<code class="docutils literal notranslate"><span class="pre">kiprop/hostname</span></code> (where <em>hostname</em> is the lowercase,
fully-qualified, canonical name for the host) registered in the
Kerberos database, and have keys for that principal stored in the
default keytab file (<code class="docutils literal notranslate"><span class="pre">FILE:/etc/krb5.keytab</span></code>). In release 1.13, the
<code class="docutils literal notranslate"><span class="pre">kiprop/hostname</span></code> principal is created automatically for the master
KDC, but it must still be created for replica KDCs.</p>
<p>On the master KDC side, the <code class="docutils literal notranslate"><span class="pre">kiprop/hostname</span></code> principal must be
listed in the kadmind ACL file <a class="reference internal" href="conf_files/kadm5_acl.html#kadm5-acl-5"><span class="std std-ref">kadm5.acl</span></a>, and given the
<strong>p</strong> privilege (see <a class="reference internal" href="#privileges"><span class="std std-ref">Privileges</span></a>).</p>
<p>On the replica KDC side, <a class="reference internal" href="admin_commands/kpropd.html#kpropd-8"><span class="std std-ref">kpropd</span></a> should be run. When
incremental propagation is enabled, it will connect to the kadmind on
the master KDC and start requesting updates.</p>
<p>The normal kprop mechanism is disabled by the incremental propagation
support. However, if the replica has been unable to fetch changes
from the master KDC for too long (network problems, perhaps), the log
on the master may wrap around and overwrite some of the updates that
the replica has not yet retrieved. In this case, the replica will
instruct the master KDC to dump the current database out to a file and
invoke a one-time kprop propagation, with special options to also
convey the point in the update log at which the replica should resume
fetching incremental updates. Thus, all the keytab and ACL setup
previously described for kprop propagation is still needed.</p>
<p>If an environment has a large number of replicas, it may be desirable
to arrange them in a hierarchy instead of having the master serve
updates to every replica. To do this, run <code class="docutils literal notranslate"><span class="pre">kadmind</span> <span class="pre">-proponly</span></code> on
each intermediate replica, and <code class="docutils literal notranslate"><span class="pre">kpropd</span> <span class="pre">-A</span> <span class="pre">upstreamhostname</span></code> on
downstream replicas to direct each one to the appropriate upstream
replica.</p>
<p>There are several known restrictions in the current implementation:</p>
<ul class="simple">
<li>The incremental update protocol does not transport changes to policy
objects. Any policy changes on the master will result in full
resyncs to all replicas.</li>
<li>The replica’s KDB module must support locking; it cannot be using the
LDAP KDB module.</li>
<li>The master and replica must be able to initiate TCP connections in
both directions, without an intervening NAT.</li>
</ul>
</div>
<div class="section" id="sun-mit-incremental-propagation-differences">
<h3>Sun/MIT incremental propagation differences<a class="headerlink" href="#sun-mit-incremental-propagation-differences" title="Permalink to this headline">¶</a></h3>
<p>Sun donated the original code for supporting incremental database
propagation to MIT. Some changes have been made in the MIT source
tree that will be visible to administrators. (These notes are based
on Sun’s patches. Changes to Sun’s implementation since then may not
be reflected here.)</p>
<p>The Sun config file support looks for <code class="docutils literal notranslate"><span class="pre">sunw_dbprop_enable</span></code>,
<code class="docutils literal notranslate"><span class="pre">sunw_dbprop_master_ulogsize</span></code>, and <code class="docutils literal notranslate"><span class="pre">sunw_dbprop_slave_poll</span></code>.</p>
<p>The incremental propagation service is implemented as an ONC RPC
service. In the Sun implementation, the service is registered with
rpcbind (also known as portmapper) and the client looks up the port
number to contact. In the MIT implementation, where interaction with
some modern versions of rpcbind doesn’t always work well, the port
number must be specified in the config file on both the master and
replica sides.</p>
<p>The Sun implementation hard-codes pathnames in <code class="docutils literal notranslate"><span class="pre">/var/krb5</span></code> for the
update log and the per-replica kprop dump files. In the MIT
implementation, the pathname for the update log is specified in the
config file, and the per-replica dump files are stored in
<code class="docutils literal notranslate"><span class="pre">/var/lib</span></code><code class="docutils literal notranslate"><span class="pre">/krb5kdc</span></code><code class="docutils literal notranslate"><span class="pre">/replica_datatrans_hostname</span></code>.</p>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sidebar">
<h2>On this page</h2>
<ul>
<li><a class="reference internal" href="#">Database administration</a><ul>
<li><a class="reference internal" href="#kadmin-options">kadmin options</a></li>
<li><a class="reference internal" href="#date-format">Date Format</a></li>
<li><a class="reference internal" href="#principals">Principals</a><ul>
<li><a class="reference internal" href="#adding-modifying-and-deleting-principals">Adding, modifying and deleting principals</a></li>
<li><a class="reference internal" href="#add-principal">add_principal</a></li>
<li><a class="reference internal" href="#modify-principal">modify_principal</a></li>
<li><a class="reference internal" href="#delete-principal">delete_principal</a><ul>
<li><a class="reference internal" href="#examples">Examples</a></li>
</ul>
</li>
<li><a class="reference internal" href="#retrieving-information-about-a-principal">Retrieving information about a principal</a></li>
<li><a class="reference internal" href="#get-principal">get_principal</a></li>
<li><a class="reference internal" href="#list-principals">list_principals</a></li>
<li><a class="reference internal" href="#changing-passwords">Changing passwords</a></li>
<li><a class="reference internal" href="#change-password">change_password</a></li>
</ul>
</li>
<li><a class="reference internal" href="#policies">Policies</a><ul>
<li><a class="reference internal" href="#adding-modifying-and-deleting-policies">Adding, modifying and deleting policies</a></li>
<li><a class="reference internal" href="#add-policy">add_policy</a></li>
<li><a class="reference internal" href="#modify-policy">modify_policy</a></li>
<li><a class="reference internal" href="#delete-policy">delete_policy</a></li>
<li><a class="reference internal" href="#retrieving-policies">Retrieving policies</a></li>
<li><a class="reference internal" href="#get-policy">get_policy</a></li>
<li><a class="reference internal" href="#list-policies">list_policies</a></li>
<li><a class="reference internal" href="#policies-and-principals">Policies and principals</a></li>
<li><a class="reference internal" href="#updating-the-history-key">Updating the history key</a></li>
</ul>
</li>
<li><a class="reference internal" href="#privileges">Privileges</a></li>
<li><a class="reference internal" href="#operations-on-the-kerberos-database">Operations on the Kerberos database</a><ul>
<li><a class="reference internal" href="#dumping-a-kerberos-database-to-a-file">Dumping a Kerberos database to a file</a><ul>
<li><a class="reference internal" href="#id3">Examples</a></li>
</ul>
</li>
<li><a class="reference internal" href="#restoring-a-kerberos-database-from-a-dump-file">Restoring a Kerberos database from a dump file</a><ul>
<li><a class="reference internal" href="#id4">Examples</a></li>
</ul>
</li>
<li><a class="reference internal" href="#creating-a-stash-file">Creating a stash file</a><ul>
<li><a class="reference internal" href="#example">Example</a></li>
</ul>
</li>
<li><a class="reference internal" href="#creating-and-destroying-a-kerberos-database">Creating and destroying a Kerberos database</a><ul>
<li><a class="reference internal" href="#id5">Examples</a></li>
</ul>
</li>
<li><a class="reference internal" href="#updating-the-master-key">Updating the master key</a></li>
</ul>
</li>
<li><a class="reference internal" href="#operations-on-the-ldap-database">Operations on the LDAP database</a><ul>
<li><a class="reference internal" href="#creating-a-kerberos-realm">Creating a Kerberos realm</a></li>
<li><a class="reference internal" href="#modifying-a-kerberos-realm">Modifying a Kerberos realm</a></li>
<li><a class="reference internal" href="#destroying-a-kerberos-realm">Destroying a Kerberos realm</a></li>
<li><a class="reference internal" href="#retrieving-information-about-a-kerberos-realm">Retrieving information about a Kerberos realm</a></li>
<li><a class="reference internal" href="#listing-available-kerberos-realms">Listing available Kerberos realms</a></li>
<li><a class="reference internal" href="#stashing-service-object-s-password">Stashing service object’s password</a></li>
<li><a class="reference internal" href="#ticket-policy-operations">Ticket Policy operations</a><ul>
<li><a class="reference internal" href="#creating-a-ticket-policy">Creating a Ticket Policy</a></li>
<li><a class="reference internal" href="#modifying-a-ticket-policy">Modifying a Ticket Policy</a></li>
<li><a class="reference internal" href="#retrieving-information-about-a-ticket-policy">Retrieving Information About a Ticket Policy</a></li>
<li><a class="reference internal" href="#destroying-a-ticket-policy">Destroying a Ticket Policy</a></li>
<li><a class="reference internal" href="#listing-available-ticket-policies">Listing available Ticket Policies</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#cross-realm-authentication">Cross-realm authentication</a></li>
<li><a class="reference internal" href="#changing-the-krbtgt-key">Changing the krbtgt key</a></li>
<li><a class="reference internal" href="#incremental-database-propagation">Incremental database propagation</a><ul>
<li><a class="reference internal" href="#overview">Overview</a></li>
<li><a class="reference internal" href="#sun-mit-incremental-propagation-differences">Sun/MIT incremental propagation differences</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<br/>
<h2>Table of contents</h2>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../user/index.html">For users</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="index.html">For administrators</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="install.html">Installation guide</a></li>
<li class="toctree-l2"><a class="reference internal" href="conf_files/index.html">Configuration Files</a></li>
<li class="toctree-l2"><a class="reference internal" href="realm_config.html">Realm configuration decisions</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#">Database administration</a><ul class="simple">
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="dbtypes.html">Database types</a></li>
<li class="toctree-l2"><a class="reference internal" href="lockout.html">Account lockout</a></li>
<li class="toctree-l2"><a class="reference internal" href="conf_ldap.html">Configuring Kerberos with OpenLDAP back-end</a></li>
<li class="toctree-l2"><a class="reference internal" href="appl_servers.html">Application servers</a></li>
<li class="toctree-l2"><a class="reference internal" href="host_config.html">Host configuration</a></li>
<li class="toctree-l2"><a class="reference internal" href="backup_host.html">Backups of secure hosts</a></li>
<li class="toctree-l2"><a class="reference internal" href="pkinit.html">PKINIT configuration</a></li>
<li class="toctree-l2"><a class="reference internal" href="otp.html">OTP Preauthentication</a></li>
<li class="toctree-l2"><a class="reference internal" href="spake.html">SPAKE Preauthentication</a></li>
<li class="toctree-l2"><a class="reference internal" href="dictionary.html">Addressing dictionary attack risks</a></li>
<li class="toctree-l2"><a class="reference internal" href="princ_dns.html">Principal names and DNS</a></li>
<li class="toctree-l2"><a class="reference internal" href="enctypes.html">Encryption types</a></li>
<li class="toctree-l2"><a class="reference internal" href="https.html">HTTPS proxy configuration</a></li>
<li class="toctree-l2"><a class="reference internal" href="auth_indicator.html">Authentication indicators</a></li>
<li class="toctree-l2"><a class="reference internal" href="admin_commands/index.html">Administration programs</a></li>
<li class="toctree-l2"><a class="reference internal" href="../mitK5defaults.html">MIT Kerberos defaults</a></li>
<li class="toctree-l2"><a class="reference internal" href="env_variables.html">Environment variables</a></li>
<li class="toctree-l2"><a class="reference internal" href="troubleshoot.html">Troubleshooting</a></li>
<li class="toctree-l2"><a class="reference internal" href="advanced/index.html">Advanced topics</a></li>
<li class="toctree-l2"><a class="reference internal" href="various_envs.html">Various links</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../appdev/index.html">For application developers</a></li>
<li class="toctree-l1"><a class="reference internal" href="../plugindev/index.html">For plugin module developers</a></li>
<li class="toctree-l1"><a class="reference internal" href="../build/index.html">Building Kerberos V5</a></li>
<li class="toctree-l1"><a class="reference internal" href="../basic/index.html">Kerberos V5 concepts</a></li>
<li class="toctree-l1"><a class="reference internal" href="../formats/index.html">Protocols and file formats</a></li>
<li class="toctree-l1"><a class="reference internal" href="../mitK5features.html">MIT Kerberos features</a></li>
<li class="toctree-l1"><a class="reference internal" href="../build_this.html">How to build this documentation from the source</a></li>
<li class="toctree-l1"><a class="reference internal" href="../about.html">Contributing to the MIT Kerberos Documentation</a></li>
<li class="toctree-l1"><a class="reference internal" href="../resources.html">Resources</a></li>
</ul>
<br/>
<h4><a href="../index.html">Full Table of Contents</a></h4>
<h4>Search</h4>
<form class="search" action="../search.html" method="get">
<input type="text" name="q" size="18" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
<div class="clearer"></div>
</div>
</div>
<div class="footer-wrapper">
<div class="footer" >
<div class="right" ><i>Release: 1.17</i><br />
© <a href="../copyright.html">Copyright</a> 1985-2019, MIT.
</div>
<div class="left">
<a href="../index.html" title="Full Table of Contents"
>Contents</a> |
<a href="realm_config.html" title="Realm configuration decisions"
>previous</a> |
<a href="dbtypes.html" title="Database types"
>next</a> |
<a href="../genindex.html" title="General Index"
>index</a> |
<a href="../search.html" title="Enter search criteria"
>Search</a> |
<a href="mailto:krb5-bugs@mit.edu?subject=Documentation__Database administration">feedback</a>
</div>
</div>
</div>
</body>
</html>
distrib
>
Mageia
>
7
>
armv7hl
>
media
>
core-updates
>
by-pkgid
>
1bc48f41aa3133e7c600817581bc4c91
>
files
>
88
