path: root/doc/pdf/admin.tex

% Generated by Sphinx.
\def\sphinxdocclass{report}
\documentclass[letterpaper,10pt,english]{sphinxmanual}
\usepackage[utf8]{inputenc}
\DeclareUnicodeCharacter{00A0}{\nobreakspace}
\usepackage{cmap}
\usepackage[T1]{fontenc}
\usepackage{babel}
\usepackage{times}
\usepackage[Bjarne]{fncychap}
\usepackage{longtable}
\usepackage{sphinx}
\usepackage{multirow}


\title{Kerberos Administration Guide}
\date{ }
\release{1.15.1}
\author{MIT}
\newcommand{\sphinxlogo}{}
\renewcommand{\releasename}{Release}
\makeindex

\makeatletter
\def\PYG@reset{\let\PYG@it=\relax \let\PYG@bf=\relax%
    \let\PYG@ul=\relax \let\PYG@tc=\relax%
    \let\PYG@bc=\relax \let\PYG@ff=\relax}
\def\PYG@tok#1{\csname PYG@tok@#1\endcsname}
\def\PYG@toks#1+{\ifx\relax#1\empty\else%
    \PYG@tok{#1}\expandafter\PYG@toks\fi}
\def\PYG@do#1{\PYG@bc{\PYG@tc{\PYG@ul{%
    \PYG@it{\PYG@bf{\PYG@ff{#1}}}}}}}
\def\PYG#1#2{\PYG@reset\PYG@toks#1+\relax+\PYG@do{#2}}

\expandafter\def\csname PYG@tok@gd\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.63,0.00,0.00}{##1}}}
\expandafter\def\csname PYG@tok@gu\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.50,0.00,0.50}{##1}}}
\expandafter\def\csname PYG@tok@gt\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.27,0.87}{##1}}}
\expandafter\def\csname PYG@tok@gs\endcsname{\let\PYG@bf=\textbf}
\expandafter\def\csname PYG@tok@gr\endcsname{\def\PYG@tc##1{\textcolor[rgb]{1.00,0.00,0.00}{##1}}}
\expandafter\def\csname PYG@tok@cm\endcsname{\let\PYG@it=\textit\def\PYG@tc##1{\textcolor[rgb]{0.25,0.50,0.56}{##1}}}
\expandafter\def\csname PYG@tok@vg\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.73,0.38,0.84}{##1}}}
\expandafter\def\csname PYG@tok@m\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.13,0.50,0.31}{##1}}}
\expandafter\def\csname PYG@tok@mh\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.13,0.50,0.31}{##1}}}
\expandafter\def\csname PYG@tok@cs\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.50,0.56}{##1}}\def\PYG@bc##1{\setlength{\fboxsep}{0pt}\colorbox[rgb]{1.00,0.94,0.94}{\strut ##1}}}
\expandafter\def\csname PYG@tok@ge\endcsname{\let\PYG@it=\textit}
\expandafter\def\csname PYG@tok@vc\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.73,0.38,0.84}{##1}}}
\expandafter\def\csname PYG@tok@il\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.13,0.50,0.31}{##1}}}
\expandafter\def\csname PYG@tok@go\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.20,0.20,0.20}{##1}}}
\expandafter\def\csname PYG@tok@cp\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@gi\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.63,0.00}{##1}}}
\expandafter\def\csname PYG@tok@gh\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.00,0.50}{##1}}}
\expandafter\def\csname PYG@tok@ni\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.84,0.33,0.22}{##1}}}
\expandafter\def\csname PYG@tok@nl\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.13,0.44}{##1}}}
\expandafter\def\csname PYG@tok@nn\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.05,0.52,0.71}{##1}}}
\expandafter\def\csname PYG@tok@no\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.38,0.68,0.84}{##1}}}
\expandafter\def\csname PYG@tok@na\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\expandafter\def\csname PYG@tok@nb\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@nc\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.05,0.52,0.71}{##1}}}
\expandafter\def\csname PYG@tok@nd\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.33,0.33,0.33}{##1}}}
\expandafter\def\csname PYG@tok@ne\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@nf\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.02,0.16,0.49}{##1}}}
\expandafter\def\csname PYG@tok@si\endcsname{\let\PYG@it=\textit\def\PYG@tc##1{\textcolor[rgb]{0.44,0.63,0.82}{##1}}}
\expandafter\def\csname PYG@tok@s2\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\expandafter\def\csname PYG@tok@vi\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.73,0.38,0.84}{##1}}}
\expandafter\def\csname PYG@tok@nt\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.02,0.16,0.45}{##1}}}
\expandafter\def\csname PYG@tok@nv\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.73,0.38,0.84}{##1}}}
\expandafter\def\csname PYG@tok@s1\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\expandafter\def\csname PYG@tok@gp\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.78,0.36,0.04}{##1}}}
\expandafter\def\csname PYG@tok@sh\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\expandafter\def\csname PYG@tok@ow\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@sx\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.78,0.36,0.04}{##1}}}
\expandafter\def\csname PYG@tok@bp\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@c1\endcsname{\let\PYG@it=\textit\def\PYG@tc##1{\textcolor[rgb]{0.25,0.50,0.56}{##1}}}
\expandafter\def\csname PYG@tok@kc\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@c\endcsname{\let\PYG@it=\textit\def\PYG@tc##1{\textcolor[rgb]{0.25,0.50,0.56}{##1}}}
\expandafter\def\csname PYG@tok@mf\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.13,0.50,0.31}{##1}}}
\expandafter\def\csname PYG@tok@err\endcsname{\def\PYG@bc##1{\setlength{\fboxsep}{0pt}\fcolorbox[rgb]{1.00,0.00,0.00}{1,1,1}{\strut ##1}}}
\expandafter\def\csname PYG@tok@kd\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@ss\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.32,0.47,0.09}{##1}}}
\expandafter\def\csname PYG@tok@sr\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.14,0.33,0.53}{##1}}}
\expandafter\def\csname PYG@tok@mo\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.13,0.50,0.31}{##1}}}
\expandafter\def\csname PYG@tok@mi\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.13,0.50,0.31}{##1}}}
\expandafter\def\csname PYG@tok@kn\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@o\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.40,0.40,0.40}{##1}}}
\expandafter\def\csname PYG@tok@kr\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@s\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\expandafter\def\csname PYG@tok@kp\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@w\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.73,0.73,0.73}{##1}}}
\expandafter\def\csname PYG@tok@kt\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.56,0.13,0.00}{##1}}}
\expandafter\def\csname PYG@tok@sc\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\expandafter\def\csname PYG@tok@sb\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\expandafter\def\csname PYG@tok@k\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@se\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\expandafter\def\csname PYG@tok@sd\endcsname{\let\PYG@it=\textit\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}

\def\PYGZbs{\char`\\}
\def\PYGZus{\char`\_}
\def\PYGZob{\char`\{}
\def\PYGZcb{\char`\}}
\def\PYGZca{\char`\^}
\def\PYGZam{\char`\&}
\def\PYGZlt{\char`\<}
\def\PYGZgt{\char`\>}
\def\PYGZsh{\char`\#}
\def\PYGZpc{\char`\%}
\def\PYGZdl{\char`\$}
\def\PYGZhy{\char`\-}
\def\PYGZsq{\char`\'}
\def\PYGZdq{\char`\"}
\def\PYGZti{\char`\~}
% for compatibility with earlier versions
\def\PYGZat{@}
\def\PYGZlb{[}
\def\PYGZrb{]}
\makeatother

\begin{document}

\maketitle
\tableofcontents
\phantomsection\label{admin/index::doc}



\chapter{Installation guide}
\label{admin/install:for-administrators}\label{admin/install::doc}\label{admin/install:installation-guide}

\section{Contents}
\label{admin/install:contents}

\subsection{Installing KDCs}
\label{admin/install_kdc:installing-kdcs}\label{admin/install_kdc::doc}
When setting up Kerberos in a production environment, it is best to
have multiple slave KDCs alongside with a master KDC to ensure the
continued availability of the Kerberized services.  Each KDC contains
a copy of the Kerberos database.  The master KDC contains the writable
copy of the realm database, which it replicates to the slave KDCs at
regular intervals.  All database changes (such as password changes)
are made on the master KDC.  Slave KDCs provide Kerberos
ticket-granting services, but not database administration, when the
master KDC is unavailable.  MIT recommends that you install all of
your KDCs to be able to function as either the master or one of the
slaves.  This will enable you to easily switch your master KDC with
one of the slaves if necessary (see {\hyperref[admin/install_kdc:switch-master-slave]{\emph{Switching master and slave KDCs}}}).  This
installation procedure is based on that recommendation.

\begin{notice}{warning}{Warning:}\begin{itemize}
\item {} 
The Kerberos system relies on the availability of correct time
information.  Ensure that the master and all slave KDCs have
properly synchronized clocks.

\item {} 
It is best to install and run KDCs on secured and dedicated
hardware with limited access.  If your KDC is also a file
server, FTP server, Web server, or even just a client machine,
someone who obtained root access through a security hole in any
of those areas could potentially gain access to the Kerberos
database.

\end{itemize}
\end{notice}


\subsubsection{Install and configure the master KDC}
\label{admin/install_kdc:install-and-configure-the-master-kdc}
Install Kerberos either from the OS-provided packages or from the
source (See \emph{do\_build}).

\begin{notice}{note}{Note:}
For the purpose of this document we will use the following
names:

\begin{Verbatim}[commandchars=\\\{\}]
kerberos.mit.edu    \PYGZhy{} master KDC
kerberos\PYGZhy{}1.mit.edu  \PYGZhy{} slave KDC
ATHENA.MIT.EDU      \PYGZhy{} realm name
.k5.ATHENA.MIT.EDU  \PYGZhy{} stash file
admin/admin         \PYGZhy{} admin principal
\end{Verbatim}

See {\hyperref[mitK5defaults:mitk5defaults]{\emph{MIT Kerberos defaults}}} for the default names and locations
of the relevant to this topic files.  Adjust the names and
paths to your system environment.
\end{notice}


\subsubsection{Edit KDC configuration files}
\label{admin/install_kdc:edit-kdc-configuration-files}
Modify the configuration files, {\hyperref[admin/conf_files/krb5_conf:krb5-conf-5]{\emph{krb5.conf}}} and
{\hyperref[admin/conf_files/kdc_conf:kdc-conf-5]{\emph{kdc.conf}}}, to reflect the correct information (such as
domain-realm mappings and Kerberos servers names) for your realm.
(See {\hyperref[mitK5defaults:mitk5defaults]{\emph{MIT Kerberos defaults}}} for the recommended default locations for
these files).

Most of the tags in the configuration have default values that will
work well for most sites.  There are some tags in the
{\hyperref[admin/conf_files/krb5_conf:krb5-conf-5]{\emph{krb5.conf}}} file whose values must be specified, and this
section will explain those.

If the locations for these configuration files differs from the
default ones, set \textbf{KRB5\_CONFIG} and \textbf{KRB5\_KDC\_PROFILE} environment
variables to point to the krb5.conf and kdc.conf respectively.  For
example:

\begin{Verbatim}[commandchars=\\\{\}]
export KRB5\PYGZus{}CONFIG=/yourdir/krb5.conf
export KRB5\PYGZus{}KDC\PYGZus{}PROFILE=/yourdir/kdc.conf
\end{Verbatim}


\paragraph{krb5.conf}
\label{admin/install_kdc:krb5-conf}
If you are not using DNS TXT records (see {\hyperref[admin/realm_config:mapping-hostnames]{\emph{Mapping hostnames onto Kerberos realms}}}),
you must specify the \textbf{default\_realm} in the {\hyperref[admin/conf_files/krb5_conf:libdefaults]{\emph{{[}libdefaults{]}}}}
section.  If you are not using DNS URI or SRV records (see
{\hyperref[admin/realm_config:kdc-hostnames]{\emph{Hostnames for KDCs}}} and {\hyperref[admin/realm_config:kdc-discovery]{\emph{KDC Discovery}}}), you must include the
\textbf{kdc} tag for each \emph{realm} in the {\hyperref[admin/conf_files/krb5_conf:realms]{\emph{{[}realms{]}}}} section.  To
communicate with the kadmin server in each realm, the \textbf{admin\_server}
tag must be set in the
{\hyperref[admin/conf_files/krb5_conf:realms]{\emph{{[}realms{]}}}} section.

An example krb5.conf file:

\begin{Verbatim}[commandchars=\\\{\}]
[libdefaults]
    default\PYGZus{}realm = ATHENA.MIT.EDU

[realms]
    ATHENA.MIT.EDU = \PYGZob{}
        kdc = kerberos.mit.edu
        kdc = kerberos\PYGZhy{}1.mit.edu
        admin\PYGZus{}server = kerberos.mit.edu
    \PYGZcb{}
\end{Verbatim}


\paragraph{kdc.conf}
\label{admin/install_kdc:kdc-conf}
The kdc.conf file can be used to control the listening ports of the
KDC and kadmind, as well as realm-specific defaults, the database type
and location, and logging.

An example kdc.conf file:

\begin{Verbatim}[commandchars=\\\{\}]
[kdcdefaults]
    kdc\PYGZus{}listen = 88
    kdc\PYGZus{}tcp\PYGZus{}listen = 88

[realms]
    ATHENA.MIT.EDU = \PYGZob{}
        kadmind\PYGZus{}port = 749
        max\PYGZus{}life = 12h 0m 0s
        max\PYGZus{}renewable\PYGZus{}life = 7d 0h 0m 0s
        master\PYGZus{}key\PYGZus{}type = aes256\PYGZhy{}cts
        supported\PYGZus{}enctypes = aes256\PYGZhy{}cts:normal aes128\PYGZhy{}cts:normal
        \PYGZsh{} If the default location does not suit your setup,
        \PYGZsh{} explicitly configure the following values:
        \PYGZsh{}    database\PYGZus{}name = /var/krb5kdc/principal
        \PYGZsh{}    key\PYGZus{}stash\PYGZus{}file = /var/krb5kdc/.k5.ATHENA.MIT.EDU
        \PYGZsh{}    acl\PYGZus{}file = /var/krb5kdc/kadm5.acl
    \PYGZcb{}

[logging]
    \PYGZsh{} By default, the KDC and kadmind will log output using
    \PYGZsh{} syslog.  You can instead send log output to files like this:
    kdc = FILE:/var/log/krb5kdc.log
    admin\PYGZus{}server = FILE:/var/log/kadmin.log
    default = FILE:/var/log/krb5lib.log
\end{Verbatim}

Replace \code{ATHENA.MIT.EDU} and \code{kerberos.mit.edu} with the name of
your Kerberos realm and server respectively.

\begin{notice}{note}{Note:}
You have to have write permission on the target directories
(these directories must exist) used by \textbf{database\_name},
\textbf{key\_stash\_file}, and \textbf{acl\_file}.
\end{notice}


\subsubsection{Create the KDC database}
\label{admin/install_kdc:create-the-kdc-database}\label{admin/install_kdc:create-db}
You will use the {\hyperref[admin/admin_commands/kdb5_util:kdb5-util-8]{\emph{kdb5\_util}}} command on the master KDC to
create the Kerberos database and the optional \emph{stash\_definition}.

\begin{notice}{note}{Note:}
If you choose not to install a stash file, the KDC will
prompt you for the master key each time it starts up.  This
means that the KDC will not be able to start automatically,
such as after a system reboot.
\end{notice}

{\hyperref[admin/admin_commands/kdb5_util:kdb5-util-8]{\emph{kdb5\_util}}} will prompt you for the master password for the
Kerberos database.  This password can be any string.  A good password
is one you can remember, but that no one else can guess.  Examples of
bad passwords are words that can be found in a dictionary, any common
or popular name, especially a famous person (or cartoon character),
your username in any form (e.g., forward, backward, repeated twice,
etc.), and any of the sample passwords that appear in this manual.
One example of a password which might be good if it did not appear in
this manual is ``MITiys4K5!'', which represents the sentence ``MIT is
your source for Kerberos 5!''  (It's the first letter of each word,
substituting the numeral ``4'' for the word ``for'', and includes the
punctuation mark at the end.)

The following is an example of how to create a Kerberos database and
stash file on the master KDC, using the {\hyperref[admin/admin_commands/kdb5_util:kdb5-util-8]{\emph{kdb5\_util}}} command.
Replace \code{ATHENA.MIT.EDU} with the name of your Kerberos realm:

\begin{Verbatim}[commandchars=\\\{\}]
shell\PYGZpc{} kdb5\PYGZus{}util create \PYGZhy{}r ATHENA.MIT.EDU \PYGZhy{}s

Initializing database \PYGZsq{}/usr/local/var/krb5kdc/principal\PYGZsq{} for realm \PYGZsq{}ATHENA.MIT.EDU\PYGZsq{},
master key name \PYGZsq{}K/M@ATHENA.MIT.EDU\PYGZsq{}
You will be prompted for the database Master Password.
It is important that you NOT FORGET this password.
Enter KDC database master key:  \PYGZlt{}= Type the master password.
Re\PYGZhy{}enter KDC database master key to verify:  \PYGZlt{}= Type it again.
shell\PYGZpc{}
\end{Verbatim}

This will create five files in {\hyperref[mitK5defaults:paths]{\emph{LOCALSTATEDIR}}}\code{/krb5kdc} (or at the locations specified
in {\hyperref[admin/conf_files/kdc_conf:kdc-conf-5]{\emph{kdc.conf}}}):
\begin{itemize}
\item {} 
two Kerberos database files, \code{principal}, and \code{principal.ok}

\item {} 
the Kerberos administrative database file, \code{principal.kadm5}

\item {} 
the administrative database lock file, \code{principal.kadm5.lock}

\item {} 
the stash file, in this example \code{.k5.ATHENA.MIT.EDU}.  If you do
not want a stash file, run the above command without the \textbf{-s}
option.

\end{itemize}

For more information on administrating Kerberos database see
{\hyperref[admin/database:db-operations]{\emph{Operations on the Kerberos database}}}.


\subsubsection{Add administrators to the ACL file}
\label{admin/install_kdc:add-administrators-to-the-acl-file}\label{admin/install_kdc:admin-acl}
Next, you need create an Access Control List (ACL) file and put the
Kerberos principal of at least one of the administrators into it.
This file is used by the {\hyperref[admin/admin_commands/kadmind:kadmind-8]{\emph{kadmind}}} daemon to control which
principals may view and make privileged modifications to the Kerberos
database files.  The ACL filename is determined by the \textbf{acl\_file}
variable in {\hyperref[admin/conf_files/kdc_conf:kdc-conf-5]{\emph{kdc.conf}}}; the default is {\hyperref[mitK5defaults:paths]{\emph{LOCALSTATEDIR}}}\code{/krb5kdc}\code{/kadm5.acl}.

For more information on Kerberos ACL file see {\hyperref[admin/conf_files/kadm5_acl:kadm5-acl-5]{\emph{kadm5.acl}}}.


\subsubsection{Add administrators to the Kerberos database}
\label{admin/install_kdc:add-administrators-to-the-kerberos-database}\label{admin/install_kdc:addadmin-kdb}
Next you need to add administrative principals (i.e., principals who
are allowed to administer Kerberos database) to the Kerberos database.
You \emph{must} add at least one principal now to allow communication
between the Kerberos administration daemon kadmind and the kadmin
program over the network for further administration.  To do this, use
the kadmin.local utility on the master KDC.  kadmin.local is designed
to be run on the master KDC host without using Kerberos authentication
to an admin server; instead, it must have read and write access to the
Kerberos database on the local filesystem.

The administrative principals you create should be the ones you added
to the ACL file (see {\hyperref[admin/install_kdc:admin-acl]{\emph{Add administrators to the ACL file}}}).

In the following example, the administrative principal \code{admin/admin}
is created:

\begin{Verbatim}[commandchars=\\\{\}]
shell\PYGZpc{} kadmin.local

kadmin.local: addprinc admin/admin@ATHENA.MIT.EDU

WARNING: no policy specified for \PYGZdq{}admin/admin@ATHENA.MIT.EDU\PYGZdq{};
assigning \PYGZdq{}default\PYGZdq{}.
Enter password for principal admin/admin@ATHENA.MIT.EDU:  \PYGZlt{}= Enter a password.
Re\PYGZhy{}enter password for principal admin/admin@ATHENA.MIT.EDU:  \PYGZlt{}= Type it again.
Principal \PYGZdq{}admin/admin@ATHENA.MIT.EDU\PYGZdq{} created.
kadmin.local:
\end{Verbatim}


\subsubsection{Start the Kerberos daemons on the master KDC}
\label{admin/install_kdc:start-the-kerberos-daemons-on-the-master-kdc}\label{admin/install_kdc:start-kdc-daemons}
At this point, you are ready to start the Kerberos KDC
({\hyperref[admin/admin_commands/krb5kdc:krb5kdc-8]{\emph{krb5kdc}}}) and administrative daemons on the Master KDC.  To
do so, type:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n}{shell}\PYG{o}{\PYGZpc{}} \PYG{n}{krb5kdc}
\PYG{n}{shell}\PYG{o}{\PYGZpc{}} \PYG{n}{kadmind}
\end{Verbatim}

Each server daemon will fork and run in the background.

\begin{notice}{note}{Note:}
Assuming you want these daemons to start up automatically at
boot time, you can add them to the KDC's \code{/etc/rc} or
\code{/etc/inittab} file.  You need to have a
\emph{stash\_definition} in order to do this.
\end{notice}

You can verify that they started properly by checking for their
startup messages in the logging locations you defined in
{\hyperref[admin/conf_files/krb5_conf:krb5-conf-5]{\emph{krb5.conf}}} (see {\hyperref[admin/conf_files/kdc_conf:logging]{\emph{{[}logging{]}}}}).  For example:

\begin{Verbatim}[commandchars=\\\{\}]
shell\PYGZpc{} tail /var/log/krb5kdc.log
Dec 02 12:35:47 beeblebrox krb5kdc[3187](info): commencing operation
shell\PYGZpc{} tail /var/log/kadmin.log
Dec 02 12:35:52 beeblebrox kadmind[3189](info): starting
\end{Verbatim}

Any errors the daemons encounter while starting will also be listed in
the logging output.

As an additional verification, check if \emph{kinit(1)} succeeds
against the principals that you have created on the previous step
({\hyperref[admin/install_kdc:addadmin-kdb]{\emph{Add administrators to the Kerberos database}}}).  Run:

\begin{Verbatim}[commandchars=\\\{\}]
shell\PYGZpc{} kinit admin/admin@ATHENA.MIT.EDU
\end{Verbatim}


\subsubsection{Install the slave KDCs}
\label{admin/install_kdc:install-the-slave-kdcs}
You are now ready to start configuring the slave KDCs.

\begin{notice}{note}{Note:}
Assuming you are setting the KDCs up so that you can easily
switch the master KDC with one of the slaves, you should
perform each of these steps on the master KDC as well as the
slave KDCs, unless these instructions specify otherwise.
\end{notice}


\paragraph{Create host keytabs for slave KDCs}
\label{admin/install_kdc:slave-host-key}\label{admin/install_kdc:create-host-keytabs-for-slave-kdcs}
Each KDC needs a \code{host} key in the Kerberos database.  These keys
are used for mutual authentication when propagating the database dump
file from the master KDC to the secondary KDC servers.

On the master KDC, connect to administrative interface and create the
host principal for each of the KDCs' \code{host} services.  For example,
if the master KDC were called \code{kerberos.mit.edu}, and you had a
slave KDC named \code{kerberos-1.mit.edu}, you would type the following:

\begin{Verbatim}[commandchars=\\\{\}]
shell\PYGZpc{} kadmin
kadmin: addprinc \PYGZhy{}randkey host/kerberos.mit.edu
NOTICE: no policy specified for \PYGZdq{}host/kerberos.mit.edu@ATHENA.MIT.EDU\PYGZdq{}; assigning \PYGZdq{}default\PYGZdq{}
Principal \PYGZdq{}host/kerberos.mit.edu@ATHENA.MIT.EDU\PYGZdq{} created.

kadmin: addprinc \PYGZhy{}randkey host/kerberos\PYGZhy{}1.mit.edu
NOTICE: no policy specified for \PYGZdq{}host/kerberos\PYGZhy{}1.mit.edu@ATHENA.MIT.EDU\PYGZdq{}; assigning \PYGZdq{}default\PYGZdq{}
Principal \PYGZdq{}host/kerberos\PYGZhy{}1.mit.edu@ATHENA.MIT.EDU\PYGZdq{} created.
\end{Verbatim}

It is not strictly necessary to have the master KDC server in the
Kerberos database, but it can be handy if you want to be able to swap
the master KDC with one of the slaves.

Next, extract \code{host} random keys for all participating KDCs and
store them in each host's default keytab file.  Ideally, you should
extract each keytab locally on its own KDC.  If this is not feasible,
you should use an encrypted session to send them across the network.
To extract a keytab directly on a slave KDC called
\code{kerberos-1.mit.edu}, you would execute the following command:

\begin{Verbatim}[commandchars=\\\{\}]
kadmin: ktadd host/kerberos\PYGZhy{}1.mit.edu
Entry for principal host/kerberos\PYGZhy{}1.mit.edu with kvno 2, encryption
    type aes256\PYGZhy{}cts\PYGZhy{}hmac\PYGZhy{}sha1\PYGZhy{}96 added to keytab FILE:/etc/krb5.keytab.
Entry for principal host/kerberos\PYGZhy{}1.mit.edu with kvno 2, encryption
    type aes128\PYGZhy{}cts\PYGZhy{}hmac\PYGZhy{}sha1\PYGZhy{}96 added to keytab FILE:/etc/krb5.keytab.
Entry for principal host/kerberos\PYGZhy{}1.mit.edu with kvno 2, encryption
    type des3\PYGZhy{}cbc\PYGZhy{}sha1 added to keytab FILE:/etc/krb5.keytab.
Entry for principal host/kerberos\PYGZhy{}1.mit.edu with kvno 2, encryption
    type arcfour\PYGZhy{}hmac added to keytab FILE:/etc/krb5.keytab.
\end{Verbatim}

If you are instead extracting a keytab for the slave KDC called
\code{kerberos-1.mit.edu} on the master KDC, you should use a dedicated
temporary keytab file for that machine's keytab:

\begin{Verbatim}[commandchars=\\\{\}]
kadmin: ktadd \PYGZhy{}k /tmp/kerberos\PYGZhy{}1.keytab host/kerberos\PYGZhy{}1.mit.edu
Entry for principal host/kerberos\PYGZhy{}1.mit.edu with kvno 2, encryption
    type aes256\PYGZhy{}cts\PYGZhy{}hmac\PYGZhy{}sha1\PYGZhy{}96 added to keytab FILE:/etc/krb5.keytab.
Entry for principal host/kerberos\PYGZhy{}1.mit.edu with kvno 2, encryption
    type aes128\PYGZhy{}cts\PYGZhy{}hmac\PYGZhy{}sha1\PYGZhy{}96 added to keytab FILE:/etc/krb5.keytab.
\end{Verbatim}

The file \code{/tmp/kerberos-1.keytab} can then be installed as
\code{/etc/krb5.keytab} on the host \code{kerberos-1.mit.edu}.


\paragraph{Configure slave KDCs}
\label{admin/install_kdc:configure-slave-kdcs}
Database propagation copies the contents of the master's database, but
does not propagate configuration files, stash files, or the kadm5 ACL
file.  The following files must be copied by hand to each slave (see
{\hyperref[mitK5defaults:mitk5defaults]{\emph{MIT Kerberos defaults}}} for the default locations for these files):
\begin{itemize}
\item {} 
krb5.conf

\item {} 
kdc.conf

\item {} 
kadm5.acl

\item {} 
master key stash file

\end{itemize}

Move the copied files into their appropriate directories, exactly as
on the master KDC.  kadm5.acl is only needed to allow a slave to swap
with the master KDC.

The database is propagated from the master KDC to the slave KDCs via
the {\hyperref[admin/admin_commands/kpropd:kpropd-8]{\emph{kpropd}}} daemon.  You must explicitly specify the
principals which are allowed to provide Kerberos dump updates on the
slave machine with a new database.  Create a file named kpropd.acl in
the KDC state directory containing the \code{host} principals for each of
the KDCs:

\begin{Verbatim}[commandchars=\\\{\}]
host/kerberos.mit.edu@ATHENA.MIT.EDU
host/kerberos\PYGZhy{}1.mit.edu@ATHENA.MIT.EDU
\end{Verbatim}

\begin{notice}{note}{Note:}
If you expect that the master and slave KDCs will be
switched at some point of time, list the host principals
from all participating KDC servers in kpropd.acl files on
all of the KDCs.  Otherwise, you only need to list the
master KDC's host principal in the kpropd.acl files of the
slave KDCs.
\end{notice}

Then, add the following line to \code{/etc/inetd.conf} on each KDC
(adjust the path to kpropd):

\begin{Verbatim}[commandchars=\\\{\}]
krb5\PYGZus{}prop stream tcp nowait root /usr/local/sbin/kpropd kpropd
\end{Verbatim}

You also need to add the following line to \code{/etc/services} on each
KDC, if it is not already present (assuming that the default port is
used):

\begin{Verbatim}[commandchars=\\\{\}]
krb5\PYGZus{}prop       754/tcp               \PYGZsh{} Kerberos slave propagation
\end{Verbatim}

Restart inetd daemon.

Alternatively, start {\hyperref[admin/admin_commands/kpropd:kpropd-8]{\emph{kpropd}}} as a stand-alone daemon.  This is
required when incremental propagation is enabled.

Now that the slave KDC is able to accept database propagation, you’ll
need to propagate the database from the master server.

NOTE: Do not start the slave KDC yet; you still do not have a copy of
the master's database.


\paragraph{Propagate the database to each slave KDC}
\label{admin/install_kdc:kprop-to-slaves}\label{admin/install_kdc:propagate-the-database-to-each-slave-kdc}
First, create a dump file of the database on the master KDC, as
follows:

\begin{Verbatim}[commandchars=\\\{\}]
shell\PYGZpc{} kdb5\PYGZus{}util dump /usr/local/var/krb5kdc/slave\PYGZus{}datatrans
\end{Verbatim}

Then, manually propagate the database to each slave KDC, as in the
following example:

\begin{Verbatim}[commandchars=\\\{\}]
shell\PYGZpc{} kprop \PYGZhy{}f /usr/local/var/krb5kdc/slave\PYGZus{}datatrans kerberos\PYGZhy{}1.mit.edu

Database propagation to kerberos\PYGZhy{}1.mit.edu: SUCCEEDED
\end{Verbatim}

You will need a script to dump and propagate the database. The
following is an example of a Bourne shell script that will do this.

\begin{notice}{note}{Note:}
Remember that you need to replace \code{/usr/local/var/krb5kdc}
with the name of the KDC state directory.
\end{notice}

\begin{Verbatim}[commandchars=\\\{\}]
\PYGZsh{}!/bin/sh

kdclist = \PYGZdq{}kerberos\PYGZhy{}1.mit.edu kerberos\PYGZhy{}2.mit.edu\PYGZdq{}

kdb5\PYGZus{}util dump /usr/local/var/krb5kdc/slave\PYGZus{}datatrans

for kdc in \PYGZdl{}kdclist
do
    kprop \PYGZhy{}f /usr/local/var/krb5kdc/slave\PYGZus{}datatrans \PYGZdl{}kdc
done
\end{Verbatim}

You will need to set up a cron job to run this script at the intervals
you decided on earlier (see {\hyperref[admin/realm_config:db-prop]{\emph{Database propagation}}}).

Now that the slave KDC has a copy of the Kerberos database, you can
start the krb5kdc daemon:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n}{shell}\PYG{o}{\PYGZpc{}} \PYG{n}{krb5kdc}
\end{Verbatim}

As with the master KDC, you will probably want to add this command to
the KDCs' \code{/etc/rc} or \code{/etc/inittab} files, so they will start
the krb5kdc daemon automatically at boot time.


\subparagraph{Propagation failed?}
\label{admin/install_kdc:propagation-failed}
You may encounter the following error messages. For a more detailed
discussion on possible causes and solutions click on the error link
to be redirected to {\hyperref[admin/troubleshoot:troubleshoot]{\emph{Troubleshooting}}} section.
\begin{enumerate}
\item {} 
{\hyperref[admin/troubleshoot:kprop-no-route]{\emph{kprop: No route to host while connecting to server}}}

\item {} 
{\hyperref[admin/troubleshoot:kprop-con-refused]{\emph{kprop: Connection refused while connecting to server}}}

\item {} 
{\hyperref[admin/troubleshoot:kprop-sendauth-exchange]{\emph{kprop: Server rejected authentication (during sendauth exchange) while authenticating to server}}}

\end{enumerate}


\subsubsection{Add Kerberos principals to the database}
\label{admin/install_kdc:add-kerberos-principals-to-the-database}
Once your KDCs are set up and running, you are ready to use
{\hyperref[admin/admin_commands/kadmin_local:kadmin-1]{\emph{kadmin}}} to load principals for your users, hosts, and other
services into the Kerberos database.  This procedure is described
fully in {\hyperref[admin/database:add-mod-del-princs]{\emph{Adding, modifying and deleting principals}}}.

You may occasionally want to use one of your slave KDCs as the master.
This might happen if you are upgrading the master KDC, or if your
master KDC has a disk crash.  See the following section for the
instructions.


\subsubsection{Switching master and slave KDCs}
\label{admin/install_kdc:switching-master-and-slave-kdcs}\label{admin/install_kdc:switch-master-slave}
You may occasionally want to use one of your slave KDCs as the master.
This might happen if you are upgrading the master KDC, or if your
master KDC has a disk crash.

Assuming you have configured all of your KDCs to be able to function
as either the master KDC or a slave KDC (as this document recommends),
all you need to do to make the changeover is:

If the master KDC is still running, do the following on the \emph{old}
master KDC:
\begin{enumerate}
\item {} 
Kill the kadmind process.

\item {} 
Disable the cron job that propagates the database.

\item {} 
Run your database propagation script manually, to ensure that the
slaves all have the latest copy of the database (see
{\hyperref[admin/install_kdc:kprop-to-slaves]{\emph{Propagate the database to each slave KDC}}}).

\end{enumerate}

On the \emph{new} master KDC:
\begin{enumerate}
\item {} 
Start the {\hyperref[admin/admin_commands/kadmind:kadmind-8]{\emph{kadmind}}} daemon (see {\hyperref[admin/install_kdc:start-kdc-daemons]{\emph{Start the Kerberos daemons on the master KDC}}}).

\item {} 
Set up the cron job to propagate the database (see
{\hyperref[admin/install_kdc:kprop-to-slaves]{\emph{Propagate the database to each slave KDC}}}).

\item {} 
Switch the CNAMEs of the old and new master KDCs.  If you can't do
this, you'll need to change the {\hyperref[admin/conf_files/krb5_conf:krb5-conf-5]{\emph{krb5.conf}}} file on every
client machine in your Kerberos realm.

\end{enumerate}


\subsubsection{Incremental database propagation}
\label{admin/install_kdc:incremental-database-propagation}
If you expect your Kerberos database to become large, you may wish to
set up incremental propagation to slave KDCs.  See {\hyperref[admin/database:incr-db-prop]{\emph{Incremental database propagation}}}
for details.


\subsection{Installing and configuring UNIX client machines}
\label{admin/install_clients:installing-and-configuring-unix-client-machines}\label{admin/install_clients::doc}
The Kerberized client programs include \emph{kinit(1)},
\emph{klist(1)}, \emph{kdestroy(1)}, and \emph{kpasswd(1)}.  All of
these programs are in the directory {\hyperref[mitK5defaults:paths]{\emph{BINDIR}}}.

You can often integrate Kerberos with the login system on client
machines, typically through the use of PAM.  The details vary by
operating system, and should be covered in your operating system's
documentation.  If you do this, you will need to make sure your users
know to use their Kerberos passwords when they log in.

You will also need to educate your users to use the ticket management
programs kinit, klist, and kdestroy.  If you do not have Kerberos
password changing integrated into the native password program (again,
typically through PAM), you will need to educate users to use kpasswd
in place of its non-Kerberos counterparts passwd.


\subsubsection{Client machine configuration files}
\label{admin/install_clients:client-machine-configuration-files}
Each machine running Kerberos should have a {\hyperref[admin/conf_files/krb5_conf:krb5-conf-5]{\emph{krb5.conf}}} file.
At a minimum, it should define a \textbf{default\_realm} setting in
{\hyperref[admin/conf_files/krb5_conf:libdefaults]{\emph{{[}libdefaults{]}}}}.  If you are not using DNS SRV records
({\hyperref[admin/realm_config:kdc-hostnames]{\emph{Hostnames for KDCs}}}) or URI records ({\hyperref[admin/realm_config:kdc-discovery]{\emph{KDC Discovery}}}), it must
also contain a {\hyperref[admin/conf_files/krb5_conf:realms]{\emph{{[}realms{]}}}} section containing information for your
realm's KDCs.

Consider setting \textbf{rdns} to false in order to reduce your dependence
on precisely correct DNS information for service hostnames.  Turning
this flag off means that service hostnames will be canonicalized
through forward name resolution (which adds your domain name to
unqualified hostnames, and resolves CNAME records in DNS), but not
through reverse address lookup.  The default value of this flag is
true for historical reasons only.

If you anticipate users frequently logging into remote hosts
(e.g., using ssh) using forwardable credentials, consider setting
\textbf{forwardable} to true so that users obtain forwardable tickets by
default.  Otherwise users will need to use \code{kinit -f} to get
forwardable tickets.

Consider adjusting the \textbf{ticket\_lifetime} setting to match the likely
length of sessions for your users.  For instance, if most of your
users will be logging in for an eight-hour workday, you could set the
default to ten hours so that tickets obtained in the morning expire
shortly after the end of the workday.  Users can still manually
request longer tickets when necessary, up to the maximum allowed by
each user's principal record on the KDC.

If a client host may access services in different realms, it may be
useful to define a {\hyperref[admin/conf_files/krb5_conf:domain-realm]{\emph{{[}domain\_realm{]}}}} mapping so that clients know
which hosts belong to which realms.  However, if your clients and KDC
are running release 1.7 or later, it is also reasonable to leave this
section out on client machines and just define it in the KDC's
krb5.conf.


\subsection{UNIX Application Servers}
\label{admin/install_appl_srv:unix-application-servers}\label{admin/install_appl_srv::doc}
An application server is a host that provides one or more services
over the network.  Application servers can be ``secure'' or ``insecure.''
A ``secure'' host is set up to require authentication from every client
connecting to it.  An ``insecure'' host will still provide Kerberos
authentication, but will also allow unauthenticated clients to
connect.

If you have Kerberos V5 installed on all of your client machines, MIT
recommends that you make your hosts secure, to take advantage of the
security that Kerberos authentication affords.  However, if you have
some clients that do not have Kerberos V5 installed, you can run an
insecure server, and still take advantage of Kerberos V5's single
sign-on capability.


\subsubsection{The keytab file}
\label{admin/install_appl_srv:the-keytab-file}\label{admin/install_appl_srv:keytab-file}
All Kerberos server machines need a keytab file to authenticate to the
KDC.  By default on UNIX-like systems this file is named {\hyperref[mitK5defaults:paths]{\emph{DEFKTNAME}}}.
The keytab file is an local copy of the host's key.  The keytab file
is a potential point of entry for a break-in, and if compromised,
would allow unrestricted access to its host.  The keytab file should
be readable only by root, and should exist only on the machine's local
disk.  The file should not be part of any backup of the machine,
unless access to the backup data is secured as tightly as access to
the machine's root password.

In order to generate a keytab for a host, the host must have a
principal in the Kerberos database.  The procedure for adding hosts to
the database is described fully in {\hyperref[admin/database:add-mod-del-princs]{\emph{Adding, modifying and deleting principals}}}.  (See
{\hyperref[admin/install_kdc:slave-host-key]{\emph{Create host keytabs for slave KDCs}}} for a brief description.)  The keytab is
generated by running {\hyperref[admin/admin_commands/kadmin_local:kadmin-1]{\emph{kadmin}}} and issuing the {\hyperref[admin/admin_commands/kadmin_local:ktadd]{\emph{ktadd}}}
command.

For example, to generate a keytab file to allow the host
\code{trillium.mit.edu} to authenticate for the services host, ftp, and
pop, the administrator \code{joeadmin} would issue the command (on
\code{trillium.mit.edu}):

\begin{Verbatim}[commandchars=\\\{\}]
trillium\PYGZpc{} kadmin
kadmin5: ktadd host/trillium.mit.edu ftp/trillium.mit.edu
    pop/trillium.mit.edu
kadmin: Entry for principal host/trillium.mit.edu@ATHENA.MIT.EDU with
    kvno 3, encryption type DES\PYGZhy{}CBC\PYGZhy{}CRC added to keytab
    FILE:/etc/krb5.keytab.
kadmin: Entry for principal ftp/trillium.mit.edu@ATHENA.MIT.EDU with
    kvno 3, encryption type DES\PYGZhy{}CBC\PYGZhy{}CRC added to keytab
    FILE:/etc/krb5.keytab.
kadmin: Entry for principal pop/trillium.mit.edu@ATHENA.MIT.EDU with
    kvno 3, encryption type DES\PYGZhy{}CBC\PYGZhy{}CRC added to keytab
    FILE:/etc/krb5.keytab.
kadmin5: quit
trillium\PYGZpc{}
\end{Verbatim}

If you generate the keytab file on another host, you need to get a
copy of the keytab file onto the destination host (\code{trillium}, in
the above example) without sending it unencrypted over the network.


\subsubsection{Some advice about secure hosts}
\label{admin/install_appl_srv:some-advice-about-secure-hosts}
Kerberos V5 can protect your host from certain types of break-ins, but
it is possible to install Kerberos V5 and still leave your host
vulnerable to attack.  Obviously an installation guide is not the
place to try to include an exhaustive list of countermeasures for
every possible attack, but it is worth noting some of the larger holes
and how to close them.

We recommend that backups of secure machines exclude the keytab file
({\hyperref[mitK5defaults:paths]{\emph{DEFKTNAME}}}).  If this is not possible, the backups should at least be
done locally, rather than over a network, and the backup tapes should
be physically secured.

The keytab file and any programs run by root, including the Kerberos
V5 binaries, should be kept on local disk.  The keytab file should be
readable only by root.


\section{Additional references}
\label{admin/install:additional-references}\begin{enumerate}
\item {} 
Debian: \href{http://techpubs.spinlocksolutions.com/dklar/kerberos.html}{Setting up MIT Kerberos 5}

\item {} 
Solaris: \href{http://download.oracle.com/docs/cd/E19253-01/816-4557/6maosrjv2/index.html}{Configuring the Kerberos Service}

\end{enumerate}


\chapter{Configuration Files}
\label{admin/conf_files/index:configuration-files}\label{admin/conf_files/index::doc}
Kerberos uses configuration files to allow administrators to specify
settings on a per-machine basis.  {\hyperref[admin/conf_files/krb5_conf:krb5-conf-5]{\emph{krb5.conf}}} applies to all
applications using the Kerboros library, on clients and servers.
For KDC-specific applications, additional settings can be specified in
{\hyperref[admin/conf_files/kdc_conf:kdc-conf-5]{\emph{kdc.conf}}}; the two files are merged into a configuration profile
used by applications accessing the KDC database directly.  {\hyperref[admin/conf_files/kadm5_acl:kadm5-acl-5]{\emph{kadm5.acl}}}
is also only used on the KDC, it controls permissions for modifying the
KDC database.


\section{Contents}
\label{admin/conf_files/index:contents}

\subsection{krb5.conf}
\label{admin/conf_files/krb5_conf::doc}\label{admin/conf_files/krb5_conf:krb5-conf}\label{admin/conf_files/krb5_conf:krb5-conf-5}
The krb5.conf file contains Kerberos configuration information,
including the locations of KDCs and admin servers for the Kerberos
realms of interest, defaults for the current realm and for Kerberos
applications, and mappings of hostnames onto Kerberos realms.
Normally, you should install your krb5.conf file in the directory
\code{/etc}.  You can override the default location by setting the
environment variable \textbf{KRB5\_CONFIG}.  Multiple colon-separated
filenames may be specified in \textbf{KRB5\_CONFIG}; all files which are
present will be read.  Starting in release 1.14, directory names can
also be specified in \textbf{KRB5\_CONFIG}; all files within the directory
whose names consist solely of alphanumeric characters, dashes, or
underscores will be read.


\subsubsection{Structure}
\label{admin/conf_files/krb5_conf:structure}
The krb5.conf file is set up in the style of a Windows INI file.
Sections are headed by the section name, in square brackets.  Each
section may contain zero or more relations, of the form:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n}{foo} \PYG{o}{=} \PYG{n}{bar}
\end{Verbatim}

or:

\begin{Verbatim}[commandchars=\\\{\}]
fubar = \PYGZob{}
    foo = bar
    baz = quux
\PYGZcb{}
\end{Verbatim}

Placing a `*' at the end of a line indicates that this is the \emph{final}
value for the tag.  This means that neither the remainder of this
configuration file nor any other configuration file will be checked
for any other values for this tag.

For example, if you have the following lines:

\begin{Verbatim}[commandchars=\\\{\}]
foo = bar*
foo = baz
\end{Verbatim}

then the second value of \code{foo} (\code{baz}) would never be read.

The krb5.conf file can include other files using either of the
following directives at the beginning of a line:

\begin{Verbatim}[commandchars=\\\{\}]
include FILENAME
includedir DIRNAME
\end{Verbatim}

\emph{FILENAME} or \emph{DIRNAME} should be an absolute path. The named file or
directory must exist and be readable.  Including a directory includes
all files within the directory whose names consist solely of
alphanumeric characters, dashes, or underscores.  Starting in release
1.15, files with names ending in ''.conf'' are also included.  Included
profile files are syntactically independent of their parents, so each
included file must begin with a section header.

The krb5.conf file can specify that configuration should be obtained
from a loadable module, rather than the file itself, using the
following directive at the beginning of a line before any section
headers:

\begin{Verbatim}[commandchars=\\\{\}]
module MODULEPATH:RESIDUAL
\end{Verbatim}

\emph{MODULEPATH} may be relative to the library path of the krb5
installation, or it may be an absolute path.  \emph{RESIDUAL} is provided
to the module at initialization time.  If krb5.conf uses a module
directive, {\hyperref[admin/conf_files/kdc_conf:kdc-conf-5]{\emph{kdc.conf}}} should also use one if it exists.


\subsubsection{Sections}
\label{admin/conf_files/krb5_conf:sections}
The krb5.conf file may contain the following sections:

\begin{tabulary}{\linewidth}{|L|L|}
\hline

{\hyperref[admin/conf_files/krb5_conf:libdefaults]{\emph{{[}libdefaults{]}}}}
 & 
Settings used by the Kerberos V5 library
\\
\hline
{\hyperref[admin/conf_files/krb5_conf:realms]{\emph{{[}realms{]}}}}
 & 
Realm-specific contact information and settings
\\
\hline
{\hyperref[admin/conf_files/krb5_conf:domain-realm]{\emph{{[}domain\_realm{]}}}}
 & 
Maps server hostnames to Kerberos realms
\\
\hline
{\hyperref[admin/conf_files/krb5_conf:capaths]{\emph{{[}capaths{]}}}}
 & 
Authentication paths for non-hierarchical cross-realm
\\
\hline
{\hyperref[admin/conf_files/krb5_conf:appdefaults]{\emph{{[}appdefaults{]}}}}
 & 
Settings used by some Kerberos V5 applications
\\
\hline
{\hyperref[admin/conf_files/krb5_conf:plugins]{\emph{{[}plugins{]}}}}
 & 
Controls plugin module registration
\\
\hline\end{tabulary}


Additionally, krb5.conf may include any of the relations described in
{\hyperref[admin/conf_files/kdc_conf:kdc-conf-5]{\emph{kdc.conf}}}, but it is not a recommended practice.


\paragraph{{[}libdefaults{]}}
\label{admin/conf_files/krb5_conf:libdefaults}\label{admin/conf_files/krb5_conf:id1}
The libdefaults section may contain any of the following relations:
\begin{description}
\item[{\textbf{allow\_weak\_crypto}}] \leavevmode
If this flag is set to false, then weak encryption types (as noted
in {\hyperref[admin/conf_files/kdc_conf:encryption-types]{\emph{Encryption types}}} in {\hyperref[admin/conf_files/kdc_conf:kdc-conf-5]{\emph{kdc.conf}}}) will be filtered
out of the lists \textbf{default\_tgs\_enctypes},
\textbf{default\_tkt\_enctypes}, and \textbf{permitted\_enctypes}.  The default
value for this tag is false, which may cause authentication
failures in existing Kerberos infrastructures that do not support
strong crypto.  Users in affected environments should set this tag
to true until their infrastructure adopts stronger ciphers.

\item[{\textbf{ap\_req\_checksum\_type}}] \leavevmode
An integer which specifies the type of AP-REQ checksum to use in
authenticators.  This variable should be unset so the appropriate
checksum for the encryption key in use will be used.  This can be
set if backward compatibility requires a specific checksum type.
See the \textbf{kdc\_req\_checksum\_type} configuration option for the
possible values and their meanings.

\item[{\textbf{canonicalize}}] \leavevmode
If this flag is set to true, initial ticket requests to the KDC
will request canonicalization of the client principal name, and
answers with different client principals than the requested
principal will be accepted.  The default value is false.

\item[{\textbf{ccache\_type}}] \leavevmode
This parameter determines the format of credential cache types
created by \emph{kinit(1)} or other programs.  The default value
is 4, which represents the most current format.  Smaller values
can be used for compatibility with very old implementations of
Kerberos which interact with credential caches on the same host.

\item[{\textbf{clockskew}}] \leavevmode
Sets the maximum allowable amount of clockskew in seconds that the
library will tolerate before assuming that a Kerberos message is
invalid.  The default value is 300 seconds, or five minutes.

The clockskew setting is also used when evaluating ticket start
and expiration times.  For example, tickets that have reached
their expiration time can still be used (and renewed if they are
renewable tickets) if they have been expired for a shorter
duration than the \textbf{clockskew} setting.

\item[{\textbf{default\_ccache\_name}}] \leavevmode
This relation specifies the name of the default credential cache.
The default is {\hyperref[mitK5defaults:paths]{\emph{DEFCCNAME}}}.  This relation is subject to parameter
expansion (see below).  New in release 1.11.

\item[{\textbf{default\_client\_keytab\_name}}] \leavevmode
This relation specifies the name of the default keytab for
obtaining client credentials.  The default is {\hyperref[mitK5defaults:paths]{\emph{DEFCKTNAME}}}.  This
relation is subject to parameter expansion (see below).
New in release 1.11.

\item[{\textbf{default\_keytab\_name}}] \leavevmode
This relation specifies the default keytab name to be used by
application servers such as sshd.  The default is {\hyperref[mitK5defaults:paths]{\emph{DEFKTNAME}}}.  This
relation is subject to parameter expansion (see below).

\item[{\textbf{default\_realm}}] \leavevmode
Identifies the default Kerberos realm for the client.  Set its
value to your Kerberos realm.  If this value is not set, then a
realm must be specified with every Kerberos principal when
invoking programs such as \emph{kinit(1)}.

\item[{\textbf{default\_tgs\_enctypes}}] \leavevmode
Identifies the supported list of session key encryption types that
the client should request when making a TGS-REQ, in order of
preference from highest to lowest.  The list may be delimited with
commas or whitespace.  See {\hyperref[admin/conf_files/kdc_conf:encryption-types]{\emph{Encryption types}}} in
{\hyperref[admin/conf_files/kdc_conf:kdc-conf-5]{\emph{kdc.conf}}} for a list of the accepted values for this tag.
The default value is \code{aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 des3-cbc-sha1 arcfour-hmac-md5 camellia256-cts-cmac camellia128-cts-cmac des-cbc-crc des-cbc-md5 des-cbc-md4}, but single-DES encryption types
will be implicitly removed from this list if the value of
\textbf{allow\_weak\_crypto} is false.

Do not set this unless required for specific backward
compatibility purposes; stale values of this setting can prevent
clients from taking advantage of new stronger enctypes when the
libraries are upgraded.

\item[{\textbf{default\_tkt\_enctypes}}] \leavevmode
Identifies the supported list of session key encryption types that
the client should request when making an AS-REQ, in order of
preference from highest to lowest.  The format is the same as for
default\_tgs\_enctypes.  The default value for this tag is
\code{aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 des3-cbc-sha1 arcfour-hmac-md5 camellia256-cts-cmac camellia128-cts-cmac des-cbc-crc des-cbc-md5 des-cbc-md4}, but single-DES encryption types will be implicitly
removed from this list if the value of \textbf{allow\_weak\_crypto} is
false.

Do not set this unless required for specific backward
compatibility purposes; stale values of this setting can prevent
clients from taking advantage of new stronger enctypes when the
libraries are upgraded.

\item[{\textbf{dns\_canonicalize\_hostname}}] \leavevmode
Indicate whether name lookups will be used to canonicalize
hostnames for use in service principal names.  Setting this flag
to false can improve security by reducing reliance on DNS, but
means that short hostnames will not be canonicalized to
fully-qualified hostnames.  The default value is true.

\item[{\textbf{dns\_lookup\_kdc}}] \leavevmode
Indicate whether DNS SRV records should be used to locate the KDCs
and other servers for a realm, if they are not listed in the
krb5.conf information for the realm.  (Note that the admin\_server
entry must be in the krb5.conf realm information in order to
contact kadmind, because the DNS implementation for kadmin is
incomplete.)

Enabling this option does open up a type of denial-of-service
attack, if someone spoofs the DNS records and redirects you to
another server.  However, it's no worse than a denial of service,
because that fake KDC will be unable to decode anything you send
it (besides the initial ticket request, which has no encrypted
data), and anything the fake KDC sends will not be trusted without
verification using some secret that it won't know.

\item[{\textbf{dns\_uri\_lookup}}] \leavevmode
Indicate whether DNS URI records should be used to locate the KDCs
and other servers for a realm, if they are not listed in the
krb5.conf information for the realm.  SRV records are used as a
fallback if no URI records were found.  The default value is true.
New in release 1.15.

\item[{\textbf{err\_fmt}}] \leavevmode
This relation allows for custom error message formatting.  If a
value is set, error messages will be formatted by substituting a
normal error message for \%M and an error code for \%C in the value.

\item[{\textbf{extra\_addresses}}] \leavevmode
This allows a computer to use multiple local addresses, in order
to allow Kerberos to work in a network that uses NATs while still
using address-restricted tickets.  The addresses should be in a
comma-separated list.  This option has no effect if
\textbf{noaddresses} is true.

\item[{\textbf{forwardable}}] \leavevmode
If this flag is true, initial tickets will be forwardable by
default, if allowed by the KDC.  The default value is false.

\item[{\textbf{ignore\_acceptor\_hostname}}] \leavevmode
When accepting GSSAPI or krb5 security contexts for host-based
service principals, ignore any hostname passed by the calling
application, and allow clients to authenticate to any service
principal in the keytab matching the service name and realm name
(if given).  This option can improve the administrative
flexibility of server applications on multihomed hosts, but could
compromise the security of virtual hosting environments.  The
default value is false.  New in release 1.10.

\item[{\textbf{k5login\_authoritative}}] \leavevmode
If this flag is true, principals must be listed in a local user's
k5login file to be granted login access, if a \emph{.k5login(5)}
file exists.  If this flag is false, a principal may still be
granted login access through other mechanisms even if a k5login
file exists but does not list the principal.  The default value is
true.

\item[{\textbf{k5login\_directory}}] \leavevmode
If set, the library will look for a local user's k5login file
within the named directory, with a filename corresponding to the
local username.  If not set, the library will look for k5login
files in the user's home directory, with the filename .k5login.
For security reasons, .k5login files must be owned by
the local user or by root.

\item[{\textbf{kcm\_mach\_service}}] \leavevmode
On OS X only, determines the name of the bootstrap service used to
contact the KCM daemon for the KCM credential cache type.  If the
value is \code{-}, Mach RPC will not be used to contact the KCM
daemon.  The default value is \code{org.h5l.kcm}.

\item[{\textbf{kcm\_socket}}] \leavevmode
Determines the path to the Unix domain socket used to access the
KCM daemon for the KCM credential cache type.  If the value is
\code{-}, Unix domain sockets will not be used to contact the KCM
daemon.  The default value is
\code{/var/run/.heim\_org.h5l.kcm-socket}.

\item[{\textbf{kdc\_default\_options}}] \leavevmode
Default KDC options (Xored for multiple values) when requesting
initial tickets.  By default it is set to 0x00000010
(KDC\_OPT\_RENEWABLE\_OK).

\item[{\textbf{kdc\_timesync}}] \leavevmode
Accepted values for this relation are 1 or 0.  If it is nonzero,
client machines will compute the difference between their time and
the time returned by the KDC in the timestamps in the tickets and
use this value to correct for an inaccurate system clock when
requesting service tickets or authenticating to services.  This
corrective factor is only used by the Kerberos library; it is not
used to change the system clock.  The default value is 1.

\item[{\textbf{kdc\_req\_checksum\_type}}] \leavevmode
An integer which specifies the type of checksum to use for the KDC
requests, for compatibility with very old KDC implementations.
This value is only used for DES keys; other keys use the preferred
checksum type for those keys.

The possible values and their meanings are as follows.

\begin{tabulary}{\linewidth}{|L|L|}
\hline

1
 & 
CRC32
\\
\hline
2
 & 
RSA MD4
\\
\hline
3
 & 
RSA MD4 DES
\\
\hline
4
 & 
DES CBC
\\
\hline
7
 & 
RSA MD5
\\
\hline
8
 & 
RSA MD5 DES
\\
\hline
9
 & 
NIST SHA
\\
\hline
12
 & 
HMAC SHA1 DES3
\\
\hline
-138
 & 
Microsoft MD5 HMAC checksum type
\\
\hline\end{tabulary}


\item[{\textbf{noaddresses}}] \leavevmode
If this flag is true, requests for initial tickets will not be
made with address restrictions set, allowing the tickets to be
used across NATs.  The default value is true.

\item[{\textbf{permitted\_enctypes}}] \leavevmode
Identifies all encryption types that are permitted for use in
session key encryption.  The default value for this tag is
\code{aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 des3-cbc-sha1 arcfour-hmac-md5 camellia256-cts-cmac camellia128-cts-cmac des-cbc-crc des-cbc-md5 des-cbc-md4}, but single-DES encryption types will be implicitly
removed from this list if the value of \textbf{allow\_weak\_crypto} is
false.

\item[{\textbf{plugin\_base\_dir}}] \leavevmode
If set, determines the base directory where krb5 plugins are
located.  The default value is the \code{krb5/plugins} subdirectory
of the krb5 library directory.

\item[{\textbf{preferred\_preauth\_types}}] \leavevmode
This allows you to set the preferred preauthentication types which
the client will attempt before others which may be advertised by a
KDC.  The default value for this setting is ``17, 16, 15, 14'',
which forces libkrb5 to attempt to use PKINIT if it is supported.

\item[{\textbf{proxiable}}] \leavevmode
If this flag is true, initial tickets will be proxiable by
default, if allowed by the KDC.  The default value is false.

\item[{\textbf{rdns}}] \leavevmode
If this flag is true, reverse name lookup will be used in addition
to forward name lookup to canonicalizing hostnames for use in
service principal names.  If \textbf{dns\_canonicalize\_hostname} is set
to false, this flag has no effect.  The default value is true.

\item[{\textbf{realm\_try\_domains}}] \leavevmode
Indicate whether a host's domain components should be used to
determine the Kerberos realm of the host.  The value of this
variable is an integer: -1 means not to search, 0 means to try the
host's domain itself, 1 means to also try the domain's immediate
parent, and so forth.  The library's usual mechanism for locating
Kerberos realms is used to determine whether a domain is a valid
realm, which may involve consulting DNS if \textbf{dns\_lookup\_kdc} is
set.  The default is not to search domain components.

\item[{\textbf{renew\_lifetime}}] \leavevmode
(\emph{duration} string.)  Sets the default renewable lifetime
for initial ticket requests.  The default value is 0.

\item[{\textbf{safe\_checksum\_type}}] \leavevmode
An integer which specifies the type of checksum to use for the
KRB-SAFE requests.  By default it is set to 8 (RSA MD5 DES).  For
compatibility with applications linked against DCE version 1.1 or
earlier Kerberos libraries, use a value of 3 to use the RSA MD4
DES instead.  This field is ignored when its value is incompatible
with the session key type.  See the \textbf{kdc\_req\_checksum\_type}
configuration option for the possible values and their meanings.

\item[{\textbf{ticket\_lifetime}}] \leavevmode
(\emph{duration} string.)  Sets the default lifetime for initial
ticket requests.  The default value is 1 day.

\item[{\textbf{udp\_preference\_limit}}] \leavevmode
When sending a message to the KDC, the library will try using TCP
before UDP if the size of the message is above
\textbf{udp\_preference\_limit}.  If the message is smaller than
\textbf{udp\_preference\_limit}, then UDP will be tried before TCP.
Regardless of the size, both protocols will be tried if the first
attempt fails.

\item[{\textbf{verify\_ap\_req\_nofail}}] \leavevmode
If this flag is true, then an attempt to verify initial
credentials will fail if the client machine does not have a
keytab.  The default value is false.

\end{description}


\paragraph{{[}realms{]}}
\label{admin/conf_files/krb5_conf:id2}\label{admin/conf_files/krb5_conf:realms}
Each tag in the {[}realms{]} section of the file is the name of a Kerberos
realm.  The value of the tag is a subsection with relations that
define the properties of that particular realm.  For each realm, the
following tags may be specified in the realm's subsection:
\begin{description}
\item[{\textbf{admin\_server}}] \leavevmode
Identifies the host where the administration server is running.
Typically, this is the master Kerberos server.  This tag must be
given a value in order to communicate with the {\hyperref[admin/admin_commands/kadmind:kadmind-8]{\emph{kadmind}}}
server for the realm.

\item[{\textbf{auth\_to\_local}}] \leavevmode
This tag allows you to set a general rule for mapping principal
names to local user names.  It will be used if there is not an
explicit mapping for the principal name that is being
translated. The possible values are:
\begin{description}
\item[{\textbf{RULE:}\emph{exp}}] \leavevmode
The local name will be formulated from \emph{exp}.

The format for \emph{exp} is \textbf{{[}}\emph{n}\textbf{:}\emph{string}\textbf{{]}(}\emph{regexp}\textbf{)s/}\emph{pattern}\textbf{/}\emph{replacement}\textbf{/g}.
The integer \emph{n} indicates how many components the target
principal should have.  If this matches, then a string will be
formed from \emph{string}, substituting the realm of the principal
for \code{\$0} and the \emph{n}`th component of the principal for
\code{\$n} (e.g., if the principal was \code{johndoe/admin} then
\code{{[}2:\$2\$1foo{]}} would result in the string
\code{adminjohndoefoo}).  If this string matches \emph{regexp}, then
the \code{s//{[}g{]}} substitution command will be run over the
string.  The optional \textbf{g} will cause the substitution to be
global over the \emph{string}, instead of replacing only the first
match in the \emph{string}.

\item[{\textbf{DEFAULT}}] \leavevmode
The principal name will be used as the local user name.  If
the principal has more than one component or is not in the
default realm, this rule is not applicable and the conversion
will fail.

\end{description}

For example:

\begin{Verbatim}[commandchars=\\\{\}]
[realms]
    ATHENA.MIT.EDU = \PYGZob{}
        auth\PYGZus{}to\PYGZus{}local = RULE:[2:\PYGZdl{}1](johndoe)s/\PYGZca{}.*\PYGZdl{}/guest/
        auth\PYGZus{}to\PYGZus{}local = RULE:[2:\PYGZdl{}1;\PYGZdl{}2](\PYGZca{}.*;admin\PYGZdl{})s/;admin\PYGZdl{}//
        auth\PYGZus{}to\PYGZus{}local = RULE:[2:\PYGZdl{}2](\PYGZca{}.*;root)s/\PYGZca{}.*\PYGZdl{}/root/
        auto\PYGZus{}to\PYGZus{}local = DEFAULT
    \PYGZcb{}
\end{Verbatim}

would result in any principal without \code{root} or \code{admin} as the
second component to be translated with the default rule.  A
principal with a second component of \code{admin} will become its
first component.  \code{root} will be used as the local name for any
principal with a second component of \code{root}.  The exception to
these two rules are any principals \code{johndoe/*}, which will
always get the local name \code{guest}.

\item[{\textbf{auth\_to\_local\_names}}] \leavevmode
This subsection allows you to set explicit mappings from principal
names to local user names.  The tag is the mapping name, and the
value is the corresponding local user name.

\item[{\textbf{default\_domain}}] \leavevmode
This tag specifies the domain used to expand hostnames when
translating Kerberos 4 service principals to Kerberos 5 principals
(for example, when converting \code{rcmd.hostname} to
\code{host/hostname.domain}).

\item[{\textbf{http\_anchors}}] \leavevmode
When KDCs and kpasswd servers are accessed through HTTPS proxies, this tag
can be used to specify the location of the CA certificate which should be
trusted to issue the certificate for a proxy server.  If left unspecified,
the system-wide default set of CA certificates is used.

The syntax for values is similar to that of values for the
\textbf{pkinit\_anchors} tag:

\textbf{FILE:} \emph{filename}

\emph{filename} is assumed to be the name of an OpenSSL-style ca-bundle file.

\textbf{DIR:} \emph{dirname}

\emph{dirname} is assumed to be an directory which contains CA certificates.
All files in the directory will be examined; if they contain certificates
(in PEM format), they will be used.

\textbf{ENV:} \emph{envvar}

\emph{envvar} specifies the name of an environment variable which has been set
to a value conforming to one of the previous values.  For example,
\code{ENV:X509\_PROXY\_CA}, where environment variable \code{X509\_PROXY\_CA} has
been set to \code{FILE:/tmp/my\_proxy.pem}.

\item[{\textbf{kdc}}] \leavevmode
The name or address of a host running a KDC for that realm.  An
optional port number, separated from the hostname by a colon, may
be included.  If the name or address contains colons (for example,
if it is an IPv6 address), enclose it in square brackets to
distinguish the colon from a port separator.  For your computer to
be able to communicate with the KDC for each realm, this tag must
be given a value in each realm subsection in the configuration
file, or there must be DNS SRV records specifying the KDCs.

\item[{\textbf{kpasswd\_server}}] \leavevmode
Points to the server where all the password changes are performed.
If there is no such entry, the port 464 on the \textbf{admin\_server}
host will be tried.

\item[{\textbf{master\_kdc}}] \leavevmode
Identifies the master KDC(s).  Currently, this tag is used in only
one case: If an attempt to get credentials fails because of an
invalid password, the client software will attempt to contact the
master KDC, in case the user's password has just been changed, and
the updated database has not been propagated to the slave servers
yet.

\item[{\textbf{v4\_instance\_convert}}] \leavevmode
This subsection allows the administrator to configure exceptions
to the \textbf{default\_domain} mapping rule.  It contains V4 instances
(the tag name) which should be translated to some specific
hostname (the tag value) as the second component in a Kerberos V5
principal name.

\item[{\textbf{v4\_realm}}] \leavevmode
This relation is used by the krb524 library routines when
converting a V5 principal name to a V4 principal name.  It is used
when the V4 realm name and the V5 realm name are not the same, but
still share the same principal names and passwords. The tag value
is the Kerberos V4 realm name.

\end{description}


\paragraph{{[}domain\_realm{]}}
\label{admin/conf_files/krb5_conf:id3}\label{admin/conf_files/krb5_conf:domain-realm}
The {[}domain\_realm{]} section provides a translation from a domain name
or hostname to a Kerberos realm name.  The tag name can be a host name
or domain name, where domain names are indicated by a prefix of a
period (\code{.}).  The value of the relation is the Kerberos realm name
for that particular host or domain.  A host name relation implicitly
provides the corresponding domain name relation, unless an explicit domain
name relation is provided.  The Kerberos realm may be
identified either in the {\hyperref[admin/conf_files/krb5_conf:realms]{realms}} section or using DNS SRV records.
Host names and domain names should be in lower case.  For example:

\begin{Verbatim}[commandchars=\\\{\}]
[domain\PYGZus{}realm]
    crash.mit.edu = TEST.ATHENA.MIT.EDU
    .dev.mit.edu = TEST.ATHENA.MIT.EDU
    mit.edu = ATHENA.MIT.EDU
\end{Verbatim}

maps the host with the name \code{crash.mit.edu} into the
\code{TEST.ATHENA.MIT.EDU} realm.  The second entry maps all hosts under the
domain \code{dev.mit.edu} into the \code{TEST.ATHENA.MIT.EDU} realm, but not
the host with the name \code{dev.mit.edu}.  That host is matched
by the third entry, which maps the host \code{mit.edu} and all hosts
under the domain \code{mit.edu} that do not match a preceding rule
into the realm \code{ATHENA.MIT.EDU}.

If no translation entry applies to a hostname used for a service
principal for a service ticket request, the library will try to get a
referral to the appropriate realm from the client realm's KDC.  If
that does not succeed, the host's realm is considered to be the
hostname's domain portion converted to uppercase, unless the
\textbf{realm\_try\_domains} setting in {[}libdefaults{]} causes a different
parent domain to be used.


\paragraph{{[}capaths{]}}
\label{admin/conf_files/krb5_conf:id4}\label{admin/conf_files/krb5_conf:capaths}
In order to perform direct (non-hierarchical) cross-realm
authentication, configuration is needed to determine the
authentication paths between realms.

A client will use this section to find the authentication path between
its realm and the realm of the server.  The server will use this
section to verify the authentication path used by the client, by
checking the transited field of the received ticket.

There is a tag for each participating client realm, and each tag has
subtags for each of the server realms.  The value of the subtags is an
intermediate realm which may participate in the cross-realm
authentication.  The subtags may be repeated if there is more then one
intermediate realm.  A value of ''.'' means that the two realms share
keys directly, and no intermediate realms should be allowed to
participate.

Only those entries which will be needed on the client or the server
need to be present.  A client needs a tag for its local realm with
subtags for all the realms of servers it will need to authenticate to.
A server needs a tag for each realm of the clients it will serve, with
a subtag of the server realm.

For example, \code{ANL.GOV}, \code{PNL.GOV}, and \code{NERSC.GOV} all wish to
use the \code{ES.NET} realm as an intermediate realm.  ANL has a sub
realm of \code{TEST.ANL.GOV} which will authenticate with \code{NERSC.GOV}
but not \code{PNL.GOV}.  The {[}capaths{]} section for \code{ANL.GOV} systems
would look like this:

\begin{Verbatim}[commandchars=\\\{\}]
[capaths]
    ANL.GOV = \PYGZob{}
        TEST.ANL.GOV = .
        PNL.GOV = ES.NET
        NERSC.GOV = ES.NET
        ES.NET = .
    \PYGZcb{}
    TEST.ANL.GOV = \PYGZob{}
        ANL.GOV = .
    \PYGZcb{}
    PNL.GOV = \PYGZob{}
        ANL.GOV = ES.NET
    \PYGZcb{}
    NERSC.GOV = \PYGZob{}
        ANL.GOV = ES.NET
    \PYGZcb{}
    ES.NET = \PYGZob{}
        ANL.GOV = .
    \PYGZcb{}
\end{Verbatim}

The {[}capaths{]} section of the configuration file used on \code{NERSC.GOV}
systems would look like this:

\begin{Verbatim}[commandchars=\\\{\}]
[capaths]
    NERSC.GOV = \PYGZob{}
        ANL.GOV = ES.NET
        TEST.ANL.GOV = ES.NET
        TEST.ANL.GOV = ANL.GOV
        PNL.GOV = ES.NET
        ES.NET = .
    \PYGZcb{}
    ANL.GOV = \PYGZob{}
        NERSC.GOV = ES.NET
    \PYGZcb{}
    PNL.GOV = \PYGZob{}
        NERSC.GOV = ES.NET
    \PYGZcb{}
    ES.NET = \PYGZob{}
        NERSC.GOV = .
    \PYGZcb{}
    TEST.ANL.GOV = \PYGZob{}
        NERSC.GOV = ANL.GOV
        NERSC.GOV = ES.NET
    \PYGZcb{}
\end{Verbatim}

When a subtag is used more than once within a tag, clients will use
the order of values to determine the path.  The order of values is not
important to servers.


\paragraph{{[}appdefaults{]}}
\label{admin/conf_files/krb5_conf:id5}\label{admin/conf_files/krb5_conf:appdefaults}
Each tag in the {[}appdefaults{]} section names a Kerberos V5 application
or an option that is used by some Kerberos V5 application{[}s{]}.  The
value of the tag defines the default behaviors for that application.

For example:

\begin{Verbatim}[commandchars=\\\{\}]
[appdefaults]
    telnet = \PYGZob{}
        ATHENA.MIT.EDU = \PYGZob{}
            option1 = false
        \PYGZcb{}
    \PYGZcb{}
    telnet = \PYGZob{}
        option1 = true
        option2 = true
    \PYGZcb{}
    ATHENA.MIT.EDU = \PYGZob{}
        option2 = false
    \PYGZcb{}
    option2 = true
\end{Verbatim}

The above four ways of specifying the value of an option are shown in
order of decreasing precedence. In this example, if telnet is running
in the realm EXAMPLE.COM, it should, by default, have option1 and
option2 set to true.  However, a telnet program in the realm
\code{ATHENA.MIT.EDU} should have \code{option1} set to false and
\code{option2} set to true.  Any other programs in ATHENA.MIT.EDU should
have \code{option2} set to false by default.  Any programs running in
other realms should have \code{option2} set to true.

The list of specifiable options for each application may be found in
that application's man pages.  The application defaults specified here
are overridden by those specified in the {\hyperref[admin/conf_files/krb5_conf:realms]{realms}} section.


\paragraph{{[}plugins{]}}
\label{admin/conf_files/krb5_conf:id6}\label{admin/conf_files/krb5_conf:plugins}\begin{itemize}
\item {} 
{\hyperref[admin/conf_files/krb5_conf:pwqual]{pwqual}} interface

\item {} 
{\hyperref[admin/conf_files/krb5_conf:kadm5-hook]{kadm5\_hook}} interface

\item {} 
{\hyperref[admin/conf_files/krb5_conf:clpreauth]{clpreauth}} and {\hyperref[admin/conf_files/krb5_conf:kdcpreauth]{kdcpreauth}} interfaces

\end{itemize}

Tags in the {[}plugins{]} section can be used to register dynamic plugin
modules and to turn modules on and off.  Not every krb5 pluggable
interface uses the {[}plugins{]} section; the ones that do are documented
here.

New in release 1.9.

Each pluggable interface corresponds to a subsection of {[}plugins{]}.
All subsections support the same tags:
\begin{description}
\item[{\textbf{disable}}] \leavevmode
This tag may have multiple values. If there are values for this
tag, then the named modules will be disabled for the pluggable
interface.

\item[{\textbf{enable\_only}}] \leavevmode
This tag may have multiple values. If there are values for this
tag, then only the named modules will be enabled for the pluggable
interface.

\item[{\textbf{module}}] \leavevmode
This tag may have multiple values.  Each value is a string of the
form \code{modulename:pathname}, which causes the shared object
located at \emph{pathname} to be registered as a dynamic module named
\emph{modulename} for the pluggable interface.  If \emph{pathname} is not an
absolute path, it will be treated as relative to the
\textbf{plugin\_base\_dir} value from {\hyperref[admin/conf_files/krb5_conf:libdefaults]{\emph{{[}libdefaults{]}}}}.

\end{description}

For pluggable interfaces where module order matters, modules
registered with a \textbf{module} tag normally come first, in the order
they are registered, followed by built-in modules in the order they
are documented below.  If \textbf{enable\_only} tags are used, then the
order of those tags overrides the normal module order.

The following subsections are currently supported within the {[}plugins{]}
section:


\subparagraph{ccselect interface}
\label{admin/conf_files/krb5_conf:ccselect}\label{admin/conf_files/krb5_conf:ccselect-interface}
The ccselect subsection controls modules for credential cache
selection within a cache collection.  In addition to any registered
dynamic modules, the following built-in modules exist (and may be
disabled with the disable tag):
\begin{description}
\item[{\textbf{k5identity}}] \leavevmode
Uses a .k5identity file in the user's home directory to select a
client principal

\item[{\textbf{realm}}] \leavevmode
Uses the service realm to guess an appropriate cache from the
collection

\end{description}


\subparagraph{pwqual interface}
\label{admin/conf_files/krb5_conf:pwqual-interface}\label{admin/conf_files/krb5_conf:pwqual}
The pwqual subsection controls modules for the password quality
interface, which is used to reject weak passwords when passwords are
changed.  The following built-in modules exist for this interface:
\begin{description}
\item[{\textbf{dict}}] \leavevmode
Checks against the realm dictionary file

\item[{\textbf{empty}}] \leavevmode
Rejects empty passwords

\item[{\textbf{hesiod}}] \leavevmode
Checks against user information stored in Hesiod (only if Kerberos
was built with Hesiod support)

\item[{\textbf{princ}}] \leavevmode
Checks against components of the principal name

\end{description}


\subparagraph{kadm5\_hook interface}
\label{admin/conf_files/krb5_conf:kadm5-hook-interface}\label{admin/conf_files/krb5_conf:kadm5-hook}
The kadm5\_hook interface provides plugins with information on
principal creation, modification, password changes and deletion.  This
interface can be used to write a plugin to synchronize MIT Kerberos
with another database such as Active Directory.  No plugins are built
in for this interface.
\phantomsection\label{admin/conf_files/krb5_conf:clpreauth}

\subparagraph{clpreauth and kdcpreauth interfaces}
\label{admin/conf_files/krb5_conf:clpreauth-and-kdcpreauth-interfaces}\label{admin/conf_files/krb5_conf:clpreauth}\label{admin/conf_files/krb5_conf:kdcpreauth}
The clpreauth and kdcpreauth interfaces allow plugin modules to
provide client and KDC preauthentication mechanisms.  The following
built-in modules exist for these interfaces:
\begin{description}
\item[{\textbf{pkinit}}] \leavevmode
This module implements the PKINIT preauthentication mechanism.

\item[{\textbf{encrypted\_challenge}}] \leavevmode
This module implements the encrypted challenge FAST factor.

\item[{\textbf{encrypted\_timestamp}}] \leavevmode
This module implements the encrypted timestamp mechanism.

\end{description}


\subparagraph{hostrealm interface}
\label{admin/conf_files/krb5_conf:hostrealm-interface}\label{admin/conf_files/krb5_conf:hostrealm}
The hostrealm section (introduced in release 1.12) controls modules
for the host-to-realm interface, which affects the local mapping of
hostnames to realm names and the choice of default realm.  The following
built-in modules exist for this interface:
\begin{description}
\item[{\textbf{profile}}] \leavevmode
This module consults the {[}domain\_realm{]} section of the profile for
authoritative host-to-realm mappings, and the \textbf{default\_realm}
variable for the default realm.

\item[{\textbf{dns}}] \leavevmode
This module looks for DNS records for fallback host-to-realm
mappings and the default realm.  It only operates if the
\textbf{dns\_lookup\_realm} variable is set to true.

\item[{\textbf{domain}}] \leavevmode
This module applies heuristics for fallback host-to-realm
mappings.  It implements the \textbf{realm\_try\_domains} variable, and
uses the uppercased parent domain of the hostname if that does not
produce a result.

\end{description}


\subparagraph{localauth interface}
\label{admin/conf_files/krb5_conf:localauth-interface}\label{admin/conf_files/krb5_conf:localauth}
The localauth section (introduced in release 1.12) controls modules
for the local authorization interface, which affects the relationship
between Kerberos principals and local system accounts.  The following
built-in modules exist for this interface:
\begin{description}
\item[{\textbf{default}}] \leavevmode
This module implements the \textbf{DEFAULT} type for \textbf{auth\_to\_local}
values.

\item[{\textbf{rule}}] \leavevmode
This module implements the \textbf{RULE} type for \textbf{auth\_to\_local}
values.

\item[{\textbf{names}}] \leavevmode
This module looks for an \textbf{auth\_to\_local\_names} mapping for the
principal name.

\item[{\textbf{auth\_to\_local}}] \leavevmode
This module processes \textbf{auth\_to\_local} values in the default
realm's section, and applies the default method if no
\textbf{auth\_to\_local} values exist.

\item[{\textbf{k5login}}] \leavevmode
This module authorizes a principal to a local account according to
the account's \emph{.k5login(5)} file.

\item[{\textbf{an2ln}}] \leavevmode
This module authorizes a principal to a local account if the
principal name maps to the local account name.

\end{description}


\subsubsection{PKINIT options}
\label{admin/conf_files/krb5_conf:pkinit-options}
\begin{notice}{note}{Note:}
The following are PKINIT-specific options.  These values may
be specified in {[}libdefaults{]} as global defaults, or within
a realm-specific subsection of {[}libdefaults{]}, or may be
specified as realm-specific values in the {[}realms{]} section.
A realm-specific value overrides, not adds to, a generic
{[}libdefaults{]} specification.  The search order is:
\end{notice}
\begin{enumerate}
\item {} 
realm-specific subsection of {[}libdefaults{]}:

\begin{Verbatim}[commandchars=\\\{\}]
[libdefaults]
    EXAMPLE.COM = \PYGZob{}
        pkinit\PYGZus{}anchors = FILE:/usr/local/example.com.crt
    \PYGZcb{}
\end{Verbatim}

\item {} 
realm-specific value in the {[}realms{]} section:

\begin{Verbatim}[commandchars=\\\{\}]
[realms]
    OTHERREALM.ORG = \PYGZob{}
        pkinit\PYGZus{}anchors = FILE:/usr/local/otherrealm.org.crt
    \PYGZcb{}
\end{Verbatim}

\item {} 
generic value in the {[}libdefaults{]} section:

\begin{Verbatim}[commandchars=\\\{\}]
[libdefaults]
    pkinit\PYGZus{}anchors = DIR:/usr/local/generic\PYGZus{}trusted\PYGZus{}cas/
\end{Verbatim}

\end{enumerate}


\paragraph{Specifying PKINIT identity information}
\label{admin/conf_files/krb5_conf:specifying-pkinit-identity-information}\label{admin/conf_files/krb5_conf:pkinit-identity}
The syntax for specifying Public Key identity, trust, and revocation
information for PKINIT is as follows:
\begin{description}
\item[{\textbf{FILE:}\emph{filename}{[}\textbf{,}\emph{keyfilename}{]}}] \leavevmode
This option has context-specific behavior.

In \textbf{pkinit\_identity} or \textbf{pkinit\_identities}, \emph{filename}
specifies the name of a PEM-format file containing the user's
certificate.  If \emph{keyfilename} is not specified, the user's
private key is expected to be in \emph{filename} as well.  Otherwise,
\emph{keyfilename} is the name of the file containing the private key.

In \textbf{pkinit\_anchors} or \textbf{pkinit\_pool}, \emph{filename} is assumed to
be the name of an OpenSSL-style ca-bundle file.

\item[{\textbf{DIR:}\emph{dirname}}] \leavevmode
This option has context-specific behavior.

In \textbf{pkinit\_identity} or \textbf{pkinit\_identities}, \emph{dirname}
specifies a directory with files named \code{*.crt} and \code{*.key}
where the first part of the file name is the same for matching
pairs of certificate and private key files.  When a file with a
name ending with \code{.crt} is found, a matching file ending with
\code{.key} is assumed to contain the private key.  If no such file
is found, then the certificate in the \code{.crt} is not used.

In \textbf{pkinit\_anchors} or \textbf{pkinit\_pool}, \emph{dirname} is assumed to
be an OpenSSL-style hashed CA directory where each CA cert is
stored in a file named \code{hash-of-ca-cert.\#}.  This infrastructure
is encouraged, but all files in the directory will be examined and
if they contain certificates (in PEM format), they will be used.

In \textbf{pkinit\_revoke}, \emph{dirname} is assumed to be an OpenSSL-style
hashed CA directory where each revocation list is stored in a file
named \code{hash-of-ca-cert.r\#}.  This infrastructure is encouraged,
but all files in the directory will be examined and if they
contain a revocation list (in PEM format), they will be used.

\item[{\textbf{PKCS12:}\emph{filename}}] \leavevmode
\emph{filename} is the name of a PKCS \#12 format file, containing the
user's certificate and private key.

\item[{\textbf{PKCS11:}{[}\textbf{module\_name=}{]}\emph{modname}{[}\textbf{:slotid=}\emph{slot-id}{]}{[}\textbf{:token=}\emph{token-label}{]}{[}\textbf{:certid=}\emph{cert-id}{]}{[}\textbf{:certlabel=}\emph{cert-label}{]}}] \leavevmode
All keyword/values are optional.  \emph{modname} specifies the location
of a library implementing PKCS \#11.  If a value is encountered
with no keyword, it is assumed to be the \emph{modname}.  If no
module-name is specified, the default is \code{opensc-pkcs11.so}.
\code{slotid=} and/or \code{token=} may be specified to force the use of
a particular smard card reader or token if there is more than one
available.  \code{certid=} and/or \code{certlabel=} may be specified to
force the selection of a particular certificate on the device.
See the \textbf{pkinit\_cert\_match} configuration option for more ways
to select a particular certificate to use for PKINIT.

\item[{\textbf{ENV:}\emph{envvar}}] \leavevmode
\emph{envvar} specifies the name of an environment variable which has
been set to a value conforming to one of the previous values.  For
example, \code{ENV:X509\_PROXY}, where environment variable
\code{X509\_PROXY} has been set to \code{FILE:/tmp/my\_proxy.pem}.

\end{description}


\paragraph{PKINIT krb5.conf options}
\label{admin/conf_files/krb5_conf:pkinit-krb5-conf-options}\begin{description}
\item[{\textbf{pkinit\_anchors}}] \leavevmode
Specifies the location of trusted anchor (root) certificates which
the client trusts to sign KDC certificates.  This option may be
specified multiple times.  These values from the config file are
not used if the user specifies X509\_anchors on the command line.

\item[{\textbf{pkinit\_cert\_match}}] \leavevmode
Specifies matching rules that the client certificate must match
before it is used to attempt PKINIT authentication.  If a user has
multiple certificates available (on a smart card, or via other
media), there must be exactly one certificate chosen before
attempting PKINIT authentication.  This option may be specified
multiple times.  All the available certificates are checked
against each rule in order until there is a match of exactly one
certificate.

The Subject and Issuer comparison strings are the \index{RFC!RFC 2253}\href{http://tools.ietf.org/html/rfc2253.html}{\textbf{RFC 2253}}
string representations from the certificate Subject DN and Issuer
DN values.

The syntax of the matching rules is:
\begin{quote}

{[}\emph{relation-operator}{]}\emph{component-rule} ...
\end{quote}

where:
\begin{description}
\item[{\emph{relation-operator}}] \leavevmode
can be either \code{\&\&}, meaning all component rules must match,
or \code{\textbar{}\textbar{}}, meaning only one component rule must match.  The
default is \code{\&\&}.

\item[{\emph{component-rule}}] \leavevmode
can be one of the following.  Note that there is no
punctuation or whitespace between component rules.
\begin{quote}

\begin{DUlineblock}{0em}
\item[] \textbf{\textless{}SUBJECT\textgreater{}}\emph{regular-expression}
\item[] \textbf{\textless{}ISSUER\textgreater{}}\emph{regular-expression}
\item[] \textbf{\textless{}SAN\textgreater{}}\emph{regular-expression}
\item[] \textbf{\textless{}EKU\textgreater{}}\emph{extended-key-usage-list}
\item[] \textbf{\textless{}KU\textgreater{}}\emph{key-usage-list}
\end{DUlineblock}
\end{quote}

\emph{extended-key-usage-list} is a comma-separated list of
required Extended Key Usage values.  All values in the list
must be present in the certificate.  Extended Key Usage values
can be:
\begin{itemize}
\item {} 
pkinit

\item {} 
msScLogin

\item {} 
clientAuth

\item {} 
emailProtection

\end{itemize}

\emph{key-usage-list} is a comma-separated list of required Key
Usage values.  All values in the list must be present in the
certificate.  Key Usage values can be:
\begin{itemize}
\item {} 
digitalSignature

\item {} 
keyEncipherment

\end{itemize}

\end{description}

Examples:

\begin{Verbatim}[commandchars=\\\{\}]
pkinit\PYGZus{}cert\PYGZus{}match = \textbar{}\textbar{}\PYGZlt{}SUBJECT\PYGZgt{}.*DoE.*\PYGZlt{}SAN\PYGZgt{}.*@EXAMPLE.COM
pkinit\PYGZus{}cert\PYGZus{}match = \PYGZam{}\PYGZam{}\PYGZlt{}EKU\PYGZgt{}msScLogin,clientAuth\PYGZlt{}ISSUER\PYGZgt{}.*DoE.*
pkinit\PYGZus{}cert\PYGZus{}match = \PYGZlt{}EKU\PYGZgt{}msScLogin,clientAuth\PYGZlt{}KU\PYGZgt{}digitalSignature
\end{Verbatim}

\item[{\textbf{pkinit\_eku\_checking}}] \leavevmode
This option specifies what Extended Key Usage value the KDC
certificate presented to the client must contain.  (Note that if
the KDC certificate has the pkinit SubjectAlternativeName encoded
as the Kerberos TGS name, EKU checking is not necessary since the
issuing CA has certified this as a KDC certificate.)  The values
recognized in the krb5.conf file are:
\begin{description}
\item[{\textbf{kpKDC}}] \leavevmode
This is the default value and specifies that the KDC must have
the id-pkinit-KPKdc EKU as defined in \index{RFC!RFC 4556}\href{http://tools.ietf.org/html/rfc4556.html}{\textbf{RFC 4556}}.

\item[{\textbf{kpServerAuth}}] \leavevmode
If \textbf{kpServerAuth} is specified, a KDC certificate with the
id-kp-serverAuth EKU will be accepted.  This key usage value
is used in most commercially issued server certificates.

\item[{\textbf{none}}] \leavevmode
If \textbf{none} is specified, then the KDC certificate will not be
checked to verify it has an acceptable EKU.  The use of this
option is not recommended.

\end{description}

\item[{\textbf{pkinit\_dh\_min\_bits}}] \leavevmode
Specifies the size of the Diffie-Hellman key the client will
attempt to use.  The acceptable values are 1024, 2048, and 4096.
The default is 2048.

\item[{\textbf{pkinit\_identities}}] \leavevmode
Specifies the location(s) to be used to find the user's X.509
identity information.  This option may be specified multiple
times.  Each value is attempted in order until identity
information is found and authentication is attempted.  Note that
these values are not used if the user specifies
\textbf{X509\_user\_identity} on the command line.

\item[{\textbf{pkinit\_kdc\_hostname}}] \leavevmode
The presense of this option indicates that the client is willing
to accept a KDC certificate with a dNSName SAN (Subject
Alternative Name) rather than requiring the id-pkinit-san as
defined in \index{RFC!RFC 4556}\href{http://tools.ietf.org/html/rfc4556.html}{\textbf{RFC 4556}}.  This option may be specified multiple
times.  Its value should contain the acceptable hostname for the
KDC (as contained in its certificate).

\item[{\textbf{pkinit\_pool}}] \leavevmode
Specifies the location of intermediate certificates which may be
used by the client to complete the trust chain between a KDC
certificate and a trusted anchor.  This option may be specified
multiple times.

\item[{\textbf{pkinit\_require\_crl\_checking}}] \leavevmode
The default certificate verification process will always check the
available revocation information to see if a certificate has been
revoked.  If a match is found for the certificate in a CRL,
verification fails.  If the certificate being verified is not
listed in a CRL, or there is no CRL present for its issuing CA,
and \textbf{pkinit\_require\_crl\_checking} is false, then verification
succeeds.

However, if \textbf{pkinit\_require\_crl\_checking} is true and there is
no CRL information available for the issuing CA, then verification
fails.

\textbf{pkinit\_require\_crl\_checking} should be set to true if the
policy is such that up-to-date CRLs must be present for every CA.

\item[{\textbf{pkinit\_revoke}}] \leavevmode
Specifies the location of Certificate Revocation List (CRL)
information to be used by the client when verifying the validity
of the KDC certificate presented.  This option may be specified
multiple times.

\end{description}


\subsubsection{Parameter expansion}
\label{admin/conf_files/krb5_conf:id7}\label{admin/conf_files/krb5_conf:parameter-expansion}
Starting with release 1.11, several variables, such as
\textbf{default\_keytab\_name}, allow parameters to be expanded.
Valid parameters are:
\begin{quote}

\begin{tabulary}{\linewidth}{|L|L|}
\hline

\%\{TEMP\}
 & 
Temporary directory
\\
\hline
\%\{uid\}
 & 
Unix real UID or Windows SID
\\
\hline
\%\{euid\}
 & 
Unix effective user ID or Windows SID
\\
\hline
\%\{USERID\}
 & 
Same as \%\{uid\}
\\
\hline
\%\{null\}
 & 
Empty string
\\
\hline
\%\{LIBDIR\}
 & 
Installation library directory
\\
\hline
\%\{BINDIR\}
 & 
Installation binary directory
\\
\hline
\%\{SBINDIR\}
 & 
Installation admin binary directory
\\
\hline
\%\{username\}
 & 
(Unix) Username of effective user ID
\\
\hline
\%\{APPDATA\}
 & 
(Windows) Roaming application data for current user
\\
\hline
\%\{COMMON\_APPDATA\}
 & 
(Windows) Application data for all users
\\
\hline
\%\{LOCAL\_APPDATA\}
 & 
(Windows) Local application data for current user
\\
\hline
\%\{SYSTEM\}
 & 
(Windows) Windows system folder
\\
\hline
\%\{WINDOWS\}
 & 
(Windows) Windows folder
\\
\hline
\%\{USERCONFIG\}
 & 
(Windows) Per-user MIT krb5 config file directory
\\
\hline
\%\{COMMONCONFIG\}
 & 
(Windows) Common MIT krb5 config file directory
\\
\hline\end{tabulary}

\end{quote}


\subsubsection{Sample krb5.conf file}
\label{admin/conf_files/krb5_conf:sample-krb5-conf-file}
Here is an example of a generic krb5.conf file:

\begin{Verbatim}[commandchars=\\\{\}]
[libdefaults]
    default\PYGZus{}realm = ATHENA.MIT.EDU
    dns\PYGZus{}lookup\PYGZus{}kdc = true
    dns\PYGZus{}lookup\PYGZus{}realm = false

[realms]
    ATHENA.MIT.EDU = \PYGZob{}
        kdc = kerberos.mit.edu
        kdc = kerberos\PYGZhy{}1.mit.edu
        kdc = kerberos\PYGZhy{}2.mit.edu
        admin\PYGZus{}server = kerberos.mit.edu
        master\PYGZus{}kdc = kerberos.mit.edu
    \PYGZcb{}
    EXAMPLE.COM = \PYGZob{}
        kdc = kerberos.example.com
        kdc = kerberos\PYGZhy{}1.example.com
        admin\PYGZus{}server = kerberos.example.com
    \PYGZcb{}

[domain\PYGZus{}realm]
    mit.edu = ATHENA.MIT.EDU

[capaths]
    ATHENA.MIT.EDU = \PYGZob{}
           EXAMPLE.COM = .
    \PYGZcb{}
    EXAMPLE.COM = \PYGZob{}
           ATHENA.MIT.EDU = .
    \PYGZcb{}
\end{Verbatim}


\subsubsection{FILES}
\label{admin/conf_files/krb5_conf:files}
\code{/etc/krb5.conf}


\subsubsection{SEE ALSO}
\label{admin/conf_files/krb5_conf:see-also}
syslog(3)


\subsection{kdc.conf}
\label{admin/conf_files/kdc_conf:kdc-conf}\label{admin/conf_files/kdc_conf::doc}\label{admin/conf_files/kdc_conf:kdc-conf-5}
The kdc.conf file supplements {\hyperref[admin/conf_files/krb5_conf:krb5-conf-5]{\emph{krb5.conf}}} for programs which
are typically only used on a KDC, such as the {\hyperref[admin/admin_commands/krb5kdc:krb5kdc-8]{\emph{krb5kdc}}} and
{\hyperref[admin/admin_commands/kadmind:kadmind-8]{\emph{kadmind}}} daemons and the {\hyperref[admin/admin_commands/kdb5_util:kdb5-util-8]{\emph{kdb5\_util}}} program.
Relations documented here may also be specified in krb5.conf; for the
KDC programs mentioned, krb5.conf and kdc.conf will be merged into a
single configuration profile.

Normally, the kdc.conf file is found in the KDC state directory,
{\hyperref[mitK5defaults:paths]{\emph{LOCALSTATEDIR}}}\code{/krb5kdc}.  You can override the default location by setting the
environment variable \textbf{KRB5\_KDC\_PROFILE}.

Please note that you need to restart the KDC daemon for any configuration
changes to take effect.


\subsubsection{Structure}
\label{admin/conf_files/kdc_conf:structure}
The kdc.conf file is set up in the same format as the
{\hyperref[admin/conf_files/krb5_conf:krb5-conf-5]{\emph{krb5.conf}}} file.


\subsubsection{Sections}
\label{admin/conf_files/kdc_conf:sections}
The kdc.conf file may contain the following sections:

\begin{tabulary}{\linewidth}{|L|L|}
\hline

{\hyperref[admin/conf_files/kdc_conf:kdcdefaults]{\emph{{[}kdcdefaults{]}}}}
 & 
Default values for KDC behavior
\\
\hline
{\hyperref[admin/conf_files/kdc_conf:kdc-realms]{\emph{{[}realms{]}}}}
 & 
Realm-specific database configuration and settings
\\
\hline
{\hyperref[admin/conf_files/kdc_conf:dbdefaults]{\emph{{[}dbdefaults{]}}}}
 & 
Default database settings
\\
\hline
{\hyperref[admin/conf_files/kdc_conf:dbmodules]{\emph{{[}dbmodules{]}}}}
 & 
Per-database settings
\\
\hline
{\hyperref[admin/conf_files/kdc_conf:logging]{\emph{{[}logging{]}}}}
 & 
Controls how Kerberos daemons perform logging
\\
\hline\end{tabulary}



\paragraph{{[}kdcdefaults{]}}
\label{admin/conf_files/kdc_conf:kdcdefaults}\label{admin/conf_files/kdc_conf:id1}
With two exceptions, relations in the {[}kdcdefaults{]} section specify
default values for realm variables, to be used if the {[}realms{]}
subsection does not contain a relation for the tag.  See the
{\hyperref[admin/conf_files/kdc_conf:kdc-realms]{\emph{{[}realms{]}}}} section for the definitions of these relations.
\begin{itemize}
\item {} 
\textbf{host\_based\_services}

\item {} 
\textbf{kdc\_listen}

\item {} 
\textbf{kdc\_ports}

\item {} 
\textbf{kdc\_tcp\_listen}

\item {} 
\textbf{kdc\_tcp\_ports}

\item {} 
\textbf{no\_host\_referral}

\item {} 
\textbf{restrict\_anonymous\_to\_tgt}

\end{itemize}
\begin{description}
\item[{\textbf{kdc\_max\_dgram\_reply\_size}}] \leavevmode
Specifies the maximum packet size that can be sent over UDP.  The
default value is 4096 bytes.

\item[{\textbf{kdc\_tcp\_listen\_backlog}}] \leavevmode
(Integer.)  Set the size of the listen queue length for the KDC
daemon.  The value may be limited by OS settings.  The default
value is 5.

\end{description}


\paragraph{{[}realms{]}}
\label{admin/conf_files/kdc_conf:realms}\label{admin/conf_files/kdc_conf:kdc-realms}
Each tag in the {[}realms{]} section is the name of a Kerberos realm.  The
value of the tag is a subsection where the relations define KDC
parameters for that particular realm.  The following example shows how
to define one parameter for the ATHENA.MIT.EDU realm:

\begin{Verbatim}[commandchars=\\\{\}]
[realms]
    ATHENA.MIT.EDU = \PYGZob{}
        max\PYGZus{}renewable\PYGZus{}life = 7d 0h 0m 0s
    \PYGZcb{}
\end{Verbatim}

The following tags may be specified in a {[}realms{]} subsection:
\begin{description}
\item[{\textbf{acl\_file}}] \leavevmode
(String.)  Location of the access control list file that
{\hyperref[admin/admin_commands/kadmind:kadmind-8]{\emph{kadmind}}} uses to determine which principals are allowed
which permissions on the Kerberos database.  The default value is
{\hyperref[mitK5defaults:paths]{\emph{LOCALSTATEDIR}}}\code{/krb5kdc}\code{/kadm5.acl}.  For more information on Kerberos ACL
file see {\hyperref[admin/conf_files/kadm5_acl:kadm5-acl-5]{\emph{kadm5.acl}}}.

\item[{\textbf{database\_module}}] \leavevmode
(String.)  This relation indicates the name of the configuration
section under {\hyperref[admin/conf_files/kdc_conf:dbmodules]{\emph{{[}dbmodules{]}}}} for database-specific parameters
used by the loadable database library.  The default value is the
realm name.  If this configuration section does not exist, default
values will be used for all database parameters.

\item[{\textbf{database\_name}}] \leavevmode
(String, deprecated.)  This relation specifies the location of the
Kerberos database for this realm, if the DB2 module is being used
and the {\hyperref[admin/conf_files/kdc_conf:dbmodules]{\emph{{[}dbmodules{]}}}} configuration section does not specify a
database name.  The default value is {\hyperref[mitK5defaults:paths]{\emph{LOCALSTATEDIR}}}\code{/krb5kdc}\code{/principal}.

\item[{\textbf{default\_principal\_expiration}}] \leavevmode
(\emph{abstime} string.)  Specifies the default expiration date of
principals created in this realm.  The default value is 0, which
means no expiration date.

\item[{\textbf{default\_principal\_flags}}] \leavevmode
(Flag string.)  Specifies the default attributes of principals
created in this realm.  The format for this string is a
comma-separated list of flags, with `+' before each flag that
should be enabled and `-` before each flag that should be
disabled.  The \textbf{postdateable}, \textbf{forwardable}, \textbf{tgt-based},
\textbf{renewable}, \textbf{proxiable}, \textbf{dup-skey}, \textbf{allow-tickets}, and
\textbf{service} flags default to enabled.

There are a number of possible flags:
\begin{description}
\item[{\textbf{allow-tickets}}] \leavevmode
Enabling this flag means that the KDC will issue tickets for
this principal.  Disabling this flag essentially deactivates
the principal within this realm.

\item[{\textbf{dup-skey}}] \leavevmode
Enabling this flag allows the principal to obtain a session
key for another user, permitting user-to-user authentication
for this principal.

\item[{\textbf{forwardable}}] \leavevmode
Enabling this flag allows the principal to obtain forwardable
tickets.

\item[{\textbf{hwauth}}] \leavevmode
If this flag is enabled, then the principal is required to
preauthenticate using a hardware device before receiving any
tickets.

\item[{\textbf{no-auth-data-required}}] \leavevmode
Enabling this flag prevents PAC or AD-SIGNEDPATH data from
being added to service tickets for the principal.

\item[{\textbf{ok-as-delegate}}] \leavevmode
If this flag is enabled, it hints the client that credentials
can and should be delegated when authenticating to the
service.

\item[{\textbf{ok-to-auth-as-delegate}}] \leavevmode
Enabling this flag allows the principal to use S4USelf tickets.

\item[{\textbf{postdateable}}] \leavevmode
Enabling this flag allows the principal to obtain postdateable
tickets.

\item[{\textbf{preauth}}] \leavevmode
If this flag is enabled on a client principal, then that
principal is required to preauthenticate to the KDC before
receiving any tickets.  On a service principal, enabling this
flag means that service tickets for this principal will only
be issued to clients with a TGT that has the preauthenticated
bit set.

\item[{\textbf{proxiable}}] \leavevmode
Enabling this flag allows the principal to obtain proxy
tickets.

\item[{\textbf{pwchange}}] \leavevmode
Enabling this flag forces a password change for this
principal.

\item[{\textbf{pwservice}}] \leavevmode
If this flag is enabled, it marks this principal as a password
change service.  This should only be used in special cases,
for example, if a user's password has expired, then the user
has to get tickets for that principal without going through
the normal password authentication in order to be able to
change the password.

\item[{\textbf{renewable}}] \leavevmode
Enabling this flag allows the principal to obtain renewable
tickets.

\item[{\textbf{service}}] \leavevmode
Enabling this flag allows the the KDC to issue service tickets
for this principal.

\item[{\textbf{tgt-based}}] \leavevmode
Enabling this flag allows a principal to obtain tickets based
on a ticket-granting-ticket, rather than repeating the
authentication process that was used to obtain the TGT.

\end{description}

\item[{\textbf{dict\_file}}] \leavevmode
(String.)  Location of the dictionary file containing strings that
are not allowed as passwords.  The file should contain one string
per line, with no additional whitespace.  If none is specified or
if there is no policy assigned to the principal, no dictionary
checks of passwords will be performed.

\item[{\textbf{host\_based\_services}}] \leavevmode
(Whitespace- or comma-separated list.)  Lists services which will
get host-based referral processing even if the server principal is
not marked as host-based by the client.

\item[{\textbf{iprop\_enable}}] \leavevmode
(Boolean value.)  Specifies whether incremental database
propagation is enabled.  The default value is false.

\item[{\textbf{iprop\_master\_ulogsize}}] \leavevmode
(Integer.)  Specifies the maximum number of log entries to be
retained for incremental propagation.  The default value is 1000.
Prior to release 1.11, the maximum value was 2500.

\item[{\textbf{iprop\_slave\_poll}}] \leavevmode
(Delta time string.)  Specifies how often the slave KDC polls for
new updates from the master.  The default value is \code{2m} (that
is, two minutes).

\item[{\textbf{iprop\_listen}}] \leavevmode
(Whitespace- or comma-separated list.)  Specifies the iprop RPC
listening addresses and/or ports for the {\hyperref[admin/admin_commands/kadmind:kadmind-8]{\emph{kadmind}}} daemon.
Each entry may be an interface address, a port number, or an
address and port number separated by a colon.  If the address
contains colons, enclose it in square brackets.  If no address is
specified, the wildcard address is used.  If kadmind fails to bind
to any of the specified addresses, it will fail to start.  The
default (when \textbf{iprop\_enable} is true) is to bind to the wildcard
address at the port specified in \textbf{iprop\_port}.  New in release
1.15.

\item[{\textbf{iprop\_port}}] \leavevmode
(Port number.)  Specifies the port number to be used for
incremental propagation.  When \textbf{iprop\_enable} is true, this
relation is required in the slave configuration file, and this
relation or \textbf{iprop\_listen} is required in the master
configuration file, as there is no default port number.  Port
numbers specified in \textbf{iprop\_listen} entries will override this
port number for the {\hyperref[admin/admin_commands/kadmind:kadmind-8]{\emph{kadmind}}} daemon.

\item[{\textbf{iprop\_resync\_timeout}}] \leavevmode
(Delta time string.)  Specifies the amount of time to wait for a
full propagation to complete.  This is optional in configuration
files, and is used by slave KDCs only.  The default value is 5
minutes (\code{5m}).  New in release 1.11.

\item[{\textbf{iprop\_logfile}}] \leavevmode
(File name.)  Specifies where the update log file for the realm
database is to be stored.  The default is to use the
\textbf{database\_name} entry from the realms section of the krb5 config
file, with \code{.ulog} appended.  (NOTE: If \textbf{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
{[}dbmodules{]} section, then the hard-coded default for
\textbf{database\_name} is used.  Determination of the \textbf{iprop\_logfile}
default value will not use values from the {[}dbmodules{]} section.)

\item[{\textbf{kadmind\_listen}}] \leavevmode
(Whitespace- or comma-separated list.)  Specifies the kadmin RPC
listening addresses and/or ports for the {\hyperref[admin/admin_commands/kadmind:kadmind-8]{\emph{kadmind}}} daemon.
Each entry may be an interface address, a port number, or an
address and port number separated by a colon.  If the address
contains colons, enclose it in square brackets.  If no address is
specified, the wildcard address is used.  If kadmind fails to bind
to any of the specified addresses, it will fail to start.  The
default is to bind to the wildcard address at the port specified
in \textbf{kadmind\_port}, or the standard kadmin port (749).  New in
release 1.15.

\item[{\textbf{kadmind\_port}}] \leavevmode
(Port number.)  Specifies the port on which the {\hyperref[admin/admin_commands/kadmind:kadmind-8]{\emph{kadmind}}}
daemon is to listen for this realm.  Port numbers specified in
\textbf{kadmind\_listen} entries will override this port number.  The
assigned port for kadmind is 749, which is used by default.

\item[{\textbf{key\_stash\_file}}] \leavevmode
(String.)  Specifies the location where the master key has been
stored (via kdb5\_util stash).  The default is {\hyperref[mitK5defaults:paths]{\emph{LOCALSTATEDIR}}}\code{/krb5kdc}\code{/.k5.REALM}, where \emph{REALM} is the Kerberos realm.

\item[{\textbf{kdc\_listen}}] \leavevmode
(Whitespace- or comma-separated list.)  Specifies the UDP
listening addresses and/or ports for the {\hyperref[admin/admin_commands/krb5kdc:krb5kdc-8]{\emph{krb5kdc}}} daemon.
Each entry may be an interface address, a port number, or an
address and port number separated by a colon.  If the address
contains colons, enclose it in square brackets.  If no address is
specified, the wildcard address is used.  If no port is specified,
the standard port (88) is used.  If the KDC daemon fails to bind
to any of the specified addresses, it will fail to start.  The
default is to bind to the wildcard address on the standard port.
New in release 1.15.

\item[{\textbf{kdc\_ports}}] \leavevmode
(Whitespace- or comma-separated list, deprecated.)  Prior to
release 1.15, this relation lists the ports for the
{\hyperref[admin/admin_commands/krb5kdc:krb5kdc-8]{\emph{krb5kdc}}} daemon to listen on for UDP requests.  In
release 1.15 and later, it has the same meaning as \textbf{kdc\_listen}
if that relation is not defined.

\item[{\textbf{kdc\_tcp\_listen}}] \leavevmode
(Whitespace- or comma-separated list.)  Specifies the TCP
listening addresses and/or ports for the {\hyperref[admin/admin_commands/krb5kdc:krb5kdc-8]{\emph{krb5kdc}}} daemon.
Each entry may be an interface address, a port number, or an
address and port number separated by a colon.  If the address
contains colons, enclose it in square brackets.  If no address is
specified, the wildcard address is used.  If no port is specified,
the standard port (88) is used.  To disable listening on TCP, set
this relation to the empty string with \code{kdc\_tcp\_listen = ""}.
If the KDC daemon fails to bind to any of the specified addresses,
it will fail to start.  The default is to bind to the wildcard
address on the standard port.  New in release 1.15.

\item[{\textbf{kdc\_tcp\_ports}}] \leavevmode
(Whitespace- or comma-separated list, deprecated.)  Prior to
release 1.15, this relation lists the ports for the
{\hyperref[admin/admin_commands/krb5kdc:krb5kdc-8]{\emph{krb5kdc}}} daemon to listen on for UDP requests.  In
release 1.15 and later, it has the same meaning as
\textbf{kdc\_tcp\_listen} if that relation is not defined.

\item[{\textbf{kpasswd\_listen}}] \leavevmode
(Comma-separated list.)  Specifies the kpasswd listening addresses
and/or ports for the {\hyperref[admin/admin_commands/kadmind:kadmind-8]{\emph{kadmind}}} daemon.  Each entry may be
an interface address, a port number, or an address and port number
separated by a colon.  If the address contains colons, enclose it
in square brackets.  If no address is specified, the wildcard
address is used.  If kadmind fails to bind to any of the specified
addresses, it will fail to start.  The default is to bind to the
wildcard address at the port specified in \textbf{kpasswd\_port}, or the
standard kpasswd port (464).  New in release 1.15.

\item[{\textbf{kpasswd\_port}}] \leavevmode
(Port number.)  Specifies the port on which the {\hyperref[admin/admin_commands/kadmind:kadmind-8]{\emph{kadmind}}}
daemon is to listen for password change requests for this realm.
Port numbers specified in \textbf{kpasswd\_listen} entries will override
this port number.  The assigned port for password change requests
is 464, which is used by default.

\item[{\textbf{master\_key\_name}}] \leavevmode
(String.)  Specifies the name of the principal associated with the
master key.  The default is \code{K/M}.

\item[{\textbf{master\_key\_type}}] \leavevmode
(Key type string.)  Specifies the master key's key type.  The
default value for this is \code{aes256-cts-hmac-sha1-96}.  For a list of all possible
values, see {\hyperref[admin/conf_files/kdc_conf:encryption-types]{\emph{Encryption types}}}.

\item[{\textbf{max\_life}}] \leavevmode
(\emph{duration} string.)  Specifies the maximum time period for
which a ticket may be valid in this realm.  The default value is
24 hours.

\item[{\textbf{max\_renewable\_life}}] \leavevmode
(\emph{duration} string.)  Specifies the maximum time period
during which a valid ticket may be renewed in this realm.
The default value is 0.

\item[{\textbf{no\_host\_referral}}] \leavevmode
(Whitespace- or comma-separated list.)  Lists services to block
from getting host-based referral processing, even if the client
marks the server principal as host-based or the service is also
listed in \textbf{host\_based\_services}.  \code{no\_host\_referral = *} will
disable referral processing altogether.

\item[{\textbf{des\_crc\_session\_supported}}] \leavevmode
(Boolean value).  If set to true, the KDC will assume that service
principals support des-cbc-crc for session key enctype negotiation
purposes.  If \textbf{allow\_weak\_crypto} in {\hyperref[admin/conf_files/krb5_conf:libdefaults]{\emph{{[}libdefaults{]}}}} is
false, or if des-cbc-crc is not a permitted enctype, then this
variable has no effect.  Defaults to true.  New in release 1.11.

\item[{\textbf{reject\_bad\_transit}}] \leavevmode
(Boolean value.)  If set to true, the KDC will check the list of
transited realms for cross-realm tickets against the transit path
computed from the realm names and the capaths section of its
{\hyperref[admin/conf_files/krb5_conf:krb5-conf-5]{\emph{krb5.conf}}} file; if the path in the ticket to be issued
contains any realms not in the computed path, the ticket will not
be issued, and an error will be returned to the client instead.
If this value is set to false, such tickets will be issued
anyways, and it will be left up to the application server to
validate the realm transit path.

If the disable-transited-check flag is set in the incoming
request, this check is not performed at all.  Having the
\textbf{reject\_bad\_transit} option will cause such ticket requests to
be rejected always.

This transit path checking and config file option currently apply
only to TGS requests.

The default value is true.

\item[{\textbf{restrict\_anonymous\_to\_tgt}}] \leavevmode
(Boolean value.)  If set to true, the KDC will reject ticket
requests from anonymous principals to service principals other
than the realm's ticket-granting service.  This option allows
anonymous PKINIT to be enabled for use as FAST armor tickets
without allowing anonymous authentication to services.  The
default value is false.  New in release 1.9.

\item[{\textbf{supported\_enctypes}}] \leavevmode
(List of \emph{key}:\emph{salt} strings.)  Specifies the default key/salt
combinations of principals for this realm.  Any principals created
through {\hyperref[admin/admin_commands/kadmin_local:kadmin-1]{\emph{kadmin}}} will have keys of these types.  The
default value for this tag is \code{aes256-cts-hmac-sha1-96:normal aes128-cts-hmac-sha1-96:normal des3-cbc-sha1:normal arcfour-hmac-md5:normal}.  For lists of
possible values, see {\hyperref[admin/conf_files/kdc_conf:keysalt-lists]{\emph{Keysalt lists}}}.

\end{description}


\paragraph{{[}dbdefaults{]}}
\label{admin/conf_files/kdc_conf:id2}\label{admin/conf_files/kdc_conf:dbdefaults}
The {[}dbdefaults{]} section specifies default values for some database
parameters, to be used if the {[}dbmodules{]} subsection does not contain
a relation for the tag.  See the {\hyperref[admin/conf_files/kdc_conf:dbmodules]{\emph{{[}dbmodules{]}}}} section for the
definitions of these relations.
\begin{itemize}
\item {} 
\textbf{ldap\_kerberos\_container\_dn}

\item {} 
\textbf{ldap\_kdc\_dn}

\item {} 
\textbf{ldap\_kdc\_sasl\_authcid}

\item {} 
\textbf{ldap\_kdc\_sasl\_authzid}

\item {} 
\textbf{ldap\_kdc\_sasl\_mech}

\item {} 
\textbf{ldap\_kdc\_sasl\_realm}

\item {} 
\textbf{ldap\_kadmind\_dn}

\item {} 
\textbf{ldap\_kadmind\_sasl\_authcid}

\item {} 
\textbf{ldap\_kadmind\_sasl\_authzid}

\item {} 
\textbf{ldap\_kadmind\_sasl\_mech}

\item {} 
\textbf{ldap\_kadmind\_sasl\_realm}

\item {} 
\textbf{ldap\_service\_password\_file}

\item {} 
\textbf{ldap\_servers}

\item {} 
\textbf{ldap\_conns\_per\_server}

\end{itemize}


\paragraph{{[}dbmodules{]}}
\label{admin/conf_files/kdc_conf:dbmodules}\label{admin/conf_files/kdc_conf:id3}
The {[}dbmodules{]} section contains parameters used by the KDC database
library and database modules.  Each tag in the {[}dbmodules{]} section is
the name of a Kerberos realm or a section name specified by a realm's
\textbf{database\_module} parameter.  The following example shows how to
define one database parameter for the ATHENA.MIT.EDU realm:

\begin{Verbatim}[commandchars=\\\{\}]
[dbmodules]
    ATHENA.MIT.EDU = \PYGZob{}
        disable\PYGZus{}last\PYGZus{}success = true
    \PYGZcb{}
\end{Verbatim}

The following tags may be specified in a {[}dbmodules{]} subsection:
\begin{description}
\item[{\textbf{database\_name}}] \leavevmode
This DB2-specific tag indicates the location of the database in
the filesystem.  The default is {\hyperref[mitK5defaults:paths]{\emph{LOCALSTATEDIR}}}\code{/krb5kdc}\code{/principal}.

\item[{\textbf{db\_library}}] \leavevmode
This tag indicates the name of the loadable database module.  The
value should be \code{db2} for the DB2 module and \code{kldap} for the
LDAP module.

\item[{\textbf{disable\_last\_success}}] \leavevmode
If set to \code{true}, suppresses KDC updates to the ``Last successful
authentication'' field of principal entries requiring
preauthentication.  Setting this flag may improve performance.
(Principal entries which do not require preauthentication never
update the ``Last successful authentication'' field.).  First
introduced in release 1.9.

\item[{\textbf{disable\_lockout}}] \leavevmode
If set to \code{true}, suppresses KDC updates to the ``Last failed
authentication'' and ``Failed password attempts'' fields of principal
entries requiring preauthentication.  Setting this flag may
improve performance, but also disables account lockout.  First
introduced in release 1.9.

\item[{\textbf{ldap\_conns\_per\_server}}] \leavevmode
This LDAP-specific tag indicates the number of connections to be
maintained per LDAP server.

\item[{\textbf{ldap\_kdc\_dn} and \textbf{ldap\_kadmind\_dn}}] \leavevmode
These LDAP-specific tags indicate the default DN for binding to
the LDAP server.  The {\hyperref[admin/admin_commands/krb5kdc:krb5kdc-8]{\emph{krb5kdc}}} daemon uses
\textbf{ldap\_kdc\_dn}, while the {\hyperref[admin/admin_commands/kadmind:kadmind-8]{\emph{kadmind}}} daemon and other
administrative programs use \textbf{ldap\_kadmind\_dn}.  The kadmind DN
must have the rights to read and write the Kerberos data in the
LDAP database.  The KDC DN must have the same rights, unless
\textbf{disable\_lockout} and \textbf{disable\_last\_success} are true, in
which case it only needs to have rights to read the Kerberos data.
These tags are ignored if a SASL mechanism is set with
\textbf{ldap\_kdc\_sasl\_mech} or \textbf{ldap\_kadmind\_sasl\_mech}.

\item[{\textbf{ldap\_kdc\_sasl\_mech} and \textbf{ldap\_kadmind\_sasl\_mech}}] \leavevmode
These LDAP-specific tags specify the SASL mechanism (such as
\code{EXTERNAL}) to use when binding to the LDAP server.  New in
release 1.13.

\item[{\textbf{ldap\_kdc\_sasl\_authcid} and \textbf{ldap\_kadmind\_sasl\_authcid}}] \leavevmode
These LDAP-specific tags specify the SASL authentication identity
to use when binding to the LDAP server.  Not all SASL mechanisms
require an authentication identity.  If the SASL mechanism
requires a secret (such as the password for \code{DIGEST-MD5}), these
tags also determine the name within the
\textbf{ldap\_service\_password\_file} where the secret is stashed.  New
in release 1.13.

\item[{\textbf{ldap\_kdc\_sasl\_authzid} and \textbf{ldap\_kadmind\_sasl\_authzid}}] \leavevmode
These LDAP-specific tags specify the SASL authorization identity
to use when binding to the LDAP server.  In most circumstances
they do not need to be specified.  New in release 1.13.

\item[{\textbf{ldap\_kdc\_sasl\_realm} and \textbf{ldap\_kadmind\_sasl\_realm}}] \leavevmode
These LDAP-specific tags specify the SASL realm to use when
binding to the LDAP server.  In most circumstances they do not
need to be set.  New in release 1.13.

\item[{\textbf{ldap\_kerberos\_container\_dn}}] \leavevmode
This LDAP-specific tag indicates the DN of the container object
where the realm objects will be located.

\item[{\textbf{ldap\_servers}}] \leavevmode
This LDAP-specific tag indicates the list of LDAP servers that the
Kerberos servers can connect to.  The list of LDAP servers is
whitespace-separated.  The LDAP server is specified by a LDAP URI.
It is recommended to use \code{ldapi:} or \code{ldaps:} URLs to connect
to the LDAP server.

\item[{\textbf{ldap\_service\_password\_file}}] \leavevmode
This LDAP-specific tag indicates the file containing the stashed
passwords (created by \code{kdb5\_ldap\_util stashsrvpw}) for the
\textbf{ldap\_kdc\_dn} and \textbf{ldap\_kadmind\_dn} objects, or for the
\textbf{ldap\_kdc\_sasl\_authcid} or \textbf{ldap\_kadmind\_sasl\_authcid} names
for SASL authentication.  This file must be kept secure.

\item[{\textbf{unlockiter}}] \leavevmode
If set to \code{true}, this DB2-specific tag causes iteration
operations to release the database lock while processing each
principal.  Setting this flag to \code{true} can prevent extended
blocking of KDC or kadmin operations when dumps of large databases
are in progress.  First introduced in release 1.13.

\end{description}

The following tag may be specified directly in the {[}dbmodules{]}
section to control where database modules are loaded from:
\begin{description}
\item[{\textbf{db\_module\_dir}}] \leavevmode
This tag controls where the plugin system looks for database
modules.  The value should be an absolute path.

\end{description}


\paragraph{{[}logging{]}}
\label{admin/conf_files/kdc_conf:id4}\label{admin/conf_files/kdc_conf:logging}
The {[}logging{]} section indicates how {\hyperref[admin/admin_commands/krb5kdc:krb5kdc-8]{\emph{krb5kdc}}} and
{\hyperref[admin/admin_commands/kadmind:kadmind-8]{\emph{kadmind}}} perform logging.  It may contain the following
relations:
\begin{description}
\item[{\textbf{admin\_server}}] \leavevmode
Specifies how {\hyperref[admin/admin_commands/kadmind:kadmind-8]{\emph{kadmind}}} performs logging.

\item[{\textbf{kdc}}] \leavevmode
Specifies how {\hyperref[admin/admin_commands/krb5kdc:krb5kdc-8]{\emph{krb5kdc}}} performs logging.

\item[{\textbf{default}}] \leavevmode
Specifies how either daemon performs logging in the absence of
relations specific to the daemon.

\item[{\textbf{debug}}] \leavevmode
(Boolean value.)  Specifies whether debugging messages are
included in log outputs other than SYSLOG.  Debugging messages are
always included in the system log output because syslog performs
its own priority filtering.  The default value is false.  New in
release 1.15.

\end{description}

Logging specifications may have the following forms:
\begin{description}
\item[{\textbf{FILE=}\emph{filename} or \textbf{FILE:}\emph{filename}}] \leavevmode
This value causes the daemon's logging messages to go to the
\emph{filename}.  If the \code{=} form is used, the file is overwritten.
If the \code{:} form is used, the file is appended to.

\item[{\textbf{STDERR}}] \leavevmode
This value causes the daemon's logging messages to go to its
standard error stream.

\item[{\textbf{CONSOLE}}] \leavevmode
This value causes the daemon's logging messages to go to the
console, if the system supports it.

\item[{\textbf{DEVICE=}\emph{\textless{}devicename\textgreater{}}}] \leavevmode
This causes the daemon's logging messages to go to the specified
device.

\item[{\textbf{SYSLOG}{[}\textbf{:}\emph{severity}{[}\textbf{:}\emph{facility}{]}{]}}] \leavevmode
This causes the daemon's logging messages to go to the system log.

The severity argument specifies the default severity of system log
messages.  This may be any of the following severities supported
by the syslog(3) call, minus the \code{LOG\_} prefix: \textbf{EMERG},
\textbf{ALERT}, \textbf{CRIT}, \textbf{ERR}, \textbf{WARNING}, \textbf{NOTICE}, \textbf{INFO},
and \textbf{DEBUG}.

The facility argument specifies the facility under which the
messages are logged.  This may be any of the following facilities
supported by the syslog(3) call minus the LOG\_ prefix: \textbf{KERN},
\textbf{USER}, \textbf{MAIL}, \textbf{DAEMON}, \textbf{AUTH}, \textbf{LPR}, \textbf{NEWS},
\textbf{UUCP}, \textbf{CRON}, and \textbf{LOCAL0} through \textbf{LOCAL7}.

If no severity is specified, the default is \textbf{ERR}.  If no
facility is specified, the default is \textbf{AUTH}.

\end{description}

In the following example, the logging messages from the KDC will go to
the console and to the system log under the facility LOG\_DAEMON with
default severity of LOG\_INFO; and the logging messages from the
administrative server will be appended to the file
\code{/var/adm/kadmin.log} and sent to the device \code{/dev/tty04}.

\begin{Verbatim}[commandchars=\\\{\}]
[logging]
    kdc = CONSOLE
    kdc = SYSLOG:INFO:DAEMON
    admin\PYGZus{}server = FILE:/var/adm/kadmin.log
    admin\PYGZus{}server = DEVICE=/dev/tty04
\end{Verbatim}


\paragraph{{[}otp{]}}
\label{admin/conf_files/kdc_conf:otp}\label{admin/conf_files/kdc_conf:id5}
Each subsection of {[}otp{]} is the name of an OTP token type.  The tags
within the subsection define the configuration required to forward a
One Time Password request to a RADIUS server.

For each token type, the following tags may be specified:
\begin{description}
\item[{\textbf{server}}] \leavevmode
This is the server to send the RADIUS request to.  It can be a
hostname with optional port, an ip address with optional port, or
a Unix domain socket address.  The default is
{\hyperref[mitK5defaults:paths]{\emph{LOCALSTATEDIR}}}\code{/krb5kdc}\code{/\textless{}name\textgreater{}.socket}.

\item[{\textbf{secret}}] \leavevmode
This tag indicates a filename (which may be relative to {\hyperref[mitK5defaults:paths]{\emph{LOCALSTATEDIR}}}\code{/krb5kdc})
containing the secret used to encrypt the RADIUS packets.  The
secret should appear in the first line of the file by itself;
leading and trailing whitespace on the line will be removed.  If
the value of \textbf{server} is a Unix domain socket address, this tag
is optional, and an empty secret will be used if it is not
specified.  Otherwise, this tag is required.

\item[{\textbf{timeout}}] \leavevmode
An integer which specifies the time in seconds during which the
KDC should attempt to contact the RADIUS server.  This tag is the
total time across all retries and should be less than the time
which an OTP value remains valid for.  The default is 5 seconds.

\item[{\textbf{retries}}] \leavevmode
This tag specifies the number of retries to make to the RADIUS
server.  The default is 3 retries (4 tries).

\item[{\textbf{strip\_realm}}] \leavevmode
If this tag is \code{true}, the principal without the realm will be
passed to the RADIUS server.  Otherwise, the realm will be
included.  The default value is \code{true}.

\item[{\textbf{indicator}}] \leavevmode
This tag specifies an authentication indicator to be included in
the ticket if this token type is used to authenticate.  This
option may be specified multiple times.  (New in release 1.14.)

\end{description}

In the following example, requests are sent to a remote server via UDP:

\begin{Verbatim}[commandchars=\\\{\}]
[otp]
    MyRemoteTokenType = \PYGZob{}
        server = radius.mydomain.com:1812
        secret = SEmfiajf42\PYGZdl{}
        timeout = 15
        retries = 5
        strip\PYGZus{}realm = true
    \PYGZcb{}
\end{Verbatim}

An implicit default token type named \code{DEFAULT} is defined for when
the per-principal configuration does not specify a token type.  Its
configuration is shown below.  You may override this token type to
something applicable for your situation:

\begin{Verbatim}[commandchars=\\\{\}]
[otp]
    DEFAULT = \PYGZob{}
        strip\PYGZus{}realm = false
    \PYGZcb{}
\end{Verbatim}


\subsubsection{PKINIT options}
\label{admin/conf_files/kdc_conf:pkinit-options}
\begin{notice}{note}{Note:}
The following are pkinit-specific options.  These values may
be specified in {[}kdcdefaults{]} as global defaults, or within
a realm-specific subsection of {[}realms{]}.  Also note that a
realm-specific value over-rides, does not add to, a generic
{[}kdcdefaults{]} specification.  The search order is:
\end{notice}
\begin{enumerate}
\item {} 
realm-specific subsection of {[}realms{]}:

\begin{Verbatim}[commandchars=\\\{\}]
[realms]
    EXAMPLE.COM = \PYGZob{}
        pkinit\PYGZus{}anchors = FILE:/usr/local/example.com.crt
    \PYGZcb{}
\end{Verbatim}

\item {} 
generic value in the {[}kdcdefaults{]} section:

\begin{Verbatim}[commandchars=\\\{\}]
[kdcdefaults]
    pkinit\PYGZus{}anchors = DIR:/usr/local/generic\PYGZus{}trusted\PYGZus{}cas/
\end{Verbatim}

\end{enumerate}

For information about the syntax of some of these options, see
{\hyperref[admin/conf_files/krb5_conf:pkinit-identity]{\emph{Specifying PKINIT identity information}}} in
{\hyperref[admin/conf_files/krb5_conf:krb5-conf-5]{\emph{krb5.conf}}}.
\begin{description}
\item[{\textbf{pkinit\_anchors}}] \leavevmode
Specifies the location of trusted anchor (root) certificates which
the KDC trusts to sign client certificates.  This option is
required if pkinit is to be supported by the KDC.  This option may
be specified multiple times.

\item[{\textbf{pkinit\_dh\_min\_bits}}] \leavevmode
Specifies the minimum number of bits the KDC is willing to accept
for a client's Diffie-Hellman key.  The default is 2048.

\item[{\textbf{pkinit\_allow\_upn}}] \leavevmode
Specifies that the KDC is willing to accept client certificates
with the Microsoft UserPrincipalName (UPN) Subject Alternative
Name (SAN).  This means the KDC accepts the binding of the UPN in
the certificate to the Kerberos principal name.  The default value
is false.

Without this option, the KDC will only accept certificates with
the id-pkinit-san as defined in \index{RFC!RFC 4556}\href{http://tools.ietf.org/html/rfc4556.html}{\textbf{RFC 4556}}.  There is currently
no option to disable SAN checking in the KDC.

\item[{\textbf{pkinit\_eku\_checking}}] \leavevmode
This option specifies what Extended Key Usage (EKU) values the KDC
is willing to accept in client certificates.  The values
recognized in the kdc.conf file are:
\begin{description}
\item[{\textbf{kpClientAuth}}] \leavevmode
This is the default value and specifies that client
certificates must have the id-pkinit-KPClientAuth EKU as
defined in \index{RFC!RFC 4556}\href{http://tools.ietf.org/html/rfc4556.html}{\textbf{RFC 4556}}.

\item[{\textbf{scLogin}}] \leavevmode
If scLogin is specified, client certificates with the
Microsoft Smart Card Login EKU (id-ms-kp-sc-logon) will be
accepted.

\item[{\textbf{none}}] \leavevmode
If none is specified, then client certificates will not be
checked to verify they have an acceptable EKU.  The use of
this option is not recommended.

\end{description}

\item[{\textbf{pkinit\_identity}}] \leavevmode
Specifies the location of the KDC's X.509 identity information.
This option is required if pkinit is to be supported by the KDC.

\item[{\textbf{pkinit\_indicator}}] \leavevmode
Specifies an authentication indicator to include in the ticket if
pkinit is used to authenticate.  This option may be specified
multiple times.  (New in release 1.14.)

\item[{\textbf{pkinit\_kdc\_ocsp}}] \leavevmode
Specifies the location of the KDC's OCSP.

\item[{\textbf{pkinit\_pool}}] \leavevmode
Specifies the location of intermediate certificates which may be
used by the KDC to complete the trust chain between a client's
certificate and a trusted anchor.  This option may be specified
multiple times.

\item[{\textbf{pkinit\_revoke}}] \leavevmode
Specifies the location of Certificate Revocation List (CRL)
information to be used by the KDC when verifying the validity of
client certificates.  This option may be specified multiple times.

\item[{\textbf{pkinit\_require\_crl\_checking}}] \leavevmode
The default certificate verification process will always check the
available revocation information to see if a certificate has been
revoked.  If a match is found for the certificate in a CRL,
verification fails.  If the certificate being verified is not
listed in a CRL, or there is no CRL present for its issuing CA,
and \textbf{pkinit\_require\_crl\_checking} is false, then verification
succeeds.

However, if \textbf{pkinit\_require\_crl\_checking} is true and there is
no CRL information available for the issuing CA, then verification
fails.

\textbf{pkinit\_require\_crl\_checking} should be set to true if the
policy is such that up-to-date CRLs must be present for every CA.

\end{description}


\subsubsection{Encryption types}
\label{admin/conf_files/kdc_conf:id6}\label{admin/conf_files/kdc_conf:encryption-types}
Any tag in the configuration files which requires a list of encryption
types can be set to some combination of the following strings.
Encryption types marked as ``weak'' are available for compatibility but
not recommended for use.

\begin{tabulary}{\linewidth}{|L|L|}
\hline

des-cbc-crc
 & 
DES cbc mode with CRC-32 (weak)
\\
\hline
des-cbc-md4
 & 
DES cbc mode with RSA-MD4 (weak)
\\
\hline
des-cbc-md5
 & 
DES cbc mode with RSA-MD5 (weak)
\\
\hline
des-cbc-raw
 & 
DES cbc mode raw (weak)
\\
\hline
des3-cbc-raw
 & 
Triple DES cbc mode raw (weak)
\\
\hline
des3-cbc-sha1 des3-hmac-sha1 des3-cbc-sha1-kd
 & 
Triple DES cbc mode with HMAC/sha1
\\
\hline
des-hmac-sha1
 & 
DES with HMAC/sha1 (weak)
\\
\hline
aes256-cts-hmac-sha1-96 aes256-cts aes256-sha1
 & 
AES-256 CTS mode with 96-bit SHA-1 HMAC
\\
\hline
aes128-cts-hmac-sha1-96 aes128-cts aes128-sha1
 & 
AES-128 CTS mode with 96-bit SHA-1 HMAC
\\
\hline
aes256-cts-hmac-sha384-192 aes256-sha2
 & 
AES-256 CTS mode with 192-bit SHA-384 HMAC
\\
\hline
aes128-cts-hmac-sha256-128 aes128-sha2
 & 
AES-128 CTS mode with 128-bit SHA-256 HMAC
\\
\hline
arcfour-hmac rc4-hmac arcfour-hmac-md5
 & 
RC4 with HMAC/MD5
\\
\hline
arcfour-hmac-exp rc4-hmac-exp arcfour-hmac-md5-exp
 & 
Exportable RC4 with HMAC/MD5 (weak)
\\
\hline
camellia256-cts-cmac camellia256-cts
 & 
Camellia-256 CTS mode with CMAC
\\
\hline
camellia128-cts-cmac camellia128-cts
 & 
Camellia-128 CTS mode with CMAC
\\
\hline
des
 & 
The DES family: des-cbc-crc, des-cbc-md5, and des-cbc-md4 (weak)
\\
\hline
des3
 & 
The triple DES family: des3-cbc-sha1
\\
\hline
aes
 & 
The AES family: aes256-cts-hmac-sha1-96 and aes128-cts-hmac-sha1-96
\\
\hline
rc4
 & 
The RC4 family: arcfour-hmac
\\
\hline
camellia
 & 
The Camellia family: camellia256-cts-cmac and camellia128-cts-cmac
\\
\hline\end{tabulary}


The string \textbf{DEFAULT} can be used to refer to the default set of
types for the variable in question.  Types or families can be removed
from the current list by prefixing them with a minus sign (``-'').
Types or families can be prefixed with a plus sign (``+'') for symmetry;
it has the same meaning as just listing the type or family.  For
example, ``\code{DEFAULT -des}'' would be the default set of encryption
types with DES types removed, and ``\code{des3 DEFAULT}'' would be the
default set of encryption types with triple DES types moved to the
front.

While \textbf{aes128-cts} and \textbf{aes256-cts} are supported for all Kerberos
operations, they are not supported by very old versions of our GSSAPI
implementation (krb5-1.3.1 and earlier).  Services running versions of
krb5 without AES support must not be given keys of these encryption
types in the KDC database.

The \textbf{aes128-sha2} and \textbf{aes256-sha2} encryption types are new in
release 1.15.  Services running versions of krb5 without support for
these newer encryption types must not be given keys of these
encryption types in the KDC database.


\subsubsection{Keysalt lists}
\label{admin/conf_files/kdc_conf:id7}\label{admin/conf_files/kdc_conf:keysalt-lists}
Kerberos keys for users are usually derived from passwords.  Kerberos
commands and configuration parameters that affect generation of keys
take lists of enctype-salttype (``keysalt'') pairs, known as \emph{keysalt
lists}.  Each keysalt pair is an enctype name followed by a salttype
name, in the format \emph{enc}:\emph{salt}.  Individual keysalt list members are
separated by comma ('','') characters or space characters.  For example:

\begin{Verbatim}[commandchars=\\\{\}]
kadmin \PYGZhy{}e aes256\PYGZhy{}cts:normal,aes128\PYGZhy{}cts:normal
\end{Verbatim}

would start up kadmin so that by default it would generate
password-derived keys for the \textbf{aes256-cts} and \textbf{aes128-cts}
encryption types, using a \textbf{normal} salt.

To ensure that people who happen to pick the same password do not have
the same key, Kerberos 5 incorporates more information into the key
using something called a salt.  The supported salt types are as
follows:

\begin{tabulary}{\linewidth}{|L|L|}
\hline

normal
 & 
default for Kerberos Version 5
\\
\hline
v4
 & 
the only type used by Kerberos Version 4 (no salt)
\\
\hline
norealm
 & 
same as the default, without using realm information
\\
\hline
onlyrealm
 & 
uses only realm information as the salt
\\
\hline
afs3
 & 
AFS version 3, only used for compatibility with Kerberos 4 in AFS
\\
\hline
special
 & 
generate a random salt
\\
\hline\end{tabulary}



\subsubsection{Sample kdc.conf File}
\label{admin/conf_files/kdc_conf:sample-kdc-conf-file}
Here's an example of a kdc.conf file:

\begin{Verbatim}[commandchars=\\\{\}]
[kdcdefaults]
    kdc\PYGZus{}listen = 88
    kdc\PYGZus{}tcp\PYGZus{}listen = 88
[realms]
    ATHENA.MIT.EDU = \PYGZob{}
        kadmind\PYGZus{}port = 749
        max\PYGZus{}life = 12h 0m 0s
        max\PYGZus{}renewable\PYGZus{}life = 7d 0h 0m 0s
        master\PYGZus{}key\PYGZus{}type = aes256\PYGZhy{}cts\PYGZhy{}hmac\PYGZhy{}sha1\PYGZhy{}96
        supported\PYGZus{}enctypes = aes256\PYGZhy{}cts\PYGZhy{}hmac\PYGZhy{}sha1\PYGZhy{}96:normal aes128\PYGZhy{}cts\PYGZhy{}hmac\PYGZhy{}sha1\PYGZhy{}96:normal
        database\PYGZus{}module = openldap\PYGZus{}ldapconf
    \PYGZcb{}

[logging]
    kdc = FILE:/usr/local/var/krb5kdc/kdc.log
    admin\PYGZus{}server = FILE:/usr/local/var/krb5kdc/kadmin.log

[dbdefaults]
    ldap\PYGZus{}kerberos\PYGZus{}container\PYGZus{}dn = cn=krbcontainer,dc=mit,dc=edu

[dbmodules]
    openldap\PYGZus{}ldapconf = \PYGZob{}
        db\PYGZus{}library = kldap
        disable\PYGZus{}last\PYGZus{}success = true
        ldap\PYGZus{}kdc\PYGZus{}dn = \PYGZdq{}cn=krbadmin,dc=mit,dc=edu\PYGZdq{}
            \PYGZsh{} this object needs to have read rights on
            \PYGZsh{} the realm container and principal subtrees
        ldap\PYGZus{}kadmind\PYGZus{}dn = \PYGZdq{}cn=krbadmin,dc=mit,dc=edu\PYGZdq{}
            \PYGZsh{} this object needs to have read and write rights on
            \PYGZsh{} the realm container and principal subtrees
        ldap\PYGZus{}service\PYGZus{}password\PYGZus{}file = /etc/kerberos/service.keyfile
        ldap\PYGZus{}servers = ldaps://kerberos.mit.edu
        ldap\PYGZus{}conns\PYGZus{}per\PYGZus{}server = 5
    \PYGZcb{}
\end{Verbatim}


\subsubsection{FILES}
\label{admin/conf_files/kdc_conf:files}
{\hyperref[mitK5defaults:paths]{\emph{LOCALSTATEDIR}}}\code{/krb5kdc}\code{/kdc.conf}


\subsubsection{SEE ALSO}
\label{admin/conf_files/kdc_conf:see-also}
{\hyperref[admin/conf_files/krb5_conf:krb5-conf-5]{\emph{krb5.conf}}}, {\hyperref[admin/admin_commands/krb5kdc:krb5kdc-8]{\emph{krb5kdc}}}, {\hyperref[admin/conf_files/kadm5_acl:kadm5-acl-5]{\emph{kadm5.acl}}}


\subsection{kadm5.acl}
\label{admin/conf_files/kadm5_acl:kadm5-acl}\label{admin/conf_files/kadm5_acl:kadm5-acl-5}\label{admin/conf_files/kadm5_acl::doc}

\subsubsection{DESCRIPTION}
\label{admin/conf_files/kadm5_acl:description}
The Kerberos {\hyperref[admin/admin_commands/kadmind:kadmind-8]{\emph{kadmind}}} daemon uses an Access Control List
(ACL) file to manage access rights to the Kerberos database.
For operations that affect principals, the ACL file also controls
which principals can operate on which other principals.

The default location of the Kerberos ACL file is
{\hyperref[mitK5defaults:paths]{\emph{LOCALSTATEDIR}}}\code{/krb5kdc}\code{/kadm5.acl}  unless this is overridden by the \emph{acl\_file}
variable in {\hyperref[admin/conf_files/kdc_conf:kdc-conf-5]{\emph{kdc.conf}}}.


\subsubsection{SYNTAX}
\label{admin/conf_files/kadm5_acl:syntax}
Empty lines and lines starting with the sharp sign (\code{\#}) are
ignored.  Lines containing ACL entries have the format:

\begin{Verbatim}[commandchars=\\\{\}]
principal  permissions  [target\PYGZus{}principal  [restrictions] ]
\end{Verbatim}

\begin{notice}{note}{Note:}
Line order in the ACL file is important.  The first matching entry
will control access for an actor principal on a target principal.
\end{notice}
\begin{description}
\item[{\emph{principal}}] \leavevmode
(Partially or fully qualified Kerberos principal name.) Specifies
the principal whose permissions are to be set.

Each component of the name may be wildcarded using the \code{*}
character.

\item[{\emph{permissions}}] \leavevmode
Specifies what operations may or may not be performed by a
\emph{principal} matching a particular entry.  This is a string of one or
more of the following list of characters or their upper-case
counterparts.  If the character is \emph{upper-case}, then the operation
is disallowed.  If the character is \emph{lower-case}, then the operation
is permitted.

\begin{tabulary}{\linewidth}{|L|L|}
\hline

a
 & 
{[}Dis{]}allows the addition of principals or policies
\\
\hline
c
 & 
{[}Dis{]}allows the changing of passwords for principals
\\
\hline
d
 & 
{[}Dis{]}allows the deletion of principals or policies
\\
\hline
e
 & 
{[}Dis{]}allows the extraction of principal keys
\\
\hline
i
 & 
{[}Dis{]}allows inquiries about principals or policies
\\
\hline
l
 & 
{[}Dis{]}allows the listing of all principals or policies
\\
\hline
m
 & 
{[}Dis{]}allows the modification of principals or policies
\\
\hline
p
 & 
{[}Dis{]}allows the propagation of the principal database (used in {\hyperref[admin/database:incr-db-prop]{\emph{Incremental database propagation}}})
\\
\hline
s
 & 
{[}Dis{]}allows the explicit setting of the key for a principal
\\
\hline
x
 & 
Short for admcilsp. All privileges (except \code{e})
\\
\hline
*
 & 
Same as x.
\\
\hline\end{tabulary}


\end{description}

\begin{notice}{note}{Note:}
The \code{extract} privilege is not included in the wildcard
privilege; it must be explicitly assigned.  This privilege
allows the user to extract keys from the database, and must be
handled with great care to avoid disclosure of important keys
like those of the kadmin/* or krbtgt/* principals.  The
\textbf{lockdown\_keys} principal attribute can be used to prevent
key extraction from specific principals regardless of the
granted privilege.
\end{notice}
\begin{description}
\item[{\emph{target\_principal}}] \leavevmode
(Optional. Partially or fully qualified Kerberos principal name.)
Specifies the principal on which \emph{permissions} may be applied.
Each component of the name may be wildcarded using the \code{*}
character.

\emph{target\_principal} can also include back-references to \emph{principal},
in which \code{*number} matches the corresponding wildcard in
\emph{principal}.

\item[{\emph{restrictions}}] \leavevmode
(Optional) A string of flags. Allowed restrictions are:
\begin{quote}
\begin{description}
\item[{\{+\textbar{}-\}\emph{flagname}}] \leavevmode
flag is forced to the indicated value.  The permissible flags
are the same as those for the \textbf{default\_principal\_flags}
variable in {\hyperref[admin/conf_files/kdc_conf:kdc-conf-5]{\emph{kdc.conf}}}.

\item[{\emph{-clearpolicy}}] \leavevmode
policy is forced to be empty.

\item[{\emph{-policy pol}}] \leavevmode
policy is forced to be \emph{pol}.

\item[{-\{\emph{expire, pwexpire, maxlife, maxrenewlife}\} \emph{time}}] \leavevmode
(\emph{getdate} string) associated value will be forced to
MIN(\emph{time}, requested value).

\end{description}
\end{quote}

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

\end{description}

\begin{notice}{warning}{Warning:}
If the kadmind ACL file is modified, the kadmind daemon needs to be
restarted for changes to take effect.
\end{notice}


\subsubsection{EXAMPLE}
\label{admin/conf_files/kadm5_acl:example}
Here is an example of a kadm5.acl file:

\begin{Verbatim}[commandchars=\\\{\}]
*/admin@ATHENA.MIT.EDU    *                               \PYGZsh{} line 1
joeadmin@ATHENA.MIT.EDU   ADMCIL                          \PYGZsh{} line 2
joeadmin/*@ATHENA.MIT.EDU i   */root@ATHENA.MIT.EDU       \PYGZsh{} line 3
*/root@ATHENA.MIT.EDU     ci  *1@ATHENA.MIT.EDU           \PYGZsh{} line 4
*/root@ATHENA.MIT.EDU     l   *                           \PYGZsh{} line 5
sms@ATHENA.MIT.EDU        x   * \PYGZhy{}maxlife 9h \PYGZhy{}postdateable \PYGZsh{} line 6
\end{Verbatim}

(line 1) Any principal in the \code{ATHENA.MIT.EDU} realm with
an \code{admin} instance has all administrative privileges.

(lines 1-3) The user \code{joeadmin} has all permissions with his
\code{admin} instance, \code{joeadmin/admin@ATHENA.MIT.EDU} (matches line
1).  He has no permissions at all with his null instance,
\code{joeadmin@ATHENA.MIT.EDU} (matches line 2).  His \code{root} and other
non-\code{admin}, non-null instances (e.g., \code{extra} or \code{dbadmin}) have
inquire permissions with any principal that has the instance \code{root}
(matches line 3).

(line 4) Any \code{root} principal in \code{ATHENA.MIT.EDU} can inquire
or change the password of their null instance, but not any other
null instance.  (Here, \code{*1} denotes a back-reference to the
component matching the first wildcard in the actor principal.)

(line 5) Any \code{root} principal in \code{ATHENA.MIT.EDU} can generate
the list of principals in the database, and the list of policies
in the database.  This line is separate from line 4, because list
permission can only be granted globally, not to specific target
principals.

(line 6) Finally, the Service Management System principal
\code{sms@ATHENA.MIT.EDU} has all permissions, but any principal that it
creates or modifies will not be able to get postdateable tickets or
tickets with a life of longer than 9 hours.


\subsubsection{SEE ALSO}
\label{admin/conf_files/kadm5_acl:see-also}
{\hyperref[admin/conf_files/kdc_conf:kdc-conf-5]{\emph{kdc.conf}}}, {\hyperref[admin/admin_commands/kadmind:kadmind-8]{\emph{kadmind}}}


\chapter{Realm configuration decisions}
\label{admin/realm_config:realm-configuration-decisions}\label{admin/realm_config::doc}
Before installing Kerberos V5, it is necessary to consider the
following issues:
\begin{itemize}
\item {} 
The name of your Kerberos realm (or the name of each realm, if you
need more than one).

\item {} 
How you will assign your hostnames to Kerberos realms.

\item {} 
Which ports your KDC and and kadmind services will use, if they will
not be using the default ports.

\item {} 
How many slave KDCs you need and where they should be located.

\item {} 
The hostnames of your master and slave KDCs.

\item {} 
How frequently you will propagate the database from the master KDC
to the slave KDCs.

\end{itemize}


\section{Realm name}
\label{admin/realm_config:realm-name}
Although your Kerberos realm can be any ASCII string, convention is to
make it the same as your domain name, in upper-case letters.

For example, hosts in the domain \code{example.com} would be in the
Kerberos realm:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n}{EXAMPLE}\PYG{o}{.}\PYG{n}{COM}
\end{Verbatim}

If you need multiple Kerberos realms, MIT recommends that you use
descriptive names which end with your domain name, such as:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n}{BOSTON}\PYG{o}{.}\PYG{n}{EXAMPLE}\PYG{o}{.}\PYG{n}{COM}
\PYG{n}{HOUSTON}\PYG{o}{.}\PYG{n}{EXAMPLE}\PYG{o}{.}\PYG{n}{COM}
\end{Verbatim}


\section{Mapping hostnames onto Kerberos realms}
\label{admin/realm_config:mapping-hostnames-onto-kerberos-realms}\label{admin/realm_config:mapping-hostnames}
Mapping hostnames onto Kerberos realms is done in one of three ways.

The first mechanism works through a set of rules in the
{\hyperref[admin/conf_files/krb5_conf:domain-realm]{\emph{{[}domain\_realm{]}}}} section of {\hyperref[admin/conf_files/krb5_conf:krb5-conf-5]{\emph{krb5.conf}}}.  You can specify
mappings for an entire domain or on a per-hostname basis.  Typically
you would do this by specifying the mappings for a given domain or
subdomain and listing the exceptions.

The second mechanism is to use KDC host-based service referrals.  With
this method, the KDC's krb5.conf has a full {[}domain\_realm{]} mapping for
hosts, but the clients do not, or have mappings for only a subset of
the hosts they might contact.  When a client needs to contact a server
host for which it has no mapping, it will ask the client realm's KDC
for the service ticket, and will receive a referral to the appropriate
service realm.

To use referrals, clients must be running MIT krb5 1.6 or later, and
the KDC must be running MIT krb5 1.7 or later.  The
\textbf{host\_based\_services} and \textbf{no\_host\_referral} variables in the
{\hyperref[admin/conf_files/kdc_conf:kdc-realms]{\emph{{[}realms{]}}}} section of {\hyperref[admin/conf_files/kdc_conf:kdc-conf-5]{\emph{kdc.conf}}} can be used to
fine-tune referral behavior on the KDC.

It is also possible for clients to use DNS TXT records, if
\textbf{dns\_lookup\_realm} is enabled in {\hyperref[admin/conf_files/krb5_conf:krb5-conf-5]{\emph{krb5.conf}}}.  Such lookups
are disabled by default because DNS is an insecure protocol and security
holes could result if DNS records are spoofed.  If enabled, the client
will try to look up a TXT record formed by prepending the prefix
\code{\_kerberos} to the hostname in question.  If that record is not
found, the client will attempt a lookup by prepending \code{\_kerberos} to the
host's domain name, then its parent domain, up to the top-level domain.
For the hostname \code{boston.engineering.example.com}, the names looked up
would be:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n}{\PYGZus{}kerberos}\PYG{o}{.}\PYG{n}{boston}\PYG{o}{.}\PYG{n}{engineering}\PYG{o}{.}\PYG{n}{example}\PYG{o}{.}\PYG{n}{com}
\PYG{n}{\PYGZus{}kerberos}\PYG{o}{.}\PYG{n}{engineering}\PYG{o}{.}\PYG{n}{example}\PYG{o}{.}\PYG{n}{com}
\PYG{n}{\PYGZus{}kerberos}\PYG{o}{.}\PYG{n}{example}\PYG{o}{.}\PYG{n}{com}
\PYG{n}{\PYGZus{}kerberos}\PYG{o}{.}\PYG{n}{com}
\end{Verbatim}

The value of the first TXT record found is taken as the realm name.

Even if you do not choose to use this mechanism within your site,
you may wish to set it up anyway, for use when interacting with other sites.


\section{Ports for the KDC and admin services}
\label{admin/realm_config:ports-for-the-kdc-and-admin-services}
The default ports used by Kerberos are port 88 for the KDC and port
749 for the admin server.  You can, however, choose to run on other
ports, as long as they are specified in each host's
{\hyperref[admin/conf_files/krb5_conf:krb5-conf-5]{\emph{krb5.conf}}} files or in DNS SRV records, and the
{\hyperref[admin/conf_files/kdc_conf:kdc-conf-5]{\emph{kdc.conf}}} file on each KDC.  For a more thorough treatment of
port numbers used by the Kerberos V5 programs, refer to the
{\hyperref[admin/appl_servers:conf-firewall]{\emph{Configuring your firewall to work with Kerberos V5}}}.


\section{Slave KDCs}
\label{admin/realm_config:slave-kdcs}
Slave KDCs provide an additional source of Kerberos ticket-granting
services in the event of inaccessibility of the master KDC.  The
number of slave KDCs you need and the decision of where to place them,
both physically and logically, depends on the specifics of your
network.

Kerberos authentication requires that each client be able to contact a
KDC.  Therefore, you need to anticipate any likely reason a KDC might
be unavailable and have a slave KDC to take up the slack.

Some considerations include:
\begin{itemize}
\item {} 
Have at least one slave KDC as a backup, for when the master KDC is
down, is being upgraded, or is otherwise unavailable.

\item {} 
If your network is split such that a network outage is likely to
cause a network partition (some segment or segments of the network
to become cut off or isolated from other segments), have a slave KDC
accessible to each segment.

\item {} 
If possible, have at least one slave KDC in a different building
from the master, in case of power outages, fires, or other localized
disasters.

\end{itemize}


\section{Hostnames for KDCs}
\label{admin/realm_config:kdc-hostnames}\label{admin/realm_config:hostnames-for-kdcs}
MIT recommends that your KDCs have a predefined set of CNAME records
(DNS hostname aliases), such as \code{kerberos} for the master KDC and
\code{kerberos-1}, \code{kerberos-2}, ... for the slave KDCs.  This way, if
you need to swap a machine, you only need to change a DNS entry,
rather than having to change hostnames.

As of MIT krb5 1.4, clients can locate a realm's KDCs through DNS
using SRV records (\index{RFC!RFC 2782}\href{http://tools.ietf.org/html/rfc2782.html}{\textbf{RFC 2782}}), assuming the Kerberos realm name is
also a DNS domain name.  These records indicate the hostname and port
number to contact for that service, optionally with weighting and
prioritization.  The domain name used in the SRV record name is the
realm name.  Several different Kerberos-related service names are
used:
\begin{description}
\item[{\_kerberos.\_udp}] \leavevmode
This is for contacting any KDC by UDP.  This entry will be used
the most often.  Normally you should list port 88 on each of your
KDCs.

\item[{\_kerberos.\_tcp}] \leavevmode
This is for contacting any KDC by TCP.  The MIT KDC by default
will not listen on any TCP ports, so unless you've changed the
configuration or you're running another KDC implementation, you
should leave this unspecified.  If you do enable TCP support,
normally you should use port 88.

\item[{\_kerberos-master.\_udp}] \leavevmode
This entry should refer to those KDCs, if any, that will
immediately see password changes to the Kerberos database.  If a
user is logging in and the password appears to be incorrect, the
client will retry with the master KDC before failing with an
``incorrect password'' error given.

If you have only one KDC, or for whatever reason there is no
accessible KDC that would get database changes faster than the
others, you do not need to define this entry.

\item[{\_kerberos-adm.\_tcp}] \leavevmode
This should list port 749 on your master KDC.  Support for it is
not complete at this time, but it will eventually be used by the
{\hyperref[admin/admin_commands/kadmin_local:kadmin-1]{\emph{kadmin}}} program and related utilities.  For now, you will
also need the \textbf{admin\_server} variable in {\hyperref[admin/conf_files/krb5_conf:krb5-conf-5]{\emph{krb5.conf}}}.

\item[{\_kpasswd.\_udp}] \leavevmode
This should list port 464 on your master KDC.  It is used when a
user changes her password.  If this entry is not defined but a
\_kerberos-adm.\_tcp entry is defined, the client will use the
\_kerberos-adm.\_tcp entry with the port number changed to 749.

\end{description}

The DNS SRV specification requires that the hostnames listed be the
canonical names, not aliases.  So, for example, you might include the
following records in your (BIND-style) zone file:

\begin{Verbatim}[commandchars=\\\{\}]
\PYGZdl{}ORIGIN foobar.com.
\PYGZus{}kerberos               TXT       \PYGZdq{}FOOBAR.COM\PYGZdq{}
kerberos                CNAME     daisy
kerberos\PYGZhy{}1              CNAME     use\PYGZhy{}the\PYGZhy{}force\PYGZhy{}luke
kerberos\PYGZhy{}2              CNAME     bunny\PYGZhy{}rabbit
\PYGZus{}kerberos.\PYGZus{}udp          SRV       0 0 88 daisy
                        SRV       0 0 88 use\PYGZhy{}the\PYGZhy{}force\PYGZhy{}luke
                        SRV       0 0 88 bunny\PYGZhy{}rabbit
\PYGZus{}kerberos\PYGZhy{}master.\PYGZus{}udp   SRV       0 0 88 daisy
\PYGZus{}kerberos\PYGZhy{}adm.\PYGZus{}tcp      SRV       0 0 749 daisy
\PYGZus{}kpasswd.\PYGZus{}udp           SRV       0 0 464 daisy
\end{Verbatim}

Clients can also be configured with the explicit location of services
using the \textbf{kdc}, \textbf{master\_kdc}, \textbf{admin\_server}, and
\textbf{kpasswd\_server} variables in the {\hyperref[admin/conf_files/krb5_conf:realms]{\emph{{[}realms{]}}}} section of
{\hyperref[admin/conf_files/krb5_conf:krb5-conf-5]{\emph{krb5.conf}}}.  Even if some clients will be configured with
explicit server locations, providing SRV records will still benefit
unconfigured clients, and be useful for other sites.


\section{KDC Discovery}
\label{admin/realm_config:kdc-discovery}\label{admin/realm_config:id1}
As of MIT krb5 1.15, clients can also locate KDCs in DNS through URI
records (\index{RFC!RFC 7553}\href{http://tools.ietf.org/html/rfc7553.html}{\textbf{RFC 7553}}).  Limitations with the SRV record format may
result in extra DNS queries in situations where a client must failover
to other transport types, or find a master server.  The URI record can
convey more information about a realm's KDCs with a single query.

The client performs a query for the following URI records:
\begin{itemize}
\item {} 
\code{\_kerberos.REALM} for fiding KDCs.

\item {} 
\code{\_kerberos-adm.REALM} for finding kadmin services.

\item {} 
\code{\_kpasswd.REALM} for finding password services.

\end{itemize}

The URI record includes a priority, weight, and a URI string that
consists of case-insensitive colon separated fields, in the form
\code{scheme:{[}flags{]}:transport:residual}.
\begin{itemize}
\item {} 
\emph{scheme} defines the registered URI type.  It should always be
\code{krb5srv}.

\item {} 
\emph{flags} contains zero or more flag characters.  Currently the only
valid flag is \code{m}, which indicates that the record is for a master
server.

\item {} 
\emph{transport} defines the transport type of the residual URL or
address.  Accepted values are \code{tcp}, \code{udp}, or \code{kkdcp} for the
MS-KKDCP type.

\item {} 
\emph{residual} contains the hostname, IP address, or URL to be
contacted using the specified transport, with an optional port
extension.  The MS-KKDCP transport type uses a HTTPS URL, and can
include a port and/or path extension.

\end{itemize}

An example of URI records in a zone file:

\begin{Verbatim}[commandchars=\\\{\}]
\PYGZus{}kerberos.EXAMPLE.COM  URI  10 1 krb5srv:m:tcp:kdc1.example.com
                       URI  20 1 krb5srv:m:udp:kdc2.example.com:89
                       URI  40 1 krb5srv::udp:10.10.0.23
                       URI  30 1 krb5srv::kkdcp:https://proxy:89/auth
\end{Verbatim}

URI lookups are enabled by default, and can be disabled by setting
\textbf{dns\_uri\_lookup} in the {\hyperref[admin/conf_files/krb5_conf:libdefaults]{\emph{{[}libdefaults{]}}}} section of
{\hyperref[admin/conf_files/krb5_conf:krb5-conf-5]{\emph{krb5.conf}}} to False.  When enabled, URI lookups take
precedence over SRV lookups, falling back to SRV lookups if no URI
records are found.


\section{Database propagation}
\label{admin/realm_config:database-propagation}\label{admin/realm_config:db-prop}
The Kerberos database resides on the master KDC, and must be
propagated regularly (usually by a cron job) to the slave KDCs.  In
deciding how frequently the propagation should happen, you will need
to balance the amount of time the propagation takes against the
maximum reasonable amount of time a user should have to wait for a
password change to take effect.

If the propagation time is longer than this maximum reasonable time
(e.g., you have a particularly large database, you have a lot of
slaves, or you experience frequent network delays), you may wish to
cut down on your propagation delay by performing the propagation in
parallel.  To do this, have the master KDC propagate the database to
one set of slaves, and then have each of these slaves propagate the
database to additional slaves.

See also {\hyperref[admin/database:incr-db-prop]{\emph{Incremental database propagation}}}


\chapter{Database administration}
\label{admin/database::doc}\label{admin/database:database-administration}
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 {\hyperref[admin/admin_commands/kdb5_util:kdb5-util-8]{\emph{kdb5\_util}}}
program to manipulate the Kerberos database as a whole, and the
{\hyperref[admin/admin_commands/kadmin_local:kadmin-1]{\emph{kadmin}}} program to make changes to the entries in the
database.  (One notable exception is that users will use the
\emph{kpasswd(1)} program to change their own passwords.)  The kadmin
program has its own command-line interface, to which you type the
database administrating commands.

{\hyperref[admin/admin_commands/kdb5_util:kdb5-util-8]{\emph{kdb5\_util}}} 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
{\hyperref[admin/admin_commands/kadmind:kadmind-8]{\emph{kadmind}}} and {\hyperref[admin/admin_commands/krb5kdc:krb5kdc-8]{\emph{krb5kdc}}} daemons can use the database
without manual input.

{\hyperref[admin/admin_commands/kadmin_local:kadmin-1]{\emph{kadmin}}} 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 {\hyperref[admin/admin_commands/kadmind:kadmind-8]{\emph{kadmind}}}, 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.

kadmin can authenticate to the admin server using the service
principal \code{kadmin/HOST} (where \emph{HOST} is the hostname of the admin
server) or \code{kadmin/admin}.  If the credentials cache contains a
ticket for either service principal and the \textbf{-c} ccache option is
specified, that ticket is used to authenticate to KADM5.  Otherwise,
the \textbf{-p} and \textbf{-k} options are used to specify the client Kerberos
principal name used to authenticate.  Once kadmin has determined the
principal name, it requests a \code{kadmin/admin} Kerberos service ticket
from the KDC, and uses that service ticket to authenticate to KADM5.

See {\hyperref[admin/admin_commands/kadmin_local:kadmin-1]{\emph{kadmin}}} for the available kadmin and kadmin.local
commands and options.


\section{kadmin options}
\label{admin/database:kadmin-options}
You can invoke {\hyperref[admin/admin_commands/kadmin_local:kadmin-1]{\emph{kadmin}}} or kadmin.local with any of the
following options:

\textbf{kadmin}
{[}\textbf{-O}\textbar{}\textbf{-N}{]}
{[}\textbf{-r} \emph{realm}{]}
{[}\textbf{-p} \emph{principal}{]}
{[}\textbf{-q} \emph{query}{]}
{[}{[}\textbf{-c} \emph{cache\_name}{]}\textbar{}{[}\textbf{-k} {[}\textbf{-t} \emph{keytab}{]}{]}\textbar{}\textbf{-n}{]}
{[}\textbf{-w} \emph{password}{]}
{[}\textbf{-s} \emph{admin\_server}{[}:\emph{port}{]}{]}
{[}command args...{]}

\textbf{kadmin.local}
{[}\textbf{-r} \emph{realm}{]}
{[}\textbf{-p} \emph{principal}{]}
{[}\textbf{-q} \emph{query}{]}
{[}\textbf{-d} \emph{dbname}{]}
{[}\textbf{-e} \emph{enc}:\emph{salt} ...{]}
{[}\textbf{-m}{]}
{[}\textbf{-x} \emph{db\_args}{]}
{[}command args...{]}

\textbf{OPTIONS}
\begin{description}
\item[{\textbf{-r} \emph{realm}}] \leavevmode
Use \emph{realm} as the default database realm.

\item[{\textbf{-p} \emph{principal}}] \leavevmode
Use \emph{principal} to authenticate.  Otherwise, kadmin will append
\code{/admin} to the primary principal name of the default ccache,
the value of the \textbf{USER} environment variable, or the username as
obtained with getpwuid, in order of preference.

\item[{\textbf{-k}}] \leavevmode
Use a keytab to decrypt the KDC response instead of prompting for
a password.  In this case, the default principal will be
\code{host/hostname}.  If there is no keytab specified with the
\textbf{-t} option, then the default keytab will be used.

\item[{\textbf{-t} \emph{keytab}}] \leavevmode
Use \emph{keytab} to decrypt the KDC response.  This can only be used
with the \textbf{-k} option.

\item[{\textbf{-n}}] \leavevmode
Requests anonymous processing.  Two types of anonymous principals
are supported.  For fully anonymous Kerberos, configure PKINIT on
the KDC and configure \textbf{pkinit\_anchors} in the client's
{\hyperref[admin/conf_files/krb5_conf:krb5-conf-5]{\emph{krb5.conf}}}.  Then use the \textbf{-n} option with a principal
of the form \code{@REALM} (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{kinit
-n} 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.

\item[{\textbf{-c} \emph{credentials\_cache}}] \leavevmode
Use \emph{credentials\_cache} as the credentials cache.  The
cache should contain a service ticket for the \code{kadmin/ADMINHOST}
(where \emph{ADMINHOST} is the fully-qualified hostname of the admin
server) or \code{kadmin/admin} service; it can be acquired with the
\emph{kinit(1)} program.  If this option is not specified, kadmin
requests a new service ticket from the KDC, and stores it in its
own temporary ccache.

\item[{\textbf{-w} \emph{password}}] \leavevmode
Use \emph{password} 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.

\item[{\textbf{-q} \emph{query}}] \leavevmode
Perform the specified query and then exit.

\item[{\textbf{-d} \emph{dbname}}] \leavevmode
Specifies the name of the KDC database.  This option does not
apply to the LDAP database module.

\item[{\textbf{-s} \emph{admin\_server}{[}:\emph{port}{]}}] \leavevmode
Specifies the admin server which kadmin should contact.

\item[{\textbf{-m}}] \leavevmode
If using kadmin.local, prompt for the database master password
instead of reading it from a stash file.

\item[{\textbf{-e} ``\emph{enc}:\emph{salt} ...''}] \leavevmode
Sets the keysalt list to be used for any new keys created.  See
{\hyperref[admin/conf_files/kdc_conf:keysalt-lists]{\emph{Keysalt lists}}} in {\hyperref[admin/conf_files/kdc_conf:kdc-conf-5]{\emph{kdc.conf}}} for a list of possible
values.

\item[{\textbf{-O}}] \leavevmode
Force use of old AUTH\_GSSAPI authentication flavor.

\item[{\textbf{-N}}] \leavevmode
Prevent fallback to AUTH\_GSSAPI authentication flavor.

\item[{\textbf{-x} \emph{db\_args}}] \leavevmode
Specifies the database specific arguments.  See the next section
for supported options.

\end{description}


\section{Date Format}
\label{admin/database:date-format}
For the supported date-time formats see \emph{getdate} section
in \emph{datetime}.


\section{Principals}
\label{admin/database:principals}
Each entry in the Kerberos database contains a Kerberos principal and
the attributes and policies associated with that principal.


\subsection{Adding, modifying and deleting principals}
\label{admin/database:add-mod-del-princs}\label{admin/database:adding-modifying-and-deleting-principals}
To add a principal to the database, use the {\hyperref[admin/admin_commands/kadmin_local:kadmin-1]{\emph{kadmin}}}
\textbf{add\_principal} command.

To modify attributes of a principal, use the kadmin
\textbf{modify\_principal} command.

To delete a principal, use the kadmin \textbf{delete\_principal} command.


\subsection{add\_principal}
\label{admin/database:add-principal}\begin{quote}

\textbf{add\_principal} {[}\emph{options}{]} \emph{newprinc}
\end{quote}

Creates the principal \emph{newprinc}, prompting twice for a password.  If
no password policy is specified with the \textbf{-policy} option, and the
policy named \code{default} is assigned to the principal if it exists.
However, creating a policy named \code{default} will not automatically
assign this policy to previously existing principals.  This policy
assignment can be suppressed with the \textbf{-clearpolicy} option.

This command requires the \textbf{add} privilege.

Aliases: \textbf{addprinc}, \textbf{ank}

Options:
\begin{description}
\item[{\textbf{-expire} \emph{expdate}}] \leavevmode
(\emph{getdate} string) The expiration date of the principal.

\item[{\textbf{-pwexpire} \emph{pwexpdate}}] \leavevmode
(\emph{getdate} string) The password expiration date.

\item[{\textbf{-maxlife} \emph{maxlife}}] \leavevmode
(\emph{duration} or \emph{getdate} string) The maximum ticket life
for the principal.

\item[{\textbf{-maxrenewlife} \emph{maxrenewlife}}] \leavevmode
(\emph{duration} or \emph{getdate} string) The maximum renewable
life of tickets for the principal.

\item[{\textbf{-kvno} \emph{kvno}}] \leavevmode
The initial key version number.

\item[{\textbf{-policy} \emph{policy}}] \leavevmode
The password policy used by this principal.  If not specified, the
policy \code{default} is used if it exists (unless \textbf{-clearpolicy}
is specified).

\item[{\textbf{-clearpolicy}}] \leavevmode
Prevents any policy from being assigned when \textbf{-policy} is not
specified.

\item[{\{-\textbar{}+\}\textbf{allow\_postdated}}] \leavevmode
\textbf{-allow\_postdated} prohibits this principal from obtaining
postdated tickets.  \textbf{+allow\_postdated} clears this flag.

\item[{\{-\textbar{}+\}\textbf{allow\_forwardable}}] \leavevmode
\textbf{-allow\_forwardable} prohibits this principal from obtaining
forwardable tickets.  \textbf{+allow\_forwardable} clears this flag.

\item[{\{-\textbar{}+\}\textbf{allow\_renewable}}] \leavevmode
\textbf{-allow\_renewable} prohibits this principal from obtaining
renewable tickets.  \textbf{+allow\_renewable} clears this flag.

\item[{\{-\textbar{}+\}\textbf{allow\_proxiable}}] \leavevmode
\textbf{-allow\_proxiable} prohibits this principal from obtaining
proxiable tickets.  \textbf{+allow\_proxiable} clears this flag.

\item[{\{-\textbar{}+\}\textbf{allow\_dup\_skey}}] \leavevmode
\textbf{-allow\_dup\_skey} disables user-to-user authentication for this
principal by prohibiting this principal from obtaining a session
key for another user.  \textbf{+allow\_dup\_skey} clears this flag.

\item[{\{-\textbar{}+\}\textbf{requires\_preauth}}] \leavevmode
\textbf{+requires\_preauth} requires this principal to preauthenticate
before being allowed to kinit.  \textbf{-requires\_preauth} clears this
flag.  When \textbf{+requires\_preauth} 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.

\item[{\{-\textbar{}+\}\textbf{requires\_hwauth}}] \leavevmode
\textbf{+requires\_hwauth} requires this principal to preauthenticate
using a hardware device before being allowed to kinit.
\textbf{-requires\_hwauth} clears this flag.  When \textbf{+requires\_hwauth} 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.

\item[{\{-\textbar{}+\}\textbf{ok\_as\_delegate}}] \leavevmode
\textbf{+ok\_as\_delegate} sets the \textbf{okay as delegate} 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.  \textbf{-ok\_as\_delegate} clears this
flag.

\item[{\{-\textbar{}+\}\textbf{allow\_svr}}] \leavevmode
\textbf{-allow\_svr} prohibits the issuance of service tickets for this
principal.  \textbf{+allow\_svr} clears this flag.

\item[{\{-\textbar{}+\}\textbf{allow\_tgs\_req}}] \leavevmode
\textbf{-allow\_tgs\_req} specifies that a Ticket-Granting Service (TGS)
request for a service ticket for this principal is not permitted.
\textbf{+allow\_tgs\_req} clears this flag.

\item[{\{-\textbar{}+\}\textbf{allow\_tix}}] \leavevmode
\textbf{-allow\_tix} forbids the issuance of any tickets for this
principal.  \textbf{+allow\_tix} clears this flag.

\item[{\{-\textbar{}+\}\textbf{needchange}}] \leavevmode
\textbf{+needchange} forces a password change on the next initial
authentication to this principal.  \textbf{-needchange} clears this
flag.

\item[{\{-\textbar{}+\}\textbf{password\_changing\_service}}] \leavevmode
\textbf{+password\_changing\_service} marks this principal as a password
change service principal.

\item[{\{-\textbar{}+\}\textbf{ok\_to\_auth\_as\_delegate}}] \leavevmode
\textbf{+ok\_to\_auth\_as\_delegate} allows this principal to acquire
forwardable tickets to itself from arbitrary users, for use with
constrained delegation.

\item[{\{-\textbar{}+\}\textbf{no\_auth\_data\_required}}] \leavevmode
\textbf{+no\_auth\_data\_required} prevents PAC or AD-SIGNEDPATH data from
being added to service tickets for the principal.

\item[{\{-\textbar{}+\}\textbf{lockdown\_keys}}] \leavevmode
\textbf{+lockdown\_keys} 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.

\item[{\textbf{-randkey}}] \leavevmode
Sets the key of the principal to a random value.

\item[{\textbf{-nokey}}] \leavevmode
Causes the principal to be created with no key.  New in release
1.12.

\item[{\textbf{-pw} \emph{password}}] \leavevmode
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.

\item[{\textbf{-e} \emph{enc}:\emph{salt},...}] \leavevmode
Uses the specified keysalt list for setting the keys of the
principal.  See {\hyperref[admin/conf_files/kdc_conf:keysalt-lists]{\emph{Keysalt lists}}} in {\hyperref[admin/conf_files/kdc_conf:kdc-conf-5]{\emph{kdc.conf}}} for a
list of possible values.

\item[{\textbf{-x} \emph{db\_princ\_args}}] \leavevmode
Indicates database-specific options.  The options for the LDAP
database module are:
\begin{description}
\item[{\textbf{-x dn=}\emph{dn}}] \leavevmode
Specifies the LDAP object that will contain the Kerberos
principal being created.

\item[{\textbf{-x linkdn=}\emph{dn}}] \leavevmode
Specifies the LDAP object to which the newly created Kerberos
principal object will point.

\item[{\textbf{-x containerdn=}\emph{container\_dn}}] \leavevmode
Specifies the container object under which the Kerberos
principal is to be created.

\item[{\textbf{-x tktpolicy=}\emph{policy}}] \leavevmode
Associates a ticket policy to the Kerberos principal.

\end{description}

\begin{notice}{note}{Note:}\begin{itemize}
\item {} 
The \textbf{containerdn} and \textbf{linkdn} options cannot be
specified with the \textbf{dn} option.

\item {} 
If the \emph{dn} or \emph{containerdn} options are not specified while
adding the principal, the principals are created under the
principal container configured in the realm or the realm
container.

\item {} 
\emph{dn} and \emph{containerdn} should be within the subtrees or
principal container configured in the realm.

\end{itemize}
\end{notice}

\end{description}

Example:

\begin{Verbatim}[commandchars=\\\{\}]
kadmin: addprinc jennifer
WARNING: no policy specified for \PYGZdq{}jennifer@ATHENA.MIT.EDU\PYGZdq{};
defaulting to no policy.
Enter password for principal jennifer@ATHENA.MIT.EDU:
Re\PYGZhy{}enter password for principal jennifer@ATHENA.MIT.EDU:
Principal \PYGZdq{}jennifer@ATHENA.MIT.EDU\PYGZdq{} created.
kadmin:
\end{Verbatim}


\subsection{modify\_principal}
\label{admin/database:modify-principal}\begin{quote}

\textbf{modify\_principal} {[}\emph{options}{]} \emph{principal}
\end{quote}

Modifies the specified principal, changing the fields as specified.
The options to \textbf{add\_principal} also apply to this command, except
for the \textbf{-randkey}, \textbf{-pw}, and \textbf{-e} options.  In addition, the
option \textbf{-clearpolicy} will clear the current policy of a principal.

This command requires the \emph{modify} privilege.

Alias: \textbf{modprinc}

Options (in addition to the \textbf{addprinc} options):
\begin{description}
\item[{\textbf{-unlock}}] \leavevmode
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.

\end{description}


\subsection{delete\_principal}
\label{admin/database:delete-principal}\begin{quote}

\textbf{delete\_principal} {[}\textbf{-force}{]} \emph{principal}
\end{quote}

Deletes the specified \emph{principal} from the database.  This command
prompts for deletion, unless the \textbf{-force} option is given.

This command requires the \textbf{delete} privilege.

Alias: \textbf{delprinc}


\subsubsection{Examples}
\label{admin/database:examples}
If you want to create a principal which is contained by a LDAP object,
all you need to do is:

\begin{Verbatim}[commandchars=\\\{\}]
kadmin: addprinc \PYGZhy{}x dn=cn=jennifer,dc=example,dc=com jennifer
WARNING: no policy specified for \PYGZdq{}jennifer@ATHENA.MIT.EDU\PYGZdq{};
defaulting to no policy.
Enter password for principal jennifer@ATHENA.MIT.EDU:  \PYGZlt{}= Type the password.
Re\PYGZhy{}enter password for principal jennifer@ATHENA.MIT.EDU:  \PYGZlt{}=Type it again.
Principal \PYGZdq{}jennifer@ATHENA.MIT.EDU\PYGZdq{} created.
kadmin:
\end{Verbatim}

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:

\begin{Verbatim}[commandchars=\\\{\}]
kadmin: addprinc \PYGZhy{}x containerdn=dc=example,dc=com \PYGZhy{}x linkdn=cn=david,dc=example,dc=com david
WARNING: no policy specified for \PYGZdq{}david@ATHENA.MIT.EDU\PYGZdq{};
defaulting to no policy.
Enter password for principal david@ATHENA.MIT.EDU:  \PYGZlt{}= Type the password.
Re\PYGZhy{}enter password for principal david@ATHENA.MIT.EDU:  \PYGZlt{}=Type it again.
Principal \PYGZdq{}david@ATHENA.MIT.EDU\PYGZdq{} created.
kadmin:
\end{Verbatim}

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

\begin{Verbatim}[commandchars=\\\{\}]
kadmin: modprinc \PYGZhy{}x tktpolicy=userpolicy david
Principal \PYGZdq{}david@ATHENA.MIT.EDU\PYGZdq{} modified.
kadmin:
\end{Verbatim}

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:

\begin{Verbatim}[commandchars=\\\{\}]
kadmin: addprinc david \PYGZhy{}expire \PYGZdq{}1/1/2000 12:01am EST\PYGZdq{} \PYGZhy{}policy stduser +needchange
Enter password for principal david@ATHENA.MIT.EDU:  \PYGZlt{}= Type the password.
Re\PYGZhy{}enter password for principal
david@ATHENA.MIT.EDU:  \PYGZlt{}= Type it again.
Principal \PYGZdq{}david@ATHENA.MIT.EDU\PYGZdq{} created.
kadmin:
\end{Verbatim}

If you want to delete a principal:

\begin{Verbatim}[commandchars=\\\{\}]
kadmin: delprinc jennifer
Are you sure you want to delete the principal
\PYGZdq{}jennifer@ATHENA.MIT.EDU\PYGZdq{}? (yes/no): yes
Principal \PYGZdq{}jennifer@ATHENA.MIT.EDU\PYGZdq{} deleted.
Make sure that you have removed this principal from
all ACLs before reusing.
kadmin:
\end{Verbatim}


\subsection{Retrieving information about a principal}
\label{admin/database:retrieving-information-about-a-principal}
To retrieve a listing of the attributes and/or policies associated
with a principal, use the {\hyperref[admin/admin_commands/kadmin_local:kadmin-1]{\emph{kadmin}}} \textbf{get\_principal} command.

To generate a listing of principals, use the kadmin
\textbf{list\_principals} command.


\subsection{get\_principal}
\label{admin/database:get-principal}\begin{quote}

\textbf{get\_principal} {[}\textbf{-terse}{]} \emph{principal}
\end{quote}

Gets the attributes of principal.  With the \textbf{-terse} option, outputs
fields as quoted tab-separated strings.

This command requires the \textbf{inquire} privilege, or that the principal
running the the program to be the same as the one being listed.

Alias: \textbf{getprinc}

Examples:

\begin{Verbatim}[commandchars=\\\{\}]
kadmin: getprinc tlyu/admin
Principal: tlyu/admin@BLEEP.COM
Expiration date: [never]
Last password change: Mon Aug 12 14:16:47 EDT 1996
Password expiration date: [none]
Maximum ticket life: 0 days 10:00:00
Maximum renewable life: 7 days 00:00:00
Last modified: Mon Aug 12 14:16:47 EDT 1996 (bjaspan/admin@BLEEP.COM)
Last successful authentication: [never]
Last failed authentication: [never]
Failed password attempts: 0
Number of keys: 2
Key: vno 1, des\PYGZhy{}cbc\PYGZhy{}crc
Key: vno 1, des\PYGZhy{}cbc\PYGZhy{}crc:v4
Attributes:
Policy: [none]

kadmin: getprinc \PYGZhy{}terse systest
systest@BLEEP.COM   3    86400     604800    1
785926535 753241234 785900000
tlyu/admin@BLEEP.COM     786100034 0    0
kadmin:
\end{Verbatim}


\subsection{list\_principals}
\label{admin/database:list-principals}\begin{quote}

\textbf{list\_principals} {[}\emph{expression}{]}
\end{quote}

Retrieves all or some principal names.  \emph{expression} is a shell-style
glob expression that can contain the wild-card characters \code{?},
\code{*}, and \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{@} character, an
\code{@} character followed by the local realm is appended to the
expression.

This command requires the \textbf{list} privilege.

Alias: \textbf{listprincs}, \textbf{get\_principals}, \textbf{get\_princs}

Example:

\begin{Verbatim}[commandchars=\\\{\}]
kadmin:  listprincs test*
test3@SECURE\PYGZhy{}TEST.OV.COM
test2@SECURE\PYGZhy{}TEST.OV.COM
test1@SECURE\PYGZhy{}TEST.OV.COM
testuser@SECURE\PYGZhy{}TEST.OV.COM
kadmin:
\end{Verbatim}


\subsection{Changing passwords}
\label{admin/database:changing-passwords}
To change a principal's password use the {\hyperref[admin/admin_commands/kadmin_local:kadmin-1]{\emph{kadmin}}}
\textbf{change\_password} command.


\subsection{change\_password}
\label{admin/database:change-password}\begin{quote}

\textbf{change\_password} {[}\emph{options}{]} \emph{principal}
\end{quote}

Changes the password of \emph{principal}.  Prompts for a new password if
neither \textbf{-randkey} or \textbf{-pw} is specified.

This command requires the \textbf{changepw} privilege, or that the
principal running the program is the same as the principal being
changed.

Alias: \textbf{cpw}

The following options are available:
\begin{description}
\item[{\textbf{-randkey}}] \leavevmode
Sets the key of the principal to a random value.

\item[{\textbf{-pw} \emph{password}}] \leavevmode
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.

\item[{\textbf{-e} \emph{enc}:\emph{salt},...}] \leavevmode
Uses the specified keysalt list for setting the keys of the
principal.  See {\hyperref[admin/conf_files/kdc_conf:keysalt-lists]{\emph{Keysalt lists}}} in {\hyperref[admin/conf_files/kdc_conf:kdc-conf-5]{\emph{kdc.conf}}} for a
list of possible values.

\item[{\textbf{-keepold}}] \leavevmode
Keeps the existing keys in the database.  This flag is usually not
necessary except perhaps for \code{krbtgt} principals.

\end{description}

Example:

\begin{Verbatim}[commandchars=\\\{\}]
kadmin: cpw systest
Enter password for principal systest@BLEEP.COM:
Re\PYGZhy{}enter password for principal systest@BLEEP.COM:
Password for systest@BLEEP.COM changed.
kadmin:
\end{Verbatim}

\begin{notice}{note}{Note:}
Password changes through kadmin are subject to the same
password policies as would apply to password changes through
\emph{kpasswd(1)}.
\end{notice}


\section{Policies}
\label{admin/database:policies}\label{admin/database:id1}
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.


\subsection{Adding, modifying and deleting policies}
\label{admin/database:adding-modifying-and-deleting-policies}
To add a new policy, use the {\hyperref[admin/admin_commands/kadmin_local:kadmin-1]{\emph{kadmin}}} \textbf{add\_policy} command.

To modify attributes of a principal, use the kadmin \textbf{modify\_policy}
command.

To delete a policy, use the kadmin \textbf{delete\_policy} command.


\subsection{add\_policy}
\label{admin/database:add-policy}\begin{quote}

\textbf{add\_policy} {[}\emph{options}{]} \emph{policy}
\end{quote}

Adds a password policy named \emph{policy} to the database.

This command requires the \textbf{add} privilege.

Alias: \textbf{addpol}

The following options are available:
\begin{description}
\item[{\textbf{-maxlife} \emph{time}}] \leavevmode
(\emph{duration} or \emph{getdate} string) Sets the maximum
lifetime of a password.

\item[{\textbf{-minlife} \emph{time}}] \leavevmode
(\emph{duration} or \emph{getdate} string) Sets the minimum
lifetime of a password.

\item[{\textbf{-minlength} \emph{length}}] \leavevmode
Sets the minimum length of a password.

\item[{\textbf{-minclasses} \emph{number}}] \leavevmode
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.

\item[{\textbf{-history} \emph{number}}] \leavevmode
Sets the number of past keys kept for a principal.  This option is
not supported with the LDAP KDC database module.

\end{description}
\phantomsection\label{admin/database:policy-maxfailure}\begin{description}
\item[{\textbf{-maxfailure} \emph{maxnumber}}] \leavevmode
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
\emph{maxnumber} value of 0 (the default) disables lockout.

\end{description}
\phantomsection\label{admin/database:policy-failurecountinterval}\begin{description}
\item[{\textbf{-failurecountinterval} \emph{failuretime}}] \leavevmode
(\emph{duration} or \emph{getdate} string) Sets the allowable time
between authentication failures.  If an authentication failure
happens after \emph{failuretime} has elapsed since the previous
failure, the number of authentication failures is reset to 1.  A
\emph{failuretime} value of 0 (the default) means forever.

\end{description}
\phantomsection\label{admin/database:policy-lockoutduration}\begin{description}
\item[{\textbf{-lockoutduration} \emph{lockouttime}}] \leavevmode
(\emph{duration} or \emph{getdate} 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{modprinc -unlock}.

\item[{\textbf{-allowedkeysalts}}] \leavevmode
Specifies the key/salt tuples supported for long-term keys when
setting or changing a principal's password/keys.  See
{\hyperref[admin/conf_files/kdc_conf:keysalt-lists]{\emph{Keysalt lists}}} in {\hyperref[admin/conf_files/kdc_conf:kdc-conf-5]{\emph{kdc.conf}}} 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 `-`.

\end{description}

Example:

\begin{Verbatim}[commandchars=\\\{\}]
kadmin: add\PYGZus{}policy \PYGZhy{}maxlife \PYGZdq{}2 days\PYGZdq{} \PYGZhy{}minlength 5 guests
kadmin:
\end{Verbatim}


\subsection{modify\_policy}
\label{admin/database:modify-policy}\begin{quote}

\textbf{modify\_policy} {[}\emph{options}{]} \emph{policy}
\end{quote}

Modifies the password policy named \emph{policy}.  Options are as described
for \textbf{add\_policy}.

This command requires the \textbf{modify} privilege.

Alias: \textbf{modpol}


\subsection{delete\_policy}
\label{admin/database:delete-policy}\begin{quote}

\textbf{delete\_policy} {[}\textbf{-force}{]} \emph{policy}
\end{quote}

Deletes the password policy named \emph{policy}.  Prompts for confirmation
before deletion.  The command will fail if the policy is in use by any
principals.

This command requires the \textbf{delete} privilege.

Alias: \textbf{delpol}

Example:

\begin{Verbatim}[commandchars=\\\{\}]
kadmin: del\PYGZus{}policy guests
Are you sure you want to delete the policy \PYGZdq{}guests\PYGZdq{}?
(yes/no): yes
kadmin:
\end{Verbatim}

\begin{notice}{note}{Note:}
You must cancel the policy from \emph{all} principals before
deleting it.  The \emph{delete\_policy} command will fail if the policy
is in use by any principals.
\end{notice}


\subsection{Retrieving policies}
\label{admin/database:retrieving-policies}
To retrieve a policy, use the {\hyperref[admin/admin_commands/kadmin_local:kadmin-1]{\emph{kadmin}}} \textbf{get\_policy} command.

You can retrieve the list of policies with the kadmin
\textbf{list\_policies} command.


\subsection{get\_policy}
\label{admin/database:get-policy}\begin{quote}

\textbf{get\_policy} {[} \textbf{-terse} {]} \emph{policy}
\end{quote}

Displays the values of the password policy named \emph{policy}.  With the
\textbf{-terse} flag, outputs the fields as quoted strings separated by
tabs.

This command requires the \textbf{inquire} privilege.

Alias: getpol

Examples:

\begin{Verbatim}[commandchars=\\\{\}]
kadmin: get\PYGZus{}policy admin
Policy: admin
Maximum password life: 180 days 00:00:00
Minimum password life: 00:00:00
Minimum password length: 6
Minimum number of password character classes: 2
Number of old keys kept: 5
Reference count: 17

kadmin: get\PYGZus{}policy \PYGZhy{}terse admin
admin     15552000  0    6    2    5    17
kadmin:
\end{Verbatim}

The ``Reference count'' is the number of principals using that policy.
With the LDAP KDC database module, the reference count field is not
meaningful.


\subsection{list\_policies}
\label{admin/database:list-policies}\begin{quote}

\textbf{list\_policies} {[}\emph{expression}{]}
\end{quote}

Retrieves all or some policy names.  \emph{expression} is a shell-style
glob expression that can contain the wild-card characters \code{?},
\code{*}, and \code{{[}{]}}.  All policy names matching the expression are
printed.  If no expression is provided, all existing policy names are
printed.

This command requires the \textbf{list} privilege.

Aliases: \textbf{listpols}, \textbf{get\_policies}, \textbf{getpols}.

Examples:

\begin{Verbatim}[commandchars=\\\{\}]
kadmin:  listpols
test\PYGZhy{}pol
dict\PYGZhy{}only
once\PYGZhy{}a\PYGZhy{}min
test\PYGZhy{}pol\PYGZhy{}nopw

kadmin:  listpols t*
test\PYGZhy{}pol
test\PYGZhy{}pol\PYGZhy{}nopw
kadmin:
\end{Verbatim}


\subsection{Policies and principals}
\label{admin/database:policies-and-principals}
Policies can be applied to principals as they are created by using
the \textbf{-policy} flag to {\hyperref[admin/admin_commands/kadmin_local:add-principal]{\emph{add\_principal}}}. Existing principals can
be modified by using the \textbf{-policy} or \textbf{-clearpolicy} flag to
{\hyperref[admin/admin_commands/kadmin_local:modify-principal]{\emph{modify\_principal}}}.


\subsection{Updating the history key}
\label{admin/database:updating-the-history-key}
If a policy specifies a number of old keys kept of two or more, the
stored old keys are encrypted in a history key, which is found in the
key data of the \code{kadmin/history} principal.

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

\begin{Verbatim}[commandchars=\\\{\}]
kadmin: change\PYGZus{}password \PYGZhy{}randkey kadmin/history
\end{Verbatim}

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

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


\section{Privileges}
\label{admin/database:privileges}\label{admin/database:id2}
Administrative privileges for the Kerberos database are stored in the
file {\hyperref[admin/conf_files/kadm5_acl:kadm5-acl-5]{\emph{kadm5.acl}}}.

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


\section{Operations on the Kerberos database}
\label{admin/database:db-operations}\label{admin/database:operations-on-the-kerberos-database}
The {\hyperref[admin/admin_commands/kdb5_util:kdb5-util-8]{\emph{kdb5\_util}}} command is the primary tool for administrating
the Kerberos database.

\textbf{kdb5\_util}
{[}\textbf{-r} \emph{realm}{]}
{[}\textbf{-d} \emph{dbname}{]}
{[}\textbf{-k} \emph{mkeytype}{]}
{[}\textbf{-M} \emph{mkeyname}{]}
{[}\textbf{-kv} \emph{mkeyVNO}{]}
{[}\textbf{-sf} \emph{stashfilename}{]}
{[}\textbf{-m}{]}
\emph{command} {[}\emph{command\_options}{]}

\textbf{OPTIONS}
\begin{description}
\item[{\textbf{-r} \emph{realm}}] \leavevmode
specifies the Kerberos realm of the database.

\item[{\textbf{-d} \emph{dbname}}] \leavevmode
specifies the name under which the principal database is stored;
by default the database is that listed in {\hyperref[admin/conf_files/kdc_conf:kdc-conf-5]{\emph{kdc.conf}}}.  The
password policy database and lock files are also derived from this
value.

\item[{\textbf{-k} \emph{mkeytype}}] \leavevmode
specifies the key type of the master key in the database.  The
default is given by the \textbf{master\_key\_type} variable in
{\hyperref[admin/conf_files/kdc_conf:kdc-conf-5]{\emph{kdc.conf}}}.

\item[{\textbf{-kv} \emph{mkeyVNO}}] \leavevmode
Specifies the version number of the master key in the database;
the default is 1.  Note that 0 is not allowed.

\item[{\textbf{-M} \emph{mkeyname}}] \leavevmode
principal name for the master key in the database.  If not
specified, the name is determined by the \textbf{master\_key\_name}
variable in {\hyperref[admin/conf_files/kdc_conf:kdc-conf-5]{\emph{kdc.conf}}}.

\item[{\textbf{-m}}] \leavevmode
specifies that the master database password should be read from
the keyboard rather than fetched from a file on disk.

\item[{\textbf{-sf} \emph{stash\_file}}] \leavevmode
specifies the stash filename of the master database password.  If
not specified, the filename is determined by the
\textbf{key\_stash\_file} variable in {\hyperref[admin/conf_files/kdc_conf:kdc-conf-5]{\emph{kdc.conf}}}.

\item[{\textbf{-P} \emph{password}}] \leavevmode
specifies the master database password.  Using this option may
expose the password to other users on the system via the process
list.

\end{description}


\subsection{Dumping a Kerberos database to a file}
\label{admin/database:dumping-a-kerberos-database-to-a-file}
To dump a Kerberos database into a file, use the {\hyperref[admin/admin_commands/kdb5_util:kdb5-util-8]{\emph{kdb5\_util}}}
\textbf{dump} command on one of the KDCs.
\begin{quote}

\textbf{dump} {[}\textbf{-b7}\textbar{}\textbf{-ov}\textbar{}\textbf{-r13}{]} {[}\textbf{-verbose}{]}
{[}\textbf{-mkey\_convert}{]} {[}\textbf{-new\_mkey\_file} \emph{mkey\_file}{]} {[}\textbf{-rev}{]}
{[}\textbf{-recurse}{]} {[}\emph{filename} {[}\emph{principals}...{]}{]}
\end{quote}

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:
\begin{description}
\item[{\textbf{-b7}}] \leavevmode
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.

\item[{\textbf{-ov}}] \leavevmode
causes the dump to be in ``ovsec\_adm\_export'' format.

\item[{\textbf{-r13}}] \leavevmode
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.

\item[{\textbf{-r18}}] \leavevmode
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.

\item[{\textbf{-verbose}}] \leavevmode
causes the name of each principal and policy to be printed as it
is dumped.

\item[{\textbf{-mkey\_convert}}] \leavevmode
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.

\item[{\textbf{-new\_mkey\_file} \emph{mkey\_file}}] \leavevmode
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.

\item[{\textbf{-rev}}] \leavevmode
dumps in reverse order.  This may recover principals that do not
dump normally, in cases where database corruption has occurred.

\item[{\textbf{-recurse}}] \leavevmode
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 \textbf{-rev} option will.

\DUspan{versionmodified}{Changed in version 1.15: }Release 1.15 restored the functionality of the \textbf{-recurse}
option.

\DUspan{versionmodified}{Changed in version 1.5: }The \textbf{-recurse} option ceased working until release 1.15,
doing a normal dump instead of a recursive traversal.

\end{description}


\subsubsection{Examples}
\label{admin/database:id3}
\begin{Verbatim}[commandchars=\\\{\}]
shell\PYGZpc{} kdb5\PYGZus{}util dump dumpfile
shell\PYGZpc{}

shell\PYGZpc{} kbd5\PYGZus{}util dump \PYGZhy{}verbose dumpfile
kadmin/admin@ATHENA.MIT.EDU
krbtgt/ATHENA.MIT.EDU@ATHENA.MIT.EDU
kadmin/history@ATHENA.MIT.EDU
K/M@ATHENA.MIT.EDU
kadmin/changepw@ATHENA.MIT.EDU
shell\PYGZpc{}
\end{Verbatim}

If you specify which principals to dump, you must use the full
principal, as in the following example:

\begin{Verbatim}[commandchars=\\\{\}]
shell\PYGZpc{} kdb5\PYGZus{}util dump \PYGZhy{}verbose dumpfile K/M@ATHENA.MIT.EDU kadmin/admin@ATHENA.MIT.EDU
kadmin/admin@ATHENA.MIT.EDU
K/M@ATHENA.MIT.EDU
shell\PYGZpc{}
\end{Verbatim}

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

\begin{Verbatim}[commandchars=\\\{\}]
shell\PYGZpc{} kdb5\PYGZus{}util dump \PYGZhy{}verbose dumpfile K/M kadmin/admin
shell\PYGZpc{}
\end{Verbatim}

If you do not specify a dump file, kdb5\_util will dump the database to
the standard output.


\subsection{Restoring a Kerberos database from a dump file}
\label{admin/database:restore-from-dump}\label{admin/database:restoring-a-kerberos-database-from-a-dump-file}
To restore a Kerberos database dump from a file, use the
{\hyperref[admin/admin_commands/kdb5_util:kdb5-util-8]{\emph{kdb5\_util}}} \textbf{load} command on one of the KDCs.
\begin{quote}

\textbf{load} {[}\textbf{-b7}\textbar{}\textbf{-ov}\textbar{}\textbf{-r13}{]} {[}\textbf{-hash}{]}
{[}\textbf{-verbose}{]} {[}\textbf{-update}{]} \emph{filename} {[}\emph{dbname}{]}
\end{quote}

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 \textbf{-update} option is given, \textbf{load} 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 \textbf{-update} flag is required.

Options:
\begin{description}
\item[{\textbf{-b7}}] \leavevmode
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.

\item[{\textbf{-ov}}] \leavevmode
requires the database to be in ``ovsec\_adm\_import'' format.  Must be
used with the \textbf{-update} option.

\item[{\textbf{-r13}}] \leavevmode
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.

\item[{\textbf{-r18}}] \leavevmode
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.

\item[{\textbf{-hash}}] \leavevmode
requires the database to be stored as a hash.  If this option is
not specified, the database will be stored as a btree.  This
option is not recommended, as databases stored in hash format are
known to corrupt data and lose principals.

\item[{\textbf{-verbose}}] \leavevmode
causes the name of each principal and policy to be printed as it
is dumped.

\item[{\textbf{-update}}] \leavevmode
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.

\end{description}

If specified, \emph{dbname} overrides the value specified on the command
line or the default.


\subsubsection{Examples}
\label{admin/database:id4}
To load a single principal, either replacing or updating the database:

\begin{Verbatim}[commandchars=\\\{\}]
shell\PYGZpc{} kdb5\PYGZus{}util load dumpfile principal
shell\PYGZpc{}

shell\PYGZpc{} kdb5\PYGZus{}util load \PYGZhy{}update dumpfile principal
shell\PYGZpc{}
\end{Verbatim}

\begin{notice}{note}{Note:}
If the database file exists, and the \emph{-update} flag was not
given, \emph{kdb5\_util} will overwrite the existing database.
\end{notice}

Using kdb5\_util to upgrade a master KDC from krb5 1.1.x:

\begin{Verbatim}[commandchars=\\\{\}]
shell\PYGZpc{} kdb5\PYGZus{}util dump old\PYGZhy{}kdb\PYGZhy{}dump
shell\PYGZpc{} kdb5\PYGZus{}util dump \PYGZhy{}ov old\PYGZhy{}kdb\PYGZhy{}dump.ov
  [Create a new KDC installation, using the old stash file/master password]
shell\PYGZpc{} kdb5\PYGZus{}util load old\PYGZhy{}kdb\PYGZhy{}dump
shell\PYGZpc{} kdb5\PYGZus{}util load \PYGZhy{}update old\PYGZhy{}kdb\PYGZhy{}dump.ov
\end{Verbatim}

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.

\begin{notice}{note}{Note:}
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.
\end{notice}


\subsection{Creating a stash file}
\label{admin/database:create-stash}\label{admin/database:creating-a-stash-file}
A stash file allows a KDC to authenticate itself to the database
utilities, such as {\hyperref[admin/admin_commands/kadmind:kadmind-8]{\emph{kadmind}}}, {\hyperref[admin/admin_commands/krb5kdc:krb5kdc-8]{\emph{krb5kdc}}}, and
{\hyperref[admin/admin_commands/kdb5_util:kdb5-util-8]{\emph{kdb5\_util}}}.

To create a stash file, use the {\hyperref[admin/admin_commands/kdb5_util:kdb5-util-8]{\emph{kdb5\_util}}} \textbf{stash} command.
\begin{quote}

\textbf{stash} {[}\textbf{-f} \emph{keyfile}{]}
\end{quote}

Stores the master principal's keys in a stash file.  The \textbf{-f}
argument can be used to override the \emph{keyfile} specified in
{\hyperref[admin/conf_files/kdc_conf:kdc-conf-5]{\emph{kdc.conf}}}.


\subsubsection{Example}
\label{admin/database:example}\begin{quote}

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:  \textless{}= Type the KDC database master password.
shell\%
\end{quote}

If you do not specify a stash file, kdb5\_util will stash the key in
the file specified in your {\hyperref[admin/conf_files/kdc_conf:kdc-conf-5]{\emph{kdc.conf}}} file.


\subsection{Creating and destroying a Kerberos database}
\label{admin/database:creating-and-destroying-a-kerberos-database}
If you need to create a new Kerberos database, use the
{\hyperref[admin/admin_commands/kdb5_util:kdb5-util-8]{\emph{kdb5\_util}}} \textbf{create} command.
\begin{quote}

\textbf{create} {[}\textbf{-s}{]}
\end{quote}

Creates a new database.  If the \textbf{-s} 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.

If you need to destroy the current Kerberos database, use the
{\hyperref[admin/admin_commands/kdb5_util:kdb5-util-8]{\emph{kdb5\_util}}} \textbf{destroy} command.
\begin{quote}

\textbf{destroy} {[}\textbf{-f}{]}
\end{quote}

Destroys the database, first overwriting the disk sectors and then
unlinking the files, after prompting the user for confirmation.  With
the \textbf{-f} argument, does not prompt the user.


\subsubsection{Examples}
\label{admin/database:id5}
\begin{Verbatim}[commandchars=\\\{\}]
shell\PYGZpc{} kdb5\PYGZus{}util \PYGZhy{}r ATHENA.MIT.EDU create \PYGZhy{}s
Loading random data
Initializing database \PYGZsq{}/usr/local/var/krb5kdc/principal\PYGZsq{} for realm \PYGZsq{}ATHENA.MIT.EDU\PYGZsq{},
master key name \PYGZsq{}K/M@ATHENA.MIT.EDU\PYGZsq{}
You will be prompted for the database Master Password.
It is important that you NOT FORGET this password.
Enter KDC database master key:  \PYGZlt{}= Type the master password.
Re\PYGZhy{}enter KDC database master key to verify:  \PYGZlt{}= Type it again.
shell\PYGZpc{}

shell\PYGZpc{} kdb5\PYGZus{}util \PYGZhy{}r ATHENA.MIT.EDU destroy
Deleting KDC database stored in \PYGZsq{}/usr/local/var/krb5kdc/principal\PYGZsq{}, are you sure?
(type \PYGZsq{}yes\PYGZsq{} to confirm)?  \PYGZlt{}= yes
OK, deleting database \PYGZsq{}/usr/local/var/krb5kdc/principal\PYGZsq{}...
** Database \PYGZsq{}/usr/local/var/krb5kdc/principal\PYGZsq{} destroyed.
shell\PYGZpc{}
\end{Verbatim}


\subsection{Updating the master key}
\label{admin/database:updating-the-master-key}
Starting with release 1.7, {\hyperref[admin/admin_commands/kdb5_util:kdb5-util-8]{\emph{kdb5\_util}}} 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:
\begin{enumerate}
\item {} 
On the master KDC, run \code{kdb5\_util list\_mkeys} 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:

\begin{Verbatim}[commandchars=\\\{\}]
\PYGZdl{} kdb5\PYGZus{}util list\PYGZus{}mkeys
Master keys for Principal: K/M@KRBTEST.COM
KVNO: 1, Enctype: des\PYGZhy{}cbc\PYGZhy{}crc, Active on: Wed Dec 31 19:00:00 EST 1969 *
\end{Verbatim}

\item {} 
On the master KDC, run \code{kdb5\_util use\_mkey 1} 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.

\item {} 
On the master KDC, run \code{kdb5\_util add\_mkey -s} 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.

\item {} 
Propagate the database to all slave KDCs, either manually or by
waiting until the next scheduled propagation.  If you do not have
any slave KDCs, you can skip this and the next step.

\item {} 
On each slave KDC, run \code{kdb5\_util list\_mkeys} to verify that the
new master key is present, and then \code{kdb5\_util stash} to write
the new master key to the slave KDC's stash file.

\item {} 
On the master KDC, run \code{kdb5\_util use\_mkey 2} to begin using the
new master key.  Replace \code{2} 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, {\hyperref[admin/admin_commands/kadmind:kadmind-8]{\emph{kadmind}}} must be
restarted for this change to take full effect.

\item {} 
On the master KDC, run \code{kdb5\_util update\_princ\_encryption}.  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 slave KDCs (if any are present) during
this time period.  In release 1.13 and later, you can instead run
\code{kdb5\_util -x unlockiter update\_princ\_encryption} to use unlocked
iteration; this variant will take longer, but will keep the
database available to the KDC and kadmind while it runs.

\item {} 
On the master KDC, run \code{kdb5\_util purge\_mkeys} to clean up the
old master key.

\end{enumerate}


\section{Operations on the LDAP database}
\label{admin/database:operations-on-the-ldap-database}\label{admin/database:ops-on-ldap}
The {\hyperref[admin/admin_commands/kdb5_ldap_util:kdb5-ldap-util-8]{\emph{kdb5\_ldap\_util}}} is the primary tool for administrating
the Kerberos LDAP database.  It allows an administrator to manage
realms, Kerberos services (KDC and Admin Server) and ticket policies.

\textbf{kdb5\_ldap\_util}
{[}\textbf{-D} \emph{user\_dn} {[}\textbf{-w} \emph{passwd}{]}{]}
{[}\textbf{-H} \emph{ldapuri}{]}
\textbf{command}
{[}\emph{command\_options}{]}

\textbf{OPTIONS}
\begin{description}
\item[{\textbf{-D} \emph{user\_dn}}] \leavevmode
Specifies the Distinguished Name (DN) of the user who has
sufficient rights to perform the operation on the LDAP server.

\item[{\textbf{-w} \emph{passwd}}] \leavevmode
Specifies the password of \emph{user\_dn}.  This option is not
recommended.

\item[{\textbf{-H} \emph{ldapuri}}] \leavevmode
Specifies the URI of the LDAP server.  It is recommended to use
\code{ldapi://} or \code{ldaps://} to connect to the LDAP server.

\end{description}


\subsection{Creating a Kerberos realm}
\label{admin/database:creating-a-kerberos-realm}\label{admin/database:ldap-create-realm}
If you need to create a new realm, use the {\hyperref[admin/admin_commands/kdb5_ldap_util:kdb5-ldap-util-8]{\emph{kdb5\_ldap\_util}}}
\textbf{create} command as follows.
\begin{quote}

\textbf{create}
{[}\textbf{-subtrees} \emph{subtree\_dn\_list}{]}
{[}\textbf{-sscope} \emph{search\_scope}{]}
{[}\textbf{-containerref} \emph{container\_reference\_dn}{]}
{[}\textbf{-k} \emph{mkeytype}{]}
{[}\textbf{-kv} \emph{mkeyVNO}{]}
{[}\textbf{-m\textbar{}-P} \emph{password}\textbar{}\textbf{-sf} \emph{stashfilename}{]}
{[}\textbf{-s}{]}
{[}\textbf{-r} \emph{realm}{]}
{[}\textbf{-maxtktlife} \emph{max\_ticket\_life}{]}
{[}\textbf{-maxrenewlife} \emph{max\_renewable\_ticket\_life}{]}
{[}\emph{ticket\_flags}{]}
\end{quote}

Creates realm in directory. Options:
\begin{description}
\item[{\textbf{-subtrees} \emph{subtree\_dn\_list}}] \leavevmode
Specifies the list of subtrees containing the principals of a
realm.  The list contains the DNs of the subtree objects separated
by colon (\code{:}).

\item[{\textbf{-sscope} \emph{search\_scope}}] \leavevmode
Specifies the scope for searching the principals under the
subtree.  The possible values are 1 or one (one level), 2 or sub
(subtrees).

\item[{\textbf{-containerref} \emph{container\_reference\_dn}}] \leavevmode
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.

\item[{\textbf{-k} \emph{mkeytype}}] \leavevmode
Specifies the key type of the master key in the database.  The
default is given by the \textbf{master\_key\_type} variable in
{\hyperref[admin/conf_files/kdc_conf:kdc-conf-5]{\emph{kdc.conf}}}.

\item[{\textbf{-kv} \emph{mkeyVNO}}] \leavevmode
Specifies the version number of the master key in the database;
the default is 1.  Note that 0 is not allowed.

\item[{\textbf{-m}}] \leavevmode
Specifies that the master database password should be read from
the TTY rather than fetched from a file on the disk.

\item[{\textbf{-P} \emph{password}}] \leavevmode
Specifies the master database password. This option is not
recommended.

\item[{\textbf{-r} \emph{realm}}] \leavevmode
Specifies the Kerberos realm of the database.

\item[{\textbf{-sf} \emph{stashfilename}}] \leavevmode
Specifies the stash file of the master database password.

\item[{\textbf{-s}}] \leavevmode
Specifies that the stash file is to be created.

\item[{\textbf{-maxtktlife} \emph{max\_ticket\_life}}] \leavevmode
(\emph{getdate} string) Specifies maximum ticket life for
principals in this realm.

\item[{\textbf{-maxrenewlife} \emph{max\_renewable\_ticket\_life}}] \leavevmode
(\emph{getdate} string) Specifies maximum renewable life of
tickets for principals in this realm.

\item[{\emph{ticket\_flags}}] \leavevmode
Specifies global ticket flags for the realm.  Allowable flags are
documented in the description of the \textbf{add\_principal} command in
{\hyperref[admin/admin_commands/kadmin_local:kadmin-1]{\emph{kadmin}}}.

\end{description}

Example:

\begin{Verbatim}[commandchars=\\\{\}]
kdb5\PYGZus{}ldap\PYGZus{}util \PYGZhy{}D cn=admin,o=org \PYGZhy{}H ldaps://ldap\PYGZhy{}server1.mit.edu
    create \PYGZhy{}subtrees o=org \PYGZhy{}sscope SUB \PYGZhy{}r ATHENA.MIT.EDU
Password for \PYGZdq{}cn=admin,o=org\PYGZdq{}:
Initializing database for realm \PYGZsq{}ATHENA.MIT.EDU\PYGZsq{}
You will be prompted for the database Master Password.
It is important that you NOT FORGET this password.
Enter KDC database master key:
Re\PYGZhy{}enter KDC database master key to verify:
\end{Verbatim}


\subsection{Modifying a Kerberos realm}
\label{admin/database:ldap-mod-realm}\label{admin/database:modifying-a-kerberos-realm}
If you need to modify a realm, use the {\hyperref[admin/admin_commands/kdb5_ldap_util:kdb5-ldap-util-8]{\emph{kdb5\_ldap\_util}}}
\textbf{modify} command as follows.
\begin{quote}

\textbf{modify}
{[}\textbf{-subtrees} \emph{subtree\_dn\_list}{]}
{[}\textbf{-sscope} \emph{search\_scope}{]}
{[}\textbf{-containerref} \emph{container\_reference\_dn}{]}
{[}\textbf{-r} \emph{realm}{]}
{[}\textbf{-maxtktlife} \emph{max\_ticket\_life}{]}
{[}\textbf{-maxrenewlife} \emph{max\_renewable\_ticket\_life}{]}
{[}\emph{ticket\_flags}{]}
\end{quote}

Modifies the attributes of a realm.  Options:
\begin{description}
\item[{\textbf{-subtrees} \emph{subtree\_dn\_list}}] \leavevmode
Specifies the list of subtrees containing the principals of a
realm.  The list contains the DNs of the subtree objects separated
by colon (\code{:}).  This list replaces the existing list.

\item[{\textbf{-sscope} \emph{search\_scope}}] \leavevmode
Specifies the scope for searching the principals under the
subtrees.  The possible values are 1 or one (one level), 2 or sub
(subtrees).

\item[{\textbf{-containerref} \emph{container\_reference\_dn} Specifies the DN of the}] \leavevmode
container object in which the principals of a realm will be
created.

\item[{\textbf{-r} \emph{realm}}] \leavevmode
Specifies the Kerberos realm of the database.

\item[{\textbf{-maxtktlife} \emph{max\_ticket\_life}}] \leavevmode
(\emph{getdate} string) Specifies maximum ticket life for
principals in this realm.

\item[{\textbf{-maxrenewlife} \emph{max\_renewable\_ticket\_life}}] \leavevmode
(\emph{getdate} string) Specifies maximum renewable life of
tickets for principals in this realm.

\item[{\emph{ticket\_flags}}] \leavevmode
Specifies global ticket flags for the realm.  Allowable flags are
documented in the description of the \textbf{add\_principal} command in
{\hyperref[admin/admin_commands/kadmin_local:kadmin-1]{\emph{kadmin}}}.

\end{description}

Example:

\begin{Verbatim}[commandchars=\\\{\}]
shell\PYGZpc{} kdb5\PYGZus{}ldap\PYGZus{}util \PYGZhy{}D cn=admin,o=org \PYGZhy{}H
    ldaps://ldap\PYGZhy{}server1.mit.edu modify +requires\PYGZus{}preauth \PYGZhy{}r
    ATHENA.MIT.EDU
Password for \PYGZdq{}cn=admin,o=org\PYGZdq{}:
shell\PYGZpc{}
\end{Verbatim}


\subsection{Destroying a Kerberos realm}
\label{admin/database:destroying-a-kerberos-realm}
If you need to destroy a Kerberos realm, use the
{\hyperref[admin/admin_commands/kdb5_ldap_util:kdb5-ldap-util-8]{\emph{kdb5\_ldap\_util}}} \textbf{destroy} command as follows.
\begin{quote}

\textbf{destroy} {[}\textbf{-f}{]} {[}\textbf{-r} \emph{realm}{]}
\end{quote}

Destroys an existing realm. Options:
\begin{description}
\item[{\textbf{-f}}] \leavevmode
If specified, will not prompt the user for confirmation.

\item[{\textbf{-r} \emph{realm}}] \leavevmode
Specifies the Kerberos realm of the database.

\end{description}

Example:

\begin{Verbatim}[commandchars=\\\{\}]
shell\PYGZpc{} kdb5\PYGZus{}ldap\PYGZus{}util \PYGZhy{}D cn=admin,o=org \PYGZhy{}H
    ldaps://ldap\PYGZhy{}server1.mit.edu destroy \PYGZhy{}r ATHENA.MIT.EDU
Password for \PYGZdq{}cn=admin,o=org\PYGZdq{}:
Deleting KDC database of \PYGZsq{}ATHENA.MIT.EDU\PYGZsq{}, are you sure?
(type \PYGZsq{}yes\PYGZsq{} to confirm)? yes
OK, deleting database of \PYGZsq{}ATHENA.MIT.EDU\PYGZsq{}...
shell\PYGZpc{}
\end{Verbatim}


\subsection{Retrieving information about a Kerberos realm}
\label{admin/database:retrieving-information-about-a-kerberos-realm}
If you need to display the attributes of a realm, use the
{\hyperref[admin/admin_commands/kdb5_ldap_util:kdb5-ldap-util-8]{\emph{kdb5\_ldap\_util}}} \textbf{view} command as follows.
\begin{quote}

\textbf{view} {[}\textbf{-r} \emph{realm}{]}
\end{quote}

Displays the attributes of a realm.  Options:
\begin{description}
\item[{\textbf{-r} \emph{realm}}] \leavevmode
Specifies the Kerberos realm of the database.

\end{description}

Example:

\begin{Verbatim}[commandchars=\\\{\}]
kdb5\PYGZus{}ldap\PYGZus{}util \PYGZhy{}D cn=admin,o=org \PYGZhy{}H ldaps://ldap\PYGZhy{}server1.mit.edu
    view \PYGZhy{}r ATHENA.MIT.EDU
Password for \PYGZdq{}cn=admin,o=org\PYGZdq{}:
Realm Name: ATHENA.MIT.EDU
Subtree: ou=users,o=org
Subtree: ou=servers,o=org
SearchScope: ONE
Maximum ticket life: 0 days 01:00:00
Maximum renewable life: 0 days 10:00:00
Ticket flags: DISALLOW\PYGZus{}FORWARDABLE REQUIRES\PYGZus{}PWCHANGE
\end{Verbatim}


\subsection{Listing available Kerberos realms}
\label{admin/database:listing-available-kerberos-realms}
If you need to display the list of the realms, use the
{\hyperref[admin/admin_commands/kdb5_ldap_util:kdb5-ldap-util-8]{\emph{kdb5\_ldap\_util}}} \textbf{list} command as follows.
\begin{quote}

\textbf{list}
\end{quote}

Lists the name of realms.

Example:

\begin{Verbatim}[commandchars=\\\{\}]
shell\PYGZpc{} kdb5\PYGZus{}ldap\PYGZus{}util \PYGZhy{}D cn=admin,o=org \PYGZhy{}H
    ldaps://ldap\PYGZhy{}server1.mit.edu list
Password for \PYGZdq{}cn=admin,o=org\PYGZdq{}:
ATHENA.MIT.EDU
OPENLDAP.MIT.EDU
MEDIA\PYGZhy{}LAB.MIT.EDU
shell\PYGZpc{}
\end{Verbatim}


\subsection{Stashing service object's password}
\label{admin/database:stashing-service-object-s-password}\label{admin/database:stash-ldap}
The {\hyperref[admin/admin_commands/kdb5_ldap_util:kdb5-ldap-util-8]{\emph{kdb5\_ldap\_util}}} \textbf{stashsrvpw} 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.
\begin{quote}

\textbf{stashsrvpw}
{[}\textbf{-f} \emph{filename}{]}
\emph{name}
\end{quote}

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:
\begin{description}
\item[{\textbf{-f} \emph{filename}}] \leavevmode
Specifies the complete path of the service password file. By
default, \code{/usr/local/var/service\_passwd} is used.

\item[{\emph{name}}] \leavevmode
Specifies the name of the object whose password is to be stored.
If {\hyperref[admin/admin_commands/krb5kdc:krb5kdc-8]{\emph{krb5kdc}}} or {\hyperref[admin/admin_commands/kadmind:kadmind-8]{\emph{kadmind}}} are configured for
simple binding, this should be the distinguished name it will
use as given by the \textbf{ldap\_kdc\_dn} or \textbf{ldap\_kadmind\_dn}
variable in {\hyperref[admin/conf_files/kdc_conf:kdc-conf-5]{\emph{kdc.conf}}}.  If the KDC or kadmind is
configured for SASL binding, this should be the authentication
name it will use as given by the \textbf{ldap\_kdc\_sasl\_authcid} or
\textbf{ldap\_kadmind\_sasl\_authcid} variable.

\end{description}

Example:

\begin{Verbatim}[commandchars=\\\{\}]
kdb5\PYGZus{}ldap\PYGZus{}util stashsrvpw \PYGZhy{}f /home/andrew/conf\PYGZus{}keyfile
    cn=service\PYGZhy{}kdc,o=org
Password for \PYGZdq{}cn=service\PYGZhy{}kdc,o=org\PYGZdq{}:
Re\PYGZhy{}enter password for \PYGZdq{}cn=service\PYGZhy{}kdc,o=org\PYGZdq{}:
\end{Verbatim}


\subsection{Ticket Policy operations}
\label{admin/database:ticket-policy-operations}

\subsubsection{Creating a Ticket Policy}
\label{admin/database:creating-a-ticket-policy}
To create a new ticket policy in directory , use the
{\hyperref[admin/admin_commands/kdb5_ldap_util:kdb5-ldap-util-8]{\emph{kdb5\_ldap\_util}}} \textbf{create\_policy} command.  Ticket policy
objects are created under the realm container.
\begin{quote}

\textbf{create\_policy}
{[}\textbf{-r} \emph{realm}{]}
{[}\textbf{-maxtktlife} \emph{max\_ticket\_life}{]}
{[}\textbf{-maxrenewlife} \emph{max\_renewable\_ticket\_life}{]}
{[}\emph{ticket\_flags}{]}
\emph{policy\_name}
\end{quote}

Creates a ticket policy in the directory.  Options:
\begin{description}
\item[{\textbf{-r} \emph{realm}}] \leavevmode
Specifies the Kerberos realm of the database.

\item[{\textbf{-maxtktlife} \emph{max\_ticket\_life}}] \leavevmode
(\emph{getdate} string) Specifies maximum ticket life for
principals.

\item[{\textbf{-maxrenewlife} \emph{max\_renewable\_ticket\_life}}] \leavevmode
(\emph{getdate} string) Specifies maximum renewable life of
tickets for principals.

\item[{\emph{ticket\_flags}}] \leavevmode
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 \textbf{add\_principal}
command in {\hyperref[admin/admin_commands/kadmin_local:kadmin-1]{\emph{kadmin}}}.

\item[{\emph{policy\_name}}] \leavevmode
Specifies the name of the ticket policy.

\end{description}

Example:

\begin{Verbatim}[commandchars=\\\{\}]
kdb5\PYGZus{}ldap\PYGZus{}util \PYGZhy{}D cn=admin,o=org \PYGZhy{}H ldaps://ldap\PYGZhy{}server1.mit.edu
    create\PYGZus{}policy \PYGZhy{}r ATHENA.MIT.EDU \PYGZhy{}maxtktlife \PYGZdq{}1 day\PYGZdq{}
    \PYGZhy{}maxrenewlife \PYGZdq{}1 week\PYGZdq{} \PYGZhy{}allow\PYGZus{}postdated +needchange
    \PYGZhy{}allow\PYGZus{}forwardable tktpolicy
Password for \PYGZdq{}cn=admin,o=org\PYGZdq{}:
\end{Verbatim}


\subsubsection{Modifying a Ticket Policy}
\label{admin/database:modifying-a-ticket-policy}
To modify a ticket policy in directory, use the
{\hyperref[admin/admin_commands/kdb5_ldap_util:kdb5-ldap-util-8]{\emph{kdb5\_ldap\_util}}} \textbf{modify\_policy} command.
\begin{quote}

\textbf{modify\_policy}
{[}\textbf{-r} \emph{realm}{]}
{[}\textbf{-maxtktlife} \emph{max\_ticket\_life}{]}
{[}\textbf{-maxrenewlife} \emph{max\_renewable\_ticket\_life}{]}
{[}\emph{ticket\_flags}{]}
\emph{policy\_name}
\end{quote}

Modifies the attributes of a ticket policy.  Options are same as for
\textbf{create\_policy}.

Example:

\begin{Verbatim}[commandchars=\\\{\}]
kdb5\PYGZus{}ldap\PYGZus{}util \PYGZhy{}D cn=admin,o=org \PYGZhy{}H
    ldaps://ldap\PYGZhy{}server1.mit.edu modify\PYGZus{}policy \PYGZhy{}r ATHENA.MIT.EDU
    \PYGZhy{}maxtktlife \PYGZdq{}60 minutes\PYGZdq{} \PYGZhy{}maxrenewlife \PYGZdq{}10 hours\PYGZdq{}
    +allow\PYGZus{}postdated \PYGZhy{}requires\PYGZus{}preauth tktpolicy
Password for \PYGZdq{}cn=admin,o=org\PYGZdq{}:
\end{Verbatim}


\subsubsection{Retrieving Information About a Ticket Policy}
\label{admin/database:retrieving-information-about-a-ticket-policy}
To display the attributes of a ticket policy, use the
{\hyperref[admin/admin_commands/kdb5_ldap_util:kdb5-ldap-util-8]{\emph{kdb5\_ldap\_util}}} \textbf{view\_policy} command.
\begin{quote}

\textbf{view\_policy}
{[}\textbf{-r} \emph{realm}{]}
\emph{policy\_name}
\end{quote}

Displays the attributes of a ticket policy.  Options:
\begin{description}
\item[{\emph{policy\_name}}] \leavevmode
Specifies the name of the ticket policy.

\end{description}

Example:

\begin{Verbatim}[commandchars=\\\{\}]
kdb5\PYGZus{}ldap\PYGZus{}util \PYGZhy{}D cn=admin,o=org \PYGZhy{}H ldaps://ldap\PYGZhy{}server1.mit.edu
    view\PYGZus{}policy \PYGZhy{}r ATHENA.MIT.EDU tktpolicy
Password for \PYGZdq{}cn=admin,o=org\PYGZdq{}:
Ticket policy: tktpolicy
Maximum ticket life: 0 days 01:00:00
Maximum renewable life: 0 days 10:00:00
Ticket flags: DISALLOW\PYGZus{}FORWARDABLE REQUIRES\PYGZus{}PWCHANGE
\end{Verbatim}


\subsubsection{Destroying a Ticket Policy}
\label{admin/database:destroying-a-ticket-policy}
To destroy an existing ticket policy, use the {\hyperref[admin/admin_commands/kdb5_ldap_util:kdb5-ldap-util-8]{\emph{kdb5\_ldap\_util}}}
\textbf{destroy\_policy} command.
\begin{quote}

\textbf{destroy\_policy}
{[}\textbf{-r} \emph{realm}{]}
{[}\textbf{-force}{]}
\emph{policy\_name}
\end{quote}

Destroys an existing ticket policy.  Options:
\begin{description}
\item[{\textbf{-r} \emph{realm}}] \leavevmode
Specifies the Kerberos realm of the database.

\item[{\textbf{-force}}] \leavevmode
Forces the deletion of the policy object.  If not specified, the
user will be prompted for confirmation before deleting the policy.

\item[{\emph{policy\_name}}] \leavevmode
Specifies the name of the ticket policy.

\end{description}

Example:

\begin{Verbatim}[commandchars=\\\{\}]
kdb5\PYGZus{}ldap\PYGZus{}util \PYGZhy{}D cn=admin,o=org \PYGZhy{}H ldaps://ldap\PYGZhy{}server1.mit.edu
    destroy\PYGZus{}policy \PYGZhy{}r ATHENA.MIT.EDU tktpolicy
Password for \PYGZdq{}cn=admin,o=org\PYGZdq{}:
This will delete the policy object \PYGZsq{}tktpolicy\PYGZsq{}, are you sure?
(type \PYGZsq{}yes\PYGZsq{} to confirm)? yes
** policy object \PYGZsq{}tktpolicy\PYGZsq{} deleted.
\end{Verbatim}


\subsubsection{Listing available Ticket Policies}
\label{admin/database:listing-available-ticket-policies}
To list the name of ticket policies in a realm, use the
{\hyperref[admin/admin_commands/kdb5_ldap_util:kdb5-ldap-util-8]{\emph{kdb5\_ldap\_util}}} \textbf{list\_policy} command.
\begin{quote}

\textbf{list\_policy}
{[}\textbf{-r} \emph{realm}{]}
\end{quote}

Lists the ticket policies in realm if specified or in the default
realm.  Options:
\begin{description}
\item[{\textbf{-r} \emph{realm}}] \leavevmode
Specifies the Kerberos realm of the database.

\end{description}

Example:

\begin{Verbatim}[commandchars=\\\{\}]
kdb5\PYGZus{}ldap\PYGZus{}util \PYGZhy{}D cn=admin,o=org \PYGZhy{}H ldaps://ldap\PYGZhy{}server1.mit.edu
    list\PYGZus{}policy \PYGZhy{}r ATHENA.MIT.EDU
Password for \PYGZdq{}cn=admin,o=org\PYGZdq{}:
tktpolicy
tmppolicy
userpolicy
\end{Verbatim}


\section{Cross-realm authentication}
\label{admin/database:cross-realm-authentication}\label{admin/database:xrealm-authn}
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{ATHENA.MIT.EDU} and \code{EXAMPLE.COM}, you would need to add the
principals \code{krbtgt/EXAMPLE.COM@ATHENA.MIT.EDU} and
\code{krbtgt/ATHENA.MIT.EDU@EXAMPLE.COM} 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 \textbf{-kvno} option.

In the ATHENA.MIT.EDU and EXAMPLE.COM cross-realm case, the administrators
would run the following commands on the KDCs in both realms:

\begin{Verbatim}[commandchars=\\\{\}]
shell\PYGZpc{}: kadmin.local \PYGZhy{}e \PYGZdq{}aes256\PYGZhy{}cts:normal\PYGZdq{}
kadmin: addprinc \PYGZhy{}requires\PYGZus{}preauth krbtgt/ATHENA.MIT.EDU@EXAMPLE.COM
Enter password for principal krbtgt/ATHENA.MIT.EDU@EXAMPLE.COM:
Re\PYGZhy{}enter password for principal krbtgt/ATHENA.MIT.EDU@EXAMPLE.COM:
kadmin: addprinc \PYGZhy{}requires\PYGZus{}preauth krbtgt/EXAMPLE.COM@ATHENA.MIT.EDU
Enter password for principal krbtgt/EXAMPLE.COM@ATHENA.MIT.EDU:
Enter password for principal krbtgt/EXAMPLE.COM@ATHENA.MIT.EDU:
kadmin:
\end{Verbatim}

\begin{notice}{note}{Note:}
Even if most principals in a realm are generally created
with the \textbf{requires\_preauth} 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.
\end{notice}

\begin{notice}{note}{Note:}
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.
\end{notice}


\section{Changing the krbtgt key}
\label{admin/database:changing-krbtgt-key}\label{admin/database:changing-the-krbtgt-key}
A Kerberos Ticket Granting Ticket (TGT) is a service ticket for the
principal \code{krbtgt/REALM}.  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.

Changing this key using the normal {\hyperref[admin/admin_commands/kadmin_local:kadmin-1]{\emph{kadmin}}}
\textbf{change\_password} command would invalidate any previously issued
TGTs.  Therefore, when changing this key, normally one should use the
\textbf{-keepold} flag to change\_password to retain the previous key in the
database as well as the new key.  For example:

\begin{Verbatim}[commandchars=\\\{\}]
kadmin: change\PYGZus{}password \PYGZhy{}randkey \PYGZhy{}keepold krbtgt/ATHENA.MIT.EDU@ATHENA.MIT.EDU
\end{Verbatim}

\begin{notice}{warning}{Warning:}
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 \textbf{purgekeys} command to delete keys
with older kvnos, ideally first making sure that all
tickets issued with the old keys have expired.
\end{notice}

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
{\hyperref[admin/enctypes:session-key-selection]{\emph{Session key selection}}}).  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 \textbf{-e} option when changing the krbtgt key, or by
setting the \textbf{session\_enctypes} string attribute on the krbtgt
principal (see {\hyperref[admin/admin_commands/kadmin_local:set-string]{\emph{set\_string}}}).

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.


\section{Incremental database propagation}
\label{admin/database:incremental-database-propagation}\label{admin/database:incr-db-prop}

\subsection{Overview}
\label{admin/database:overview}
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 slave KDCs.  The incremental propagation support
added in the 1.7 release is intended to address this.

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 slave KDC connects to a service on the master
KDC (currently implemented in the {\hyperref[admin/admin_commands/kadmind:kadmind-8]{\emph{kadmind}}} 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 slave 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.

Incremental propagation uses the following entries in the per-realm
data in the KDC config file (See {\hyperref[admin/conf_files/kdc_conf:kdc-conf-5]{\emph{kdc.conf}}}):

\begin{tabulary}{\linewidth}{|L|L|L|}
\hline

iprop\_enable
 & 
\emph{boolean}
 & 
If \emph{true}, then incremental propagation is enabled, and (as noted below) normal kprop propagation is disabled. The default is \emph{false}.
\\
\hline
iprop\_master\_ulogsize
 & 
\emph{integer}
 & 
Indicates the number of entries that should be retained in the update log. The default is 1000; the maximum number is 2500.
\\
\hline
iprop\_slave\_poll
 & 
\emph{time interval}
 & 
Indicates how often the slave should poll the master KDC for changes to the database. The default is two minutes.
\\
\hline
iprop\_port
 & 
\emph{integer}
 & 
Specifies the port number to be used for incremental propagation. This is required in both master and slave configuration files.
\\
\hline
iprop\_resync\_timeout
 & 
\emph{integer}
 & 
Specifies the number of seconds to wait for a full propagation to complete. This is optional on slave configurations.  Defaults to 300 seconds (5 minutes).
\\
\hline
iprop\_logfile
 & 
\emph{file name}
 & 
Specifies where the update log file for the realm database is to be stored. The default is to use the \emph{database\_name} entry from the realms section of the config file {\hyperref[admin/conf_files/kdc_conf:kdc-conf-5]{\emph{kdc.conf}}}, with \emph{.ulog} 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 \emph{dbmodules} section, then the hard-coded default for \emph{database\_name} is used. Determination of the \emph{iprop\_logfile}  default value will not use values from the \emph{dbmodules} section.)
\\
\hline\end{tabulary}


Both master and slave sides must have a principal named
\code{kiprop/hostname} (where \emph{hostname} 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 ({\hyperref[mitK5defaults:paths]{\emph{DEFKTNAME}}}).  In release 1.13, the
\code{kiprop/hostname} principal is created automatically for the master
KDC, but it must still be created for slave KDCs.

On the master KDC side, the \code{kiprop/hostname} principal must be
listed in the kadmind ACL file {\hyperref[admin/conf_files/kadm5_acl:kadm5-acl-5]{\emph{kadm5.acl}}}, and given the
\textbf{p} privilege (see {\hyperref[admin/database:privileges]{\emph{Privileges}}}).

On the slave KDC side, {\hyperref[admin/admin_commands/kpropd:kpropd-8]{\emph{kpropd}}} should be run.  When
incremental propagation is enabled, it will connect to the kadmind on
the master KDC and start requesting updates.

The normal kprop mechanism is disabled by the incremental propagation
support.  However, if the slave 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
slave has not yet retrieved.  In this case, the slave 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 slave should resume fetching
incremental updates.  Thus, all the keytab and ACL setup previously
described for kprop propagation is still needed.

If an environment has a large number of slaves, it may be desirable to
arrange them in a hierarchy instead of having the master serve updates
to every slave.  To do this, run \code{kadmind -proponly} on each
intermediate slave, and \code{kpropd -A upstreamhostname} on downstream
slaves to direct each one to the appropriate upstream slave.

There are several known restrictions in the current implementation:
\begin{itemize}
\item {} 
The incremental update protocol does not transport changes to policy
objects.  Any policy changes on the master will result in full
resyncs to all slaves.

\item {} 
The slave's KDB module must support locking; it cannot be using the
LDAP KDB module.

\item {} 
The master and slave must be able to initiate TCP connections in
both directions, without an intervening NAT.

\end{itemize}


\subsection{Sun/MIT incremental propagation differences}
\label{admin/database:sun-mit-incremental-propagation-differences}
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.)

The Sun config file support looks for \code{sunw\_dbprop\_enable},
\code{sunw\_dbprop\_master\_ulogsize}, and \code{sunw\_dbprop\_slave\_poll}.

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

The Sun implementation hard-codes pathnames in \code{/var/krb5} for the
update log and the per-slave kprop dump files.  In the MIT
implementation, the pathname for the update log is specified in the
config file, and the per-slave dump files are stored in
{\hyperref[mitK5defaults:paths]{\emph{LOCALSTATEDIR}}}\code{/krb5kdc}\code{/slave\_datatrans\_hostname}.


\chapter{Account lockout}
\label{admin/lockout::doc}\label{admin/lockout:account-lockout}
As of release 1.8, the KDC can be configured to lock out principals
after a number of failed authentication attempts within a period of
time.  Account lockout can make it more difficult to attack a
principal's password by brute force, but also makes it easy for an
attacker to deny access to a principal.


\section{Configuring account lockout}
\label{admin/lockout:configuring-account-lockout}
Account lockout only works for principals with the
\textbf{+requires\_preauth} flag set.  Without this flag, the KDC cannot
know whether or not a client successfully decrypted the ticket it
issued.  It is also important to set the \textbf{-allow\_svr} flag on a
principal to protect its password from an off-line dictionary attack
through a TGS request.  You can set these flags on a principal with
{\hyperref[admin/admin_commands/kadmin_local:kadmin-1]{\emph{kadmin}}} as follows:

\begin{Verbatim}[commandchars=\\\{\}]
kadmin: modprinc +requires\PYGZus{}preauth \PYGZhy{}allow\PYGZus{}svr PRINCNAME
\end{Verbatim}

Account lockout parameters are configured via {\hyperref[admin/database:policies]{\emph{policy objects}}}.  There may be an existing policy associated with user
principals (such as the ``default'' policy), or you may need to create a
new one and associate it with each user principal.

The policy parameters related to account lockout are:
\begin{itemize}
\item {} 
{\hyperref[admin/database:policy-maxfailure]{\emph{maxfailure}}}: the number of failed attempts
before the principal is locked out

\item {} 
{\hyperref[admin/database:policy-failurecountinterval]{\emph{failurecountinterval}}}: the
allowable interval between failed attempts

\item {} 
{\hyperref[admin/database:policy-lockoutduration]{\emph{lockoutduration}}}: the amount of time
a principal is locked out for

\end{itemize}

Here is an example of setting these parameters on a new policy and
associating it with a principal:

\begin{Verbatim}[commandchars=\\\{\}]
kadmin: addpol \PYGZhy{}maxfailure 10 \PYGZhy{}failurecountinterval 180
    \PYGZhy{}lockoutduration 60 lockout\PYGZus{}policy
kadmin: modprinc \PYGZhy{}policy lockout\PYGZus{}policy PRINCNAME
\end{Verbatim}


\section{Testing account lockout}
\label{admin/lockout:testing-account-lockout}
To test that account lockout is working, try authenticating as the
principal (hopefully not one that might be in use) multiple times with
the wrong password.  For instance, if \textbf{maxfailure} is set to 2, you
might see:

\begin{Verbatim}[commandchars=\\\{\}]
\PYGZdl{} kinit user
Password for user@KRBTEST.COM:
kinit: Password incorrect while getting initial credentials
\PYGZdl{} kinit user
Password for user@KRBTEST.COM:
kinit: Password incorrect while getting initial credentials
\PYGZdl{} kinit user
kinit: Client\PYGZsq{}s credentials have been revoked while getting initial credentials
\end{Verbatim}


\section{Account lockout principal state}
\label{admin/lockout:account-lockout-principal-state}
A principal entry keeps three pieces of state related to account
lockout:
\begin{itemize}
\item {} 
The time of last successful authentication

\item {} 
The time of last failed authentication

\item {} 
A counter of failed attempts

\end{itemize}

The time of last successful authentication is not actually needed for
the account lockout system to function, but may be of administrative
interest.  These fields can be observed with the \textbf{getprinc} kadmin
command.  For example:

\begin{Verbatim}[commandchars=\\\{\}]
kadmin: getprinc user
Principal: user@KRBTEST.COM
...
Last successful authentication: [never]
Last failed authentication: Mon Dec 03 12:30:33 EST 2012
Failed password attempts: 2
...
\end{Verbatim}

A principal which has been locked out can be administratively unlocked
with the \textbf{-unlock} option to the \textbf{modprinc} kadmin command:

\begin{Verbatim}[commandchars=\\\{\}]
kadmin: modprinc \PYGZhy{}unlock PRINCNAME
\end{Verbatim}

This command will reset the number of failed attempts to 0.


\section{KDC replication and account lockout}
\label{admin/lockout:kdc-replication-and-account-lockout}
The account lockout state of a principal is not replicated by either
traditional {\hyperref[admin/admin_commands/kprop:kprop-8]{\emph{kprop}}} or incremental propagation.  Because of
this, the number of attempts an attacker can make within a time period
is multiplied by the number of KDCs.  For instance, if the
\textbf{maxfailure} parameter on a policy is 10 and there are four KDCs in
the environment (a master and three slaves), an attacker could make as
many as 40 attempts before the principal is locked out on all four
KDCs.

An administrative unlock is propagated from the master to the slave
KDCs during the next propagation.  Propagation of an administrative
unlock will cause the counter of failed attempts on each slave to
reset to 1 on the next failure.

If a KDC environment uses a replication strategy other than kprop or
incremental propagation, such as the LDAP KDB module with multi-master
LDAP replication, then account lockout state may be replicated between
KDCs and the concerns of this section may not apply.


\section{KDC performance and account lockout}
\label{admin/lockout:kdc-performance-and-account-lockout}
In order to fully track account lockout state, the KDC must write to
the the database on each successful and failed authentication.
Writing to the database is generally more expensive than reading from
it, so these writes may have a significant impact on KDC performance.
As of release 1.9, it is possible to turn off account lockout state
tracking in order to improve performance, by setting the
\textbf{disable\_last\_success} and \textbf{disable\_lockout} variables in the
database module subsection of {\hyperref[admin/conf_files/kdc_conf:kdc-conf-5]{\emph{kdc.conf}}}.  For example:

\begin{Verbatim}[commandchars=\\\{\}]
[dbmodules]
    DB = \PYGZob{}
        disable\PYGZus{}last\PYGZus{}success = true
        disable\PYGZus{}lockout = true
    \PYGZcb{}
\end{Verbatim}

Of the two variables, setting \textbf{disable\_last\_success} will usually
have the largest positive impact on performance, and will still allow
account lockout policies to operate.  However, it will make it
impossible to observe the last successful authentication time with
kadmin.


\section{KDC setup and account lockout}
\label{admin/lockout:kdc-setup-and-account-lockout}
To update the account lockout state on principals, the KDC must be
able to write to the principal database.  For the DB2 module, no
special setup is required.  For the LDAP module, the KDC DN must be
granted write access to the principal objects.  If the KDC DN has only
read access, account lockout will not function.


\chapter{Configuring Kerberos with OpenLDAP back-end}
\label{admin/conf_ldap::doc}\label{admin/conf_ldap:configuring-kerberos-with-openldap-back-end}\begin{enumerate}
\item {} 
Set up SSL on the OpenLDAP server and client to ensure secure
communication when the KDC service and LDAP server are on different
machines.  \code{ldapi://} can be used if the LDAP server and KDC
service are running on the same machine.
\begin{enumerate}
\item {} 
Setting up SSL on the OpenLDAP server:

\end{enumerate}
\begin{enumerate}
\item {} 
Get a CA certificate using OpenSSL tools

\item {} 
Configure OpenLDAP server for using SSL/TLS

For the latter, you need to specify the location of CA
certificate location in \emph{slapd.conf} file.

Refer to the following link for more information:
\href{http://www.openldap.org/doc/admin23/tls.html}{http://www.openldap.org/doc/admin23/tls.html}

\end{enumerate}
\begin{enumerate}
\setcounter{enumi}{1}
\item {} 
Setting up SSL on OpenLDAP client:
\begin{enumerate}
\item {} 
For the KDC and Admin Server, you need to do the client-side
configuration in ldap.conf.  For example:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n}{TLS\PYGZus{}CACERT} \PYG{o}{/}\PYG{n}{etc}\PYG{o}{/}\PYG{n}{openldap}\PYG{o}{/}\PYG{n}{certs}\PYG{o}{/}\PYG{n}{cacert}\PYG{o}{.}\PYG{n}{pem}
\end{Verbatim}

\end{enumerate}

\end{enumerate}

\item {} 
Include the Kerberos schema file (kerberos.schema) in the
configuration file (slapd.conf) on the LDAP Server, by providing
the location where it is stored:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n}{include} \PYG{o}{/}\PYG{n}{etc}\PYG{o}{/}\PYG{n}{openldap}\PYG{o}{/}\PYG{n}{schema}\PYG{o}{/}\PYG{n}{kerberos}\PYG{o}{.}\PYG{n}{schema}
\end{Verbatim}

\item {} 
Choose DNs for the {\hyperref[admin/admin_commands/krb5kdc:krb5kdc-8]{\emph{krb5kdc}}} and {\hyperref[admin/admin_commands/kadmind:kadmind-8]{\emph{kadmind}}} servers
to bind to the LDAP server, and create them if necessary. These DNs
will be specified with the \textbf{ldap\_kdc\_dn} and \textbf{ldap\_kadmind\_dn}
directives in {\hyperref[admin/conf_files/kdc_conf:kdc-conf-5]{\emph{kdc.conf}}}; their passwords can be stashed
with ``\code{kdb5\_ldap\_util stashsrvpw}'' and the resulting file
specified with the \textbf{ldap\_service\_password\_file} directive.

\item {} 
Choose a DN for the global Kerberos container entry (but do not
create the entry at this time).  This DN will be specified with the
\textbf{ldap\_kerberos\_container\_dn} directive in {\hyperref[admin/conf_files/kdc_conf:kdc-conf-5]{\emph{kdc.conf}}}.
Realm container entries will be created underneath this DN.
Principal entries may exist either underneath the realm container
(the default) or in separate trees referenced from the realm
container.

\item {} 
Configure the LDAP server ACLs to enable the KDC and kadmin server
DNs to read and write the Kerberos data.  If
\textbf{disable\_last\_success} and \textbf{disable\_lockout} are both set to
true in the {\hyperref[admin/conf_files/kdc_conf:dbmodules]{\emph{{[}dbmodules{]}}}} subsection for the realm, then the
KDC DN only requires read access to the Kerberos data.

Sample access control information:

\begin{Verbatim}[commandchars=\\\{\}]
access to dn.base=\PYGZdq{}\PYGZdq{}
    by * read

access to dn.base=\PYGZdq{}cn=Subschema\PYGZdq{}
    by * read

access to attrs=userPassword,userPKCS12
    by self write
    by * auth

access to attrs=shadowLastChange
    by self write
    by * read

\PYGZsh{} Providing access to realm container
access to dn.subtree= \PYGZdq{}cn=EXAMPLE.COM,cn=krbcontainer,dc=example,dc=com\PYGZdq{}
    by dn.exact=\PYGZdq{}cn=kdc\PYGZhy{}service,dc=example,dc=com\PYGZdq{} write
    by dn.exact=\PYGZdq{}cn=adm\PYGZhy{}service,dc=example,dc=com\PYGZdq{} write
    by * none

\PYGZsh{} Providing access to principals, if not underneath realm container
access to dn.subtree= \PYGZdq{}ou=users,dc=example,dc=com\PYGZdq{}
    by dn.exact=\PYGZdq{}cn=kdc\PYGZhy{}service,dc=example,dc=com\PYGZdq{} write
    by dn.exact=\PYGZdq{}cn=adm\PYGZhy{}service,dc=example,dc=com\PYGZdq{} write
    by * none

access to *
    by * read
\end{Verbatim}

If the locations of the container and principals or the DNs of
the service objects for a realm are changed then this
information should be updated.

\item {} 
Start the LDAP server as follows:

\begin{Verbatim}[commandchars=\\\{\}]
slapd \PYGZhy{}h \PYGZdq{}ldapi:/// ldaps:///\PYGZdq{}
\end{Verbatim}

\item {} 
Modify the {\hyperref[admin/conf_files/kdc_conf:kdc-conf-5]{\emph{kdc.conf}}} file to include LDAP specific items
listed below:

\begin{Verbatim}[commandchars=\\\{\}]
realms
    database\PYGZus{}module

dbmodules
    db\PYGZus{}library
    db\PYGZus{}module\PYGZus{}dir
    ldap\PYGZus{}kdc\PYGZus{}dn
    ldap\PYGZus{}kadmind\PYGZus{}dn
    ldap\PYGZus{}service\PYGZus{}password\PYGZus{}file
    ldap\PYGZus{}servers
    ldap\PYGZus{}conns\PYGZus{}per\PYGZus{}server
\end{Verbatim}

\item {} 
Create the realm using {\hyperref[admin/admin_commands/kdb5_ldap_util:kdb5-ldap-util-8]{\emph{kdb5\_ldap\_util}}} (see
{\hyperref[admin/database:ldap-create-realm]{\emph{Creating a Kerberos realm}}}):

\begin{Verbatim}[commandchars=\\\{\}]
kdb5\PYGZus{}ldap\PYGZus{}util \PYGZhy{}D cn=admin,dc=example,dc=com create \PYGZhy{}subtrees ou=users,dc=example,dc=com \PYGZhy{}r EXAMPLE.COM \PYGZhy{}s
\end{Verbatim}

Use the \textbf{-subtrees} option if the principals are to exist in a
separate subtree from the realm container.  Before executing the
command, make sure that the subtree mentioned above
\code{(ou=users,dc=example,dc=com)} exists.  If the principals will
exist underneath the realm container, omit the \textbf{-subtrees} option
and do not worry about creating the principal subtree.

For more information, refer to the section {\hyperref[admin/database:ops-on-ldap]{\emph{Operations on the LDAP database}}}.

The realm object is created under the
\textbf{ldap\_kerberos\_container\_dn} specified in the configuration file.
This operation will also create the Kerberos container, if not
present already.  This will be used to store information related to
all realms.

\item {} 
Stash the password of the service object used by the KDC and
Administration service to bind to the LDAP server using the
{\hyperref[admin/admin_commands/kdb5_ldap_util:kdb5-ldap-util-8]{\emph{kdb5\_ldap\_util}}} \textbf{stashsrvpw} command (see
{\hyperref[admin/database:stash-ldap]{\emph{Stashing service object's password}}}).  The object DN should be the same as
\textbf{ldap\_kdc\_dn} and \textbf{ldap\_kadmind\_dn} values specified in the
{\hyperref[admin/conf_files/kdc_conf:kdc-conf-5]{\emph{kdc.conf}}} file:

\begin{Verbatim}[commandchars=\\\{\}]
kdb5\PYGZus{}ldap\PYGZus{}util \PYGZhy{}D cn=admin,dc=example,dc=com stashsrvpw \PYGZhy{}f /etc/kerberos/service.keyfile cn=krbadmin,dc=example,dc=com
\end{Verbatim}

\item {} 
Add \code{krbPrincipalName} to the indexes in slapd.conf to speed up
the access.

\end{enumerate}

With the LDAP back end it is possible to provide aliases for principal
entries.  Currently we provide no mechanism provided for creating
aliases, so it must be done by direct manipulation of the LDAP
entries.

An entry with aliases contains multiple values of the
\emph{krbPrincipalName} attribute.  Since LDAP attribute values are not
ordered, it is necessary to specify which principal name is canonical,
by using the \emph{krbCanonicalName} attribute.  Therefore, to create
aliases for an entry, first set the \emph{krbCanonicalName} attribute of
the entry to the canonical principal name (which should be identical
to the pre-existing \emph{krbPrincipalName} value), and then add additional
\emph{krbPrincipalName} attributes for the aliases.

Principal aliases are only returned by the KDC when the client
requests canonicalization.  Canonicalization is normally requested for
service principals; for client principals, an explicit flag is often
required (e.g., \code{kinit -C}) and canonicalization is only performed
for initial ticket requests.


\strong{See also:}


{\hyperref[admin/advanced/ldapbackend:ldap-be-ubuntu]{\emph{LDAP backend on Ubuntu 10.4 (lucid)}}}




\chapter{Application servers}
\label{admin/appl_servers::doc}\label{admin/appl_servers:application-servers}
If you need to install the Kerberos V5 programs on an application
server, please refer to the Kerberos V5 Installation Guide.  Once you
have installed the software, you need to add that host to the Kerberos
database (see {\hyperref[admin/database:add-mod-del-princs]{\emph{Adding, modifying and deleting principals}}}), and generate a keytab for
that host, that contains the host's key.  You also need to make sure
the host's clock is within your maximum clock skew of the KDCs.


\section{Keytabs}
\label{admin/appl_servers:keytabs}
A keytab is a host's copy of its own keylist, which is analogous to a
user's password.  An application server that needs to authenticate
itself to the KDC has to have a keytab that contains its own principal
and key.  Just as it is important for users to protect their
passwords, it is equally important for hosts to protect their keytabs.
You should always store keytab files on local disk, and make them
readable only by root, and you should never send a keytab file over a
network in the clear.  Ideally, you should run the {\hyperref[admin/admin_commands/kadmin_local:kadmin-1]{\emph{kadmin}}}
command to extract a keytab on the host on which the keytab is to
reside.


\subsection{Adding principals to keytabs}
\label{admin/appl_servers:adding-principals-to-keytabs}\label{admin/appl_servers:add-princ-kt}
To generate a keytab, or to add a principal to an existing keytab, use
the \textbf{ktadd} command from kadmin.


\subsection{ktadd}
\label{admin/appl_servers:ktadd}\begin{quote}

\begin{DUlineblock}{0em}
\item[] \textbf{ktadd} {[}options{]} \emph{principal}
\item[] \textbf{ktadd} {[}options{]} \textbf{-glob} \emph{princ-exp}
\end{DUlineblock}
\end{quote}

Adds a \emph{principal}, or all principals matching \emph{princ-exp}, to a
keytab file.  Each principal's keys are randomized in the process.
The rules for \emph{princ-exp} are described in the \textbf{list\_principals}
command.

This command requires the \textbf{inquire} and \textbf{changepw} privileges.
With the \textbf{-glob} form, it also requires the \textbf{list} privilege.

The options are:
\begin{description}
\item[{\textbf{-k{[}eytab{]}} \emph{keytab}}] \leavevmode
Use \emph{keytab} as the keytab file.  Otherwise, the default keytab is
used.

\item[{\textbf{-e} \emph{enc}:\emph{salt},...}] \leavevmode
Uses the specified keysalt list for setting the new keys of the
principal.  See {\hyperref[admin/conf_files/kdc_conf:keysalt-lists]{\emph{Keysalt lists}}} in {\hyperref[admin/conf_files/kdc_conf:kdc-conf-5]{\emph{kdc.conf}}} for a
list of possible values.

\item[{\textbf{-q}}] \leavevmode
Display less verbose information.

\item[{\textbf{-norandkey}}] \leavevmode
Do not randomize the keys. The keys and their version numbers stay
unchanged.  This option cannot be specified in combination with the
\textbf{-e} option.

\end{description}

An entry for each of the principal's unique encryption types is added,
ignoring multiple keys with the same encryption type but different
salt types.

Example:

\begin{Verbatim}[commandchars=\\\{\}]
kadmin: ktadd \PYGZhy{}k /tmp/foo\PYGZhy{}new\PYGZhy{}keytab host/foo.mit.edu
Entry for principal host/foo.mit.edu@ATHENA.MIT.EDU with kvno 3,
     encryption type aes256\PYGZhy{}cts\PYGZhy{}hmac\PYGZhy{}sha1\PYGZhy{}96 added to keytab
     FILE:/tmp/foo\PYGZhy{}new\PYGZhy{}keytab
kadmin:
\end{Verbatim}


\subsubsection{Examples}
\label{admin/appl_servers:examples}
Here is a sample session, using configuration files that enable only
AES encryption:

\begin{Verbatim}[commandchars=\\\{\}]
kadmin: ktadd host/daffodil.mit.edu@ATHENA.MIT.EDU
Entry for principal host/daffodil.mit.edu with kvno 2, encryption type aes256\PYGZhy{}cts\PYGZhy{}hmac\PYGZhy{}sha1\PYGZhy{}96 added to keytab FILE:/etc/krb5.keytab
Entry for principal host/daffodil.mit.edu with kvno 2, encryption type aes128\PYGZhy{}cts\PYGZhy{}hmac\PYGZhy{}sha1\PYGZhy{}96 added to keytab FILE:/etc/krb5.keytab
kadmin:
\end{Verbatim}


\subsection{Removing principals from keytabs}
\label{admin/appl_servers:removing-principals-from-keytabs}
To remove a principal from an existing keytab, use the kadmin
\textbf{ktremove} command.


\subsection{ktremove}
\label{admin/appl_servers:ktremove}\begin{quote}

\textbf{ktremove} {[}options{]} \emph{principal} {[}\emph{kvno} \textbar{} \emph{all} \textbar{} \emph{old}{]}
\end{quote}

Removes entries for the specified \emph{principal} from a keytab.  Requires
no permissions, since this does not require database access.

If the string ``all'' is specified, all entries for that principal are
removed; if the string ``old'' is specified, all entries for that
principal except those with the highest kvno are removed.  Otherwise,
the value specified is parsed as an integer, and all entries whose
kvno match that integer are removed.

The options are:
\begin{description}
\item[{\textbf{-k{[}eytab{]}} \emph{keytab}}] \leavevmode
Use \emph{keytab} as the keytab file.  Otherwise, the default keytab is
used.

\item[{\textbf{-q}}] \leavevmode
Display less verbose information.

\end{description}

Example:

\begin{Verbatim}[commandchars=\\\{\}]
kadmin: ktremove kadmin/admin all
Entry for principal kadmin/admin with kvno 3 removed from keytab
     FILE:/etc/krb5.keytab
kadmin:
\end{Verbatim}


\section{Clock Skew}
\label{admin/appl_servers:clock-skew}
A Kerberos application server host must keep its clock synchronized or
it will reject authentication requests from clients.  Modern operating
systems typically provide a facility to maintain the correct time;
make sure it is enabled.  This is especially important on virtual
machines, where clocks tend to drift more rapidly than normal machine
clocks.

The default allowable clock skew is controlled by the \textbf{clockskew}
variable in {\hyperref[admin/conf_files/krb5_conf:libdefaults]{\emph{{[}libdefaults{]}}}}.


\section{Getting DNS information correct}
\label{admin/appl_servers:getting-dns-information-correct}
Several aspects of Kerberos rely on name service.  When a hostname is
used to name a service, the Kerberos library canonicalizes the
hostname using forward and reverse name resolution.  (The reverse name
resolution step can be turned off using the \textbf{rdns} variable in
{\hyperref[admin/conf_files/krb5_conf:libdefaults]{\emph{{[}libdefaults{]}}}}.)  The result of this canonicalization must match
the principal entry in the host's keytab, or authentication will fail.

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

Configuration of hostnames varies by operating system.  On the
application server itself, canonicalization will typically use the
\code{/etc/hosts} file rather than the DNS.  Ensure that the line for the
server's hostname is in the following form:

\begin{Verbatim}[commandchars=\\\{\}]
IP address      fully\PYGZhy{}qualified hostname        aliases
\end{Verbatim}

Here is a sample \code{/etc/hosts} file:

\begin{Verbatim}[commandchars=\\\{\}]
\PYGZsh{} this is a comment
127.0.0.1      localhost localhost.mit.edu
10.0.0.6       daffodil.mit.edu daffodil trillium wake\PYGZhy{}robin
\end{Verbatim}

The output of \code{klist -k} for this example host should look like:

\begin{Verbatim}[commandchars=\\\{\}]
viola\PYGZsh{} klist \PYGZhy{}k
Keytab name: /etc/krb5.keytab
KVNO Principal
\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{} \PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}
   2 host/daffodil.mit.edu@ATHENA.MIT.EDU
\end{Verbatim}

If you were to ssh to this host with a fresh credentials cache (ticket
file), and then \emph{klist(1)}, the output should list a service
principal of \code{host/daffodil.mit.edu@ATHENA.MIT.EDU}.


\section{Configuring your firewall to work with Kerberos V5}
\label{admin/appl_servers:conf-firewall}\label{admin/appl_servers:configuring-your-firewall-to-work-with-kerberos-v5}
If you need off-site users to be able to get Kerberos tickets in your
realm, they must be able to get to your KDC.  This requires either
that you have a slave KDC outside your firewall, or that you configure
your firewall to allow UDP requests into at least one of your KDCs, on
whichever port the KDC is running.  (The default is port 88; other
ports may be specified in the KDC's {\hyperref[admin/conf_files/kdc_conf:kdc-conf-5]{\emph{kdc.conf}}} file.)
Similarly, if you need off-site users to be able to change their
passwords in your realm, they must be able to get to your Kerberos
admin server on the kpasswd port (which defaults to 464).  If you need
off-site users to be able to administer your Kerberos realm, they must
be able to get to your Kerberos admin server on the administrative
port (which defaults to 749).

If your on-site users inside your firewall will need to get to KDCs in
other realms, you will also need to configure your firewall to allow
outgoing TCP and UDP requests to port 88, and to port 464 to allow
password changes.  If your on-site users inside your firewall will
need to get to Kerberos admin servers in other realms, you will also
need to allow outgoing TCP and UDP requests to port 749.

If any of your KDCs are outside your firewall, you will need to allow
kprop requests to get through to the remote KDC.  {\hyperref[admin/admin_commands/kprop:kprop-8]{\emph{kprop}}} uses
the \code{krb5\_prop} service on port 754 (tcp).

The book \emph{UNIX System Security}, by David Curry, is a good starting
point for learning to configure firewalls.


\chapter{Host configuration}
\label{admin/host_config:host-configuration}\label{admin/host_config::doc}
All hosts running Kerberos software, whether they are clients,
application servers, or KDCs, can be configured using
{\hyperref[admin/conf_files/krb5_conf:krb5-conf-5]{\emph{krb5.conf}}}.  Here we describe some of the behavior changes
you might want to make.


\section{Default realm}
\label{admin/host_config:default-realm}
In the {\hyperref[admin/conf_files/krb5_conf:libdefaults]{\emph{{[}libdefaults{]}}}} section, the \textbf{default\_realm} realm
relation sets the default Kerberos realm.  For example:

\begin{Verbatim}[commandchars=\\\{\}]
[libdefaults]
    default\PYGZus{}realm = ATHENA.MIT.EDU
\end{Verbatim}

The default realm affects Kerberos behavior in the following ways:
\begin{itemize}
\item {} 
When a principal name is parsed from text, the default realm is used
if no \code{@REALM} component is specified.

\item {} 
The default realm affects login authorization as described below.

\item {} 
For programs which operate on a Kerberos database, the default realm
is used to determine which database to operate on, unless the \textbf{-r}
parameter is given to specify a realm.

\item {} 
A server program may use the default realm when looking up its key
in a {\hyperref[admin/install_appl_srv:keytab-file]{\emph{keytab file}}}, if its realm is not
determined by {\hyperref[admin/conf_files/krb5_conf:domain-realm]{\emph{{[}domain\_realm{]}}}} configuration or by the server
program itself.

\item {} 
If \emph{kinit(1)} is passed the \textbf{-n} flag, it requests anonymous
tickets from the default realm.

\end{itemize}

In some situations, these uses of the default realm might conflict.
For example, it might be desirable for principal name parsing to use
one realm by default, but for login authorization to use a second
realm.  In this situation, the first realm can be configured as the
default realm, and \textbf{auth\_to\_local} relations can be used as
described below to use the second realm for login authorization.


\section{Login authorization}
\label{admin/host_config:login-authorization}\label{admin/host_config:id1}
If a host runs a Kerberos-enabled login service such as OpenSSH with
GSSAPIAuthentication enabled, login authorization rules determine
whether a Kerberos principal is allowed to access a local account.

By default, a Kerberos principal is allowed access to an account if
its realm matches the default realm and its name matches the account
name.  (For historical reasons, access is also granted by default if
the name has two components and the second component matches the
default realm; for instance, \code{alice/ATHENA.MIT.EDU@ATHENA.MIT.EDU}
is granted access to the \code{alice} account if \code{ATHENA.MIT.EDU} is
the default realm.)

The simplest way to control local access is using \emph{.k5login(5)}
files.  To use these, place a \code{.k5login} file in the home directory
of each account listing the principal names which should have login
access to that account.  If it is not desirable to use \code{.k5login}
files located in account home directories, the \textbf{k5login\_directory}
relation in the {\hyperref[admin/conf_files/krb5_conf:libdefaults]{\emph{{[}libdefaults{]}}}} section can specify a directory
containing one file per account uname.

By default, if a \code{.k5login} file is present, it controls
authorization both positively and negatively--any principal name
contained in the file is granted access and any other principal name
is denied access, even if it would have had access if the \code{.k5login}
file didn't exist.  The \textbf{k5login\_authoritative} relation in the
{\hyperref[admin/conf_files/krb5_conf:libdefaults]{\emph{{[}libdefaults{]}}}} section can be set to false to make \code{.k5login}
files provide positive authorization only.

The \textbf{auth\_to\_local} relation in the {\hyperref[admin/conf_files/krb5_conf:realms]{\emph{{[}realms{]}}}} section for the
default realm can specify pattern-matching rules to control login
authorization.  For example, the following configuration allows access
to principals from a different realm than the default realm:

\begin{Verbatim}[commandchars=\\\{\}]
[realms]
    DEFAULT.REALM = \PYGZob{}
        \PYGZsh{} Allow access to principals from OTHER.REALM.
        \PYGZsh{}
        \PYGZsh{} [1:\PYGZdl{}1@\PYGZdl{}0] matches single\PYGZhy{}component principal names and creates
        \PYGZsh{} a selection string containing the principal name and realm.
        \PYGZsh{}
        \PYGZsh{} (.*@OTHER\PYGZbs{}.REALM) matches against the selection string, so that
        \PYGZsh{} only principals in OTHER.REALM are matched.
        \PYGZsh{}
        \PYGZsh{} s/@OTHER\PYGZbs{}.REALM\PYGZdl{}// removes the realm name, leaving behind the
        \PYGZsh{} principal name as the acount name.
        auth\PYGZus{}to\PYGZus{}local = RULE:[1:\PYGZdl{}1@\PYGZdl{}0](.*@OTHER\PYGZbs{}.REALM)s/@OTHER\PYGZbs{}.REALM\PYGZdl{}//

        \PYGZsh{} Also allow principals from the default realm.  Omit this line
        \PYGZsh{} to only allow access to principals in OTHER.REALM.
        auth\PYGZus{}to\PYGZus{}local = DEFAULT
    \PYGZcb{}
\end{Verbatim}

The \textbf{auth\_to\_local\_names} subsection of the {\hyperref[admin/conf_files/krb5_conf:realms]{\emph{{[}realms{]}}}} section
for the default realm can specify explicit mappings from principal
names to local accounts.  The key used in this subsection is the
principal name without realm, so it is only safe to use in a Kerberos
environment with a single realm or a tightly controlled set of realms.
An example use of \textbf{auth\_to\_local\_names} might be:

\begin{Verbatim}[commandchars=\\\{\}]
[realms]
    ATHENA.MIT.EDU = \PYGZob{}
        auth\PYGZus{}to\PYGZus{}local\PYGZus{}names = \PYGZob{}
            \PYGZsh{} Careful, these match principals in any realm!
            host/example.com = hostaccount
            fred = localfred
        \PYGZcb{}
    \PYGZcb{}
\end{Verbatim}

Local authorization behavior can also be modified using plugin
modules; see \emph{hostrealm\_plugin} for details.


\section{Plugin module configuration}
\label{admin/host_config:plugin-config}\label{admin/host_config:plugin-module-configuration}
Many aspects of Kerberos behavior, such as client preauthentication
and KDC service location, can be modified through the use of plugin
modules.  For most of these behaviors, you can use the {\hyperref[admin/conf_files/krb5_conf:plugins]{\emph{{[}plugins{]}}}}
section of krb5.conf to register third-party modules, and to switch
off registered or built-in modules.

A plugin module takes the form of a Unix shared object
(\code{modname.so}) or Windows DLL (\code{modname.dll}).  If you have
installed a third-party plugin module and want to register it, you do
so using the \textbf{module} relation in the appropriate subsection of the
{[}plugins{]} section.  The value for \textbf{module} must give the module name
and the path to the module, separated by a colon.  The module name
will often be the same as the shared object's name, but in unusual
cases (such as a shared object which implements multiple modules for
the same interface) it might not be.  For example, to register a
client preauthentication module named \code{mypreauth} installed at
\code{/path/to/mypreauth.so}, you could write:

\begin{Verbatim}[commandchars=\\\{\}]
[plugins]
    clpreauth = \PYGZob{}
        module = mypreauth:/path/to/mypreauth.so
    \PYGZcb{}
\end{Verbatim}

Many of the pluggable behaviors in MIT krb5 contain built-in modules
which can be switched off.  You can disable a built-in module (or one
you have registered) using the \textbf{disable} directive in the
appropriate subsection of the {[}plugins{]} section.  For example, to
disable the use of .k5identity files to select credential caches, you
could write:

\begin{Verbatim}[commandchars=\\\{\}]
[plugins]
    ccselect = \PYGZob{}
        disable = k5identity
    \PYGZcb{}
\end{Verbatim}

If you want to disable multiple modules, specify the \textbf{disable}
directive multiple times, giving one module to disable each time.

Alternatively, you can explicitly specify which modules you want to be
enabled for that behavior using the \textbf{enable\_only} directive.  For
example, to make {\hyperref[admin/admin_commands/kadmind:kadmind-8]{\emph{kadmind}}} check password quality using only a
module you have registered, and no other mechanism, you could write:

\begin{Verbatim}[commandchars=\\\{\}]
[plugins]
    pwqual = \PYGZob{}
        module = mymodule:/path/to/mymodule.so
        enable\PYGZus{}only = mymodule
    \PYGZcb{}
\end{Verbatim}

Again, if you want to specify multiple modules, specify the
\textbf{enable\_only} directive multiple times, giving one module to enable
each time.

Some Kerberos interfaces use different mechanisms to register plugin
modules.


\subsection{KDC location modules}
\label{admin/host_config:kdc-location-modules}
For historical reasons, modules to control how KDC servers are located
are registered simply by placing the shared object or DLL into the
``libkrb5'' subdirectory of the krb5 plugin directory, which defaults to
{\hyperref[mitK5defaults:paths]{\emph{LIBDIR}}}\code{/krb5/plugins}.  For example, Samba's winbind krb5
locator plugin would be registered by placing its shared object in
{\hyperref[mitK5defaults:paths]{\emph{LIBDIR}}}\code{/krb5/plugins/libkrb5/winbind\_krb5\_locator.so}.


\subsection{GSSAPI mechanism modules}
\label{admin/host_config:gssapi-plugin-config}\label{admin/host_config:gssapi-mechanism-modules}
GSSAPI mechanism modules are registered using the file
\code{/etc/gss/mech} or configuration files in the \code{/etc/gss/mech.d/}
directory.  Only files with a \code{.conf} suffix will be read from the
\code{/etc/gss/mech.d/} directory.  Each line in these files has the
form:

\begin{Verbatim}[commandchars=\\\{\}]
oid  pathname  [options]  \PYGZlt{}type\PYGZgt{}
\end{Verbatim}

Only the oid and pathname are required.  \emph{oid} is the object
identifier of the GSSAPI mechanism to be registered.  \emph{pathname} is a
path to the module shared object or DLL.  \emph{options} (if present) are
options provided to the plugin module, surrounded in square brackets.
\emph{type} (if present) can be used to indicate a special type of module.
Currently the only special module type is ``interposer'', for a module
designed to intercept calls to other mechanisms.


\subsection{Configuration profile modules}
\label{admin/host_config:profile-plugin-config}\label{admin/host_config:configuration-profile-modules}
A configuration profile module replaces the information source for
{\hyperref[admin/conf_files/krb5_conf:krb5-conf-5]{\emph{krb5.conf}}} itself.  To use a profile module, begin krb5.conf
with the line:

\begin{Verbatim}[commandchars=\\\{\}]
module PATHNAME:STRING
\end{Verbatim}

where \emph{PATHNAME} is a path to the module shared object or DLL, and
\emph{STRING} is a string to provide to the module.  The module will then
take over, and the rest of krb5.conf will be ignored.


\chapter{Backups of secure hosts}
\label{admin/backup_host:backups-of-secure-hosts}\label{admin/backup_host::doc}
When you back up a secure host, you should exclude the host's keytab
file from the backup.  If someone obtained a copy of the keytab from a
backup, that person could make any host masquerade as the host whose
keytab was compromised.  In many configurations, knowledge of the
host's keytab also allows root access to the host.  This could be
particularly dangerous if the compromised keytab was from one of your
KDCs.  If the machine has a disk crash and the keytab file is lost, it
is easy to generate another keytab file.  (See {\hyperref[admin/appl_servers:add-princ-kt]{\emph{Adding principals to keytabs}}}.)
If you are unable to exclude particular files from backups, you should
ensure that the backups are kept as secure as the host's root
password.


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


\chapter{PKINIT configuration}
\label{admin/pkinit:pkinit-configuration}\label{admin/pkinit:pkinit}\label{admin/pkinit::doc}
PKINIT is a preauthentication mechanism for Kerberos 5 which uses
X.509 certificates to authenticate the KDC to clients and vice versa.
PKINIT can also be used to enable anonymity support, allowing clients
to communicate securely with the KDC or with application servers
without authenticating as a particular client principal.


\section{Creating certificates}
\label{admin/pkinit:creating-certificates}
PKINIT requires an X.509 certificate for the KDC and one for each
client principal which will authenticate using PKINIT.  For anonymous
PKINIT, a KDC certificate is required, but client certificates are
not.  A commercially issued server certificate can be used for the KDC
certificate, but generally cannot be used for client certificates.

The instruction in this section describe how to establish a
certificate authority and create standard PKINIT certificates.  Skip
this section if you are using a commercially issued server certificate
as the KDC certificate for anonymous PKINIT, or if you are configuring
a client to use an Active Directory KDC.


\subsection{Generating a certificate authority certificate}
\label{admin/pkinit:generating-a-certificate-authority-certificate}
You can establish a new certificate authority (CA) for use with a
PKINIT deployment with the commands:

\begin{Verbatim}[commandchars=\\\{\}]
openssl genrsa \PYGZhy{}out cakey.pem 2048
openssl req \PYGZhy{}key cakey.pem \PYGZhy{}new \PYGZhy{}x509 \PYGZhy{}out cacert.pem \PYGZhy{}days 3650
\end{Verbatim}

The second command will ask for the values of several certificate
fields.  These fields can be set to any values.  You can adjust the
expiration time of the CA certificate by changing the number after
\code{-days}.  Since the CA certificate must be deployed to client
machines each time it changes, it should normally have an expiration
time far in the future; however, expiration times after 2037 may cause
interoperability issues in rare circumstances.

The result of these commands will be two files, cakey.pem and
cacert.pem.  cakey.pem will contain a 2048-bit RSA private key, which
must be carefully protected.  cacert.pem will contain the CA
certificate, which must be placed in the filesytems of the KDC and
each client host.  cakey.pem will be required to create KDC and client
certificates.


\subsection{Generating a KDC certificate}
\label{admin/pkinit:generating-a-kdc-certificate}
A KDC certificate for use with PKINIT is required to have some unusual
fields, which makes generating them with OpenSSL somewhat complicated.
First, you will need a file containing the following:

\begin{Verbatim}[commandchars=\\\{\}]
[kdc\PYGZus{}cert]
basicConstraints=CA:FALSE
keyUsage=nonRepudiation,digitalSignature,keyEncipherment,keyAgreement
extendedKeyUsage=1.3.6.1.5.2.3.5
subjectKeyIdentifier=hash
authorityKeyIdentifier=keyid,issuer
issuerAltName=issuer:copy
subjectAltName=otherName:1.3.6.1.5.2.2;SEQUENCE:kdc\PYGZus{}princ\PYGZus{}name

[kdc\PYGZus{}princ\PYGZus{}name]
realm=EXP:0,GeneralString:\PYGZdl{}\PYGZob{}ENV::REALM\PYGZcb{}
principal\PYGZus{}name=EXP:1,SEQUENCE:kdc\PYGZus{}principal\PYGZus{}seq

[kdc\PYGZus{}principal\PYGZus{}seq]
name\PYGZus{}type=EXP:0,INTEGER:1
name\PYGZus{}string=EXP:1,SEQUENCE:kdc\PYGZus{}principals

[kdc\PYGZus{}principals]
princ1=GeneralString:krbtgt
princ2=GeneralString:\PYGZdl{}\PYGZob{}ENV::REALM\PYGZcb{}
\end{Verbatim}

If the above contents are placed in extensions.kdc, you can generate
and sign a KDC certificate with the following commands:

\begin{Verbatim}[commandchars=\\\{\}]
openssl genrsa \PYGZhy{}out kdckey.pem 2048
openssl req \PYGZhy{}new \PYGZhy{}out kdc.req \PYGZhy{}key kdckey.pem
env REALM=YOUR\PYGZus{}REALMNAME openssl x509 \PYGZhy{}req \PYGZhy{}in kdc.req \PYGZbs{}
    \PYGZhy{}CAkey cakey.pem \PYGZhy{}CA cacert.pem \PYGZhy{}out kdc.pem \PYGZhy{}days 365 \PYGZbs{}
    \PYGZhy{}extfile extensions.kdc \PYGZhy{}extensions kdc\PYGZus{}cert \PYGZhy{}CAcreateserial
rm kdc.req
\end{Verbatim}

The second command will ask for the values of certificate fields,
which can be set to any values.  In the third command, substitute your
KDC's realm name for YOUR\_REALMNAME.  You can adjust the certificate's
expiration date by changing the number after \code{-days}.  Remember to
create a new KDC certificate before the old one expires.

The result of this operation will be in two files, kdckey.pem and
kdc.pem.  Both files must be placed in the KDC's filesystem.
kdckey.pem, which contains the KDC's private key, must be carefully
protected.

If you examine the KDC certificate with \code{openssl x509 -in kdc.pem
-text -noout}, OpenSSL will not know how to display the KDC principal
name in the Subject Alternative Name extension, so it will appear as
\code{othername:\textless{}unsupported\textgreater{}}.  This is normal and does not mean
anything is wrong with the KDC certificate.


\subsection{Generating client certificates}
\label{admin/pkinit:generating-client-certificates}
PKINIT client certificates also must have some unusual certificate
fields.  To generate a client certificate with OpenSSL for a
single-component principal name, you will need an extensions file
(different from the KDC extensions file above) containing:

\begin{Verbatim}[commandchars=\\\{\}]
[client\PYGZus{}cert]
basicConstraints=CA:FALSE
keyUsage=digitalSignature,keyEncipherment,keyAgreement
extendedKeyUsage=1.3.6.1.5.2.3.4
subjectKeyIdentifier=hash
authorityKeyIdentifier=keyid,issuer
issuerAltName=issuer:copy
subjectAltName=otherName:1.3.6.1.5.2.2;SEQUENCE:princ\PYGZus{}name

[princ\PYGZus{}name]
realm=EXP:0,GeneralString:\PYGZdl{}\PYGZob{}ENV::REALM\PYGZcb{}
principal\PYGZus{}name=EXP:1,SEQUENCE:principal\PYGZus{}seq

[principal\PYGZus{}seq]
name\PYGZus{}type=EXP:0,INTEGER:1
name\PYGZus{}string=EXP:1,SEQUENCE:principals

[principals]
princ1=GeneralString:\PYGZdl{}\PYGZob{}ENV::CLIENT\PYGZcb{}
\end{Verbatim}

If the above contents are placed in extensions.client, you can
generate and sign a client certificate with the following commands:

\begin{Verbatim}[commandchars=\\\{\}]
openssl genrsa \PYGZhy{}out clientkey.pem 2048
openssl req \PYGZhy{}new \PYGZhy{}key clientkey.pem \PYGZhy{}out client.req
env REALM=YOUR\PYGZus{}REALMNAME CLIENT=YOUR\PYGZus{}PRINCNAME openssl x509 \PYGZbs{}
    \PYGZhy{}CAkey cakey.pem \PYGZhy{}CA cacert.pem \PYGZhy{}req \PYGZhy{}in client.req \PYGZbs{}
    \PYGZhy{}extensions client\PYGZus{}cert \PYGZhy{}extfile extensions.client \PYGZbs{}
    \PYGZhy{}days 365 \PYGZhy{}out client.pem
rm client.req
\end{Verbatim}

Normally, the first two commands should be run on the client host, and
the resulting client.req file transferred to the certificate authority
host for the third command.  As in the previous steps, the second
command will ask for the values of certificate fields, which can be
set to any values.  In the third command, substitute your realm's name
for YOUR\_REALMNAME and the client's principal name (without realm) for
YOUR\_PRINCNAME.  You can adjust the certificate's expiration date by
changing the number after \code{-days}.

The result of this operation will be two files, clientkey.pem and
client.pem.  Both files must be present on the client's host;
clientkey.pem, which contains the client's private key, must be
protected from access by others.

As in the KDC certificate, OpenSSL will display the client principal
name as \code{othername:\textless{}unsupported\textgreater{}} in the Subject Alternative Name
extension of a PKINIT client certificate.

If the client principal name contains more than one component
(e.g. \code{host/example.com@REALM}), the \code{{[}principals{]}} section of
\code{extensions.client} must be altered to contain multiple entries.
(Simply setting \code{CLIENT} to \code{host/example.com} would generate a
certificate for \code{host\textbackslash{}/example.com@REALM} which would not match the
multi-component principal name.)  For a two-component principal, the
section should read:

\begin{Verbatim}[commandchars=\\\{\}]
[principals]
princ1=GeneralString:\PYGZdl{}\PYGZob{}ENV::CLIENT1\PYGZcb{}
princ2=GeneralString:\PYGZdl{}\PYGZob{}ENV::CLIENT2\PYGZcb{}
\end{Verbatim}

The environment variables \code{CLIENT1} and \code{CLIENT2} must then be set
to the first and second components when running \code{openssl x509}.


\section{Configuring the KDC}
\label{admin/pkinit:configuring-the-kdc}
The KDC must have filesystem access to the KDC certificate (kdc.pem)
and the KDC private key (kdckey.pem).  Configure the following
relation in the KDC's {\hyperref[admin/conf_files/kdc_conf:kdc-conf-5]{\emph{kdc.conf}}} file, either in the
{\hyperref[admin/conf_files/kdc_conf:kdcdefaults]{\emph{{[}kdcdefaults{]}}}} section or in a {\hyperref[admin/conf_files/kdc_conf:kdc-realms]{\emph{{[}realms{]}}}} subsection (with
appropriate pathnames):

\begin{Verbatim}[commandchars=\\\{\}]
pkinit\PYGZus{}identity = FILE:/var/lib/krb5kdc/kdc.pem,/var/lib/krb5kdc/kdckey.pem
\end{Verbatim}

If any clients will authenticate using regular (as opposed to
anonymous) PKINIT, the KDC must also have filesystem access to the CA
certificate (cacert.pem), and the following configuration (with the
appropriate pathname):

\begin{Verbatim}[commandchars=\\\{\}]
pkinit\PYGZus{}anchors = FILE:/var/lib/krb5kdc/cacert.pem
\end{Verbatim}

Because of the larger size of requests and responses using PKINIT, you
may also need to allow TCP access to the KDC:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n}{kdc\PYGZus{}tcp\PYGZus{}listen} \PYG{o}{=} \PYG{l+m+mi}{88}
\end{Verbatim}

Restart the {\hyperref[admin/admin_commands/krb5kdc:krb5kdc-8]{\emph{krb5kdc}}} daemon to pick up the configuration
changes.

The principal entry for each PKINIT-using client must be configured to
require preauthentication.  Ensure this with the command:

\begin{Verbatim}[commandchars=\\\{\}]
kadmin \PYGZhy{}q \PYGZsq{}modprinc +requires\PYGZus{}preauth YOUR\PYGZus{}PRINCNAME\PYGZsq{}
\end{Verbatim}

Starting with release 1.12, it is possible to remove the long-term
keys of a principal entry, which can save some space in the database
and help to clarify some PKINIT-related error conditions by not asking
for a password:

\begin{Verbatim}[commandchars=\\\{\}]
kadmin \PYGZhy{}q \PYGZsq{}purgekeys \PYGZhy{}all YOUR\PYGZus{}PRINCNAME\PYGZsq{}
\end{Verbatim}

These principal options can also be specified at principal creation
time as follows:

\begin{Verbatim}[commandchars=\\\{\}]
kadmin \PYGZhy{}q \PYGZsq{}add\PYGZus{}principal +requires\PYGZus{}preauth \PYGZhy{}nokey YOUR\PYGZus{}PRINCNAME\PYGZsq{}
\end{Verbatim}


\section{Configuring the clients}
\label{admin/pkinit:configuring-the-clients}
Client hosts must be configured to trust the issuing authority for the
KDC certificate.  For a newly established certificate authority, the
client host must have filesystem access to the CA certificate
(cacert.pem) and the following relation in {\hyperref[admin/conf_files/krb5_conf:krb5-conf-5]{\emph{krb5.conf}}} in the
appropriate {\hyperref[admin/conf_files/krb5_conf:realms]{\emph{{[}realms{]}}}} subsection (with appropriate pathnames):

\begin{Verbatim}[commandchars=\\\{\}]
pkinit\PYGZus{}anchors = FILE:/etc/krb5/cacert.pem
\end{Verbatim}

If the KDC certificate is a commercially issued server certificate,
the issuing certificate is most likely included in a system directory.
You can specify it by filename as above, or specify the whole
directory like so:

\begin{Verbatim}[commandchars=\\\{\}]
pkinit\PYGZus{}anchors = DIR:/etc/ssl/certs
\end{Verbatim}

A commercially issued server certificate will usually not have the
standard PKINIT principal name or Extended Key Usage extensions, so
the following additional configuration is required:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n}{pkinit\PYGZus{}eku\PYGZus{}checking} \PYG{o}{=} \PYG{n}{kpServerAuth}
\PYG{n}{pkinit\PYGZus{}kdc\PYGZus{}hostname} \PYG{o}{=} \PYG{n}{hostname}\PYG{o}{.}\PYG{n}{of}\PYG{o}{.}\PYG{n}{kdc}\PYG{o}{.}\PYG{n}{certificate}
\end{Verbatim}

Multiple \textbf{pkinit\_kdc\_hostname} relations can be configured to
recognize multiple KDC certificates.  If the KDC is an Active
Directory domain controller, setting \textbf{pkinit\_kdc\_hostname} is
necessary, but it should not be necessary to set
\textbf{pkinit\_eku\_checking}.

To perform regular (as opposed to anonymous) PKINIT authentication, a
client host must have filesystem access to a client certificate
(client.pem), and the corresponding private key (clientkey.pem).
Configure the following relations in the client host's
{\hyperref[admin/conf_files/krb5_conf:krb5-conf-5]{\emph{krb5.conf}}} file in the appropriate {\hyperref[admin/conf_files/krb5_conf:realms]{\emph{{[}realms{]}}}} subsection
(with appropriate pathnames):

\begin{Verbatim}[commandchars=\\\{\}]
pkinit\PYGZus{}identities = FILE:/etc/krb5/client.pem,/etc/krb5/clientkey.pem
\end{Verbatim}

If the KDC and client are properly configured, it should now be
possible to run \code{kinit username} without entering a password.


\section{Anonymous PKINIT}
\label{admin/pkinit:anonymous-pkinit}\label{admin/pkinit:id1}
Anonymity support in Kerberos allows a client to obtain a ticket
without authenticating as any particular principal.  Such a ticket can
be used as a FAST armor ticket, or to securely communicate with an
application server anonymously.

To configure anonymity support, you must generate or otherwise procure
a KDC certificate and configure the KDC host, but you do not need to
generate any client certificates.  On the KDC, you must set the
\textbf{pkinit\_identity} variable to provide the KDC certificate, but do
not need to set the \textbf{pkinit\_anchors} variable or store the issuing
certificate if you won't have any client certificates to verify.  On
client hosts, you must set the \textbf{pkinit\_anchors} variable (and
possibly \textbf{pkinit\_kdc\_hostname} and \textbf{pkinit\_eku\_checking}) in order
to trust the issuing authority for the KDC certificate, but do not
need to set the \textbf{pkinit\_identities} variable.

Anonymity support is not enabled by default.  To enable it, you must
create the principal \code{WELLKNOWN/ANONYMOUS} using the command:

\begin{Verbatim}[commandchars=\\\{\}]
kadmin \PYGZhy{}q \PYGZsq{}addprinc \PYGZhy{}randkey WELLKNOWN/ANONYMOUS\PYGZsq{}
\end{Verbatim}

Some Kerberos deployments include application servers which lack
proper access control, and grant some level of access to any user who
can authenticate.  In such an environment, enabling anonymity support
on the KDC would present a security issue.  If you need to enable
anonymity support for TGTs (for use as FAST armor tickets) without
enabling anonymous authentication to application servers, you can set
the variable \textbf{restrict\_anonymous\_to\_tgt} to \code{true} in the
appropriate {\hyperref[admin/conf_files/kdc_conf:kdc-realms]{\emph{{[}realms{]}}}} subsection of the KDC's
{\hyperref[admin/conf_files/kdc_conf:kdc-conf-5]{\emph{kdc.conf}}} file.

To obtain anonymous credentials on a client, run \code{kinit -n}, or
\code{kinit -n @REALMNAME} to specify a realm.  The resulting tickets
will have the client name \code{WELLKNOWN/ANONYMOUS@WELLKNOWN:ANONYMOUS}.


\chapter{OTP Preauthentication}
\label{admin/otp::doc}\label{admin/otp:otp-preauthentication}\label{admin/otp:otp-preauth}
OTP is a preauthentication mechanism for Kerberos 5 which uses One
Time Passwords (OTP) to authenticate the client to the KDC.  The OTP
is passed to the KDC over an encrypted FAST channel in clear-text.
The KDC uses the password along with per-user configuration to proxy
the request to a third-party RADIUS system.  This enables
out-of-the-box compatibility with a large number of already widely
deployed proprietary systems.

Additionally, our implementation of the OTP system allows for the
passing of RADIUS requests over a UNIX domain stream socket.  This
permits the use of a local companion daemon which can handle the
details of authentication.


\section{Defining token types}
\label{admin/otp:defining-token-types}
Token types are defined in either {\hyperref[admin/conf_files/krb5_conf:krb5-conf-5]{\emph{krb5.conf}}} or
{\hyperref[admin/conf_files/kdc_conf:kdc-conf-5]{\emph{kdc.conf}}} according to the following format:

\begin{Verbatim}[commandchars=\\\{\}]
[otp]
    \PYGZlt{}name\PYGZgt{} = \PYGZob{}
        server = \PYGZlt{}host:port or filename\PYGZgt{} (default: see below)
        secret = \PYGZlt{}filename\PYGZgt{}
        timeout = \PYGZlt{}integer\PYGZgt{} (default: 5 [seconds])
        retries = \PYGZlt{}integer\PYGZgt{} (default: 3)
        strip\PYGZus{}realm = \PYGZlt{}boolean\PYGZgt{} (default: true)
        indicator = \PYGZlt{}string\PYGZgt{} (default: none)
    \PYGZcb{}
\end{Verbatim}

If the server field begins with `/', it will be interpreted as a UNIX
socket.  Otherwise, it is assumed to be in the format host:port.  When
a UNIX domain socket is specified, the secret field is optional and an
empty secret is used by default.  If the server field is not
specified, it defaults to {\hyperref[mitK5defaults:paths]{\emph{RUNSTATEDIR}}}\code{/krb5kdc}\code{/\textless{}name\textgreater{}.socket}.

When forwarding the request over RADIUS, by default the principal is
used in the User-Name attribute of the RADIUS packet.  The strip\_realm
parameter controls whether the principal is forwarded with or without
the realm portion.

If an indicator field is present, tickets issued using this token type
will be annotated with the specified authentication indicator (see
{\hyperref[admin/auth_indicator:auth-indicator]{\emph{Authentication indicators}}}).  This key may be specified multiple times to
add multiple indicators.


\section{The default token type}
\label{admin/otp:the-default-token-type}
A default token type is used internally when no token type is specified for a
given user.  It is defined as follows:

\begin{Verbatim}[commandchars=\\\{\}]
[otp]
    DEFAULT = \PYGZob{}
        strip\PYGZus{}realm = false
    \PYGZcb{}
\end{Verbatim}

The administrator may override the internal \code{DEFAULT} token type
simply by defining a configuration with the same name.


\section{Token instance configuration}
\label{admin/otp:token-instance-configuration}
To enable OTP for a client principal, the administrator must define
the \textbf{otp} string attribute for that principal.  (See
{\hyperref[admin/admin_commands/kadmin_local:set-string]{\emph{set\_string}}}.)  The \textbf{otp} user string is a JSON string of the
format:

\begin{Verbatim}[commandchars=\\\{\}]
[\PYGZob{}
    \PYGZdq{}type\PYGZdq{}: \PYG{n+nt}{\PYGZlt{}string}\PYG{n+nt}{\PYGZgt{}},
    \PYGZdq{}username\PYGZdq{}: \PYG{n+nt}{\PYGZlt{}string}\PYG{n+nt}{\PYGZgt{}},
    \PYGZdq{}indicators\PYGZdq{}: [\PYG{n+nt}{\PYGZlt{}string}\PYG{n+nt}{\PYGZgt{}}, ...]
 \PYGZcb{}, ...]
\end{Verbatim}

This is an array of token objects.  Both fields of token objects are
optional.  The \textbf{type} field names the token type of this token; if
not specified, it defaults to \code{DEFAULT}.  The \textbf{username} field
specifies the value to be sent in the User-Name RADIUS attribute.  If
not specified, the principal name is sent, with or without realm as
defined in the token type.  The \textbf{indicators} field specifies a list
of authentication indicators to annotate tickets with, overriding any
indicators specified in the token type.

For ease of configuration, an empty array (\code{{[}{]}}) is treated as
equivalent to one DEFAULT token (\code{{[}\{\}{]}}).


\section{Other considerations}
\label{admin/otp:other-considerations}\begin{enumerate}
\item {} 
FAST is required for OTP to work.

\end{enumerate}


\chapter{Principal names and DNS}
\label{admin/princ_dns:principal-names-and-dns}\label{admin/princ_dns::doc}
Kerberos clients can do DNS lookups to canonicalize service principal
names.  This can cause difficulties when setting up Kerberos
application servers, especially when the client's name for the service
is different from what the service thinks its name is.


\section{Service principal names}
\label{admin/princ_dns:service-principal-names}
A frequently used kind of principal name is the host-based service
principal name.  This kind of principal name has two components: a
service name and a hostname.  For example, \code{imap/imap.example.com}
is the principal name of the ``imap'' service on the host
``imap.example.com''.  Other possible service names for the first
component include ``host'' (remote login services such as ssh), ``HTTP'',
and ``nfs'' (Network File System).

Service administrators often publish well-known hostname aliases that
they would prefer users to use instead of the canonical name of the
service host.  This gives service administrators more flexibility in
deploying services.  For example, a shell login server might be named
``long-vanity-hostname.example.com'', but users will naturally prefer to
type something like ``login.example.com''.  Hostname aliases also allow
for administrators to set up load balancing for some sorts of services
based on rotating \code{CNAME} records in DNS.


\section{Service principal canonicalization}
\label{admin/princ_dns:service-principal-canonicalization}
MIT Kerberos clients currently always do forward resolution (looking
up the IPv4 and possibly IPv6 addresses using \code{getaddrinfo()}) of
the hostname part of a host-based service principal to canonicalize
the hostname.  They obtain the ``canonical'' name of the host when doing
so.  By default, MIT Kerberos clients will also then do reverse DNS
resolution (looking up the hostname associated with the IPv4 or IPv6
address using \code{getnameinfo()}) of the hostname.  Using the
{\hyperref[admin/conf_files/krb5_conf:krb5-conf-5]{\emph{krb5.conf}}} setting:

\begin{Verbatim}[commandchars=\\\{\}]
[libdefaults]
    rdns = false
\end{Verbatim}

will disable reverse DNS lookup on clients.  The default setting is
``true''.

Operating system bugs may prevent a setting of \code{rdns = false} from
disabling reverse DNS lookup.  Some versions of GNU libc have a bug in
\code{getaddrinfo()} that cause them to look up \code{PTR} records even when
not required.  MIT Kerberos releases krb5-1.10.2 and newer have a
workaround for this problem, as does the krb5-1.9.x series as of
release krb5-1.9.4.


\section{Reverse DNS mismatches}
\label{admin/princ_dns:reverse-dns-mismatches}
Sometimes, an enterprise will have control over its forward DNS but
not its reverse DNS.  The reverse DNS is sometimes under the control
of the Internet service provider of the enterprise, and the enterprise
may not have much influence in setting up reverse DNS records for its
address space.  If there are difficulties with getting forward and
reverse DNS to match, it is best to set \code{rdns = false} on client
machines.


\section{Overriding application behavior}
\label{admin/princ_dns:overriding-application-behavior}
Applications can choose to use a default hostname component in their
service principal name when accepting authentication, which avoids
some sorts of hostname mismatches.  Because not all relevant
applications do this yet, using the {\hyperref[admin/conf_files/krb5_conf:krb5-conf-5]{\emph{krb5.conf}}} setting:

\begin{Verbatim}[commandchars=\\\{\}]
[libdefaults]
    ignore\PYGZus{}acceptor\PYGZus{}hostname = true
\end{Verbatim}

will allow the Kerberos library to override the application's choice
of service principal hostname and will allow a server program to
accept incoming authentications using any key in its keytab that
matches the service name and realm name (if given).  This setting
defaults to ``false'' and is available in releases krb5-1.10 and later.


\section{Provisioning keytabs}
\label{admin/princ_dns:provisioning-keytabs}
One service principal entry that should be in the keytab is a
principal whose hostname component is the canonical hostname that
\code{getaddrinfo()} reports for all known aliases for the host.  If the
reverse DNS information does not match this canonical hostname, an
additional service principal entry should be in the keytab for this
different hostname.


\section{Specific application advice}
\label{admin/princ_dns:specific-application-advice}

\subsection{Secure shell (ssh)}
\label{admin/princ_dns:secure-shell-ssh}
Setting \code{GSSAPIStrictAcceptorCheck = no} in the configuration file
of modern versions of the openssh daemon will allow the daemon to try
any key in its keytab when accepting a connection, rather than looking
for the keytab entry that matches the host's own idea of its name
(typically the name that \code{gethostname()} returns).  This requires
krb5-1.10 or later.


\chapter{Encryption types}
\label{admin/enctypes:enctypes}\label{admin/enctypes::doc}\label{admin/enctypes:encryption-types}
Kerberos can use a variety of cipher algorithms to protect data.  A
Kerberos \textbf{encryption type} (also known as an \textbf{enctype}) is a
specific combination of a cipher algorithm with an integrity algorithm
to provide both confidentiality and integrity to data.


\section{Enctypes in requests}
\label{admin/enctypes:enctypes-in-requests}
Clients make two types of requests (KDC-REQ) to the KDC: AS-REQs and
TGS-REQs.  The client uses the AS-REQ to obtain initial tickets
(typically a Ticket-Granting Ticket (TGT)), and uses the TGS-REQ to
obtain service tickets.

The KDC uses three different keys when issuing a ticket to a client:
\begin{itemize}
\item {} 
The long-term key of the service: the KDC uses this to encrypt the
actual service ticket.  The KDC only uses the first long-term key in
the most recent kvno for this purpose.

\item {} 
The session key: the KDC randomly chooses this key and places one
copy inside the ticket and the other copy inside the encrypted part
of the reply.

\item {} 
The reply-encrypting key: the KDC uses this to encrypt the reply it
sends to the client.  For AS replies, this is a long-term key of the
client principal.  For TGS replies, this is either the session key of the
authenticating ticket, or a subsession key.

\end{itemize}

Each of these keys is of a specific enctype.

Each request type allows the client to submit a list of enctypes that
it is willing to accept.  For the AS-REQ, this list affects both the
session key selection and the reply-encrypting key selection.  For the
TGS-REQ, this list only affects the session key selection.


\section{Session key selection}
\label{admin/enctypes:session-key-selection}\label{admin/enctypes:id1}
The KDC chooses the session key enctype by taking the intersection of
its \textbf{permitted\_enctypes} list, the list of long-term keys for the
most recent kvno of the service, and the client's requested list of
enctypes.  If \textbf{allow\_weak\_crypto} is true, all services are assumed
to support des-cbc-crc.

Starting in krb5-1.11, \textbf{des\_crc\_session\_supported} in
{\hyperref[admin/conf_files/kdc_conf:kdc-conf-5]{\emph{kdc.conf}}} allows additional control over whether the KDC
issues des-cbc-crc session keys.

Also starting in krb5-1.11, it is possible to set a string attribute
on a service principal to control what session key enctypes the KDC
may issue for service tickets for that principal.  See
{\hyperref[admin/admin_commands/kadmin_local:set-string]{\emph{set\_string}}} in {\hyperref[admin/admin_commands/kadmin_local:kadmin-1]{\emph{kadmin}}} for details.


\section{Choosing enctypes for a service}
\label{admin/enctypes:choosing-enctypes-for-a-service}
Generally, a service should have a key of the strongest
enctype that both it and the KDC support.  If the KDC is running a
release earlier than krb5-1.11, it is also useful to generate an
additional key for each enctype that the service can support.  The KDC
will only use the first key in the list of long-term keys for encrypting
the service ticket, but the additional long-term keys indicate the
other enctypes that the service supports.

As noted above, starting with release krb5-1.11, there are additional
configuration settings that control session key enctype selection
independently of the set of long-term keys that the KDC has stored for
a service principal.


\section{Configuration variables}
\label{admin/enctypes:configuration-variables}
The following \code{{[}libdefaults{]}} settings in {\hyperref[admin/conf_files/krb5_conf:krb5-conf-5]{\emph{krb5.conf}}} will
affect how enctypes are chosen.
\begin{description}
\item[{\textbf{allow\_weak\_crypto}}] \leavevmode
defaults to \emph{false} starting with krb5-1.8.  When \emph{false}, removes
single-DES enctypes (and other weak enctypes) from
\textbf{permitted\_enctypes}, \textbf{default\_tkt\_enctypes}, and
\textbf{default\_tgs\_enctypes}.  Do not set this to \emph{true} unless the
use of weak enctypes is an acceptable risk for your environment
and the weak enctypes are required for backward compatibility.

\item[{\textbf{permitted\_enctypes}}] \leavevmode
controls the set of enctypes that a service will accept as session
keys.

\item[{\textbf{default\_tkt\_enctypes}}] \leavevmode
controls the default set of enctypes that the Kerberos client
library requests when making an AS-REQ.  Do not set this unless
required for specific backward compatibility purposes; stale
values of this setting can prevent clients from taking advantage
of new stronger enctypes when the libraries are upgraded.

\item[{\textbf{default\_tgs\_enctypes}}] \leavevmode
controls the default set of enctypes that the Kerberos client
library requests when making a TGS-REQ.  Do not set this unless
required for specific backward compatibility purposes; stale
values of this setting can prevent clients from taking advantage
of new stronger enctypes when the libraries are upgraded.

\end{description}

The following per-realm setting in {\hyperref[admin/conf_files/kdc_conf:kdc-conf-5]{\emph{kdc.conf}}} affects the
generation of long-term keys.
\begin{description}
\item[{\textbf{supported\_enctypes}}] \leavevmode
controls the default set of enctype-salttype pairs that {\hyperref[admin/admin_commands/kadmind:kadmind-8]{\emph{kadmind}}}
will use for generating long-term keys, either randomly or from
passwords

\end{description}


\section{Enctype compatibility}
\label{admin/enctypes:enctype-compatibility}
See {\hyperref[admin/conf_files/kdc_conf:encryption-types]{\emph{Encryption types}}} for additional information about enctypes.

\begin{tabulary}{\linewidth}{|L|L|L|L|}
\hline
\textsf{\relax 
enctype
} & \textsf{\relax 
weak?
} & \textsf{\relax 
krb5
} & \textsf{\relax 
Windows
}\\
\hline
des-cbc-crc
 & 
weak
 & 
all
 & 
\textgreater{}=2000
\\
\hline
des-cbc-md4
 & 
weak
 & 
all
 & 
?
\\
\hline
des-cbc-md5
 & 
weak
 & 
all
 & 
\textgreater{}=2000
\\
\hline
des3-cbc-sha1
 &  & 
\textgreater{}=1.1
 & 
none
\\
\hline
arcfour-hmac
 &  & 
\textgreater{}=1.3
 & 
\textgreater{}=2000
\\
\hline
arcfour-hmac-exp
 & 
weak
 & 
\textgreater{}=1.3
 & 
\textgreater{}=2000
\\
\hline
aes128-cts-hmac-sha1-96
 &  & 
\textgreater{}=1.3
 & 
\textgreater{}=Vista
\\
\hline
aes256-cts-hmac-sha1-96
 &  & 
\textgreater{}=1.3
 & 
\textgreater{}=Vista
\\
\hline
aes128-cts-hmac-sha256-128
 &  & 
\textgreater{}=1.15
 & 
none
\\
\hline
aes256-cts-hmac-sha384-192
 &  & 
\textgreater{}=1.15
 & 
none
\\
\hline
camellia128-cts-cmac
 &  & 
\textgreater{}=1.9
 & 
none
\\
\hline
camellia256-cts-cmac
 &  & 
\textgreater{}=1.9
 & 
none
\\
\hline\end{tabulary}


krb5 releases 1.8 and later disable the single-DES enctypes by
default.  Microsoft Windows releases Windows 7 and later disable
single-DES enctypes by default.


\chapter{HTTPS proxy configuration}
\label{admin/https:https-proxy-configuration}\label{admin/https::doc}\label{admin/https:https}
In addition to being able to use UDP or TCP to communicate directly
with a KDC as is outlined in RFC4120, and with kpasswd services in a
similar fashion, the client libraries can attempt to use an HTTPS
proxy server to communicate with a KDC or kpasswd service, using the
protocol outlined in {[}MS-KKDCP{]}.

Communicating with a KDC through an HTTPS proxy allows clients to
contact servers when network firewalls might otherwise prevent them
from doing so.  The use of TLS also encrypts all traffic between the
clients and the KDC, preventing observers from conducting password
dictionary attacks or from observing the client and server principals
being authenticated, at additional computational cost to both clients
and servers.

An HTTPS proxy server is provided as a feature in some versions of
Microsoft Windows Server, and a WSGI implementation named \emph{kdcproxy}
is available in the python package index.


\section{Configuring the clients}
\label{admin/https:configuring-the-clients}
To use an HTTPS proxy, a client host must trust the CA which issued
that proxy's SSL certificate.  If that CA's certificate is not in the
system-wide default set of trusted certificates, configure the
following relation in the client host's {\hyperref[admin/conf_files/krb5_conf:krb5-conf-5]{\emph{krb5.conf}}} file in
the appropriate {\hyperref[admin/conf_files/krb5_conf:realms]{\emph{{[}realms{]}}}} subsection:

\begin{Verbatim}[commandchars=\\\{\}]
http\PYGZus{}anchors = FILE:/etc/krb5/cacert.pem
\end{Verbatim}

Adjust the pathname to match the path of the file which contains a
copy of the CA's certificate.  The \emph{http\_anchors} option is documented
more fully in {\hyperref[admin/conf_files/krb5_conf:krb5-conf-5]{\emph{krb5.conf}}}.

Configure the client to access the KDC and kpasswd service by
specifying their locations in its {\hyperref[admin/conf_files/krb5_conf:krb5-conf-5]{\emph{krb5.conf}}} file in the form
of HTTPS URLs for the proxy server:

\begin{Verbatim}[commandchars=\\\{\}]
kdc = https://server.fqdn/KdcProxy
kpasswd\PYGZus{}server = https://server.fqdn/KdcProxy
\end{Verbatim}

If the proxy and client are properly configured, client commands such
as \code{kinit}, \code{kvno}, and \code{kpasswd} should all function normally.


\chapter{Authentication indicators}
\label{admin/auth_indicator:auth-indicator}\label{admin/auth_indicator:authentication-indicators}\label{admin/auth_indicator::doc}
As of release 1.14, the KDC can be configured to annotate tickets if
the client authenticated using a stronger preauthentication mechanism
such as {\hyperref[admin/pkinit:pkinit]{\emph{PKINIT}}} or {\hyperref[admin/otp:otp-preauth]{\emph{OTP}}}.  These
annotations are called ``authentication indicators.''  Service
principals can be configured to require particular authentication
indicators in order to authenticate to that service.  An
authentication indicator value can be any string chosen by the KDC
administrator; there are no pre-set values.

To use authentication indicators with PKINIT or OTP, first configure
the KDC to include an indicator when that preauthentication mechanism
is used.  For PKINIT, use the \textbf{pkinit\_indicator} variable in
{\hyperref[admin/conf_files/kdc_conf:kdc-conf-5]{\emph{kdc.conf}}}.  For OTP, use the \textbf{indicator} variable in the
token type definition, or specify the indicators in the \textbf{otp} user
string as described in {\hyperref[admin/otp:otp-preauth]{\emph{OTP Preauthentication}}}.

To require an indicator to be present in order to authenticate to a
service principal, set the \textbf{require\_auth} string attribute on the
principal to the indicator value to be required.  If you wish to allow
one of several indicators to be accepted, you can specify multiple
indicator values separated by spaces.

For example, a realm could be configured to set the authentication
indicator value ``strong'' when PKINIT is used to authenticate, using a
setting in the {\hyperref[admin/conf_files/kdc_conf:kdc-realms]{\emph{{[}realms{]}}}} subsection:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n}{pkinit\PYGZus{}indicator} \PYG{o}{=} \PYG{n}{strong}
\end{Verbatim}

A service principal could be configured to require the ``strong''
authentication indicator value:

\begin{Verbatim}[commandchars=\\\{\}]
\PYGZdl{} kadmin setstr host/high.value.server require\PYGZus{}auth strong
Password for user/admin@KRBTEST.COM:
\end{Verbatim}

A user who authenticates with PKINIT would be able to obtain a ticket
for the service principal:

\begin{Verbatim}[commandchars=\\\{\}]
\PYGZdl{} kinit \PYGZhy{}X X509\PYGZus{}user\PYGZus{}identity=FILE:/my/cert.pem,/my/key.pem user
\PYGZdl{} kvno host/high.value.server
host/high.value.server@KRBTEST.COM: kvno = 1
\end{Verbatim}

but a user who authenticates with a password would not:

\begin{Verbatim}[commandchars=\\\{\}]
\PYGZdl{} kinit user
Password for user@KRBTEST.COM:
\PYGZdl{} kvno host/high.value.server
kvno: KDC policy rejects request while getting credentials for
  host/high.value.server@KRBTEST.COM
\end{Verbatim}

GSSAPI server applications can inspect authentication indicators
through the \emph{auth-indicators} name
attribute.


\chapter{Administration  programs}
\label{admin/admin_commands/index:administration-programs}\label{admin/admin_commands/index::doc}

\section{kadmin}
\label{admin/admin_commands/kadmin_local::doc}\label{admin/admin_commands/kadmin_local:kadmin}\label{admin/admin_commands/kadmin_local:kadmin-1}

\subsection{SYNOPSIS}
\label{admin/admin_commands/kadmin_local:synopsis}\phantomsection\label{admin/admin_commands/kadmin_local:kadmin-synopsis}
\textbf{kadmin}
{[}\textbf{-O}\textbar{}\textbf{-N}{]}
{[}\textbf{-r} \emph{realm}{]}
{[}\textbf{-p} \emph{principal}{]}
{[}\textbf{-q} \emph{query}{]}
{[}{[}\textbf{-c} \emph{cache\_name}{]}\textbar{}{[}\textbf{-k} {[}\textbf{-t} \emph{keytab}{]}{]}\textbar{}\textbf{-n}{]}
{[}\textbf{-w} \emph{password}{]}
{[}\textbf{-s} \emph{admin\_server}{[}:\emph{port}{]}{]}
{[}command args...{]}

\textbf{kadmin.local}
{[}\textbf{-r} \emph{realm}{]}
{[}\textbf{-p} \emph{principal}{]}
{[}\textbf{-q} \emph{query}{]}
{[}\textbf{-d} \emph{dbname}{]}
{[}\textbf{-e} \emph{enc}:\emph{salt} ...{]}
{[}\textbf{-m}{]}
{[}\textbf{-x} \emph{db\_args}{]}
{[}command args...{]}


\subsection{DESCRIPTION}
\label{admin/admin_commands/kadmin_local:kadmin-synopsis-end}\label{admin/admin_commands/kadmin_local:description}
kadmin and kadmin.local are command-line interfaces to the Kerberos V5
administration system.  They provide nearly identical functionalities;
the difference is that kadmin.local directly accesses the KDC
database, while kadmin performs operations using {\hyperref[admin/admin_commands/kadmind:kadmind-8]{\emph{kadmind}}}.
Except as explicitly noted otherwise, this man page will use ``kadmin''
to refer to both versions.  kadmin provides for the maintenance of
Kerberos principals, password policies, and service key tables
(keytabs).

The remote kadmin client uses Kerberos to authenticate to kadmind
using the service principal \code{kadmin/ADMINHOST} (where \emph{ADMINHOST} is
the fully-qualified hostname of the admin server) or \code{kadmin/admin}.
If the credentials cache contains a ticket for one of these
principals, and the \textbf{-c} credentials\_cache option is specified, that
ticket is used to authenticate to kadmind.  Otherwise, the \textbf{-p} and
\textbf{-k} options are used to specify the client Kerberos principal name
used to authenticate.  Once kadmin has determined the principal name,
it requests a service ticket from the KDC, and uses that service
ticket to authenticate to kadmind.

Since kadmin.local directly accesses the KDC database, it usually must
be run directly on the master KDC with sufficient permissions to read
the KDC database.  If the KDC database uses the LDAP database module,
kadmin.local can be run on any host which can access the LDAP server.


\subsection{OPTIONS}
\label{admin/admin_commands/kadmin_local:options}\phantomsection\label{admin/admin_commands/kadmin_local:kadmin-options}\begin{description}
\item[{\textbf{-r} \emph{realm}}] \leavevmode
Use \emph{realm} as the default database realm.

\item[{\textbf{-p} \emph{principal}}] \leavevmode
Use \emph{principal} to authenticate.  Otherwise, kadmin will append
\code{/admin} to the primary principal name of the default ccache,
the value of the \textbf{USER} environment variable, or the username as
obtained with getpwuid, in order of preference.

\item[{\textbf{-k}}] \leavevmode
Use a keytab to decrypt the KDC response instead of prompting for
a password.  In this case, the default principal will be
\code{host/hostname}.  If there is no keytab specified with the
\textbf{-t} option, then the default keytab will be used.

\item[{\textbf{-t} \emph{keytab}}] \leavevmode
Use \emph{keytab} to decrypt the KDC response.  This can only be used
with the \textbf{-k} option.

\item[{\textbf{-n}}] \leavevmode
Requests anonymous processing.  Two types of anonymous principals
are supported.  For fully anonymous Kerberos, configure PKINIT on
the KDC and configure \textbf{pkinit\_anchors} in the client's
{\hyperref[admin/conf_files/krb5_conf:krb5-conf-5]{\emph{krb5.conf}}}.  Then use the \textbf{-n} option with a principal
of the form \code{@REALM} (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{kinit
-n} 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.

\item[{\textbf{-c} \emph{credentials\_cache}}] \leavevmode
Use \emph{credentials\_cache} as the credentials cache.  The
cache should contain a service ticket for the \code{kadmin/ADMINHOST}
(where \emph{ADMINHOST} is the fully-qualified hostname of the admin
server) or \code{kadmin/admin} service; it can be acquired with the
\emph{kinit(1)} program.  If this option is not specified, kadmin
requests a new service ticket from the KDC, and stores it in its
own temporary ccache.

\item[{\textbf{-w} \emph{password}}] \leavevmode
Use \emph{password} 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.

\item[{\textbf{-q} \emph{query}}] \leavevmode
Perform the specified query and then exit.

\item[{\textbf{-d} \emph{dbname}}] \leavevmode
Specifies the name of the KDC database.  This option does not
apply to the LDAP database module.

\item[{\textbf{-s} \emph{admin\_server}{[}:\emph{port}{]}}] \leavevmode
Specifies the admin server which kadmin should contact.

\item[{\textbf{-m}}] \leavevmode
If using kadmin.local, prompt for the database master password
instead of reading it from a stash file.

\item[{\textbf{-e} ``\emph{enc}:\emph{salt} ...''}] \leavevmode
Sets the keysalt list to be used for any new keys created.  See
{\hyperref[admin/conf_files/kdc_conf:keysalt-lists]{\emph{Keysalt lists}}} in {\hyperref[admin/conf_files/kdc_conf:kdc-conf-5]{\emph{kdc.conf}}} for a list of possible
values.

\item[{\textbf{-O}}] \leavevmode
Force use of old AUTH\_GSSAPI authentication flavor.

\item[{\textbf{-N}}] \leavevmode
Prevent fallback to AUTH\_GSSAPI authentication flavor.

\item[{\textbf{-x} \emph{db\_args}}] \leavevmode
Specifies the database specific arguments.  See the next section
for supported options.

\end{description}
\phantomsection\label{admin/admin_commands/kadmin_local:kadmin-options-end}
Starting with release 1.14, if any command-line arguments remain after
the options, they will be treated as a single query to be executed.
This mode of operation is intended for scripts and behaves differently
from the interactive mode in several respects:
\begin{itemize}
\item {} 
Query arguments are split by the shell, not by kadmin.

\item {} 
Informational and warning messages are suppressed.  Error messages
and query output (e.g. for \textbf{get\_principal}) will still be
displayed.

\item {} 
Confirmation prompts are disabled (as if \textbf{-force} was given).
Password prompts will still be issued as required.

\item {} 
The exit status will be non-zero if the query fails.

\end{itemize}

The \textbf{-q} option does not carry these behavior differences; the query
will be processed as if it was entered interactively.  The \textbf{-q}
option cannot be used in combination with a query in the remaining
arguments.


\subsection{DATABASE OPTIONS}
\label{admin/admin_commands/kadmin_local:database-options}\label{admin/admin_commands/kadmin_local:dboptions}
Database options can be used to override database-specific defaults.
Supported options for the DB2 module are:
\begin{quote}
\begin{description}
\item[{\textbf{-x dbname=}*filename*}] \leavevmode
Specifies the base filename of the DB2 database.

\item[{\textbf{-x lockiter}}] \leavevmode
Make iteration operations hold the lock for the duration of
the entire operation, rather than temporarily releasing the
lock while handling each principal.  This is the default
behavior, but this option exists to allow command line
override of a {[}dbmodules{]} setting.  First introduced in
release 1.13.

\item[{\textbf{-x unlockiter}}] \leavevmode
Make iteration operations unlock the database for each
principal, instead of holding the lock for the duration of the
entire operation.  First introduced in release 1.13.

\end{description}
\end{quote}

Supported options for the LDAP module are:
\begin{quote}
\begin{description}
\item[{\textbf{-x host=}\emph{ldapuri}}] \leavevmode
Specifies the LDAP server to connect to by a LDAP URI.

\item[{\textbf{-x binddn=}\emph{bind\_dn}}] \leavevmode
Specifies the DN used to bind to the LDAP server.

\item[{\textbf{-x bindpwd=}\emph{password}}] \leavevmode
Specifies the password or SASL secret used to bind to the LDAP
server.  Using this option may expose the password to other
users on the system via the process list; to avoid this,
instead stash the password using the \textbf{stashsrvpw} command of
{\hyperref[admin/admin_commands/kdb5_ldap_util:kdb5-ldap-util-8]{\emph{kdb5\_ldap\_util}}}.

\item[{\textbf{-x sasl\_mech=}\emph{mechanism}}] \leavevmode
Specifies the SASL mechanism used to bind to the LDAP server.
The bind DN is ignored if a SASL mechanism is used.  New in
release 1.13.

\item[{\textbf{-x sasl\_authcid=}\emph{name}}] \leavevmode
Specifies the authentication name used when binding to the
LDAP server with a SASL mechanism, if the mechanism requires
one.  New in release 1.13.

\item[{\textbf{-x sasl\_authzid=}\emph{name}}] \leavevmode
Specifies the authorization name used when binding to the LDAP
server with a SASL mechanism.  New in release 1.13.

\item[{\textbf{-x sasl\_realm=}\emph{realm}}] \leavevmode
Specifies the realm used when binding to the LDAP server with
a SASL mechanism, if the mechanism uses one.  New in release
1.13.

\item[{\textbf{-x debug=}\emph{level}}] \leavevmode
sets the OpenLDAP client library debug level.  \emph{level} is an
integer to be interpreted by the library.  Debugging messages
are printed to standard error.  New in release 1.12.

\end{description}
\end{quote}


\subsection{COMMANDS}
\label{admin/admin_commands/kadmin_local:commands}
When using the remote client, available commands may be restricted
according to the privileges specified in the {\hyperref[admin/conf_files/kadm5_acl:kadm5-acl-5]{\emph{kadm5.acl}}} file
on the admin server.


\subsubsection{add\_principal}
\label{admin/admin_commands/kadmin_local:add-principal}\label{admin/admin_commands/kadmin_local:id1}\begin{quote}

\textbf{add\_principal} {[}\emph{options}{]} \emph{newprinc}
\end{quote}

Creates the principal \emph{newprinc}, prompting twice for a password.  If
no password policy is specified with the \textbf{-policy} option, and the
policy named \code{default} is assigned to the principal if it exists.
However, creating a policy named \code{default} will not automatically
assign this policy to previously existing principals.  This policy
assignment can be suppressed with the \textbf{-clearpolicy} option.

This command requires the \textbf{add} privilege.

Aliases: \textbf{addprinc}, \textbf{ank}

Options:
\begin{description}
\item[{\textbf{-expire} \emph{expdate}}] \leavevmode
(\emph{getdate} string) The expiration date of the principal.

\item[{\textbf{-pwexpire} \emph{pwexpdate}}] \leavevmode
(\emph{getdate} string) The password expiration date.

\item[{\textbf{-maxlife} \emph{maxlife}}] \leavevmode
(\emph{duration} or \emph{getdate} string) The maximum ticket life
for the principal.

\item[{\textbf{-maxrenewlife} \emph{maxrenewlife}}] \leavevmode
(\emph{duration} or \emph{getdate} string) The maximum renewable
life of tickets for the principal.

\item[{\textbf{-kvno} \emph{kvno}}] \leavevmode
The initial key version number.

\item[{\textbf{-policy} \emph{policy}}] \leavevmode
The password policy used by this principal.  If not specified, the
policy \code{default} is used if it exists (unless \textbf{-clearpolicy}
is specified).

\item[{\textbf{-clearpolicy}}] \leavevmode
Prevents any policy from being assigned when \textbf{-policy} is not
specified.

\item[{\{-\textbar{}+\}\textbf{allow\_postdated}}] \leavevmode
\textbf{-allow\_postdated} prohibits this principal from obtaining
postdated tickets.  \textbf{+allow\_postdated} clears this flag.

\item[{\{-\textbar{}+\}\textbf{allow\_forwardable}}] \leavevmode
\textbf{-allow\_forwardable} prohibits this principal from obtaining
forwardable tickets.  \textbf{+allow\_forwardable} clears this flag.

\item[{\{-\textbar{}+\}\textbf{allow\_renewable}}] \leavevmode
\textbf{-allow\_renewable} prohibits this principal from obtaining
renewable tickets.  \textbf{+allow\_renewable} clears this flag.

\item[{\{-\textbar{}+\}\textbf{allow\_proxiable}}] \leavevmode
\textbf{-allow\_proxiable} prohibits this principal from obtaining
proxiable tickets.  \textbf{+allow\_proxiable} clears this flag.

\item[{\{-\textbar{}+\}\textbf{allow\_dup\_skey}}] \leavevmode
\textbf{-allow\_dup\_skey} disables user-to-user authentication for this
principal by prohibiting this principal from obtaining a session
key for another user.  \textbf{+allow\_dup\_skey} clears this flag.

\item[{\{-\textbar{}+\}\textbf{requires\_preauth}}] \leavevmode
\textbf{+requires\_preauth} requires this principal to preauthenticate
before being allowed to kinit.  \textbf{-requires\_preauth} clears this
flag.  When \textbf{+requires\_preauth} 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.

\item[{\{-\textbar{}+\}\textbf{requires\_hwauth}}] \leavevmode
\textbf{+requires\_hwauth} requires this principal to preauthenticate
using a hardware device before being allowed to kinit.
\textbf{-requires\_hwauth} clears this flag.  When \textbf{+requires\_hwauth} 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.

\item[{\{-\textbar{}+\}\textbf{ok\_as\_delegate}}] \leavevmode
\textbf{+ok\_as\_delegate} sets the \textbf{okay as delegate} 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.  \textbf{-ok\_as\_delegate} clears this
flag.

\item[{\{-\textbar{}+\}\textbf{allow\_svr}}] \leavevmode
\textbf{-allow\_svr} prohibits the issuance of service tickets for this
principal.  \textbf{+allow\_svr} clears this flag.

\item[{\{-\textbar{}+\}\textbf{allow\_tgs\_req}}] \leavevmode
\textbf{-allow\_tgs\_req} specifies that a Ticket-Granting Service (TGS)
request for a service ticket for this principal is not permitted.
\textbf{+allow\_tgs\_req} clears this flag.

\item[{\{-\textbar{}+\}\textbf{allow\_tix}}] \leavevmode
\textbf{-allow\_tix} forbids the issuance of any tickets for this
principal.  \textbf{+allow\_tix} clears this flag.

\item[{\{-\textbar{}+\}\textbf{needchange}}] \leavevmode
\textbf{+needchange} forces a password change on the next initial
authentication to this principal.  \textbf{-needchange} clears this
flag.

\item[{\{-\textbar{}+\}\textbf{password\_changing\_service}}] \leavevmode
\textbf{+password\_changing\_service} marks this principal as a password
change service principal.

\item[{\{-\textbar{}+\}\textbf{ok\_to\_auth\_as\_delegate}}] \leavevmode
\textbf{+ok\_to\_auth\_as\_delegate} allows this principal to acquire
forwardable tickets to itself from arbitrary users, for use with
constrained delegation.

\item[{\{-\textbar{}+\}\textbf{no\_auth\_data\_required}}] \leavevmode
\textbf{+no\_auth\_data\_required} prevents PAC or AD-SIGNEDPATH data from
being added to service tickets for the principal.

\item[{\{-\textbar{}+\}\textbf{lockdown\_keys}}] \leavevmode
\textbf{+lockdown\_keys} 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.

\item[{\textbf{-randkey}}] \leavevmode
Sets the key of the principal to a random value.

\item[{\textbf{-nokey}}] \leavevmode
Causes the principal to be created with no key.  New in release
1.12.

\item[{\textbf{-pw} \emph{password}}] \leavevmode
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.

\item[{\textbf{-e} \emph{enc}:\emph{salt},...}] \leavevmode
Uses the specified keysalt list for setting the keys of the
principal.  See {\hyperref[admin/conf_files/kdc_conf:keysalt-lists]{\emph{Keysalt lists}}} in {\hyperref[admin/conf_files/kdc_conf:kdc-conf-5]{\emph{kdc.conf}}} for a
list of possible values.

\item[{\textbf{-x} \emph{db\_princ\_args}}] \leavevmode
Indicates database-specific options.  The options for the LDAP
database module are:
\begin{description}
\item[{\textbf{-x dn=}\emph{dn}}] \leavevmode
Specifies the LDAP object that will contain the Kerberos
principal being created.

\item[{\textbf{-x linkdn=}\emph{dn}}] \leavevmode
Specifies the LDAP object to which the newly created Kerberos
principal object will point.

\item[{\textbf{-x containerdn=}\emph{container\_dn}}] \leavevmode
Specifies the container object under which the Kerberos
principal is to be created.

\item[{\textbf{-x tktpolicy=}\emph{policy}}] \leavevmode
Associates a ticket policy to the Kerberos principal.

\end{description}

\begin{notice}{note}{Note:}\begin{itemize}
\item {} 
The \textbf{containerdn} and \textbf{linkdn} options cannot be
specified with the \textbf{dn} option.

\item {} 
If the \emph{dn} or \emph{containerdn} options are not specified while
adding the principal, the principals are created under the
principal container configured in the realm or the realm
container.

\item {} 
\emph{dn} and \emph{containerdn} should be within the subtrees or
principal container configured in the realm.

\end{itemize}
\end{notice}

\end{description}

Example:

\begin{Verbatim}[commandchars=\\\{\}]
kadmin: addprinc jennifer
WARNING: no policy specified for \PYGZdq{}jennifer@ATHENA.MIT.EDU\PYGZdq{};
defaulting to no policy.
Enter password for principal jennifer@ATHENA.MIT.EDU:
Re\PYGZhy{}enter password for principal jennifer@ATHENA.MIT.EDU:
Principal \PYGZdq{}jennifer@ATHENA.MIT.EDU\PYGZdq{} created.
kadmin:
\end{Verbatim}
\phantomsection\label{admin/admin_commands/kadmin_local:add-principal-end}

\subsubsection{modify\_principal}
\label{admin/admin_commands/kadmin_local:add-principal-end}\label{admin/admin_commands/kadmin_local:id2}\label{admin/admin_commands/kadmin_local:modify-principal}\begin{quote}

\textbf{modify\_principal} {[}\emph{options}{]} \emph{principal}
\end{quote}

Modifies the specified principal, changing the fields as specified.
The options to \textbf{add\_principal} also apply to this command, except
for the \textbf{-randkey}, \textbf{-pw}, and \textbf{-e} options.  In addition, the
option \textbf{-clearpolicy} will clear the current policy of a principal.

This command requires the \emph{modify} privilege.

Alias: \textbf{modprinc}

Options (in addition to the \textbf{addprinc} options):
\begin{description}
\item[{\textbf{-unlock}}] \leavevmode
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.

\end{description}
\phantomsection\label{admin/admin_commands/kadmin_local:modify-principal-end}

\subsubsection{rename\_principal}
\label{admin/admin_commands/kadmin_local:modify-principal-end}\label{admin/admin_commands/kadmin_local:rename-principal}\label{admin/admin_commands/kadmin_local:id3}\begin{quote}

\textbf{rename\_principal} {[}\textbf{-force}{]} \emph{old\_principal} \emph{new\_principal}
\end{quote}

Renames the specified \emph{old\_principal} to \emph{new\_principal}.  This
command prompts for confirmation, unless the \textbf{-force} option is
given.

This command requires the \textbf{add} and \textbf{delete} privileges.

Alias: \textbf{renprinc}
\phantomsection\label{admin/admin_commands/kadmin_local:rename-principal-end}

\subsubsection{delete\_principal}
\label{admin/admin_commands/kadmin_local:id4}\label{admin/admin_commands/kadmin_local:delete-principal}\label{admin/admin_commands/kadmin_local:rename-principal-end}\begin{quote}

\textbf{delete\_principal} {[}\textbf{-force}{]} \emph{principal}
\end{quote}

Deletes the specified \emph{principal} from the database.  This command
prompts for deletion, unless the \textbf{-force} option is given.

This command requires the \textbf{delete} privilege.

Alias: \textbf{delprinc}
\phantomsection\label{admin/admin_commands/kadmin_local:delete-principal-end}

\subsubsection{change\_password}
\label{admin/admin_commands/kadmin_local:id5}\label{admin/admin_commands/kadmin_local:delete-principal-end}\label{admin/admin_commands/kadmin_local:change-password}\begin{quote}

\textbf{change\_password} {[}\emph{options}{]} \emph{principal}
\end{quote}

Changes the password of \emph{principal}.  Prompts for a new password if
neither \textbf{-randkey} or \textbf{-pw} is specified.

This command requires the \textbf{changepw} privilege, or that the
principal running the program is the same as the principal being
changed.

Alias: \textbf{cpw}

The following options are available:
\begin{description}
\item[{\textbf{-randkey}}] \leavevmode
Sets the key of the principal to a random value.

\item[{\textbf{-pw} \emph{password}}] \leavevmode
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.

\item[{\textbf{-e} \emph{enc}:\emph{salt},...}] \leavevmode
Uses the specified keysalt list for setting the keys of the
principal.  See {\hyperref[admin/conf_files/kdc_conf:keysalt-lists]{\emph{Keysalt lists}}} in {\hyperref[admin/conf_files/kdc_conf:kdc-conf-5]{\emph{kdc.conf}}} for a
list of possible values.

\item[{\textbf{-keepold}}] \leavevmode
Keeps the existing keys in the database.  This flag is usually not
necessary except perhaps for \code{krbtgt} principals.

\end{description}

Example:

\begin{Verbatim}[commandchars=\\\{\}]
kadmin: cpw systest
Enter password for principal systest@BLEEP.COM:
Re\PYGZhy{}enter password for principal systest@BLEEP.COM:
Password for systest@BLEEP.COM changed.
kadmin:
\end{Verbatim}
\phantomsection\label{admin/admin_commands/kadmin_local:change-password-end}

\subsubsection{purgekeys}
\label{admin/admin_commands/kadmin_local:id6}\label{admin/admin_commands/kadmin_local:change-password-end}\label{admin/admin_commands/kadmin_local:purgekeys}\begin{quote}

\textbf{purgekeys} {[}\textbf{-all}\textbar{}\textbf{-keepkvno} \emph{oldest\_kvno\_to\_keep}{]} \emph{principal}
\end{quote}

Purges previously retained old keys (e.g., from \textbf{change\_password
-keepold}) from \emph{principal}.  If \textbf{-keepkvno} is specified, then
only purges keys with kvnos lower than \emph{oldest\_kvno\_to\_keep}.  If
\textbf{-all} is specified, then all keys are purged.  The \textbf{-all} option
is new in release 1.12.

This command requires the \textbf{modify} privilege.
\phantomsection\label{admin/admin_commands/kadmin_local:purgekeys-end}

\subsubsection{get\_principal}
\label{admin/admin_commands/kadmin_local:get-principal}\label{admin/admin_commands/kadmin_local:id7}\label{admin/admin_commands/kadmin_local:purgekeys-end}\begin{quote}

\textbf{get\_principal} {[}\textbf{-terse}{]} \emph{principal}
\end{quote}

Gets the attributes of principal.  With the \textbf{-terse} option, outputs
fields as quoted tab-separated strings.

This command requires the \textbf{inquire} privilege, or that the principal
running the the program to be the same as the one being listed.

Alias: \textbf{getprinc}

Examples:

\begin{Verbatim}[commandchars=\\\{\}]
kadmin: getprinc tlyu/admin
Principal: tlyu/admin@BLEEP.COM
Expiration date: [never]
Last password change: Mon Aug 12 14:16:47 EDT 1996
Password expiration date: [none]
Maximum ticket life: 0 days 10:00:00
Maximum renewable life: 7 days 00:00:00
Last modified: Mon Aug 12 14:16:47 EDT 1996 (bjaspan/admin@BLEEP.COM)
Last successful authentication: [never]
Last failed authentication: [never]
Failed password attempts: 0
Number of keys: 2
Key: vno 1, des\PYGZhy{}cbc\PYGZhy{}crc
Key: vno 1, des\PYGZhy{}cbc\PYGZhy{}crc:v4
Attributes:
Policy: [none]

kadmin: getprinc \PYGZhy{}terse systest
systest@BLEEP.COM   3    86400     604800    1
785926535 753241234 785900000
tlyu/admin@BLEEP.COM     786100034 0    0
kadmin:
\end{Verbatim}
\phantomsection\label{admin/admin_commands/kadmin_local:get-principal-end}

\subsubsection{list\_principals}
\label{admin/admin_commands/kadmin_local:get-principal-end}\label{admin/admin_commands/kadmin_local:id8}\label{admin/admin_commands/kadmin_local:list-principals}\begin{quote}

\textbf{list\_principals} {[}\emph{expression}{]}
\end{quote}

Retrieves all or some principal names.  \emph{expression} is a shell-style
glob expression that can contain the wild-card characters \code{?},
\code{*}, and \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{@} character, an
\code{@} character followed by the local realm is appended to the
expression.

This command requires the \textbf{list} privilege.

Alias: \textbf{listprincs}, \textbf{get\_principals}, \textbf{get\_princs}

Example:

\begin{Verbatim}[commandchars=\\\{\}]
kadmin:  listprincs test*
test3@SECURE\PYGZhy{}TEST.OV.COM
test2@SECURE\PYGZhy{}TEST.OV.COM
test1@SECURE\PYGZhy{}TEST.OV.COM
testuser@SECURE\PYGZhy{}TEST.OV.COM
kadmin:
\end{Verbatim}
\phantomsection\label{admin/admin_commands/kadmin_local:list-principals-end}

\subsubsection{get\_strings}
\label{admin/admin_commands/kadmin_local:id9}\label{admin/admin_commands/kadmin_local:get-strings}\label{admin/admin_commands/kadmin_local:list-principals-end}\begin{quote}

\textbf{get\_strings} \emph{principal}
\end{quote}

Displays string attributes on \emph{principal}.

This command requires the \textbf{inquire} privilege.

Alias: \textbf{getstr}
\phantomsection\label{admin/admin_commands/kadmin_local:get-strings-end}

\subsubsection{set\_string}
\label{admin/admin_commands/kadmin_local:id10}\label{admin/admin_commands/kadmin_local:set-string}\label{admin/admin_commands/kadmin_local:get-strings-end}\begin{quote}

\textbf{set\_string} \emph{principal} \emph{name} \emph{value}
\end{quote}

Sets a string attribute on \emph{principal}.  String attributes are used to
supply per-principal configuration to the KDC and some KDC plugin
modules.  The following string attribute names are recognized by the
KDC:
\begin{description}
\item[{\textbf{require\_auth}}] \leavevmode
Specifies an authentication indicator which is required to
authenticate to the principal as a service.  Multiple indicators
can be specified, separated by spaces; in this case any of the
specified indicators will be accepted.  (New in release 1.14.)

\item[{\textbf{session\_enctypes}}] \leavevmode
Specifies the encryption types supported for session keys when the
principal is authenticated to as a server.  See
{\hyperref[admin/conf_files/kdc_conf:encryption-types]{\emph{Encryption types}}} in {\hyperref[admin/conf_files/kdc_conf:kdc-conf-5]{\emph{kdc.conf}}} for a list of the
accepted values.

\item[{\textbf{otp}}] \leavevmode
Enables One Time Passwords (OTP) preauthentication for a client
\emph{principal}.  The \emph{value} is a JSON string representing an array
of objects, each having optional \code{type} and \code{username} fields.

\end{description}

This command requires the \textbf{modify} privilege.

Alias: \textbf{setstr}

Example:

\begin{Verbatim}[commandchars=\\\{\}]
set\PYGZus{}string host/foo.mit.edu session\PYGZus{}enctypes aes128\PYGZhy{}cts
set\PYGZus{}string user@FOO.COM otp \PYGZdq{}[\PYGZob{}\PYGZdq{}\PYGZdq{}type\PYGZdq{}\PYGZdq{}:\PYGZdq{}\PYGZdq{}hotp\PYGZdq{}\PYGZdq{},\PYGZdq{}\PYGZdq{}username\PYGZdq{}\PYGZdq{}:\PYGZdq{}\PYGZdq{}al\PYGZdq{}\PYGZdq{}\PYGZcb{}]\PYGZdq{}
\end{Verbatim}
\phantomsection\label{admin/admin_commands/kadmin_local:set-string-end}

\subsubsection{del\_string}
\label{admin/admin_commands/kadmin_local:set-string-end}\label{admin/admin_commands/kadmin_local:del-string}\label{admin/admin_commands/kadmin_local:id11}\begin{quote}

\textbf{del\_string} \emph{principal} \emph{key}
\end{quote}

Deletes a string attribute from \emph{principal}.

This command requires the \textbf{delete} privilege.

Alias: \textbf{delstr}
\phantomsection\label{admin/admin_commands/kadmin_local:del-string-end}

\subsubsection{add\_policy}
\label{admin/admin_commands/kadmin_local:id12}\label{admin/admin_commands/kadmin_local:del-string-end}\label{admin/admin_commands/kadmin_local:add-policy}\begin{quote}

\textbf{add\_policy} {[}\emph{options}{]} \emph{policy}
\end{quote}

Adds a password policy named \emph{policy} to the database.

This command requires the \textbf{add} privilege.

Alias: \textbf{addpol}

The following options are available:
\begin{description}
\item[{\textbf{-maxlife} \emph{time}}] \leavevmode
(\emph{duration} or \emph{getdate} string) Sets the maximum
lifetime of a password.

\item[{\textbf{-minlife} \emph{time}}] \leavevmode
(\emph{duration} or \emph{getdate} string) Sets the minimum
lifetime of a password.

\item[{\textbf{-minlength} \emph{length}}] \leavevmode
Sets the minimum length of a password.

\item[{\textbf{-minclasses} \emph{number}}] \leavevmode
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.

\item[{\textbf{-history} \emph{number}}] \leavevmode
Sets the number of past keys kept for a principal.  This option is
not supported with the LDAP KDC database module.

\end{description}
\phantomsection\label{admin/admin_commands/kadmin_local:policy-maxfailure}\begin{description}
\item[{\textbf{-maxfailure} \emph{maxnumber}}] \leavevmode
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
\emph{maxnumber} value of 0 (the default) disables lockout.

\end{description}
\phantomsection\label{admin/admin_commands/kadmin_local:policy-failurecountinterval}\begin{description}
\item[{\textbf{-failurecountinterval} \emph{failuretime}}] \leavevmode
(\emph{duration} or \emph{getdate} string) Sets the allowable time
between authentication failures.  If an authentication failure
happens after \emph{failuretime} has elapsed since the previous
failure, the number of authentication failures is reset to 1.  A
\emph{failuretime} value of 0 (the default) means forever.

\end{description}
\phantomsection\label{admin/admin_commands/kadmin_local:policy-lockoutduration}\begin{description}
\item[{\textbf{-lockoutduration} \emph{lockouttime}}] \leavevmode
(\emph{duration} or \emph{getdate} 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{modprinc -unlock}.

\item[{\textbf{-allowedkeysalts}}] \leavevmode
Specifies the key/salt tuples supported for long-term keys when
setting or changing a principal's password/keys.  See
{\hyperref[admin/conf_files/kdc_conf:keysalt-lists]{\emph{Keysalt lists}}} in {\hyperref[admin/conf_files/kdc_conf:kdc-conf-5]{\emph{kdc.conf}}} 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 `-`.

\end{description}

Example:

\begin{Verbatim}[commandchars=\\\{\}]
kadmin: add\PYGZus{}policy \PYGZhy{}maxlife \PYGZdq{}2 days\PYGZdq{} \PYGZhy{}minlength 5 guests
kadmin:
\end{Verbatim}
\phantomsection\label{admin/admin_commands/kadmin_local:add-policy-end}

\subsubsection{modify\_policy}
\label{admin/admin_commands/kadmin_local:id13}\label{admin/admin_commands/kadmin_local:modify-policy}\label{admin/admin_commands/kadmin_local:add-policy-end}\begin{quote}

\textbf{modify\_policy} {[}\emph{options}{]} \emph{policy}
\end{quote}

Modifies the password policy named \emph{policy}.  Options are as described
for \textbf{add\_policy}.

This command requires the \textbf{modify} privilege.

Alias: \textbf{modpol}
\phantomsection\label{admin/admin_commands/kadmin_local:modify-policy-end}

\subsubsection{delete\_policy}
\label{admin/admin_commands/kadmin_local:delete-policy}\label{admin/admin_commands/kadmin_local:modify-policy-end}\label{admin/admin_commands/kadmin_local:id14}\begin{quote}

\textbf{delete\_policy} {[}\textbf{-force}{]} \emph{policy}
\end{quote}

Deletes the password policy named \emph{policy}.  Prompts for confirmation
before deletion.  The command will fail if the policy is in use by any
principals.

This command requires the \textbf{delete} privilege.

Alias: \textbf{delpol}

Example:

\begin{Verbatim}[commandchars=\\\{\}]
kadmin: del\PYGZus{}policy guests
Are you sure you want to delete the policy \PYGZdq{}guests\PYGZdq{}?
(yes/no): yes
kadmin:
\end{Verbatim}
\phantomsection\label{admin/admin_commands/kadmin_local:delete-policy-end}

\subsubsection{get\_policy}
\label{admin/admin_commands/kadmin_local:delete-policy-end}\label{admin/admin_commands/kadmin_local:get-policy}\label{admin/admin_commands/kadmin_local:id15}\begin{quote}

\textbf{get\_policy} {[} \textbf{-terse} {]} \emph{policy}
\end{quote}

Displays the values of the password policy named \emph{policy}.  With the
\textbf{-terse} flag, outputs the fields as quoted strings separated by
tabs.

This command requires the \textbf{inquire} privilege.

Alias: getpol

Examples:

\begin{Verbatim}[commandchars=\\\{\}]
kadmin: get\PYGZus{}policy admin
Policy: admin
Maximum password life: 180 days 00:00:00
Minimum password life: 00:00:00
Minimum password length: 6
Minimum number of password character classes: 2
Number of old keys kept: 5
Reference count: 17

kadmin: get\PYGZus{}policy \PYGZhy{}terse admin
admin     15552000  0    6    2    5    17
kadmin:
\end{Verbatim}

The ``Reference count'' is the number of principals using that policy.
With the LDAP KDC database module, the reference count field is not
meaningful.
\phantomsection\label{admin/admin_commands/kadmin_local:get-policy-end}

\subsubsection{list\_policies}
\label{admin/admin_commands/kadmin_local:get-policy-end}\label{admin/admin_commands/kadmin_local:list-policies}\label{admin/admin_commands/kadmin_local:id16}\begin{quote}

\textbf{list\_policies} {[}\emph{expression}{]}
\end{quote}

Retrieves all or some policy names.  \emph{expression} is a shell-style
glob expression that can contain the wild-card characters \code{?},
\code{*}, and \code{{[}{]}}.  All policy names matching the expression are
printed.  If no expression is provided, all existing policy names are
printed.

This command requires the \textbf{list} privilege.

Aliases: \textbf{listpols}, \textbf{get\_policies}, \textbf{getpols}.

Examples:

\begin{Verbatim}[commandchars=\\\{\}]
kadmin:  listpols
test\PYGZhy{}pol
dict\PYGZhy{}only
once\PYGZhy{}a\PYGZhy{}min
test\PYGZhy{}pol\PYGZhy{}nopw

kadmin:  listpols t*
test\PYGZhy{}pol
test\PYGZhy{}pol\PYGZhy{}nopw
kadmin:
\end{Verbatim}
\phantomsection\label{admin/admin_commands/kadmin_local:list-policies-end}

\subsubsection{ktadd}
\label{admin/admin_commands/kadmin_local:ktadd}\label{admin/admin_commands/kadmin_local:list-policies-end}\label{admin/admin_commands/kadmin_local:id17}\begin{quote}

\begin{DUlineblock}{0em}
\item[] \textbf{ktadd} {[}options{]} \emph{principal}
\item[] \textbf{ktadd} {[}options{]} \textbf{-glob} \emph{princ-exp}
\end{DUlineblock}
\end{quote}

Adds a \emph{principal}, or all principals matching \emph{princ-exp}, to a
keytab file.  Each principal's keys are randomized in the process.
The rules for \emph{princ-exp} are described in the \textbf{list\_principals}
command.

This command requires the \textbf{inquire} and \textbf{changepw} privileges.
With the \textbf{-glob} form, it also requires the \textbf{list} privilege.

The options are:
\begin{description}
\item[{\textbf{-k{[}eytab{]}} \emph{keytab}}] \leavevmode
Use \emph{keytab} as the keytab file.  Otherwise, the default keytab is
used.

\item[{\textbf{-e} \emph{enc}:\emph{salt},...}] \leavevmode
Uses the specified keysalt list for setting the new keys of the
principal.  See {\hyperref[admin/conf_files/kdc_conf:keysalt-lists]{\emph{Keysalt lists}}} in {\hyperref[admin/conf_files/kdc_conf:kdc-conf-5]{\emph{kdc.conf}}} for a
list of possible values.

\item[{\textbf{-q}}] \leavevmode
Display less verbose information.

\item[{\textbf{-norandkey}}] \leavevmode
Do not randomize the keys. The keys and their version numbers stay
unchanged.  This option cannot be specified in combination with the
\textbf{-e} option.

\end{description}

An entry for each of the principal's unique encryption types is added,
ignoring multiple keys with the same encryption type but different
salt types.

Example:

\begin{Verbatim}[commandchars=\\\{\}]
kadmin: ktadd \PYGZhy{}k /tmp/foo\PYGZhy{}new\PYGZhy{}keytab host/foo.mit.edu
Entry for principal host/foo.mit.edu@ATHENA.MIT.EDU with kvno 3,
     encryption type aes256\PYGZhy{}cts\PYGZhy{}hmac\PYGZhy{}sha1\PYGZhy{}96 added to keytab
     FILE:/tmp/foo\PYGZhy{}new\PYGZhy{}keytab
kadmin:
\end{Verbatim}
\phantomsection\label{admin/admin_commands/kadmin_local:ktadd-end}

\subsubsection{ktremove}
\label{admin/admin_commands/kadmin_local:id18}\label{admin/admin_commands/kadmin_local:ktremove}\label{admin/admin_commands/kadmin_local:ktadd-end}\begin{quote}

\textbf{ktremove} {[}options{]} \emph{principal} {[}\emph{kvno} \textbar{} \emph{all} \textbar{} \emph{old}{]}
\end{quote}

Removes entries for the specified \emph{principal} from a keytab.  Requires
no permissions, since this does not require database access.

If the string ``all'' is specified, all entries for that principal are
removed; if the string ``old'' is specified, all entries for that
principal except those with the highest kvno are removed.  Otherwise,
the value specified is parsed as an integer, and all entries whose
kvno match that integer are removed.

The options are:
\begin{description}
\item[{\textbf{-k{[}eytab{]}} \emph{keytab}}] \leavevmode
Use \emph{keytab} as the keytab file.  Otherwise, the default keytab is
used.

\item[{\textbf{-q}}] \leavevmode
Display less verbose information.

\end{description}

Example:

\begin{Verbatim}[commandchars=\\\{\}]
kadmin: ktremove kadmin/admin all
Entry for principal kadmin/admin with kvno 3 removed from keytab
     FILE:/etc/krb5.keytab
kadmin:
\end{Verbatim}


\subsubsection{lock}
\label{admin/admin_commands/kadmin_local:ktremove-end}\label{admin/admin_commands/kadmin_local:lock}
Lock database exclusively.  Use with extreme caution!  This command
only works with the DB2 KDC database module.


\subsubsection{unlock}
\label{admin/admin_commands/kadmin_local:unlock}
Release the exclusive database lock.


\subsubsection{list\_requests}
\label{admin/admin_commands/kadmin_local:list-requests}
Lists available for kadmin requests.

Aliases: \textbf{lr}, \textbf{?}


\subsubsection{quit}
\label{admin/admin_commands/kadmin_local:quit}
Exit program.  If the database was locked, the lock is released.

Aliases: \textbf{exit}, \textbf{q}


\subsection{HISTORY}
\label{admin/admin_commands/kadmin_local:history}
The kadmin program was originally written by Tom Yu at MIT, as an
interface to the OpenVision Kerberos administration program.


\subsection{SEE ALSO}
\label{admin/admin_commands/kadmin_local:see-also}
\emph{kpasswd(1)}, {\hyperref[admin/admin_commands/kadmind:kadmind-8]{\emph{kadmind}}}


\section{kadmind}
\label{admin/admin_commands/kadmind:kadmind-8}\label{admin/admin_commands/kadmind:kadmind}\label{admin/admin_commands/kadmind::doc}

\subsection{SYNOPSIS}
\label{admin/admin_commands/kadmind:synopsis}
\textbf{kadmind}
{[}\textbf{-x} \emph{db\_args}{]}
{[}\textbf{-r} \emph{realm}{]}
{[}\textbf{-m}{]}
{[}\textbf{-nofork}{]}
{[}\textbf{-proponly}{]}
{[}\textbf{-port} \emph{port-number}{]}
{[}\textbf{-P} \emph{pid\_file}{]}
{[}\textbf{-p} \emph{kdb5\_util\_path}{]}
{[}\textbf{-K} \emph{kprop\_path}{]}
{[}\textbf{-k} \emph{kprop\_port}{]}
{[}\textbf{-F} \emph{dump\_file}{]}


\subsection{DESCRIPTION}
\label{admin/admin_commands/kadmind:description}
kadmind starts the Kerberos administration server.  kadmind typically
runs on the master Kerberos server, which stores the KDC database.  If
the KDC database uses the LDAP module, the administration server and
the KDC server need not run on the same machine.  kadmind accepts
remote requests from programs such as {\hyperref[admin/admin_commands/kadmin_local:kadmin-1]{\emph{kadmin}}} and
\emph{kpasswd(1)} to administer the information in these database.

kadmind requires a number of configuration files to be set up in order
for it to work:
\begin{description}
\item[{{\hyperref[admin/conf_files/kdc_conf:kdc-conf-5]{\emph{kdc.conf}}}}] \leavevmode
The KDC configuration file contains configuration information for
the KDC and admin servers.  kadmind uses settings in this file to
locate the Kerberos database, and is also affected by the
\textbf{acl\_file}, \textbf{dict\_file}, \textbf{kadmind\_port}, and iprop-related
settings.

\item[{{\hyperref[admin/conf_files/kadm5_acl:kadm5-acl-5]{\emph{kadm5.acl}}}}] \leavevmode
kadmind's ACL (access control list) tells it which principals are
allowed to perform administration actions.  The pathname to the
ACL file can be specified with the \textbf{acl\_file} {\hyperref[admin/conf_files/kdc_conf:kdc-conf-5]{\emph{kdc.conf}}}
variable; by default, it is {\hyperref[mitK5defaults:paths]{\emph{LOCALSTATEDIR}}}\code{/krb5kdc}\code{/kadm5.acl}.

\end{description}

After the server begins running, it puts itself in the background and
disassociates itself from its controlling terminal.

kadmind can be configured for incremental database propagation.
Incremental propagation allows slave KDC servers to receive principal
and policy updates incrementally instead of receiving full dumps of
the database.  This facility can be enabled in the {\hyperref[admin/conf_files/kdc_conf:kdc-conf-5]{\emph{kdc.conf}}}
file with the \textbf{iprop\_enable} option.  Incremental propagation
requires the principal \code{kiprop/MASTER\textbackslash{}@REALM} (where MASTER is the
master KDC's canonical host name, and REALM the realm name).  In
release 1.13, this principal is automatically created and registered
into the datebase.


\subsection{OPTIONS}
\label{admin/admin_commands/kadmind:options}\begin{description}
\item[{\textbf{-r} \emph{realm}}] \leavevmode
specifies the realm that kadmind will serve; if it is not
specified, the default realm of the host is used.

\item[{\textbf{-m}}] \leavevmode
causes the master database password to be fetched from the
keyboard (before the server puts itself in the background, if not
invoked with the \textbf{-nofork} option) rather than from a file on
disk.

\item[{\textbf{-nofork}}] \leavevmode
causes the server to remain in the foreground and remain
associated to the terminal.  In normal operation, you should allow
the server to place itself in the background.

\item[{\textbf{-proponly}}] \leavevmode
causes the server to only listen and respond to Kerberos slave
incremental propagation polling requests.  This option can be used
to set up a hierarchical propagation topology where a slave KDC
provides incremental updates to other Kerberos slaves.

\item[{\textbf{-port} \emph{port-number}}] \leavevmode
specifies the port on which the administration server listens for
connections.  The default port is determined by the
\textbf{kadmind\_port} configuration variable in {\hyperref[admin/conf_files/kdc_conf:kdc-conf-5]{\emph{kdc.conf}}}.

\item[{\textbf{-P} \emph{pid\_file}}] \leavevmode
specifies the file to which the PID of kadmind process should be
written after it starts up.  This file can be used to identify
whether kadmind is still running and to allow init scripts to stop
the correct process.

\item[{\textbf{-p} \emph{kdb5\_util\_path}}] \leavevmode
specifies the path to the kdb5\_util command to use when dumping the
KDB in response to full resync requests when iprop is enabled.

\item[{\textbf{-K} \emph{kprop\_path}}] \leavevmode
specifies the path to the kprop command to use to send full dumps
to slaves in response to full resync requests.

\item[{\textbf{-k} \emph{kprop\_port}}] \leavevmode
specifies the port by which the kprop process that is spawned by kadmind
connects to the slave kpropd, in order to transfer the dump file during
an iprop full resync request.

\item[{\textbf{-F} \emph{dump\_file}}] \leavevmode
specifies the file path to be used for dumping the KDB in response
to full resync requests when iprop is enabled.

\item[{\textbf{-x} \emph{db\_args}}] \leavevmode
specifies database-specific arguments.  See {\hyperref[admin/admin_commands/kadmin_local:dboptions]{\emph{Database Options}}} in {\hyperref[admin/admin_commands/kadmin_local:kadmin-1]{\emph{kadmin}}} for supported arguments.

\end{description}


\subsection{SEE ALSO}
\label{admin/admin_commands/kadmind:see-also}
\emph{kpasswd(1)}, {\hyperref[admin/admin_commands/kadmin_local:kadmin-1]{\emph{kadmin}}}, {\hyperref[admin/admin_commands/kdb5_util:kdb5-util-8]{\emph{kdb5\_util}}},
{\hyperref[admin/admin_commands/kdb5_ldap_util:kdb5-ldap-util-8]{\emph{kdb5\_ldap\_util}}}, {\hyperref[admin/conf_files/kadm5_acl:kadm5-acl-5]{\emph{kadm5.acl}}}


\section{kdb5\_util}
\label{admin/admin_commands/kdb5_util:kdb5-util-8}\label{admin/admin_commands/kdb5_util::doc}\label{admin/admin_commands/kdb5_util:kdb5-util}

\subsection{SYNOPSIS}
\label{admin/admin_commands/kdb5_util:synopsis}\phantomsection\label{admin/admin_commands/kdb5_util:kdb5-util-synopsis}
\textbf{kdb5\_util}
{[}\textbf{-r} \emph{realm}{]}
{[}\textbf{-d} \emph{dbname}{]}
{[}\textbf{-k} \emph{mkeytype}{]}
{[}\textbf{-M} \emph{mkeyname}{]}
{[}\textbf{-kv} \emph{mkeyVNO}{]}
{[}\textbf{-sf} \emph{stashfilename}{]}
{[}\textbf{-m}{]}
\emph{command} {[}\emph{command\_options}{]}


\subsection{DESCRIPTION}
\label{admin/admin_commands/kdb5_util:kdb5-util-synopsis-end}\label{admin/admin_commands/kdb5_util:description}
kdb5\_util allows an administrator to perform maintenance procedures on
the KDC database.  Databases can be created, destroyed, and dumped to
or loaded from ASCII files.  kdb5\_util can create a Kerberos master
key stash file or perform live rollover of the master key.

When kdb5\_util is run, it attempts to acquire the master key and open
the database.  However, execution continues regardless of whether or
not kdb5\_util successfully opens the database, because the database
may not exist yet or the stash file may be corrupt.

Note that some KDC database modules may not support all kdb5\_util
commands.


\subsection{COMMAND-LINE OPTIONS}
\label{admin/admin_commands/kdb5_util:command-line-options}\phantomsection\label{admin/admin_commands/kdb5_util:kdb5-util-options}\begin{description}
\item[{\textbf{-r} \emph{realm}}] \leavevmode
specifies the Kerberos realm of the database.

\item[{\textbf{-d} \emph{dbname}}] \leavevmode
specifies the name under which the principal database is stored;
by default the database is that listed in {\hyperref[admin/conf_files/kdc_conf:kdc-conf-5]{\emph{kdc.conf}}}.  The
password policy database and lock files are also derived from this
value.

\item[{\textbf{-k} \emph{mkeytype}}] \leavevmode
specifies the key type of the master key in the database.  The
default is given by the \textbf{master\_key\_type} variable in
{\hyperref[admin/conf_files/kdc_conf:kdc-conf-5]{\emph{kdc.conf}}}.

\item[{\textbf{-kv} \emph{mkeyVNO}}] \leavevmode
Specifies the version number of the master key in the database;
the default is 1.  Note that 0 is not allowed.

\item[{\textbf{-M} \emph{mkeyname}}] \leavevmode
principal name for the master key in the database.  If not
specified, the name is determined by the \textbf{master\_key\_name}
variable in {\hyperref[admin/conf_files/kdc_conf:kdc-conf-5]{\emph{kdc.conf}}}.

\item[{\textbf{-m}}] \leavevmode
specifies that the master database password should be read from
the keyboard rather than fetched from a file on disk.

\item[{\textbf{-sf} \emph{stash\_file}}] \leavevmode
specifies the stash filename of the master database password.  If
not specified, the filename is determined by the
\textbf{key\_stash\_file} variable in {\hyperref[admin/conf_files/kdc_conf:kdc-conf-5]{\emph{kdc.conf}}}.

\item[{\textbf{-P} \emph{password}}] \leavevmode
specifies the master database password.  Using this option may
expose the password to other users on the system via the process
list.

\end{description}


\subsection{COMMANDS}
\label{admin/admin_commands/kdb5_util:commands}\label{admin/admin_commands/kdb5_util:kdb5-util-options-end}

\subsubsection{create}
\label{admin/admin_commands/kdb5_util:create}\phantomsection\label{admin/admin_commands/kdb5_util:kdb5-util-create}\begin{quote}

\textbf{create} {[}\textbf{-s}{]}
\end{quote}

Creates a new database.  If the \textbf{-s} 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.


\subsubsection{destroy}
\label{admin/admin_commands/kdb5_util:destroy}\label{admin/admin_commands/kdb5_util:kdb5-util-create-end}\phantomsection\label{admin/admin_commands/kdb5_util:kdb5-util-destroy}\begin{quote}

\textbf{destroy} {[}\textbf{-f}{]}
\end{quote}

Destroys the database, first overwriting the disk sectors and then
unlinking the files, after prompting the user for confirmation.  With
the \textbf{-f} argument, does not prompt the user.


\subsubsection{stash}
\label{admin/admin_commands/kdb5_util:kdb5-util-destroy-end}\label{admin/admin_commands/kdb5_util:stash}\phantomsection\label{admin/admin_commands/kdb5_util:kdb5-util-stash}\begin{quote}

\textbf{stash} {[}\textbf{-f} \emph{keyfile}{]}
\end{quote}

Stores the master principal's keys in a stash file.  The \textbf{-f}
argument can be used to override the \emph{keyfile} specified in
{\hyperref[admin/conf_files/kdc_conf:kdc-conf-5]{\emph{kdc.conf}}}.


\subsubsection{dump}
\label{admin/admin_commands/kdb5_util:kdb5-util-stash-end}\label{admin/admin_commands/kdb5_util:dump}\phantomsection\label{admin/admin_commands/kdb5_util:kdb5-util-dump}\begin{quote}

\textbf{dump} {[}\textbf{-b7}\textbar{}\textbf{-ov}\textbar{}\textbf{-r13}{]} {[}\textbf{-verbose}{]}
{[}\textbf{-mkey\_convert}{]} {[}\textbf{-new\_mkey\_file} \emph{mkey\_file}{]} {[}\textbf{-rev}{]}
{[}\textbf{-recurse}{]} {[}\emph{filename} {[}\emph{principals}...{]}{]}
\end{quote}

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:
\begin{description}
\item[{\textbf{-b7}}] \leavevmode
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.

\item[{\textbf{-ov}}] \leavevmode
causes the dump to be in ``ovsec\_adm\_export'' format.

\item[{\textbf{-r13}}] \leavevmode
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.

\item[{\textbf{-r18}}] \leavevmode
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.

\item[{\textbf{-verbose}}] \leavevmode
causes the name of each principal and policy to be printed as it
is dumped.

\item[{\textbf{-mkey\_convert}}] \leavevmode
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.

\item[{\textbf{-new\_mkey\_file} \emph{mkey\_file}}] \leavevmode
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.

\item[{\textbf{-rev}}] \leavevmode
dumps in reverse order.  This may recover principals that do not
dump normally, in cases where database corruption has occurred.

\item[{\textbf{-recurse}}] \leavevmode
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 \textbf{-rev} option will.

\DUspan{versionmodified}{Changed in version 1.15: }Release 1.15 restored the functionality of the \textbf{-recurse}
option.

\DUspan{versionmodified}{Changed in version 1.5: }The \textbf{-recurse} option ceased working until release 1.15,
doing a normal dump instead of a recursive traversal.

\end{description}


\subsubsection{load}
\label{admin/admin_commands/kdb5_util:kdb5-util-dump-end}\label{admin/admin_commands/kdb5_util:load}\phantomsection\label{admin/admin_commands/kdb5_util:kdb5-util-load}\begin{quote}

\textbf{load} {[}\textbf{-b7}\textbar{}\textbf{-ov}\textbar{}\textbf{-r13}{]} {[}\textbf{-hash}{]}
{[}\textbf{-verbose}{]} {[}\textbf{-update}{]} \emph{filename} {[}\emph{dbname}{]}
\end{quote}

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 \textbf{-update} option is given, \textbf{load} 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 \textbf{-update} flag is required.

Options:
\begin{description}
\item[{\textbf{-b7}}] \leavevmode
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.

\item[{\textbf{-ov}}] \leavevmode
requires the database to be in ``ovsec\_adm\_import'' format.  Must be
used with the \textbf{-update} option.

\item[{\textbf{-r13}}] \leavevmode
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.

\item[{\textbf{-r18}}] \leavevmode
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.

\item[{\textbf{-hash}}] \leavevmode
requires the database to be stored as a hash.  If this option is
not specified, the database will be stored as a btree.  This
option is not recommended, as databases stored in hash format are
known to corrupt data and lose principals.

\item[{\textbf{-verbose}}] \leavevmode
causes the name of each principal and policy to be printed as it
is dumped.

\item[{\textbf{-update}}] \leavevmode
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.

\end{description}

If specified, \emph{dbname} overrides the value specified on the command
line or the default.


\subsubsection{ark}
\label{admin/admin_commands/kdb5_util:kdb5-util-load-end}\label{admin/admin_commands/kdb5_util:ark}\begin{quote}

\textbf{ark} {[}\textbf{-e} \emph{enc}:\emph{salt},...{]} \emph{principal}
\end{quote}

Adds new random keys to \emph{principal} at the next available key version
number.  Keys for the current highest key version number will be
preserved.  The \textbf{-e} option specifies the list of encryption and
salt types to be used for the new keys.


\subsubsection{add\_mkey}
\label{admin/admin_commands/kdb5_util:add-mkey}\begin{quote}

\textbf{add\_mkey} {[}\textbf{-e} \emph{etype}{]} {[}\textbf{-s}{]}
\end{quote}

Adds a new master key to the master key principal, but does not mark
it as active.  Existing master keys will remain.  The \textbf{-e} option
specifies the encryption type of the new master key; see
{\hyperref[admin/conf_files/kdc_conf:encryption-types]{\emph{Encryption types}}} in {\hyperref[admin/conf_files/kdc_conf:kdc-conf-5]{\emph{kdc.conf}}} for a list of possible
values.  The \textbf{-s} option stashes the new master key in the stash
file, which will be created if it doesn't already exist.

After a new master key is added, it should be propagated to slave
servers via a manual or periodic invocation of {\hyperref[admin/admin_commands/kprop:kprop-8]{\emph{kprop}}}.  Then,
the stash files on the slave servers should be updated with the
kdb5\_util \textbf{stash} command.  Once those steps are complete, the key
is ready to be marked active with the kdb5\_util \textbf{use\_mkey} command.


\subsubsection{use\_mkey}
\label{admin/admin_commands/kdb5_util:use-mkey}\begin{quote}

\textbf{use\_mkey} \emph{mkeyVNO} {[}\emph{time}{]}
\end{quote}

Sets the activation time of the master key specified by \emph{mkeyVNO}.
Once a master key becomes active, it will be used to encrypt newly
created principal keys.  If no \emph{time} argument is given, the current
time is used, causing the specified master key version to become
active immediately.  The format for \emph{time} is \emph{getdate} string.

After a new master key becomes active, the kdb5\_util
\textbf{update\_princ\_encryption} command can be used to update all
principal keys to be encrypted in the new master key.


\subsubsection{list\_mkeys}
\label{admin/admin_commands/kdb5_util:list-mkeys}\begin{quote}

\textbf{list\_mkeys}
\end{quote}

List all master keys, from most recent to earliest, in the master key
principal.  The output will show the kvno, enctype, and salt type for
each mkey, similar to the output of {\hyperref[admin/admin_commands/kadmin_local:kadmin-1]{\emph{kadmin}}} \textbf{getprinc}.  A
\code{*} following an mkey denotes the currently active master key.


\subsubsection{purge\_mkeys}
\label{admin/admin_commands/kdb5_util:purge-mkeys}\begin{quote}

\textbf{purge\_mkeys} {[}\textbf{-f}{]} {[}\textbf{-n}{]} {[}\textbf{-v}{]}
\end{quote}

Delete master keys from the master key principal that are not used to
protect any principals.  This command can be used to remove old master
keys all principal keys are protected by a newer master key.
\begin{description}
\item[{\textbf{-f}}] \leavevmode
does not prompt for confirmation.

\item[{\textbf{-n}}] \leavevmode
performs a dry run, showing master keys that would be purged, but
not actually purging any keys.

\item[{\textbf{-v}}] \leavevmode
gives more verbose output.

\end{description}


\subsubsection{update\_princ\_encryption}
\label{admin/admin_commands/kdb5_util:update-princ-encryption}\begin{quote}

\textbf{update\_princ\_encryption} {[}\textbf{-f}{]} {[}\textbf{-n}{]} {[}\textbf{-v}{]}
{[}\emph{princ-pattern}{]}
\end{quote}

Update all principal records (or only those matching the
\emph{princ-pattern} glob pattern) to re-encrypt the key data using the
active database master key, if they are encrypted using a different
version, and give a count at the end of the number of principals
updated.  If the \textbf{-f} option is not given, ask for confirmation
before starting to make changes.  The \textbf{-v} option causes each
principal processed to be listed, with an indication as to whether it
needed updating or not.  The \textbf{-n} option performs a dry run, only
showing the actions which would have been taken.


\subsubsection{tabdump}
\label{admin/admin_commands/kdb5_util:tabdump}\begin{quote}

\textbf{tabdump} {[}\textbf{-H}{]} {[}\textbf{-c}{]} {[}\textbf{-e}{]} {[}\textbf{-n}{]} {[}\textbf{-o} \emph{outfile}{]}
\emph{dumptype}
\end{quote}

Dump selected fields of the database in a tabular format suitable for
reporting (e.g., using traditional Unix text processing tools) or
importing into relational databases.  The data format is tab-separated
(default), or optionally comma-separated (CSV), with a fixed number of
columns.  The output begins with a header line containing field names,
unless suppression is requested using the \textbf{-H} option.

The \emph{dumptype} parameter specifies the name of an output table (see
below).

Options:
\begin{description}
\item[{\textbf{-H}}] \leavevmode
suppress writing the field names in a header line

\item[{\textbf{-c}}] \leavevmode
use comma separated values (CSV) format, with minimal quoting,
instead of the default tab-separated (unquoted, unescaped) format

\item[{\textbf{-e}}] \leavevmode
write empty hexadecimal string fields as empty fields instead of
as ``-1''.

\item[{\textbf{-n}}] \leavevmode
produce numeric output for fields that normally have symbolic
output, such as enctypes and flag names.  Also requests output of
time stamps as decimal POSIX time\_t values.

\item[{\textbf{-o} \emph{outfile}}] \leavevmode
write the dump to the specified output file instead of to standard
output

\end{description}

Dump types:
\begin{description}
\item[{\textbf{keydata}}] \leavevmode
principal encryption key information, including actual key data
(which is still encrypted in the master key)
\begin{description}
\item[{\textbf{name}}] \leavevmode
principal name

\item[{\textbf{keyindex}}] \leavevmode
index of this key in the principal's key list

\item[{\textbf{kvno}}] \leavevmode
key version number

\item[{\textbf{enctype}}] \leavevmode
encryption type

\item[{\textbf{key}}] \leavevmode
key data as a hexadecimal string

\item[{\textbf{salttype}}] \leavevmode
salt type

\item[{\textbf{salt}}] \leavevmode
salt data as a hexadecimal string

\end{description}

\item[{\textbf{keyinfo}}] \leavevmode
principal encryption key information (as in \textbf{keydata} above),
excluding actual key data

\item[{\textbf{princ\_flags}}] \leavevmode
principal boolean attributes.  Flag names print as hexadecimal
numbers if the \textbf{-n} option is specified, and all flag positions
are printed regardless of whether or not they are set.  If \textbf{-n}
is not specified, print all known flag names for each principal,
but only print hexadecimal flag names if the corresponding flag is
set.
\begin{description}
\item[{\textbf{name}}] \leavevmode
principal name

\item[{\textbf{flag}}] \leavevmode
flag name

\item[{\textbf{value}}] \leavevmode
boolean value (0 for clear, or 1 for set)

\end{description}

\item[{\textbf{princ\_lockout}}] \leavevmode
state information used for tracking repeated password failures
\begin{description}
\item[{\textbf{name}}] \leavevmode
principal name

\item[{\textbf{last\_success}}] \leavevmode
time stamp of most recent successful authentication

\item[{\textbf{last\_failed}}] \leavevmode
time stamp of most recent failed authentication

\item[{\textbf{fail\_count}}] \leavevmode
count of failed attempts

\end{description}

\item[{\textbf{princ\_meta}}] \leavevmode
principal metadata
\begin{description}
\item[{\textbf{name}}] \leavevmode
principal name

\item[{\textbf{modby}}] \leavevmode
name of last principal to modify this principal

\item[{\textbf{modtime}}] \leavevmode
timestamp of last modification

\item[{\textbf{lastpwd}}] \leavevmode
timestamp of last password change

\item[{\textbf{policy}}] \leavevmode
policy object name

\item[{\textbf{mkvno}}] \leavevmode
key version number of the master key that encrypts this
principal's key data

\item[{\textbf{hist\_kvno}}] \leavevmode
key version number of the history key that encrypts the key
history data for this principal

\end{description}

\item[{\textbf{princ\_stringattrs}}] \leavevmode
string attributes (key/value pairs)
\begin{description}
\item[{\textbf{name}}] \leavevmode
principal name

\item[{\textbf{key}}] \leavevmode
attribute name

\item[{\textbf{value}}] \leavevmode
attribute value

\end{description}

\item[{\textbf{princ\_tktpolicy}}] \leavevmode
per-principal ticket policy data, including maximum ticket
lifetimes
\begin{description}
\item[{\textbf{name}}] \leavevmode
principal name

\item[{\textbf{expiration}}] \leavevmode
principal expiration date

\item[{\textbf{pw\_expiration}}] \leavevmode
password expiration date

\item[{\textbf{max\_life}}] \leavevmode
maximum ticket lifetime

\item[{\textbf{max\_renew\_life}}] \leavevmode
maximum renewable ticket lifetime

\end{description}

\end{description}

Examples:

\begin{Verbatim}[commandchars=\\\{\}]
\PYGZdl{} kdb5\PYGZus{}util tabdump \PYGZhy{}o keyinfo.txt keyinfo
\PYGZdl{} cat keyinfo.txt
name        keyindex        kvno    enctype salttype        salt
foo@EXAMPLE.COM     0       1       aes128\PYGZhy{}cts\PYGZhy{}hmac\PYGZhy{}sha1\PYGZhy{}96 normal  \PYGZhy{}1
bar@EXAMPLE.COM     0       1       aes128\PYGZhy{}cts\PYGZhy{}hmac\PYGZhy{}sha1\PYGZhy{}96 normal  \PYGZhy{}1
bar@EXAMPLE.COM     1       1       des\PYGZhy{}cbc\PYGZhy{}crc     normal  \PYGZhy{}1
\PYGZdl{} sqlite3
sqlite\PYGZgt{} .mode tabs
sqlite\PYGZgt{} .import keyinfo.txt keyinfo
sqlite\PYGZgt{} select * from keyinfo where enctype like \PYGZsq{}des\PYGZhy{}cbc\PYGZhy{}\PYGZpc{}\PYGZsq{};
bar@EXAMPLE.COM     1       1       des\PYGZhy{}cbc\PYGZhy{}crc     normal  \PYGZhy{}1
sqlite\PYGZgt{} .quit
\PYGZdl{} awk \PYGZhy{}F\PYGZsq{}\PYGZbs{}t\PYGZsq{} \PYGZsq{}\PYGZdl{}4 \PYGZti{} /des\PYGZhy{}cbc\PYGZhy{}/ \PYGZob{} print \PYGZcb{}\PYGZsq{} keyinfo.txt
bar@EXAMPLE.COM     1       1       des\PYGZhy{}cbc\PYGZhy{}crc     normal  \PYGZhy{}1
\end{Verbatim}


\subsection{SEE ALSO}
\label{admin/admin_commands/kdb5_util:see-also}
{\hyperref[admin/admin_commands/kadmin_local:kadmin-1]{\emph{kadmin}}}


\section{kdb5\_ldap\_util}
\label{admin/admin_commands/kdb5_ldap_util:kdb5-ldap-util-8}\label{admin/admin_commands/kdb5_ldap_util::doc}\label{admin/admin_commands/kdb5_ldap_util:kdb5-ldap-util}

\subsection{SYNOPSIS}
\label{admin/admin_commands/kdb5_ldap_util:synopsis}\phantomsection\label{admin/admin_commands/kdb5_ldap_util:kdb5-ldap-util-synopsis}
\textbf{kdb5\_ldap\_util}
{[}\textbf{-D} \emph{user\_dn} {[}\textbf{-w} \emph{passwd}{]}{]}
{[}\textbf{-H} \emph{ldapuri}{]}
\textbf{command}
{[}\emph{command\_options}{]}


\subsection{DESCRIPTION}
\label{admin/admin_commands/kdb5_ldap_util:kdb5-ldap-util-synopsis-end}\label{admin/admin_commands/kdb5_ldap_util:description}
kdb5\_ldap\_util allows an administrator to manage realms, Kerberos
services and ticket policies.


\subsection{COMMAND-LINE OPTIONS}
\label{admin/admin_commands/kdb5_ldap_util:command-line-options}\phantomsection\label{admin/admin_commands/kdb5_ldap_util:kdb5-ldap-util-options}\begin{description}
\item[{\textbf{-D} \emph{user\_dn}}] \leavevmode
Specifies the Distinguished Name (DN) of the user who has
sufficient rights to perform the operation on the LDAP server.

\item[{\textbf{-w} \emph{passwd}}] \leavevmode
Specifies the password of \emph{user\_dn}.  This option is not
recommended.

\item[{\textbf{-H} \emph{ldapuri}}] \leavevmode
Specifies the URI of the LDAP server.  It is recommended to use
\code{ldapi://} or \code{ldaps://} to connect to the LDAP server.

\end{description}


\subsection{COMMANDS}
\label{admin/admin_commands/kdb5_ldap_util:kdb5-ldap-util-options-end}\label{admin/admin_commands/kdb5_ldap_util:commands}

\subsubsection{create}
\label{admin/admin_commands/kdb5_ldap_util:create}\phantomsection\label{admin/admin_commands/kdb5_ldap_util:kdb5-ldap-util-create}\begin{quote}

\textbf{create}
{[}\textbf{-subtrees} \emph{subtree\_dn\_list}{]}
{[}\textbf{-sscope} \emph{search\_scope}{]}
{[}\textbf{-containerref} \emph{container\_reference\_dn}{]}
{[}\textbf{-k} \emph{mkeytype}{]}
{[}\textbf{-kv} \emph{mkeyVNO}{]}
{[}\textbf{-m\textbar{}-P} \emph{password}\textbar{}\textbf{-sf} \emph{stashfilename}{]}
{[}\textbf{-s}{]}
{[}\textbf{-r} \emph{realm}{]}
{[}\textbf{-maxtktlife} \emph{max\_ticket\_life}{]}
{[}\textbf{-maxrenewlife} \emph{max\_renewable\_ticket\_life}{]}
{[}\emph{ticket\_flags}{]}
\end{quote}

Creates realm in directory. Options:
\begin{description}
\item[{\textbf{-subtrees} \emph{subtree\_dn\_list}}] \leavevmode
Specifies the list of subtrees containing the principals of a
realm.  The list contains the DNs of the subtree objects separated
by colon (\code{:}).

\item[{\textbf{-sscope} \emph{search\_scope}}] \leavevmode
Specifies the scope for searching the principals under the
subtree.  The possible values are 1 or one (one level), 2 or sub
(subtrees).

\item[{\textbf{-containerref} \emph{container\_reference\_dn}}] \leavevmode
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.

\item[{\textbf{-k} \emph{mkeytype}}] \leavevmode
Specifies the key type of the master key in the database.  The
default is given by the \textbf{master\_key\_type} variable in
{\hyperref[admin/conf_files/kdc_conf:kdc-conf-5]{\emph{kdc.conf}}}.

\item[{\textbf{-kv} \emph{mkeyVNO}}] \leavevmode
Specifies the version number of the master key in the database;
the default is 1.  Note that 0 is not allowed.

\item[{\textbf{-m}}] \leavevmode
Specifies that the master database password should be read from
the TTY rather than fetched from a file on the disk.

\item[{\textbf{-P} \emph{password}}] \leavevmode
Specifies the master database password. This option is not
recommended.

\item[{\textbf{-r} \emph{realm}}] \leavevmode
Specifies the Kerberos realm of the database.

\item[{\textbf{-sf} \emph{stashfilename}}] \leavevmode
Specifies the stash file of the master database password.

\item[{\textbf{-s}}] \leavevmode
Specifies that the stash file is to be created.

\item[{\textbf{-maxtktlife} \emph{max\_ticket\_life}}] \leavevmode
(\emph{getdate} string) Specifies maximum ticket life for
principals in this realm.

\item[{\textbf{-maxrenewlife} \emph{max\_renewable\_ticket\_life}}] \leavevmode
(\emph{getdate} string) Specifies maximum renewable life of
tickets for principals in this realm.

\item[{\emph{ticket\_flags}}] \leavevmode
Specifies global ticket flags for the realm.  Allowable flags are
documented in the description of the \textbf{add\_principal} command in
{\hyperref[admin/admin_commands/kadmin_local:kadmin-1]{\emph{kadmin}}}.

\end{description}

Example:

\begin{Verbatim}[commandchars=\\\{\}]
kdb5\PYGZus{}ldap\PYGZus{}util \PYGZhy{}D cn=admin,o=org \PYGZhy{}H ldaps://ldap\PYGZhy{}server1.mit.edu
    create \PYGZhy{}subtrees o=org \PYGZhy{}sscope SUB \PYGZhy{}r ATHENA.MIT.EDU
Password for \PYGZdq{}cn=admin,o=org\PYGZdq{}:
Initializing database for realm \PYGZsq{}ATHENA.MIT.EDU\PYGZsq{}
You will be prompted for the database Master Password.
It is important that you NOT FORGET this password.
Enter KDC database master key:
Re\PYGZhy{}enter KDC database master key to verify:
\end{Verbatim}


\subsubsection{modify}
\label{admin/admin_commands/kdb5_ldap_util:kdb5-ldap-util-create-end}\label{admin/admin_commands/kdb5_ldap_util:modify}\phantomsection\label{admin/admin_commands/kdb5_ldap_util:kdb5-ldap-util-modify}\begin{quote}

\textbf{modify}
{[}\textbf{-subtrees} \emph{subtree\_dn\_list}{]}
{[}\textbf{-sscope} \emph{search\_scope}{]}
{[}\textbf{-containerref} \emph{container\_reference\_dn}{]}
{[}\textbf{-r} \emph{realm}{]}
{[}\textbf{-maxtktlife} \emph{max\_ticket\_life}{]}
{[}\textbf{-maxrenewlife} \emph{max\_renewable\_ticket\_life}{]}
{[}\emph{ticket\_flags}{]}
\end{quote}

Modifies the attributes of a realm.  Options:
\begin{description}
\item[{\textbf{-subtrees} \emph{subtree\_dn\_list}}] \leavevmode
Specifies the list of subtrees containing the principals of a
realm.  The list contains the DNs of the subtree objects separated
by colon (\code{:}).  This list replaces the existing list.

\item[{\textbf{-sscope} \emph{search\_scope}}] \leavevmode
Specifies the scope for searching the principals under the
subtrees.  The possible values are 1 or one (one level), 2 or sub
(subtrees).

\item[{\textbf{-containerref} \emph{container\_reference\_dn} Specifies the DN of the}] \leavevmode
container object in which the principals of a realm will be
created.

\item[{\textbf{-r} \emph{realm}}] \leavevmode
Specifies the Kerberos realm of the database.

\item[{\textbf{-maxtktlife} \emph{max\_ticket\_life}}] \leavevmode
(\emph{getdate} string) Specifies maximum ticket life for
principals in this realm.

\item[{\textbf{-maxrenewlife} \emph{max\_renewable\_ticket\_life}}] \leavevmode
(\emph{getdate} string) Specifies maximum renewable life of
tickets for principals in this realm.

\item[{\emph{ticket\_flags}}] \leavevmode
Specifies global ticket flags for the realm.  Allowable flags are
documented in the description of the \textbf{add\_principal} command in
{\hyperref[admin/admin_commands/kadmin_local:kadmin-1]{\emph{kadmin}}}.

\end{description}

Example:

\begin{Verbatim}[commandchars=\\\{\}]
shell\PYGZpc{} kdb5\PYGZus{}ldap\PYGZus{}util \PYGZhy{}D cn=admin,o=org \PYGZhy{}H
    ldaps://ldap\PYGZhy{}server1.mit.edu modify +requires\PYGZus{}preauth \PYGZhy{}r
    ATHENA.MIT.EDU
Password for \PYGZdq{}cn=admin,o=org\PYGZdq{}:
shell\PYGZpc{}
\end{Verbatim}


\subsubsection{view}
\label{admin/admin_commands/kdb5_ldap_util:kdb5-ldap-util-modify-end}\label{admin/admin_commands/kdb5_ldap_util:view}\phantomsection\label{admin/admin_commands/kdb5_ldap_util:kdb5-ldap-util-view}\begin{quote}

\textbf{view} {[}\textbf{-r} \emph{realm}{]}
\end{quote}

Displays the attributes of a realm.  Options:
\begin{description}
\item[{\textbf{-r} \emph{realm}}] \leavevmode
Specifies the Kerberos realm of the database.

\end{description}

Example:

\begin{Verbatim}[commandchars=\\\{\}]
kdb5\PYGZus{}ldap\PYGZus{}util \PYGZhy{}D cn=admin,o=org \PYGZhy{}H ldaps://ldap\PYGZhy{}server1.mit.edu
    view \PYGZhy{}r ATHENA.MIT.EDU
Password for \PYGZdq{}cn=admin,o=org\PYGZdq{}:
Realm Name: ATHENA.MIT.EDU
Subtree: ou=users,o=org
Subtree: ou=servers,o=org
SearchScope: ONE
Maximum ticket life: 0 days 01:00:00
Maximum renewable life: 0 days 10:00:00
Ticket flags: DISALLOW\PYGZus{}FORWARDABLE REQUIRES\PYGZus{}PWCHANGE
\end{Verbatim}


\subsubsection{destroy}
\label{admin/admin_commands/kdb5_ldap_util:destroy}\label{admin/admin_commands/kdb5_ldap_util:kdb5-ldap-util-view-end}\phantomsection\label{admin/admin_commands/kdb5_ldap_util:kdb5-ldap-util-destroy}\begin{quote}

\textbf{destroy} {[}\textbf{-f}{]} {[}\textbf{-r} \emph{realm}{]}
\end{quote}

Destroys an existing realm. Options:
\begin{description}
\item[{\textbf{-f}}] \leavevmode
If specified, will not prompt the user for confirmation.

\item[{\textbf{-r} \emph{realm}}] \leavevmode
Specifies the Kerberos realm of the database.

\end{description}

Example:

\begin{Verbatim}[commandchars=\\\{\}]
shell\PYGZpc{} kdb5\PYGZus{}ldap\PYGZus{}util \PYGZhy{}D cn=admin,o=org \PYGZhy{}H
    ldaps://ldap\PYGZhy{}server1.mit.edu destroy \PYGZhy{}r ATHENA.MIT.EDU
Password for \PYGZdq{}cn=admin,o=org\PYGZdq{}:
Deleting KDC database of \PYGZsq{}ATHENA.MIT.EDU\PYGZsq{}, are you sure?
(type \PYGZsq{}yes\PYGZsq{} to confirm)? yes
OK, deleting database of \PYGZsq{}ATHENA.MIT.EDU\PYGZsq{}...
shell\PYGZpc{}
\end{Verbatim}


\subsubsection{list}
\label{admin/admin_commands/kdb5_ldap_util:kdb5-ldap-util-destroy-end}\label{admin/admin_commands/kdb5_ldap_util:list}\phantomsection\label{admin/admin_commands/kdb5_ldap_util:kdb5-ldap-util-list}\begin{quote}

\textbf{list}
\end{quote}

Lists the name of realms.

Example:

\begin{Verbatim}[commandchars=\\\{\}]
shell\PYGZpc{} kdb5\PYGZus{}ldap\PYGZus{}util \PYGZhy{}D cn=admin,o=org \PYGZhy{}H
    ldaps://ldap\PYGZhy{}server1.mit.edu list
Password for \PYGZdq{}cn=admin,o=org\PYGZdq{}:
ATHENA.MIT.EDU
OPENLDAP.MIT.EDU
MEDIA\PYGZhy{}LAB.MIT.EDU
shell\PYGZpc{}
\end{Verbatim}


\subsubsection{stashsrvpw}
\label{admin/admin_commands/kdb5_ldap_util:kdb5-ldap-util-list-end}\label{admin/admin_commands/kdb5_ldap_util:stashsrvpw}\phantomsection\label{admin/admin_commands/kdb5_ldap_util:kdb5-ldap-util-stashsrvpw}\begin{quote}

\textbf{stashsrvpw}
{[}\textbf{-f} \emph{filename}{]}
\emph{name}
\end{quote}

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:
\begin{description}
\item[{\textbf{-f} \emph{filename}}] \leavevmode
Specifies the complete path of the service password file. By
default, \code{/usr/local/var/service\_passwd} is used.

\item[{\emph{name}}] \leavevmode
Specifies the name of the object whose password is to be stored.
If {\hyperref[admin/admin_commands/krb5kdc:krb5kdc-8]{\emph{krb5kdc}}} or {\hyperref[admin/admin_commands/kadmind:kadmind-8]{\emph{kadmind}}} are configured for
simple binding, this should be the distinguished name it will
use as given by the \textbf{ldap\_kdc\_dn} or \textbf{ldap\_kadmind\_dn}
variable in {\hyperref[admin/conf_files/kdc_conf:kdc-conf-5]{\emph{kdc.conf}}}.  If the KDC or kadmind is
configured for SASL binding, this should be the authentication
name it will use as given by the \textbf{ldap\_kdc\_sasl\_authcid} or
\textbf{ldap\_kadmind\_sasl\_authcid} variable.

\end{description}

Example:

\begin{Verbatim}[commandchars=\\\{\}]
kdb5\PYGZus{}ldap\PYGZus{}util stashsrvpw \PYGZhy{}f /home/andrew/conf\PYGZus{}keyfile
    cn=service\PYGZhy{}kdc,o=org
Password for \PYGZdq{}cn=service\PYGZhy{}kdc,o=org\PYGZdq{}:
Re\PYGZhy{}enter password for \PYGZdq{}cn=service\PYGZhy{}kdc,o=org\PYGZdq{}:
\end{Verbatim}


\subsubsection{create\_policy}
\label{admin/admin_commands/kdb5_ldap_util:create-policy}\label{admin/admin_commands/kdb5_ldap_util:kdb5-ldap-util-stashsrvpw-end}\phantomsection\label{admin/admin_commands/kdb5_ldap_util:kdb5-ldap-util-create-policy}\begin{quote}

\textbf{create\_policy}
{[}\textbf{-r} \emph{realm}{]}
{[}\textbf{-maxtktlife} \emph{max\_ticket\_life}{]}
{[}\textbf{-maxrenewlife} \emph{max\_renewable\_ticket\_life}{]}
{[}\emph{ticket\_flags}{]}
\emph{policy\_name}
\end{quote}

Creates a ticket policy in the directory.  Options:
\begin{description}
\item[{\textbf{-r} \emph{realm}}] \leavevmode
Specifies the Kerberos realm of the database.

\item[{\textbf{-maxtktlife} \emph{max\_ticket\_life}}] \leavevmode
(\emph{getdate} string) Specifies maximum ticket life for
principals.

\item[{\textbf{-maxrenewlife} \emph{max\_renewable\_ticket\_life}}] \leavevmode
(\emph{getdate} string) Specifies maximum renewable life of
tickets for principals.

\item[{\emph{ticket\_flags}}] \leavevmode
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 \textbf{add\_principal}
command in {\hyperref[admin/admin_commands/kadmin_local:kadmin-1]{\emph{kadmin}}}.

\item[{\emph{policy\_name}}] \leavevmode
Specifies the name of the ticket policy.

\end{description}

Example:

\begin{Verbatim}[commandchars=\\\{\}]
kdb5\PYGZus{}ldap\PYGZus{}util \PYGZhy{}D cn=admin,o=org \PYGZhy{}H ldaps://ldap\PYGZhy{}server1.mit.edu
    create\PYGZus{}policy \PYGZhy{}r ATHENA.MIT.EDU \PYGZhy{}maxtktlife \PYGZdq{}1 day\PYGZdq{}
    \PYGZhy{}maxrenewlife \PYGZdq{}1 week\PYGZdq{} \PYGZhy{}allow\PYGZus{}postdated +needchange
    \PYGZhy{}allow\PYGZus{}forwardable tktpolicy
Password for \PYGZdq{}cn=admin,o=org\PYGZdq{}:
\end{Verbatim}


\subsubsection{modify\_policy}
\label{admin/admin_commands/kdb5_ldap_util:modify-policy}\label{admin/admin_commands/kdb5_ldap_util:kdb5-ldap-util-create-policy-end}\phantomsection\label{admin/admin_commands/kdb5_ldap_util:kdb5-ldap-util-modify-policy}\begin{quote}

\textbf{modify\_policy}
{[}\textbf{-r} \emph{realm}{]}
{[}\textbf{-maxtktlife} \emph{max\_ticket\_life}{]}
{[}\textbf{-maxrenewlife} \emph{max\_renewable\_ticket\_life}{]}
{[}\emph{ticket\_flags}{]}
\emph{policy\_name}
\end{quote}

Modifies the attributes of a ticket policy.  Options are same as for
\textbf{create\_policy}.

Example:

\begin{Verbatim}[commandchars=\\\{\}]
kdb5\PYGZus{}ldap\PYGZus{}util \PYGZhy{}D cn=admin,o=org \PYGZhy{}H
    ldaps://ldap\PYGZhy{}server1.mit.edu modify\PYGZus{}policy \PYGZhy{}r ATHENA.MIT.EDU
    \PYGZhy{}maxtktlife \PYGZdq{}60 minutes\PYGZdq{} \PYGZhy{}maxrenewlife \PYGZdq{}10 hours\PYGZdq{}
    +allow\PYGZus{}postdated \PYGZhy{}requires\PYGZus{}preauth tktpolicy
Password for \PYGZdq{}cn=admin,o=org\PYGZdq{}:
\end{Verbatim}


\subsubsection{view\_policy}
\label{admin/admin_commands/kdb5_ldap_util:view-policy}\label{admin/admin_commands/kdb5_ldap_util:kdb5-ldap-util-modify-policy-end}\phantomsection\label{admin/admin_commands/kdb5_ldap_util:kdb5-ldap-util-view-policy}\begin{quote}

\textbf{view\_policy}
{[}\textbf{-r} \emph{realm}{]}
\emph{policy\_name}
\end{quote}

Displays the attributes of a ticket policy.  Options:
\begin{description}
\item[{\emph{policy\_name}}] \leavevmode
Specifies the name of the ticket policy.

\end{description}

Example:

\begin{Verbatim}[commandchars=\\\{\}]
kdb5\PYGZus{}ldap\PYGZus{}util \PYGZhy{}D cn=admin,o=org \PYGZhy{}H ldaps://ldap\PYGZhy{}server1.mit.edu
    view\PYGZus{}policy \PYGZhy{}r ATHENA.MIT.EDU tktpolicy
Password for \PYGZdq{}cn=admin,o=org\PYGZdq{}:
Ticket policy: tktpolicy
Maximum ticket life: 0 days 01:00:00
Maximum renewable life: 0 days 10:00:00
Ticket flags: DISALLOW\PYGZus{}FORWARDABLE REQUIRES\PYGZus{}PWCHANGE
\end{Verbatim}


\subsubsection{destroy\_policy}
\label{admin/admin_commands/kdb5_ldap_util:destroy-policy}\label{admin/admin_commands/kdb5_ldap_util:kdb5-ldap-util-view-policy-end}\phantomsection\label{admin/admin_commands/kdb5_ldap_util:kdb5-ldap-util-destroy-policy}\begin{quote}

\textbf{destroy\_policy}
{[}\textbf{-r} \emph{realm}{]}
{[}\textbf{-force}{]}
\emph{policy\_name}
\end{quote}

Destroys an existing ticket policy.  Options:
\begin{description}
\item[{\textbf{-r} \emph{realm}}] \leavevmode
Specifies the Kerberos realm of the database.

\item[{\textbf{-force}}] \leavevmode
Forces the deletion of the policy object.  If not specified, the
user will be prompted for confirmation before deleting the policy.

\item[{\emph{policy\_name}}] \leavevmode
Specifies the name of the ticket policy.

\end{description}

Example:

\begin{Verbatim}[commandchars=\\\{\}]
kdb5\PYGZus{}ldap\PYGZus{}util \PYGZhy{}D cn=admin,o=org \PYGZhy{}H ldaps://ldap\PYGZhy{}server1.mit.edu
    destroy\PYGZus{}policy \PYGZhy{}r ATHENA.MIT.EDU tktpolicy
Password for \PYGZdq{}cn=admin,o=org\PYGZdq{}:
This will delete the policy object \PYGZsq{}tktpolicy\PYGZsq{}, are you sure?
(type \PYGZsq{}yes\PYGZsq{} to confirm)? yes
** policy object \PYGZsq{}tktpolicy\PYGZsq{} deleted.
\end{Verbatim}


\subsubsection{list\_policy}
\label{admin/admin_commands/kdb5_ldap_util:list-policy}\label{admin/admin_commands/kdb5_ldap_util:kdb5-ldap-util-destroy-policy-end}\phantomsection\label{admin/admin_commands/kdb5_ldap_util:kdb5-ldap-util-list-policy}\begin{quote}

\textbf{list\_policy}
{[}\textbf{-r} \emph{realm}{]}
\end{quote}

Lists the ticket policies in realm if specified or in the default
realm.  Options:
\begin{description}
\item[{\textbf{-r} \emph{realm}}] \leavevmode
Specifies the Kerberos realm of the database.

\end{description}

Example:

\begin{Verbatim}[commandchars=\\\{\}]
kdb5\PYGZus{}ldap\PYGZus{}util \PYGZhy{}D cn=admin,o=org \PYGZhy{}H ldaps://ldap\PYGZhy{}server1.mit.edu
    list\PYGZus{}policy \PYGZhy{}r ATHENA.MIT.EDU
Password for \PYGZdq{}cn=admin,o=org\PYGZdq{}:
tktpolicy
tmppolicy
userpolicy
\end{Verbatim}


\subsection{SEE ALSO}
\label{admin/admin_commands/kdb5_ldap_util:see-also}\label{admin/admin_commands/kdb5_ldap_util:kdb5-ldap-util-list-policy-end}
{\hyperref[admin/admin_commands/kadmin_local:kadmin-1]{\emph{kadmin}}}


\section{krb5kdc}
\label{admin/admin_commands/krb5kdc::doc}\label{admin/admin_commands/krb5kdc:krb5kdc-8}\label{admin/admin_commands/krb5kdc:krb5kdc}

\subsection{SYNOPSIS}
\label{admin/admin_commands/krb5kdc:synopsis}
\textbf{krb5kdc}
{[}\textbf{-x} \emph{db\_args}{]}
{[}\textbf{-d} \emph{dbname}{]}
{[}\textbf{-k} \emph{keytype}{]}
{[}\textbf{-M} \emph{mkeyname}{]}
{[}\textbf{-p} \emph{portnum}{]}
{[}\textbf{-m}{]}
{[}\textbf{-r} \emph{realm}{]}
{[}\textbf{-n}{]}
{[}\textbf{-w} \emph{numworkers}{]}
{[}\textbf{-P} \emph{pid\_file}{]}
{[}\textbf{-T} \emph{time\_offset}{]}


\subsection{DESCRIPTION}
\label{admin/admin_commands/krb5kdc:description}
krb5kdc is the Kerberos version 5 Authentication Service and Key
Distribution Center (AS/KDC).


\subsection{OPTIONS}
\label{admin/admin_commands/krb5kdc:options}
The \textbf{-r} \emph{realm} option specifies the realm for which the server
should provide service.

The \textbf{-d} \emph{dbname} option specifies the name under which the
principal database can be found.  This option does not apply to the
LDAP database.

The \textbf{-k} \emph{keytype} option specifies the key type of the master key
to be entered manually as a password when \textbf{-m} is given; the default
is \code{des-cbc-crc}.

The \textbf{-M} \emph{mkeyname} option specifies the principal name for the
master key in the database (usually \code{K/M} in the KDC's realm).

The \textbf{-m} option specifies that the master database password should
be fetched from the keyboard rather than from a stash file.

The \textbf{-n} option specifies that the KDC does not put itself in the
background and does not disassociate itself from the terminal.  In
normal operation, you should always allow the KDC to place itself in
the background.

The \textbf{-P} \emph{pid\_file} option tells the KDC to write its PID into
\emph{pid\_file} after it starts up.  This can be used to identify whether
the KDC is still running and to allow init scripts to stop the correct
process.

The \textbf{-p} \emph{portnum} option specifies the default UDP port numbers
which the KDC should listen on for Kerberos version 5 requests, as a
comma-separated list.  This value overrides the UDP port numbers
specified in the {\hyperref[admin/conf_files/kdc_conf:kdcdefaults]{\emph{{[}kdcdefaults{]}}}} section of {\hyperref[admin/conf_files/kdc_conf:kdc-conf-5]{\emph{kdc.conf}}}, but
may be overridden by realm-specific values.  If no value is given from
any source, the default port is 88.

The \textbf{-w} \emph{numworkers} option tells the KDC to fork \emph{numworkers}
processes to listen to the KDC ports and process requests in parallel.
The top level KDC process (whose pid is recorded in the pid file if
the \textbf{-P} option is also given) acts as a supervisor.  The supervisor
will relay SIGHUP signals to the worker subprocesses, and will
terminate the worker subprocess if the it is itself terminated or if
any other worker process exits.

\begin{notice}{note}{Note:}
On operating systems which do not have \emph{pktinfo} support,
using worker processes will prevent the KDC from listening
for UDP packets on network interfaces created after the KDC
starts.
\end{notice}

The \textbf{-x} \emph{db\_args} option specifies database-specific arguments.
See {\hyperref[admin/admin_commands/kadmin_local:dboptions]{\emph{Database Options}}} in {\hyperref[admin/admin_commands/kadmin_local:kadmin-1]{\emph{kadmin}}} for
supported arguments.

The \textbf{-T} \emph{offset} option specifies a time offset, in seconds, which
the KDC will operate under.  It is intended only for testing purposes.


\subsection{EXAMPLE}
\label{admin/admin_commands/krb5kdc:example}
The KDC may service requests for multiple realms (maximum 32 realms).
The realms are listed on the command line.  Per-realm options that can
be specified on the command line pertain for each realm that follows
it and are superseded by subsequent definitions of the same option.

For example:

\begin{Verbatim}[commandchars=\\\{\}]
krb5kdc \PYGZhy{}p 2001 \PYGZhy{}r REALM1 \PYGZhy{}p 2002 \PYGZhy{}r REALM2 \PYGZhy{}r REALM3
\end{Verbatim}

specifies that the KDC listen on port 2001 for REALM1 and on port 2002
for REALM2 and REALM3.  Additionally, per-realm parameters may be
specified in the {\hyperref[admin/conf_files/kdc_conf:kdc-conf-5]{\emph{kdc.conf}}} file.  The location of this file
may be specified by the \textbf{KRB5\_KDC\_PROFILE} environment variable.
Per-realm parameters specified in this file take precedence over
options specified on the command line.  See the {\hyperref[admin/conf_files/kdc_conf:kdc-conf-5]{\emph{kdc.conf}}}
description for further details.


\subsection{ENVIRONMENT}
\label{admin/admin_commands/krb5kdc:environment}
krb5kdc uses the following environment variables:
\begin{itemize}
\item {} 
\textbf{KRB5\_CONFIG}

\item {} 
\textbf{KRB5\_KDC\_PROFILE}

\end{itemize}


\subsection{SEE ALSO}
\label{admin/admin_commands/krb5kdc:see-also}
{\hyperref[admin/admin_commands/kdb5_util:kdb5-util-8]{\emph{kdb5\_util}}}, {\hyperref[admin/conf_files/kdc_conf:kdc-conf-5]{\emph{kdc.conf}}}, {\hyperref[admin/conf_files/krb5_conf:krb5-conf-5]{\emph{krb5.conf}}},
{\hyperref[admin/admin_commands/kdb5_ldap_util:kdb5-ldap-util-8]{\emph{kdb5\_ldap\_util}}}


\section{kprop}
\label{admin/admin_commands/kprop:kprop-8}\label{admin/admin_commands/kprop::doc}\label{admin/admin_commands/kprop:kprop}

\subsection{SYNOPSIS}
\label{admin/admin_commands/kprop:synopsis}
\textbf{kprop}
{[}\textbf{-r} \emph{realm}{]}
{[}\textbf{-f} \emph{file}{]}
{[}\textbf{-d}{]}
{[}\textbf{-P} \emph{port}{]}
{[}\textbf{-s} \emph{keytab}{]}
\emph{slave\_host}


\subsection{DESCRIPTION}
\label{admin/admin_commands/kprop:description}
kprop is used to securely propagate a Kerberos V5 database dump file
from the master Kerberos server to a slave Kerberos server, which is
specified by \emph{slave\_host}.  The dump file must be created by
{\hyperref[admin/admin_commands/kdb5_util:kdb5-util-8]{\emph{kdb5\_util}}}.


\subsection{OPTIONS}
\label{admin/admin_commands/kprop:options}\begin{description}
\item[{\textbf{-r} \emph{realm}}] \leavevmode
Specifies the realm of the master server.

\item[{\textbf{-f} \emph{file}}] \leavevmode
Specifies the filename where the dumped principal database file is
to be found; by default the dumped database file is normally
{\hyperref[mitK5defaults:paths]{\emph{LOCALSTATEDIR}}}\code{/krb5kdc}\code{/slave\_datatrans}.

\item[{\textbf{-P} \emph{port}}] \leavevmode
Specifies the port to use to contact the {\hyperref[admin/admin_commands/kpropd:kpropd-8]{\emph{kpropd}}} server
on the remote host.

\item[{\textbf{-d}}] \leavevmode
Prints debugging information.

\item[{\textbf{-s} \emph{keytab}}] \leavevmode
Specifies the location of the keytab file.

\end{description}


\subsection{ENVIRONMENT}
\label{admin/admin_commands/kprop:environment}
\emph{kprop} uses the following environment variable:
\begin{itemize}
\item {} 
\textbf{KRB5\_CONFIG}

\end{itemize}


\subsection{SEE ALSO}
\label{admin/admin_commands/kprop:see-also}
{\hyperref[admin/admin_commands/kpropd:kpropd-8]{\emph{kpropd}}}, {\hyperref[admin/admin_commands/kdb5_util:kdb5-util-8]{\emph{kdb5\_util}}}, {\hyperref[admin/admin_commands/krb5kdc:krb5kdc-8]{\emph{krb5kdc}}}


\section{kpropd}
\label{admin/admin_commands/kpropd::doc}\label{admin/admin_commands/kpropd:kpropd}\label{admin/admin_commands/kpropd:kpropd-8}

\subsection{SYNOPSIS}
\label{admin/admin_commands/kpropd:synopsis}
\textbf{kpropd}
{[}\textbf{-r} \emph{realm}{]}
{[}\textbf{-A} \emph{admin\_server}{]}
{[}\textbf{-a} \emph{acl\_file}{]}
{[}\textbf{-f} \emph{slave\_dumpfile}{]}
{[}\textbf{-F} \emph{principal\_database}{]}
{[}\textbf{-p} \emph{kdb5\_util\_prog}{]}
{[}\textbf{-P} \emph{port}{]}
{[}\textbf{-d}{]}
{[}\textbf{-t}{]}


\subsection{DESCRIPTION}
\label{admin/admin_commands/kpropd:description}
The \emph{kpropd} command runs on the slave KDC server.  It listens for
update requests made by the {\hyperref[admin/admin_commands/kprop:kprop-8]{\emph{kprop}}} program.  If incremental
propagation is enabled, it periodically requests incremental updates
from the master KDC.

When the slave receives a kprop request from the master, kpropd
accepts the dumped KDC database and places it in a file, and then runs
{\hyperref[admin/admin_commands/kdb5_util:kdb5-util-8]{\emph{kdb5\_util}}} to load the dumped database into the active
database which is used by {\hyperref[admin/admin_commands/krb5kdc:krb5kdc-8]{\emph{krb5kdc}}}.  This allows the master
Kerberos server to use {\hyperref[admin/admin_commands/kprop:kprop-8]{\emph{kprop}}} to propagate its database to
the slave servers.  Upon a successful download of the KDC database
file, the slave Kerberos server will have an up-to-date KDC database.

Where incremental propagation is not used, kpropd is commonly invoked
out of inetd(8) as a nowait service.  This is done by adding a line to
the \code{/etc/inetd.conf} file which looks like this:

\begin{Verbatim}[commandchars=\\\{\}]
kprop  stream  tcp  nowait  root  /usr/local/sbin/kpropd  kpropd
\end{Verbatim}

kpropd can also run as a standalone daemon, backgrounding itself and
waiting for connections on port 754 (or the port specified with the
\textbf{-P} option if given).  Standalone mode is required for incremental
propagation.  Starting in release 1.11, kpropd automatically detects
whether it was run from inetd and runs in standalone mode if it is
not.  Prior to release 1.11, the \textbf{-S} option is required to run
kpropd in standalone mode; this option is now accepted for backward
compatibility but does nothing.

Incremental propagation may be enabled with the \textbf{iprop\_enable}
variable in {\hyperref[admin/conf_files/kdc_conf:kdc-conf-5]{\emph{kdc.conf}}}.  If incremental propagation is
enabled, the slave periodically polls the master KDC for updates, at
an interval determined by the \textbf{iprop\_slave\_poll} variable.  If the
slave receives updates, kpropd updates its log file with any updates
from the master.  {\hyperref[admin/admin_commands/kproplog:kproplog-8]{\emph{kproplog}}} can be used to view a summary of
the update entry log on the slave KDC.  If incremental propagation is
enabled, the principal \code{kiprop/slavehostname@REALM} (where
\emph{slavehostname} is the name of the slave KDC host, and \emph{REALM} is the
name of the Kerberos realm) must be present in the slave's keytab
file.

{\hyperref[admin/admin_commands/kproplog:kproplog-8]{\emph{kproplog}}} can be used to force full replication when iprop is
enabled.


\subsection{OPTIONS}
\label{admin/admin_commands/kpropd:options}\begin{description}
\item[{\textbf{-r} \emph{realm}}] \leavevmode
Specifies the realm of the master server.

\item[{\textbf{-A} \emph{admin\_server}}] \leavevmode
Specifies the server to be contacted for incremental updates; by
default, the master admin server is contacted.

\item[{\textbf{-f} \emph{file}}] \leavevmode
Specifies the filename where the dumped principal database file is
to be stored; by default the dumped database file is {\hyperref[mitK5defaults:paths]{\emph{LOCALSTATEDIR}}}\code{/krb5kdc}\code{/from\_master}.

\item[{\textbf{-p}}] \leavevmode
Allows the user to specify the pathname to the {\hyperref[admin/admin_commands/kdb5_util:kdb5-util-8]{\emph{kdb5\_util}}}
program; by default the pathname used is {\hyperref[mitK5defaults:paths]{\emph{SBINDIR}}}\code{/kdb5\_util}.

\item[{\textbf{-d}}] \leavevmode
Turn on debug mode.  In this mode, kpropd will not detach
itself from the current job and run in the background.  Instead,
it will run in the foreground and print out debugging messages
during the database propagation.

\item[{\textbf{-t}}] \leavevmode
In standalone mode without incremental propagation, exit after one
dump file is received.  In incremental propagation mode, exit as
soon as the database is up to date, or if the master returns an
error.

\item[{\textbf{-P}}] \leavevmode
Allow for an alternate port number for kpropd to listen on.  This
is only useful in combination with the \textbf{-S} option.

\item[{\textbf{-a} \emph{acl\_file}}] \leavevmode
Allows the user to specify the path to the kpropd.acl file; by
default the path used is {\hyperref[mitK5defaults:paths]{\emph{LOCALSTATEDIR}}}\code{/krb5kdc}\code{/kpropd.acl}.

\end{description}


\subsection{ENVIRONMENT}
\label{admin/admin_commands/kpropd:environment}
kpropd uses the following environment variables:
\begin{itemize}
\item {} 
\textbf{KRB5\_CONFIG}

\item {} 
\textbf{KRB5\_KDC\_PROFILE}

\end{itemize}


\subsection{FILES}
\label{admin/admin_commands/kpropd:files}\begin{description}
\item[{kpropd.acl}] \leavevmode
Access file for kpropd; the default location is
\code{/usr/local/var/krb5kdc/kpropd.acl}.  Each entry is a line
containing the principal of a host from which the local machine
will allow Kerberos database propagation via {\hyperref[admin/admin_commands/kprop:kprop-8]{\emph{kprop}}}.

\end{description}


\subsection{SEE ALSO}
\label{admin/admin_commands/kpropd:see-also}
{\hyperref[admin/admin_commands/kprop:kprop-8]{\emph{kprop}}}, {\hyperref[admin/admin_commands/kdb5_util:kdb5-util-8]{\emph{kdb5\_util}}}, {\hyperref[admin/admin_commands/krb5kdc:krb5kdc-8]{\emph{krb5kdc}}}, inetd(8)


\section{kproplog}
\label{admin/admin_commands/kproplog:kproplog}\label{admin/admin_commands/kproplog:kproplog-8}\label{admin/admin_commands/kproplog::doc}

\subsection{SYNOPSIS}
\label{admin/admin_commands/kproplog:synopsis}
\textbf{kproplog} {[}\textbf{-h}{]} {[}\textbf{-e} \emph{num}{]} {[}-v{]}
\textbf{kproplog} {[}-R{]}


\subsection{DESCRIPTION}
\label{admin/admin_commands/kproplog:description}
The kproplog command displays the contents of the KDC database update
log to standard output.  It can be used to keep track of incremental
updates to the principal database.  The update log file contains the
update log maintained by the {\hyperref[admin/admin_commands/kadmind:kadmind-8]{\emph{kadmind}}} process on the master
KDC server and the {\hyperref[admin/admin_commands/kpropd:kpropd-8]{\emph{kpropd}}} process on the slave KDC servers.
When updates occur, they are logged to this file.  Subsequently any
KDC slave configured for incremental updates will request the current
data from the master KDC and update their log file with any updates
returned.

The kproplog command requires read access to the update log file.  It
will display update entries only for the KDC it runs on.

If no options are specified, kproplog displays a summary of the update
log.  If invoked on the master, kproplog also displays all of the
update entries.  If invoked on a slave KDC server, kproplog displays
only a summary of the updates, which includes the serial number of the
last update received and the associated time stamp of the last update.


\subsection{OPTIONS}
\label{admin/admin_commands/kproplog:options}\begin{description}
\item[{\textbf{-R}}] \leavevmode
Reset the update log.  This forces full resynchronization.  If used
on a slave then that slave will request a full resync.  If used on
the master then all slaves will request full resyncs.

\item[{\textbf{-h}}] \leavevmode
Display a summary of the update log.  This information includes
the database version number, state of the database, the number of
updates in the log, the time stamp of the first and last update,
and the version number of the first and last update entry.

\item[{\textbf{-e} \emph{num}}] \leavevmode
Display the last \emph{num} update entries in the log.  This is useful
when debugging synchronization between KDC servers.

\item[{\textbf{-v}}] \leavevmode
Display individual attributes per update.  An example of the
output generated for one entry:

\begin{Verbatim}[commandchars=\\\{\}]
Update Entry
   Update serial \PYGZsh{} : 4
   Update operation : Add
   Update principal : test@EXAMPLE.COM
   Update size : 424
   Update committed : True
   Update time stamp : Fri Feb 20 23:37:42 2004
   Attributes changed : 6
         Principal
         Key data
         Password last changed
         Modifying principal
         Modification time
         TL data
\end{Verbatim}

\end{description}


\subsection{ENVIRONMENT}
\label{admin/admin_commands/kproplog:environment}
kproplog uses the following environment variables:
\begin{itemize}
\item {} 
\textbf{KRB5\_KDC\_PROFILE}

\end{itemize}


\subsection{SEE ALSO}
\label{admin/admin_commands/kproplog:see-also}
{\hyperref[admin/admin_commands/kpropd:kpropd-8]{\emph{kpropd}}}


\section{ktutil}
\label{admin/admin_commands/ktutil:ktutil-1}\label{admin/admin_commands/ktutil::doc}\label{admin/admin_commands/ktutil:ktutil}

\subsection{SYNOPSIS}
\label{admin/admin_commands/ktutil:synopsis}
\textbf{ktutil}


\subsection{DESCRIPTION}
\label{admin/admin_commands/ktutil:description}
The ktutil command invokes a command interface from which an
administrator can read, write, or edit entries in a keytab or Kerberos
V4 srvtab file.


\subsection{COMMANDS}
\label{admin/admin_commands/ktutil:commands}

\subsubsection{list}
\label{admin/admin_commands/ktutil:list}\begin{quote}

\textbf{list}
\end{quote}

Displays the current keylist.

Alias: \textbf{l}


\subsubsection{read\_kt}
\label{admin/admin_commands/ktutil:read-kt}\begin{quote}

\textbf{read\_kt} \emph{keytab}
\end{quote}

Read the Kerberos V5 keytab file \emph{keytab} into the current keylist.

Alias: \textbf{rkt}


\subsubsection{read\_st}
\label{admin/admin_commands/ktutil:read-st}\begin{quote}

\textbf{read\_st} \emph{srvtab}
\end{quote}

Read the Kerberos V4 srvtab file \emph{srvtab} into the current keylist.

Alias: \textbf{rst}


\subsubsection{write\_kt}
\label{admin/admin_commands/ktutil:write-kt}\begin{quote}

\textbf{write\_kt} \emph{keytab}
\end{quote}

Write the current keylist into the Kerberos V5 keytab file \emph{keytab}.

Alias: \textbf{wkt}


\subsubsection{write\_st}
\label{admin/admin_commands/ktutil:write-st}\begin{quote}

\textbf{write\_st} \emph{srvtab}
\end{quote}

Write the current keylist into the Kerberos V4 srvtab file \emph{srvtab}.

Alias: \textbf{wst}


\subsubsection{clear\_list}
\label{admin/admin_commands/ktutil:clear-list}\begin{quote}

\textbf{clear\_list}
\end{quote}

Clear the current keylist.

Alias: \textbf{clear}


\subsubsection{delete\_entry}
\label{admin/admin_commands/ktutil:delete-entry}\begin{quote}

\textbf{delete\_entry} \emph{slot}
\end{quote}

Delete the entry in slot number \emph{slot} from the current keylist.

Alias: \textbf{delent}


\subsubsection{add\_entry}
\label{admin/admin_commands/ktutil:add-entry}\begin{quote}

\textbf{add\_entry} \{\textbf{-key}\textbar{}\textbf{-password}\} \textbf{-p} \emph{principal}
\textbf{-k} \emph{kvno} \textbf{-e} \emph{enctype}
\end{quote}

Add \emph{principal} to keylist using key or password.

Alias: \textbf{addent}


\subsubsection{list\_requests}
\label{admin/admin_commands/ktutil:list-requests}\begin{quote}

\textbf{list\_requests}
\end{quote}

Displays a listing of available commands.

Aliases: \textbf{lr}, \textbf{?}


\subsubsection{quit}
\label{admin/admin_commands/ktutil:quit}\begin{quote}

\textbf{quit}
\end{quote}

Quits ktutil.

Aliases: \textbf{exit}, \textbf{q}


\subsection{EXAMPLE}
\label{admin/admin_commands/ktutil:example}\begin{quote}

\begin{Verbatim}[commandchars=\\\{\}]
ktutil:  add\PYGZus{}entry \PYGZhy{}password \PYGZhy{}p alice@BLEEP.COM \PYGZhy{}k 1 \PYGZhy{}e
    aes128\PYGZhy{}cts\PYGZhy{}hmac\PYGZhy{}sha1\PYGZhy{}96
Password for alice@BLEEP.COM:
ktutil:  add\PYGZus{}entry \PYGZhy{}password \PYGZhy{}p alice@BLEEP.COM \PYGZhy{}k 1 \PYGZhy{}e
    aes256\PYGZhy{}cts\PYGZhy{}hmac\PYGZhy{}sha1\PYGZhy{}96
Password for alice@BLEEP.COM:
ktutil:  write\PYGZus{}kt keytab
ktutil:
\end{Verbatim}
\end{quote}


\subsection{SEE ALSO}
\label{admin/admin_commands/ktutil:see-also}
{\hyperref[admin/admin_commands/kadmin_local:kadmin-1]{\emph{kadmin}}}, {\hyperref[admin/admin_commands/kdb5_util:kdb5-util-8]{\emph{kdb5\_util}}}


\section{k5srvutil}
\label{admin/admin_commands/k5srvutil:k5srvutil-1}\label{admin/admin_commands/k5srvutil::doc}\label{admin/admin_commands/k5srvutil:k5srvutil}

\subsection{SYNOPSIS}
\label{admin/admin_commands/k5srvutil:synopsis}
\textbf{k5srvutil} \emph{operation}
{[}\textbf{-i}{]}
{[}\textbf{-f} \emph{filename}{]}
{[}\textbf{-e} \emph{keysalts}{]}


\subsection{DESCRIPTION}
\label{admin/admin_commands/k5srvutil:description}
k5srvutil allows an administrator to list keys currently in
a keytab, to obtain new keys for a principal currently in a keytab,
or to delete non-current keys from a keytab.

\emph{operation} must be one of the following:
\begin{description}
\item[{\textbf{list}}] \leavevmode
Lists the keys in a keytab, showing version number and principal
name.

\item[{\textbf{change}}] \leavevmode
Uses the kadmin protocol to update the keys in the Kerberos
database to new randomly-generated keys, and updates the keys in
the keytab to match.  If a key's version number doesn't match the
version number stored in the Kerberos server's database, then the
operation will fail.  If the \textbf{-i} flag is given, k5srvutil will
prompt for confirmation before changing each key.  If the \textbf{-k}
option is given, the old and new keys will be displayed.
Ordinarily, keys will be generated with the default encryption
types and key salts.  This can be overridden with the \textbf{-e}
option.  Old keys are retained in the keytab so that existing
tickets continue to work, but \textbf{delold} should be used after
such tickets expire, to prevent attacks against the old keys.

\item[{\textbf{delold}}] \leavevmode
Deletes keys that are not the most recent version from the keytab.
This operation should be used some time after a change operation
to remove old keys, after existing tickets issued for the service
have expired.  If the \textbf{-i} flag is given, then k5srvutil will
prompt for confirmation for each principal.

\item[{\textbf{delete}}] \leavevmode
Deletes particular keys in the keytab, interactively prompting for
each key.

\end{description}

In all cases, the default keytab is used unless this is overridden by
the \textbf{-f} option.

k5srvutil uses the {\hyperref[admin/admin_commands/kadmin_local:kadmin-1]{\emph{kadmin}}} program to edit the keytab in
place.


\subsection{SEE ALSO}
\label{admin/admin_commands/k5srvutil:see-also}
{\hyperref[admin/admin_commands/kadmin_local:kadmin-1]{\emph{kadmin}}}, {\hyperref[admin/admin_commands/ktutil:ktutil-1]{\emph{ktutil}}}


\section{sserver}
\label{admin/admin_commands/sserver:sserver-8}\label{admin/admin_commands/sserver::doc}\label{admin/admin_commands/sserver:sserver}

\subsection{SYNOPSIS}
\label{admin/admin_commands/sserver:synopsis}
\textbf{sserver}
{[} \textbf{-p} \emph{port} {]}
{[} \textbf{-S} \emph{keytab} {]}
{[} \emph{server\_port} {]}


\subsection{DESCRIPTION}
\label{admin/admin_commands/sserver:description}
sserver and \emph{sclient(1)} are a simple demonstration client/server
application.  When sclient connects to sserver, it performs a Kerberos
authentication, and then sserver returns to sclient the Kerberos
principal which was used for the Kerberos authentication.  It makes a
good test that Kerberos has been successfully installed on a machine.

The service name used by sserver and sclient is sample.  Hence,
sserver will require that there be a keytab entry for the service
\code{sample/hostname.domain.name@REALM.NAME}.  This keytab is generated
using the {\hyperref[admin/admin_commands/kadmin_local:kadmin-1]{\emph{kadmin}}} program.  The keytab file is usually
installed as {\hyperref[mitK5defaults:paths]{\emph{DEFKTNAME}}}.

The \textbf{-S} option allows for a different keytab than the default.

sserver is normally invoked out of inetd(8), using a line in
\code{/etc/inetd.conf} that looks like this:

\begin{Verbatim}[commandchars=\\\{\}]
sample stream tcp nowait root /usr/local/sbin/sserver sserver
\end{Verbatim}

Since \code{sample} is normally not a port defined in \code{/etc/services},
you will usually have to add a line to \code{/etc/services} which looks
like this:

\begin{Verbatim}[commandchars=\\\{\}]
sample          13135/tcp
\end{Verbatim}

When using sclient, you will first have to have an entry in the
Kerberos database, by using {\hyperref[admin/admin_commands/kadmin_local:kadmin-1]{\emph{kadmin}}}, and then you have to get
Kerberos tickets, by using \emph{kinit(1)}.  Also, if you are running
the sclient program on a different host than the sserver it will be
connecting to, be sure that both hosts have an entry in /etc/services
for the sample tcp port, and that the same port number is in both
files.

When you run sclient you should see something like this:

\begin{Verbatim}[commandchars=\\\{\}]
sendauth succeeded, reply is:
reply len 32, contents:
You are nlgilman@JIMI.MIT.EDU
\end{Verbatim}


\subsection{COMMON ERROR MESSAGES}
\label{admin/admin_commands/sserver:common-error-messages}\begin{enumerate}
\item {} 
kinit returns the error:

\begin{Verbatim}[commandchars=\\\{\}]
kinit: Client not found in Kerberos database while getting
       initial credentials
\end{Verbatim}

This means that you didn't create an entry for your username in the
Kerberos database.

\item {} 
sclient returns the error:

\begin{Verbatim}[commandchars=\\\{\}]
unknown service sample/tcp; check /etc/services
\end{Verbatim}

This means that you don't have an entry in /etc/services for the
sample tcp port.

\item {} 
sclient returns the error:

\begin{Verbatim}[commandchars=\\\{\}]
connect: Connection refused
\end{Verbatim}

This probably means you didn't edit /etc/inetd.conf correctly, or
you didn't restart inetd after editing inetd.conf.

\item {} 
sclient returns the error:

\begin{Verbatim}[commandchars=\\\{\}]
sclient: Server not found in Kerberos database while using
         sendauth
\end{Verbatim}

This means that the \code{sample/hostname@LOCAL.REALM} service was not
defined in the Kerberos database; it should be created using
{\hyperref[admin/admin_commands/kadmin_local:kadmin-1]{\emph{kadmin}}}, and a keytab file needs to be generated to make
the key for that service principal available for sclient.

\item {} 
sclient returns the error:

\begin{Verbatim}[commandchars=\\\{\}]
sendauth rejected, error reply is:
    \PYGZdq{}No such file or directory\PYGZdq{}
\end{Verbatim}

This probably means sserver couldn't find the keytab file.  It was
probably not installed in the proper directory.

\end{enumerate}


\subsection{SEE ALSO}
\label{admin/admin_commands/sserver:see-also}
\emph{sclient(1)}, services(5), inetd(8)


\chapter{MIT Kerberos defaults}
\label{mitK5defaults:mitk5defaults}\label{mitK5defaults::doc}\label{mitK5defaults:mit-kerberos-defaults}

\section{General defaults}
\label{mitK5defaults:general-defaults}
\begin{tabulary}{\linewidth}{|L|L|L|}
\hline
\textsf{\relax 
Description
} & \textsf{\relax 
Default
} & \textsf{\relax 
Environment
}\\
\hline
\emph{keytab\_definition} file
 & 
{\hyperref[mitK5defaults:paths]{\emph{DEFKTNAME}}}
 & 
\textbf{KRB5\_KTNAME}
\\
\hline
Client \emph{keytab\_definition} file
 & 
{\hyperref[mitK5defaults:paths]{\emph{DEFCKTNAME}}}
 & 
\textbf{KRB5\_CLIENT\_KTNAME}
\\
\hline
Kerberos config file {\hyperref[admin/conf_files/krb5_conf:krb5-conf-5]{\emph{krb5.conf}}}
 & 
\code{/etc/krb5.conf}\code{:}{\hyperref[mitK5defaults:paths]{\emph{SYSCONFDIR}}}\code{/krb5.conf}
 & 
\textbf{KRB5\_CONFIG}
\\
\hline
KDC config file {\hyperref[admin/conf_files/kdc_conf:kdc-conf-5]{\emph{kdc.conf}}}
 & 
{\hyperref[mitK5defaults:paths]{\emph{LOCALSTATEDIR}}}\code{/krb5kdc}\code{/kdc.conf}
 & 
\textbf{KRB5\_KDC\_PROFILE}
\\
\hline
KDC database path (DB2)
 & 
{\hyperref[mitK5defaults:paths]{\emph{LOCALSTATEDIR}}}\code{/krb5kdc}\code{/principal}
 & \\
\hline
Master key \emph{stash\_definition}
 & 
{\hyperref[mitK5defaults:paths]{\emph{LOCALSTATEDIR}}}\code{/krb5kdc}\code{/.k5.}\emph{realm}
 & \\
\hline
Admin server ACL file {\hyperref[admin/conf_files/kadm5_acl:kadm5-acl-5]{\emph{kadm5.acl}}}
 & 
{\hyperref[mitK5defaults:paths]{\emph{LOCALSTATEDIR}}}\code{/krb5kdc}\code{/kadm5.acl}
 & \\
\hline
OTP socket directory
 & 
{\hyperref[mitK5defaults:paths]{\emph{RUNSTATEDIR}}}\code{/krb5kdc}
 & \\
\hline
Plugin base directory
 & 
{\hyperref[mitK5defaults:paths]{\emph{LIBDIR}}}\code{/krb5/plugins}
 & \\
\hline
\emph{rcache\_definition} directory
 & 
\code{/var/tmp}
 & 
\textbf{KRB5RCACHEDIR}
\\
\hline
Master key default enctype
 & 
\code{aes256-cts-hmac-sha1-96}
 & \\
\hline
Default {\hyperref[admin/conf_files/kdc_conf:keysalt-lists]{\emph{keysalt list}}}
 & 
\code{aes256-cts-hmac-sha1-96:normal aes128-cts-hmac-sha1-96:normal des3-cbc-sha1:normal arcfour-hmac-md5:normal}
 & \\
\hline
Permitted enctypes
 & 
\code{aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 des3-cbc-sha1 arcfour-hmac-md5 camellia256-cts-cmac camellia128-cts-cmac des-cbc-crc des-cbc-md5 des-cbc-md4}
 & \\
\hline
KDC default port
 & 
88
 & \\
\hline
Admin server port
 & 
749
 & \\
\hline
Password change port
 & 
464
 & \\
\hline\end{tabulary}



\section{Slave KDC propagation defaults}
\label{mitK5defaults:slave-kdc-propagation-defaults}
This table shows defaults used by the {\hyperref[admin/admin_commands/kprop:kprop-8]{\emph{kprop}}} and
{\hyperref[admin/admin_commands/kpropd:kpropd-8]{\emph{kpropd}}} programs.

\begin{tabulary}{\linewidth}{|L|L|L|}
\hline
\textsf{\relax 
Description
} & \textsf{\relax 
Default
} & \textsf{\relax 
Environment
}\\
\hline
kprop database dump file
 & 
{\hyperref[mitK5defaults:paths]{\emph{LOCALSTATEDIR}}}\code{/krb5kdc}\code{/slave\_datatrans}
 & \\
\hline
kpropd temporary dump file
 & 
{\hyperref[mitK5defaults:paths]{\emph{LOCALSTATEDIR}}}\code{/krb5kdc}\code{/from\_master}
 & \\
\hline
kdb5\_util location
 & 
{\hyperref[mitK5defaults:paths]{\emph{SBINDIR}}}\code{/kdb5\_util}
 & \\
\hline
kprop location
 & 
{\hyperref[mitK5defaults:paths]{\emph{SBINDIR}}}\code{/kprop}
 & \\
\hline
kpropd ACL file
 & 
{\hyperref[mitK5defaults:paths]{\emph{LOCALSTATEDIR}}}\code{/krb5kdc}\code{/kpropd.acl}
 & \\
\hline
kprop port
 & 
754
 & 
KPROP\_PORT
\\
\hline\end{tabulary}



\section{Default paths for Unix-like systems}
\label{mitK5defaults:paths}\label{mitK5defaults:default-paths-for-unix-like-systems}
On Unix-like systems, some paths used by MIT krb5 depend on parameters
chosen at build time.  For a custom build, these paths default to
subdirectories of \code{/usr/local}.  When MIT krb5 is integrated into an
operating system, the paths are generally chosen to match the
operating system's filesystem layout.

\begin{tabulary}{\linewidth}{|L|L|L|L|}
\hline
\textsf{\relax 
Description
} & \textsf{\relax 
Symbolic name
} & \textsf{\relax 
Custom build path
} & \textsf{\relax 
Typical OS path
}\\
\hline
User programs
 & 
BINDIR
 & 
\code{/usr/local/bin}
 & 
\code{/usr/bin}
\\
\hline
Libraries and plugins
 & 
LIBDIR
 & 
\code{/usr/local/lib}
 & 
\code{/usr/lib}
\\
\hline
Parent of KDC state dir
 & 
LOCALSTATEDIR
 & 
\code{/usr/local/var}
 & 
\code{/var}
\\
\hline
Parent of KDC runtime dir
 & 
RUNSTATEDIR
 & 
\code{/usr/local/var/run}
 & 
\code{/run}
\\
\hline
Administrative programs
 & 
SBINDIR
 & 
\code{/usr/local/sbin}
 & 
\code{/usr/sbin}
\\
\hline
Alternate krb5.conf dir
 & 
SYSCONFDIR
 & 
\code{/usr/local/etc}
 & 
\code{/etc}
\\
\hline
Default ccache name
 & 
DEFCCNAME
 & 
\code{FILE:/tmp/krb5cc\_\%\{uid\}}
 & 
\code{FILE:/tmp/krb5cc\_\%\{uid\}}
\\
\hline
Default keytab name
 & 
DEFKTNAME
 & 
\code{FILE:/etc/krb5.keytab}
 & 
\code{FILE:/etc/krb5.keytab}
\\
\hline\end{tabulary}


The default client keytab name (DEFCKTNAME) typically defaults to
\code{FILE:/usr/local/var/krb5/user/\%\{euid\}/client.keytab} for a custom
build.  A native build will typically use a path which will vary
according to the operating system's layout of \code{/var}.


\chapter{Environment variables}
\label{admin/env_variables:environment-variables}\label{admin/env_variables::doc}
The following environment variables can be used during runtime:
\begin{description}
\item[{\textbf{KRB5\_CONFIG}}] \leavevmode
Main Kerberos configuration file.  Multiple filenames can be
specified, separated by a colon; all files which are present will
be read.  (See {\hyperref[mitK5defaults:mitk5defaults]{\emph{MIT Kerberos defaults}}} for the default path.)

\item[{\textbf{KRB5\_KDC\_PROFILE}}] \leavevmode
KDC configuration file.  (See {\hyperref[mitK5defaults:mitk5defaults]{\emph{MIT Kerberos defaults}}} for the default
name.)

\item[{\textbf{KRB5\_KTNAME}}] \leavevmode
Default keytab file name.  (See {\hyperref[mitK5defaults:mitk5defaults]{\emph{MIT Kerberos defaults}}} for the
default name.)

\item[{\textbf{KRB5\_CLIENT\_KTNAME}}] \leavevmode
Default client keytab file name.  (See {\hyperref[mitK5defaults:mitk5defaults]{\emph{MIT Kerberos defaults}}} for
the default name.)

\item[{\textbf{KRB5CCNAME}}] \leavevmode
Default name for the credentials cache file, in the form \emph{type}:\emph{residual}.  The type of the default cache may determine the
availability of a cache collection.  For instance, a default cache
of type \code{DIR} causes caches within the directory to be present
in the global cache collection.

\item[{\textbf{KRB5RCACHETYPE}}] \leavevmode
Default replay cache type.  Defaults to \code{dfl}.  A value of
\code{none} disables the replay cache.

\item[{\textbf{KRB5RCACHEDIR}}] \leavevmode
Default replay cache directory.  (See {\hyperref[mitK5defaults:mitk5defaults]{\emph{MIT Kerberos defaults}}} for the
default location.)

\item[{\textbf{KPROP\_PORT}}] \leavevmode
{\hyperref[admin/admin_commands/kprop:kprop-8]{\emph{kprop}}} port to use.  Defaults to 754.

\item[{\textbf{KRB5\_TRACE}}] \leavevmode
Filename for trace-logging output (introduced in release 1.9).
For example, \code{env KRB5\_TRACE=/dev/stdout kinit} would send
tracing information for kinit to \code{/dev/stdout}.  Some programs
may ignore this variable (particularly setuid or login system
programs).

\end{description}


\chapter{Troubleshooting}
\label{admin/troubleshoot:troubleshoot}\label{admin/troubleshoot::doc}\label{admin/troubleshoot:troubleshooting}

\section{Trace logging}
\label{admin/troubleshoot:trace-logging}\label{admin/troubleshoot:id1}
Most programs using MIT krb5 1.9 or later can be made to provide
information about internal krb5 library operations using trace
logging.  To enable this, set the \textbf{KRB5\_TRACE} environment variable
to a filename before running the program.  On many operating systems,
the filename \code{/dev/stdout} can be used to send trace logging output
to standard output.

Some programs do not honor \textbf{KRB5\_TRACE}, either because they use
secure library contexts (this generally applies to setuid programs and
parts of the login system) or because they take direct control of the
trace logging system using the API.

Here is a short example showing trace logging output for an invocation
of the \emph{kvno(1)} command:

\begin{Verbatim}[commandchars=\\\{\}]
shell\PYGZpc{} env KRB5\PYGZus{}TRACE=/dev/stdout kvno krbtgt/KRBTEST.COM
[9138] 1332348778.823276: Getting credentials user@KRBTEST.COM \PYGZhy{}\PYGZgt{}
    krbtgt/KRBTEST.COM@KRBTEST.COM using ccache
    FILE:/me/krb5/build/testdir/ccache
[9138] 1332348778.823381: Retrieving user@KRBTEST.COM \PYGZhy{}\PYGZgt{}
    krbtgt/KRBTEST.COM@KRBTEST.COM from
    FILE:/me/krb5/build/testdir/ccache with result: 0/Unknown code 0
krbtgt/KRBTEST.COM@KRBTEST.COM: kvno = 1
\end{Verbatim}


\section{List of errors}
\label{admin/troubleshoot:list-of-errors}

\subsection{Frequently seen errors}
\label{admin/troubleshoot:frequently-seen-errors}\begin{enumerate}
\item {} 
{\hyperref[admin/troubleshoot:init-creds-etype-nosupp]{\emph{KDC has no support for encryption type while getting initial credentials}}}

\item {} 
{\hyperref[admin/troubleshoot:cert-chain-etype-nosupp]{\emph{credential verification failed: KDC has no support for encryption type}}}

\item {} 
{\hyperref[admin/troubleshoot:err-cert-chain-cert-expired]{\emph{Cannot create cert chain: certificate has expired}}}

\end{enumerate}


\subsection{Errors seen by admins}
\label{admin/troubleshoot:errors-seen-by-admins}\phantomsection\label{admin/troubleshoot:prop-failed-start}\begin{enumerate}
\item {} 
{\hyperref[admin/troubleshoot:kprop-no-route]{\emph{kprop: No route to host while connecting to server}}}

\item {} 
{\hyperref[admin/troubleshoot:kprop-con-refused]{\emph{kprop: Connection refused while connecting to server}}}

\item {} 
{\hyperref[admin/troubleshoot:kprop-sendauth-exchange]{\emph{kprop: Server rejected authentication (during sendauth exchange) while authenticating to server}}}

\end{enumerate}
\phantomsection\label{admin/troubleshoot:prop-failed-end}

\bigskip\hrule{}\bigskip



\subsubsection{KDC has no support for encryption type while getting initial credentials}
\label{admin/troubleshoot:kdc-has-no-support-for-encryption-type-while-getting-initial-credentials}\label{admin/troubleshoot:init-creds-etype-nosupp}

\subsubsection{credential verification failed: KDC has no support for encryption type}
\label{admin/troubleshoot:credential-verification-failed-kdc-has-no-support-for-encryption-type}\label{admin/troubleshoot:cert-chain-etype-nosupp}
This most commonly happens when trying to use a principal with only
DES keys, in a release (MIT krb5 1.7 or later) which disables DES by
default.  DES encryption is considered weak due to its inadequate key
size.  If you cannot migrate away from its use, you can re-enable DES
by adding \code{allow\_weak\_crypto = true} to the {\hyperref[admin/conf_files/krb5_conf:libdefaults]{\emph{{[}libdefaults{]}}}}
section of {\hyperref[admin/conf_files/krb5_conf:krb5-conf-5]{\emph{krb5.conf}}}.


\subsubsection{Cannot create cert chain: certificate has expired}
\label{admin/troubleshoot:cannot-create-cert-chain-certificate-has-expired}\label{admin/troubleshoot:err-cert-chain-cert-expired}
This error message indicates that PKINIT authentication failed because
the client certificate, KDC certificate, or one of the certificates in
the signing chain above them has expired.

If the KDC certificate has expired, this message appears in the KDC
log file, and the client will receive a ``Preauthentication failed''
error.  (Prior to release 1.11, the KDC log file message erroneously
appears as ``Out of memory''.  Prior to release 1.12, the client will
receive a ``Generic error''.)

If the client or a signing certificate has expired, this message may
appear in {\hyperref[admin/troubleshoot:trace-logging]{trace\_logging}} output from \emph{kinit(1)} or, starting in
release 1.12, as an error message from kinit or another program which
gets initial tickets.  The error message is more likely to appear
properly on the client if the principal entry has no long-term keys.


\subsubsection{kprop: No route to host while connecting to server}
\label{admin/troubleshoot:kprop-no-route}\label{admin/troubleshoot:kprop-no-route-to-host-while-connecting-to-server}
Make sure that the hostname of the slave (as given to kprop) is
correct, and that any firewalls between the master and the slave allow
a connection on port 754.


\subsubsection{kprop: Connection refused while connecting to server}
\label{admin/troubleshoot:kprop-connection-refused-while-connecting-to-server}\label{admin/troubleshoot:kprop-con-refused}
If the slave is intended to run kpropd out of inetd, make sure that
inetd is configured to accept krb5\_prop connections.  inetd may need
to be restarted or sent a SIGHUP to recognize the new configuration.
If the slave is intended to run kpropd in standalone mode, make sure
that it is running.


\subsubsection{kprop: Server rejected authentication (during sendauth exchange) while authenticating to server}
\label{admin/troubleshoot:kprop-sendauth-exchange}\label{admin/troubleshoot:kprop-server-rejected-authentication-during-sendauth-exchange-while-authenticating-to-server}
Make sure that:
\begin{enumerate}
\item {} 
The time is synchronized between the master and slave KDCs.

\item {} 
The master stash file was copied from the master to the expected
location on the slave.

\item {} 
The slave has a keytab file in the default location containing a
\code{host} principal for the slave's hostname.

\end{enumerate}


\chapter{Advanced topics}
\label{admin/advanced/index:advanced-topics}\label{admin/advanced/index::doc}

\section{LDAP backend on Ubuntu 10.4 (lucid)}
\label{admin/advanced/ldapbackend:ldap-backend-on-ubuntu-10-4-lucid}\label{admin/advanced/ldapbackend::doc}\label{admin/advanced/ldapbackend:ldap-be-ubuntu}
Setting up Kerberos v1.9 with LDAP backend on Ubuntu 10.4 (Lucid Lynx)


\subsection{Prerequisites}
\label{admin/advanced/ldapbackend:prerequisites}
Install the following packages: \emph{slapd, ldap-utils} and \emph{libldap2-dev}

You can install the necessary packages with these commands:

\begin{Verbatim}[commandchars=\\\{\}]
sudo apt\PYGZhy{}get install slapd
sudo apt\PYGZhy{}get install ldap\PYGZhy{}utils
sudo apt\PYGZhy{}get install libldap2\PYGZhy{}dev
\end{Verbatim}

Extend the user schema using schemas from standart OpenLDAP
distribution: \emph{cosine, mics, nis, inetcomperson}

\begin{Verbatim}[commandchars=\\\{\}]
ldapadd \PYGZhy{}Y EXTERNAL \PYGZhy{}H ldapi:/// \PYGZhy{}f /etc/ldap/schema/cosine.ldif
ldapadd \PYGZhy{}Y EXTERNAL \PYGZhy{}H ldapi:/// \PYGZhy{}f /etc/ldap/schema/mics.ldif
ldapadd \PYGZhy{}Y EXTERNAL \PYGZhy{}H ldapi:/// \PYGZhy{}f /etc/ldap/schema/nis.ldif
ldapadd \PYGZhy{}Y EXTERNAL \PYGZhy{}H ldapi:/// \PYGZhy{}f /etc/ldap/schema/inetcomperson.ldif
\end{Verbatim}


\subsection{Building Kerberos from source}
\label{admin/advanced/ldapbackend:building-kerberos-from-source}
\begin{Verbatim}[commandchars=\\\{\}]
./configure \PYGZhy{}\PYGZhy{}with\PYGZhy{}ldap
make
sudo make install
\end{Verbatim}


\subsection{Setting up Kerberos}
\label{admin/advanced/ldapbackend:setting-up-kerberos}

\subsubsection{Configuration}
\label{admin/advanced/ldapbackend:configuration}
Update kdc.conf with the LDAP back-end information:

\begin{Verbatim}[commandchars=\\\{\}]
[realms]
    EXAMPLE.COM = \PYGZob{}
        database\PYGZus{}module = LDAP
    \PYGZcb{}

[dbmodules]
    LDAP = \PYGZob{}
        db\PYGZus{}library = kldap
        ldap\PYGZus{}kerberos\PYGZus{}container\PYGZus{}dn = cn=krbContainer,dc=example,dc=com
        ldap\PYGZus{}kdc\PYGZus{}dn = cn=admin,dc=example,dc=com
        ldap\PYGZus{}kadmind\PYGZus{}dn = cn=admin,dc=example,dc=com
        ldap\PYGZus{}service\PYGZus{}password\PYGZus{}file = /usr/local/var/krb5kdc/admin.stash
        ldap\PYGZus{}servers = ldapi:///
    \PYGZcb{}
\end{Verbatim}


\subsubsection{Schema}
\label{admin/advanced/ldapbackend:schema}
From the source tree copy
\code{src/plugins/kdb/ldap/libkdb\_ldap/kerberos.schema} into
\code{/etc/ldap/schema}

Warning: this step should be done after slapd is installed to avoid
problems with slapd installation.

To convert kerberos.schema to run-time configuration (\code{cn=config})
do the following:
\begin{enumerate}
\item {} 
Create a temporary file \code{/tmp/schema\_convert.conf} with the
following content:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n}{include} \PYG{o}{/}\PYG{n}{etc}\PYG{o}{/}\PYG{n}{ldap}\PYG{o}{/}\PYG{n}{schema}\PYG{o}{/}\PYG{n}{kerberos}\PYG{o}{.}\PYG{n}{schema}
\end{Verbatim}

\item {} 
Create a temporary directory \code{/tmp/krb5\_ldif}.

\item {} 
Run:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n}{slaptest} \PYG{o}{\PYGZhy{}}\PYG{n}{f} \PYG{o}{/}\PYG{n}{tmp}\PYG{o}{/}\PYG{n}{schema\PYGZus{}convert}\PYG{o}{.}\PYG{n}{conf} \PYG{o}{\PYGZhy{}}\PYG{n}{F} \PYG{o}{/}\PYG{n}{tmp}\PYG{o}{/}\PYG{n}{krb5\PYGZus{}ldif}
\end{Verbatim}

This should in a new file named
\code{/tmp/krb5\_ldif/cn=config/cn=schema/cn=\{0\}kerberos.ldif}.

\item {} 
Edit \code{/tmp/krb5\_ldif/cn=config/cn=schema/cn=\{0\}kerberos.ldif} by
replacing the lines:

\begin{Verbatim}[commandchars=\\\{\}]
dn: cn=\PYGZob{}0\PYGZcb{}kerberos
cn: \PYGZob{}0\PYGZcb{}kerberos
\end{Verbatim}

with
\begin{quote}

dn: cn=kerberos,cn=schema,cn=config
cn: kerberos
\end{quote}

Also, remove following attribute-value pairs:

\begin{Verbatim}[commandchars=\\\{\}]
structuralObjectClass: olcSchemaConfig
entryUUID: ...
creatorsName: cn=config
createTimestamp: ...
entryCSN: ...
modifiersName: cn=config
modifyTimestamp: ...
\end{Verbatim}

\item {} 
Load the new schema with ldapadd (with the proper authentication):

\begin{Verbatim}[commandchars=\\\{\}]
ldapadd \PYGZhy{}Y EXTERNAL \PYGZhy{}H ldapi:/// \PYGZhy{}f  /tmp/krb5\PYGZus{}ldif/cn=config/cn=schema/cn=\PYGZob{}0\PYGZcb{}kerberos.ldif
\end{Verbatim}

which should result the message \code{adding new entry
"cn=kerberos,cn=schema,cn=config"}.

\end{enumerate}


\subsection{Create Kerberos database}
\label{admin/advanced/ldapbackend:create-kerberos-database}
Using LDAP administrator credentials, create Kerberos database and
master key stash:

\begin{Verbatim}[commandchars=\\\{\}]
kdb5\PYGZus{}ldap\PYGZus{}util \PYGZhy{}D cn=admin,dc=example,dc=com \PYGZhy{}H ldapi:/// create \PYGZhy{}s
\end{Verbatim}

Stash the LDAP administrative passwords:

\begin{Verbatim}[commandchars=\\\{\}]
kdb5\PYGZus{}ldap\PYGZus{}util \PYGZhy{}D cn=admin,dc=example,dc=com \PYGZhy{}H ldapi:/// stashsrvpw cn=admin,dc=example,dc=com
\end{Verbatim}

Start {\hyperref[admin/admin_commands/krb5kdc:krb5kdc-8]{\emph{krb5kdc}}}:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n}{krb5kdc}
\end{Verbatim}

To destroy database run:

\begin{Verbatim}[commandchars=\\\{\}]
kdb5\PYGZus{}ldap\PYGZus{}util \PYGZhy{}D cn=admin,dc=example,dc=com \PYGZhy{}H ldapi:/// destroy \PYGZhy{}f
\end{Verbatim}


\subsection{Useful references}
\label{admin/advanced/ldapbackend:useful-references}\begin{itemize}
\item {} 
\href{https://help.ubuntu.com/10.04/serverguide/C/kerberos-ldap.html}{Kerberos and LDAP}

\end{itemize}


\section{Retiring DES}
\label{admin/advanced/retiring-des:retiring-des}\label{admin/advanced/retiring-des::doc}\label{admin/advanced/retiring-des:id1}
Version 5 of the Kerberos protocol was originally implemented using
the Data Encryption Standard (DES) as a block cipher for encryption.
While it was considered secure at the time, advancements in computational
ability have rendered DES vulnerable to brute force attacks on its 56-bit
keyspace.  As such, it is now considered insecure and should not be
used (\index{RFC!RFC 6649}\href{http://tools.ietf.org/html/rfc6649.html}{\textbf{RFC 6649}}).


\subsection{History}
\label{admin/advanced/retiring-des:history}
DES was used in the original Kerberos implementation, and was the
only cryptosystem in krb5 1.0.  Partial support for triple-DES (3DES) was
added in version 1.1, with full support following in version 1.2.
The Advanced Encryption Standard (AES), which supersedes DES, gained
partial support in version 1.3.0 of krb5 and full support in version 1.3.2.
However, deployments of krb5 using Kerberos databases created with older
versions of krb5 will not necessarily start using strong crypto for
ordinary operation without administrator intervention.


\subsection{Types of keys}
\label{admin/advanced/retiring-des:types-of-keys}\begin{itemize}
\item {} 
The database master key:  This key is not exposed to user requests,
but is used to encrypt other key material stored in the kerberos
database.  The database master key is currently stored as \code{K/M}
by default.

\item {} 
Password-derived keys:  User principals frequently have keys
derived from a password.  When a new password is set, the KDC
uses various string2key functions to generate keys in the database
for that principal.

\item {} 
Keytab keys:  Application server principals generally use random
keys which are not derived from a password.  When the database
entry is created, the KDC generates random keys of various enctypes
to enter in the database, which are conveyed to the application server
and stored in a keytab.

\item {} 
Session keys:  These are short-term keys generated by the KDC while
processing client requests, with an enctype selected by the KDC.

\end{itemize}

For details on the various enctypes and how enctypes are selected by the KDC
for session keys and client/server long-term keys, see {\hyperref[admin/enctypes:enctypes]{\emph{Encryption types}}}.
When using the {\hyperref[admin/admin_commands/kadmin_local:kadmin-1]{\emph{kadmin}}} interface to generate new long-term keys,
the \textbf{-e} argument can be used to force a particular set of enctypes,
overriding the KDC default values.

\begin{notice}{note}{Note:}
When the KDC is selecting a session key, it has no knowledge about the
kerberos installation on the server which will receive the service ticket,
only what keys are in the database for the service principal.
In order to allow uninterrupted operation to
clients while migrating away from DES, care must be taken to ensure that
kerberos installations on application server machines are configured to
support newer encryption types before keys of those new encryption types
are created in the Kerberos database for those server principals.
\end{notice}


\subsection{Upgrade procedure}
\label{admin/advanced/retiring-des:upgrade-procedure}
This procedure assumes that the KDC software has already been upgraded
to a modern version of krb5 that supports non-DES keys, so that the
only remaining task is to update the actual keys used to service requests.
The realm used for demonstrating this procedure, ZONE.MIT.EDU,
is an example of the worst-case scenario, where all keys in the realm
are DES.  The realm was initially created with a very old version of krb5,
and \textbf{supported\_enctypes} in {\hyperref[admin/conf_files/kdc_conf:kdc-conf-5]{\emph{kdc.conf}}} was set to a value
appropriate when the KDC was installed, but was not updated as the KDC
was upgraded:

\begin{Verbatim}[commandchars=\\\{\}]
[realms]
        ZONE.MIT.EDU = \PYGZob{}
                [...]
                master\PYGZus{}key\PYGZus{}type = des\PYGZhy{}cbc\PYGZhy{}crc
                supported\PYGZus{}enctypes = des\PYGZhy{}cbc\PYGZhy{}crc:normal des:normal des:v4 des:norealm des:onlyrealm des:afs3
        \PYGZcb{}
\end{Verbatim}

This resulted in the keys for all principals in the realm being forced
to DES-only, unless specifically requested using {\hyperref[admin/admin_commands/kadmin_local:kadmin-1]{\emph{kadmin}}}.

Before starting the upgrade, all KDCs were running krb5 1.11,
and the database entries for some ``high-value'' principals were:

\begin{Verbatim}[commandchars=\\\{\}]
[root@casio krb5kdc]\PYGZsh{} kadmin.local \PYGZhy{}r ZONE.MIT.EDU \PYGZhy{}q \PYGZsq{}getprinc krbtgt/ZONE.MIT.EDU\PYGZsq{}
[...]
Number of keys: 1
Key: vno 1, des\PYGZhy{}cbc\PYGZhy{}crc:v4
[...]
[root@casio krb5kdc]\PYGZsh{} kadmin.local \PYGZhy{}r ZONE.MIT.EDU \PYGZhy{}q \PYGZsq{}getprinc kadmin/admin\PYGZsq{}
[...]
Number of keys: 1
Key: vno 15, des\PYGZhy{}cbc\PYGZhy{}crc
[...]
[root@casio krb5kdc]\PYGZsh{} kadmin.local \PYGZhy{}r ZONE.MIT.EDU \PYGZhy{}q \PYGZsq{}getprinc kadmin/changepw\PYGZsq{}
[...]
Number of keys: 1
Key: vno 14, des\PYGZhy{}cbc\PYGZhy{}crc
[...]
\end{Verbatim}

The \code{krbtgt/REALM} key appears to have never been changed since creation
(its kvno is 1), and all three database entries have only a des-cbc-crc key.


\subsubsection{The krbtgt key and KDC keys}
\label{admin/advanced/retiring-des:the-krbtgt-key-and-kdc-keys}
Perhaps the biggest single-step improvement in the security of the cell
is gained by strengthening the key of the ticket-granting service principal,
\code{krbtgt/REALM}---if this principal's key is compromised, so is the
entire realm.  Since the server that will handle service tickets
for this principal is the KDC itself, it is easy to guarantee that it
will be configured to support any encryption types which might be
selected.  However, the default KDC behavior when creating new keys is to
remove the old keys, which would invalidate all existing tickets issued
against that principal, rendering the TGTs cached by clients useless.
Instead, a new key can be created with the old key retained, so that
existing tickets will still function until their scheduled expiry
(see {\hyperref[admin/database:changing-krbtgt-key]{\emph{Changing the krbtgt key}}}).

\begin{Verbatim}[commandchars=\\\{\}]
[root@casio krb5kdc]\PYGZsh{} enctypes=aes256\PYGZhy{}cts\PYGZhy{}hmac\PYGZhy{}sha1\PYGZhy{}96:normal,\PYGZbs{}
\PYGZgt{} aes128\PYGZhy{}cts\PYGZhy{}hmac\PYGZhy{}sha1\PYGZhy{}96:normal,des3\PYGZhy{}hmac\PYGZhy{}sha1:normal,des\PYGZhy{}cbc\PYGZhy{}crc:normal
[root@casio krb5kdc]\PYGZsh{} kadmin.local \PYGZhy{}r ZONE.MIT.EDU \PYGZhy{}q \PYGZdq{}cpw \PYGZhy{}e \PYGZdl{}\PYGZob{}enctypes\PYGZcb{} \PYGZhy{}randkey \PYGZbs{}
\PYGZgt{} \PYGZhy{}keepold krbtgt/ZONE.MIT.EDU\PYGZdq{}
Authenticating as principal root/admin@ZONE.MIT.EDU with password.
Key for \PYGZdq{}krbtgt/ZONE.MIT.EDU@ZONE.MIT.EDU\PYGZdq{} randomized.
\end{Verbatim}

\begin{notice}{note}{Note:}
The new \code{krbtgt@REALM} key should be propagated to slave KDCs
immediately so that TGTs issued by the master KDC can be used to
issue service tickets on slave KDCs.  Slave KDCs will refuse requests
using the new TGT kvno until the new krbtgt entry has been propagated
to them.
\end{notice}

It is necessary to explicitly specify the enctypes for the new database
entry, since \textbf{supported\_enctypes} has not been changed.  Leaving
\textbf{supported\_enctypes} unchanged makes a potential rollback operation
easier, since all new keys of new enctypes are the result of explicit
administrator action and can be easily enumerated.
Upgrading the krbtgt key should have minimal user-visible disruption other
than that described in the note above, since only clients which list the
new enctypes as supported will use them, per the procedure
in {\hyperref[admin/enctypes:session-key-selection]{\emph{Session key selection}}}.
Once the krbtgt key is updated, the session and ticket keys for user
TGTs will be strong keys, but subsequent requests
for service tickets will still get DES keys until the service principals
have new keys generated.  Application service
remains uninterrupted due to the key-selection procedure on the KDC.

After the change, the database entry is now:

\begin{Verbatim}[commandchars=\\\{\}]
[root@casio krb5kdc]\PYGZsh{} kadmin.local \PYGZhy{}r ZONE.MIT.EDU \PYGZhy{}q \PYGZsq{}getprinc krbtgt/ZONE.MIT.EDU\PYGZsq{}
[...]
Number of keys: 5
Key: vno 2, aes256\PYGZhy{}cts\PYGZhy{}hmac\PYGZhy{}sha1\PYGZhy{}96
Key: vno 2, aes128\PYGZhy{}cts\PYGZhy{}hmac\PYGZhy{}sha1\PYGZhy{}96
Key: vno 2, des3\PYGZhy{}cbc\PYGZhy{}sha1
Key: vno 2, des\PYGZhy{}cbc\PYGZhy{}crc
Key: vno 1, des\PYGZhy{}cbc\PYGZhy{}crc:v4
[...]
\end{Verbatim}

Since the expected disruptions from rekeying the krbtgt principal are
minor, after a short testing period, it is
appropriate to rekey the other high-value principals, \code{kadmin/admin@REALM}
and \code{kadmin/changepw@REALM}. These are the service principals used for
changing user passwords and updating application keytabs.  The kadmin
and password-changing services are regular kerberized services, so the
session-key-selection algorithm described in {\hyperref[admin/enctypes:session-key-selection]{\emph{Session key selection}}}
applies.  It is particularly important to have strong session keys for
these services, since user passwords and new long-term keys are conveyed
over the encrypted channel.

\begin{Verbatim}[commandchars=\\\{\}]
[root@casio krb5kdc]\PYGZsh{} enctypes=aes256\PYGZhy{}cts\PYGZhy{}hmac\PYGZhy{}sha1\PYGZhy{}96:normal,\PYGZbs{}
\PYGZgt{} aes128\PYGZhy{}cts\PYGZhy{}hmac\PYGZhy{}sha1\PYGZhy{}96:normal,des3\PYGZhy{}hmac\PYGZhy{}sha1:normal
[root@casio krb5kdc]\PYGZsh{} kadmin.local \PYGZhy{}r ZONE.MIT.EDU \PYGZhy{}q \PYGZdq{}cpw \PYGZhy{}e \PYGZdl{}\PYGZob{}enctypes\PYGZcb{} \PYGZhy{}randkey \PYGZbs{}
\PYGZgt{} kadmin/admin\PYGZdq{}
Authenticating as principal root/admin@ZONE.MIT.EDU with password.
Key for \PYGZdq{}kadmin/admin@ZONE.MIT.EDU\PYGZdq{} randomized.
[root@casio krb5kdc]\PYGZsh{} kadmin.local \PYGZhy{}r ZONE.MIT.EDU \PYGZhy{}q \PYGZdq{}cpw \PYGZhy{}e \PYGZdl{}\PYGZob{}enctypes\PYGZcb{} \PYGZhy{}randkey \PYGZbs{}
\PYGZgt{} kadmin/changepw\PYGZdq{}
Authenticating as principal root/admin@ZONE.MIT.EDU with password.
Key for \PYGZdq{}kadmin/changepw@ZONE.MIT.EDU\PYGZdq{} randomized.
\end{Verbatim}

It is not necessary to retain a single-DES key for these services, since
password changes are not part of normal daily workflow, and disruption
from a client failure is likely to be minimal.  Furthermore, if a kerberos
client experiences failure changing a user password or keytab key,
this indicates that that client will become inoperative once services
are rekeyed to non-DES enctypes.  Such problems can be detected early
at this stage, giving more time for corrective action.


\subsubsection{Adding strong keys to application servers}
\label{admin/advanced/retiring-des:adding-strong-keys-to-application-servers}
Before switching the default enctypes for new keys over to strong enctypes,
it may be desired to test upgrading a handful of services with the
new configuration before flipping the switch for the defaults.  This
still requires using the \textbf{-e} argument in {\hyperref[admin/admin_commands/kadmin_local:kadmin-1]{\emph{kadmin}}} to get non-default
enctypes:

\begin{Verbatim}[commandchars=\\\{\}]
[root@casio krb5kdc]\PYGZsh{} enctypes=aes256\PYGZhy{}cts\PYGZhy{}hmac\PYGZhy{}sha1\PYGZhy{}96:normal,\PYGZbs{}
\PYGZgt{} aes128\PYGZhy{}cts\PYGZhy{}hmac\PYGZhy{}sha1\PYGZhy{}96:normal,des3\PYGZhy{}cbc\PYGZhy{}sha1:normal,des\PYGZhy{}cbc\PYGZhy{}crc:normal
[root@casio krb5kdc]\PYGZsh{} kadmin \PYGZhy{}r ZONE.MIT.EDU \PYGZhy{}p zephyr/zephyr@ZONE.MIT.EDU \PYGZhy{}k \PYGZhy{}t \PYGZbs{}
\PYGZgt{} /etc/zephyr/krb5.keytab  \PYGZhy{}q \PYGZdq{}ktadd \PYGZhy{}e \PYGZdl{}\PYGZob{}enctypes\PYGZcb{} \PYGZbs{}
\PYGZgt{} \PYGZhy{}k /etc/zephyr/krb5.keytab zephyr/zephyr@ZONE.MIT.EDU\PYGZdq{}
Authenticating as principal zephyr/zephyr@ZONE.MIT.EDU with keytab /etc/zephyr/krb5.keytab.
Entry for principal zephyr/zephyr@ZONE.MIT.EDU with kvno 4, encryption type aes256\PYGZhy{}cts\PYGZhy{}hmac\PYGZhy{}sha1\PYGZhy{}96 added to keytab WRFILE:/etc/zephyr/krb5.keytab.
Entry for principal zephyr/zephyr@ZONE.MIT.EDU with kvno 4, encryption type aes128\PYGZhy{}cts\PYGZhy{}hmac\PYGZhy{}sha1\PYGZhy{}96 added to keytab WRFILE:/etc/zephyr/krb5.keytab.
Entry for principal zephyr/zephyr@ZONE.MIT.EDU with kvno 4, encryption type des3\PYGZhy{}cbc\PYGZhy{}sha1 added to keytab WRFILE:/etc/zephyr/krb5.keytab.
Entry for principal zephyr/zephyr@ZONE.MIT.EDU with kvno 4, encryption type des\PYGZhy{}cbc\PYGZhy{}crc added to keytab WRFILE:/etc/zephyr/krb5.keytab.
\end{Verbatim}

Be sure to remove the old keys from the application keytab, per best
practice.

\begin{Verbatim}[commandchars=\\\{\}]
[root@casio krb5kdc]\PYGZsh{} k5srvutil \PYGZhy{}f /etc/zephyr/krb5.keytab delold
Authenticating as principal zephyr/zephyr@ZONE.MIT.EDU with keytab /etc/zephyr/krb5.keytab.
Entry for principal zephyr/zephyr@ZONE.MIT.EDU with kvno 3 removed from keytab WRFILE:/etc/zephyr/krb5.keytab.
\end{Verbatim}


\subsubsection{Adding strong keys by default}
\label{admin/advanced/retiring-des:adding-strong-keys-by-default}
Once the high-visibility services have been rekeyed, it is probably
appropriate to change {\hyperref[admin/conf_files/kdc_conf:kdc-conf-5]{\emph{kdc.conf}}} to generate keys with the new
encryption types by default.  This enables server administrators to generate
new enctypes with the \textbf{change} subcommand of {\hyperref[admin/admin_commands/k5srvutil:k5srvutil-1]{\emph{k5srvutil}}},
and causes user password
changes to add new encryption types for their entries.  It will probably
be necessary to implement administrative controls to cause all user
principal keys to be updated in a reasonable period of time, whether
by forcing password changes or a password synchronization service that
has access to the current password and can add the new keys.

\begin{Verbatim}[commandchars=\\\{\}]
[realms]
        ZONE.MIT.EDU = \PYGZob{}
                supported\PYGZus{}enctypes = aes256\PYGZhy{}cts\PYGZhy{}hmac\PYGZhy{}sha1\PYGZhy{}96:normal aes128\PYGZhy{}cts\PYGZhy{}hmac\PYGZhy{}sha1\PYGZhy{}96:normal des3\PYGZhy{}cbc\PYGZhy{}sha1:normal des3\PYGZhy{}hmac\PYGZhy{}sha1:normal des\PYGZhy{}cbc\PYGZhy{}crc:normal
\end{Verbatim}

\begin{notice}{note}{Note:}
The krb5kdc process must be restarted for these changes to take effect.
\end{notice}

At this point, all service administrators can update their services and the
servers behind them to take advantage of strong cryptography.
If necessary, the server's krb5 installation should be configured and/or
upgraded to a version supporting non-DES keys.  See {\hyperref[admin/enctypes:enctypes]{\emph{Encryption types}}} for
krb5 version and configuration settings.
Only when the service is configured to accept non-DES keys should
the key version number be incremented and new keys generated
(\code{k5srvutil change \&\& k5srvutil delold}).

\begin{Verbatim}[commandchars=\\\{\}]
root@dr\PYGZhy{}willy:\PYGZti{}\PYGZsh{} k5srvutil change
Authenticating as principal host/dr\PYGZhy{}willy.xvm.mit.edu@ZONE.MIT.EDU with keytab /etc/krb5.keytab.
Entry for principal host/dr\PYGZhy{}willy.xvm.mit.edu@ZONE.MIT.EDU with kvno 3, encryption type AES\PYGZhy{}256 CTS mode with 96\PYGZhy{}bit SHA\PYGZhy{}1 HMAC added to keytab WRFILE:/etc/krb5.keytab.
Entry for principal host/dr\PYGZhy{}willy.xvm.mit.edu@ZONE.MIT.EDU with kvno 3, encryption type AES\PYGZhy{}128 CTS mode with 96\PYGZhy{}bit SHA\PYGZhy{}1 HMAC added to keytab WRFILE:/etc/krb5.keytab.
Entry for principal host/dr\PYGZhy{}willy.xvm.mit.edu@ZONE.MIT.EDU with kvno 3, encryption type Triple DES cbc mode with HMAC/sha1 added to keytab WRFILE:/etc/krb5.keytab.
Entry for principal host/dr\PYGZhy{}willy.xvm.mit.edu@ZONE.MIT.EDU with kvno 3, encryption type DES cbc mode with CRC\PYGZhy{}32 added to keytab WRFILE:/etc/krb5.keytab.
root@dr\PYGZhy{}willy:\PYGZti{}\PYGZsh{} klist \PYGZhy{}e \PYGZhy{}k \PYGZhy{}t /etc/krb5.keytab
Keytab name: WRFILE:/etc/krb5.keytab
KVNO Timestamp         Principal
\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{} \PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{} \PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}\PYGZhy{}
   2 10/10/12 17:03:59 host/dr\PYGZhy{}willy.xvm.mit.edu@ZONE.MIT.EDU (DES cbc mode with CRC\PYGZhy{}32)
   3 12/12/12 15:31:19 host/dr\PYGZhy{}willy.xvm.mit.edu@ZONE.MIT.EDU (AES\PYGZhy{}256 CTS mode with 96\PYGZhy{}bit SHA\PYGZhy{}1 HMAC)
   3 12/12/12 15:31:19 host/dr\PYGZhy{}willy.xvm.mit.edu@ZONE.MIT.EDU (AES\PYGZhy{}128 CTS mode with 96\PYGZhy{}bit SHA\PYGZhy{}1 HMAC)
   3 12/12/12 15:31:19 host/dr\PYGZhy{}willy.xvm.mit.edu@ZONE.MIT.EDU (Triple DES cbc mode with HMAC/sha1)
   3 12/12/12 15:31:19 host/dr\PYGZhy{}willy.xvm.mit.edu@ZONE.MIT.EDU (DES cbc mode with CRC\PYGZhy{}32)
root@dr\PYGZhy{}willy:\PYGZti{}\PYGZsh{} k5srvutil delold
Authenticating as principal host/dr\PYGZhy{}willy.xvm.mit.edu@ZONE.MIT.EDU with keytab /etc/krb5.keytab.
Entry for principal host/dr\PYGZhy{}willy.xvm.mit.edu@ZONE.MIT.EDU with kvno 2 removed from keytab WRFILE:/etc/krb5.keytab.
\end{Verbatim}

When a single service principal is shared by multiple backend servers in
a load-balanced environment, it may be necessary to schedule downtime
or adjust the population in the load-balanced pool in order to propagate
the updated keytab to all hosts in the pool with minimal service interruption.


\subsubsection{Removing DES keys from usage}
\label{admin/advanced/retiring-des:removing-des-keys-from-usage}
This situation remains something of a testing or transitory state,
as new DES keys are still being generated, and will be used if requested
by a client.  To make more progress removing DES from the realm, the KDC
should be configured to not generate such keys by default.

\begin{notice}{note}{Note:}
An attacker posing as a client can implement a brute force attack against
a DES key for any principal, if that key is in the current (highest-kvno)
key list.  This attack is only possible if \textbf{allow\_weak\_crypto = true}
is enabled on the KDC.  Setting the \textbf{+requires\_preauth} flag on a
principal forces this attack to be an online attack, much slower than
the offline attack otherwise available to the attacker.  However, setting
this flag on a service principal is not always advisable; see the entry in
{\hyperref[admin/admin_commands/kadmin_local:add-principal]{\emph{add\_principal}}} for details.
\end{notice}

The following KDC configuration will not generate DES keys by default:

\begin{Verbatim}[commandchars=\\\{\}]
[realms]
        ZONE.MIT.EDU = \PYGZob{}
                supported\PYGZus{}enctypes = aes256\PYGZhy{}cts\PYGZhy{}hmac\PYGZhy{}sha1\PYGZhy{}96:normal aes128\PYGZhy{}cts\PYGZhy{}hmac\PYGZhy{}sha1\PYGZhy{}96:normal des3\PYGZhy{}cbc\PYGZhy{}sha1:normal des3\PYGZhy{}hmac\PYGZhy{}sha1:normal
\end{Verbatim}

\begin{notice}{note}{Note:}
As before, the KDC process must be restarted for this change to take
effect.  It is best practice to update kdc.conf on all KDCs, not just the
master, to avoid unpleasant surprises should the master fail and a slave
need to be promoted.
\end{notice}

It is now appropriate to remove the legacy single-DES key from the
\code{krbtgt/REALM} entry:

\begin{Verbatim}[commandchars=\\\{\}]
[root@casio krb5kdc]\PYGZsh{} kadmin.local \PYGZhy{}r ZONE.MIT.EDU \PYGZhy{}q \PYGZdq{}cpw \PYGZhy{}randkey \PYGZhy{}keepold \PYGZbs{}
\PYGZgt{} krbtgt/ZONE.MIT.EDU\PYGZdq{}
Authenticating as principal host/admin@ATHENA.MIT.EDU with password.
Key for \PYGZdq{}krbtgt/ZONE.MIT.EDU@ZONE.MIT.EDU\PYGZdq{} randomized.
\end{Verbatim}

After the maximum ticket lifetime has passed, the old database entry
should be removed.

\begin{Verbatim}[commandchars=\\\{\}]
[root@casio krb5kdc]\PYGZsh{} kadmin.local \PYGZhy{}r ZONE.MIT.EDU \PYGZhy{}q \PYGZsq{}purgekeys krbtgt/ZONE.MIT.EDU\PYGZsq{}
Authenticating as principal root/admin@ZONE.MIT.EDU with password.
Old keys for principal \PYGZdq{}krbtgt/ZONE.MIT.EDU@ZONE.MIT.EDU\PYGZdq{} purged.
\end{Verbatim}

After the KDC is restarted with the new \textbf{supported\_enctypes},
all user password changes and application keytab updates will not
generate DES keys by default.

\begin{Verbatim}[commandchars=\\\{\}]
contents\PYGZhy{}vnder\PYGZhy{}pressvre:\PYGZti{}\PYGZgt{} kpasswd zonetest@ZONE.MIT.EDU
Password for zonetest@ZONE.MIT.EDU:  [enter old password]
Enter new password:                  [enter new password]
Enter it again:                      [enter new password]
Password changed.
contents\PYGZhy{}vnder\PYGZhy{}pressvre:\PYGZti{}\PYGZgt{} kadmin \PYGZhy{}r ZONE.MIT.EDU \PYGZhy{}q \PYGZsq{}getprinc zonetest\PYGZsq{}
[...]
Number of keys: 3
Key: vno 9, aes256\PYGZhy{}cts\PYGZhy{}hmac\PYGZhy{}sha1\PYGZhy{}96
Key: vno 9, aes128\PYGZhy{}cts\PYGZhy{}hmac\PYGZhy{}sha1\PYGZhy{}96
Key: vno 9, des3\PYGZhy{}cbc\PYGZhy{}sha1
[...]

[kaduk@glossolalia \PYGZti{}]\PYGZdl{} kadmin \PYGZhy{}p kaduk@ZONE.MIT.EDU \PYGZhy{}r ZONE.MIT.EDU \PYGZhy{}k \PYGZbs{}
\PYGZgt{} \PYGZhy{}t kaduk\PYGZhy{}zone.keytab \PYGZhy{}q \PYGZsq{}ktadd \PYGZhy{}k kaduk\PYGZhy{}zone.keytab kaduk@ZONE.MIT.EDU\PYGZsq{}
Authenticating as principal kaduk@ZONE.MIT.EDU with keytab kaduk\PYGZhy{}zone.keytab.
Entry for principal kaduk@ZONE.MIT.EDU with kvno 3, encryption type aes256\PYGZhy{}cts\PYGZhy{}hmac\PYGZhy{}sha1\PYGZhy{}96 added to keytab WRFILE:kaduk\PYGZhy{}zone.keytab.
Entry for principal kaduk@ZONE.MIT.EDU with kvno 3, encryption type aes128\PYGZhy{}cts\PYGZhy{}hmac\PYGZhy{}sha1\PYGZhy{}96 added to keytab WRFILE:kaduk\PYGZhy{}zone.keytab.
Entry for principal kaduk@ZONE.MIT.EDU with kvno 3, encryption type des3\PYGZhy{}cbc\PYGZhy{}sha1 added to keytab WRFILE:kaduk\PYGZhy{}zone.keytab.
\end{Verbatim}

Once all principals have been re-keyed, DES support can be disabled on the
KDC (\textbf{allow\_weak\_crypto = false}), and client machines can remove
\textbf{allow\_weak\_crypto = true} from their {\hyperref[admin/conf_files/krb5_conf:krb5-conf-5]{\emph{krb5.conf}}} configuration
files, completing the migration.  \textbf{allow\_weak\_crypto} takes precedence over
all places where DES enctypes could be explicitly configured.  DES keys will
not be used, even if they are present, when \textbf{allow\_weak\_crypto = false}.


\subsubsection{Support for legacy services}
\label{admin/advanced/retiring-des:support-for-legacy-services}
If there remain legacy services which do not support non-DES enctypes
(such as older versions of AFS), \textbf{allow\_weak\_crypto} must remain
enabled on the KDC.  Client machines need not have this setting,
though---applications which require DES can use API calls to allow
weak crypto on a per-request basis, overriding the system krb5.conf.
However, having \textbf{allow\_weak\_crypto} set on the KDC means that any
principals which have a DES key in the database could still use those
keys.  To minimize the use of DES in the realm and restrict it to just
legacy services which require DES, it is necessary to remove all other
DES keys.  The realm has been configured such that at password and
keytab change, no DES keys will be generated by default.  The task
then reduces to requiring user password changes and having server
administrators update their service keytabs.  Administrative outreach
will be necessary, and if the desire to eliminate DES is sufficiently
strong, the KDC administrators may choose to randkey any principals
which have not been rekeyed after some timeout period, forcing the
user to contact the helpdesk for access.


\subsection{The Database Master Key}
\label{admin/advanced/retiring-des:the-database-master-key}
This procedure does not alter \code{K/M@REALM}, the key used to encrypt key
material in the Kerberos database.  (This is the key stored in the stash file
on the KDC if stash files are used.)  However, the security risk of
a single-DES key for \code{K/M} is minimal, given that access to material
encrypted in \code{K/M} (the Kerberos database) is generally tightly controlled.
If an attacker can gain access to the encrypted database, they likely
have access to the stash file as well, rendering the weak cryptography
broken by non-cryptographic means.  As such, upgrading \code{K/M} to a stronger
encryption type is unlikely to be a high-priority task.

Is is possible to upgrade the master key used for the database, if
desired.  Using {\hyperref[admin/admin_commands/kdb5_util:kdb5-util-8]{\emph{kdb5\_util}}}`s \textbf{add\_mkey}, \textbf{use\_mkey}, and
\textbf{update\_princ\_encryption} commands, a new master key can be added
and activated for use on new key material, and the existing entries
converted to the new master key.


\chapter{Various links}
\label{admin/various_envs:various-links}\label{admin/various_envs::doc}

\section{Whitepapers}
\label{admin/various_envs:whitepapers}\begin{enumerate}
\item {} 
\href{http://kerberos.org/software/whitepapers.html}{http://kerberos.org/software/whitepapers.html}

\end{enumerate}


\section{Tutorials}
\label{admin/various_envs:tutorials}\begin{enumerate}
\item {} 
Fulvio Ricciardi  \textless{}\href{http://www.kerberos.org/software/tutorial.html}{http://www.kerberos.org/software/tutorial.html}\textgreater{}\_

\end{enumerate}


\section{Troubleshooting}
\label{admin/various_envs:troubleshooting}\begin{enumerate}
\item {} 
\href{http://www.ncsa.illinois.edu/UserInfo/Resources/Software/kerberos/troubleshooting.html}{http://www.ncsa.illinois.edu/UserInfo/Resources/Software/kerberos/troubleshooting.html}

\item {} 
\href{http://nfsv4.bullopensource.org/doc/kerberosnfs/krbnfs\_howto\_v3.pdf}{http://nfsv4.bullopensource.org/doc/kerberosnfs/krbnfs\_howto\_v3.pdf}

\item {} 
\href{http://sysdoc.doors.ch/HP/T1417-90005.pdf}{http://sysdoc.doors.ch/HP/T1417-90005.pdf}

\item {} 
\href{http://www.shrubbery.net/solaris9ab/SUNWaadm/SYSADV6/p27.html}{http://www.shrubbery.net/solaris9ab/SUNWaadm/SYSADV6/p27.html}

\item {} 
\href{http://download.oracle.com/docs/cd/E19253-01/816-4557/trouble-1/index.html}{http://download.oracle.com/docs/cd/E19253-01/816-4557/trouble-1/index.html}

\item {} 
\href{http://technet.microsoft.com/en-us/library/bb463167.aspx\#EBAA}{http://technet.microsoft.com/en-us/library/bb463167.aspx\#EBAA}

\item {} 
\href{https://bugs.launchpad.net/ubuntu/+source/libpam-heimdal/+bug/86528}{https://bugs.launchpad.net/ubuntu/+source/libpam-heimdal/+bug/86528}

\item {} 
\href{http://h71000.www7.hp.com/doc/83final/ba548\_90007/ch06s05.html}{http://h71000.www7.hp.com/doc/83final/ba548\_90007/ch06s05.html}

\end{enumerate}



\renewcommand{\indexname}{Index}
\printindex
\end{document}