path: root/usr/src/man/man1m/kdcmgr.1m

'\" te
.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH KDCMGR 1M "Sep 19, 2007"
.SH NAME
kdcmgr \- set up a Kerberos Key Distribution Center (KDC)
.SH SYNOPSIS
.LP
.nf
\fB/usr/sbin/kdcmgr\fR [\fB-a\fR \fIadmprincipal\fR] [\fB-e\fR \fIenctype\fR]
     [\fB-h\fR] [\fB-p\fR \fIpwfile\fR] [\fB-r\fR \fIrealm\fR] \fIsubcommand\fR
.fi

.SH DESCRIPTION
.sp
.LP
Use the \fBkdcmgr\fR utility to do the following:
.RS +4
.TP
.ie t \(bu
.el o
Configure a master Key Distribution Center (KDC) server.
.RE
.RS +4
.TP
.ie t \(bu
.el o
Configure a slave KDC. This assumes that a master KDC has already been
configured. The default propagation method configured is incremental
propagation. See \fBkpropd\fR(1M).
.RE
.RS +4
.TP
.ie t \(bu
.el o
Specify a list of slave KDCs to configure service principals and create access
control list for those slaves on the master KDC.
.RE
.sp
.LP
If you specify no options, \fBkdcmgr\fR prompts you for required information,
including a password to generate the master key and a password for the
administrative principal. When you specify sufficient options, you are still
prompted for these passwords, unless you specified the \fB-p\fR \fIpwfile\fR
option.
.sp
.LP
The \fBkdcmgr\fR utility must be run as superuser or by someone who has the
Primary Administrator role. The command must be run on the server from which it
is invoked.
.sp
.LP
Note that \fBkdcmgr\fR requires the user to enter sensitive information, such
as the password used to generate the database's master key and the password for
the administrative principal. Great care must be taken to ensure that the
connection to the server is secured over the network, by using a protocol such
as \fBssh\fR(1).
.sp
.LP
You must also exercise great care when selecting the administrative and master
key passwords. They should be derived from non-dictionary words and a long
string of characters consisting of all of the following character classes:
.RS +4
.TP
.ie t \(bu
.el o
special characters (for example, !@#$%^&*)
.RE
.RS +4
.TP
.ie t \(bu
.el o
numerals (0-9)
.RE
.RS +4
.TP
.ie t \(bu
.el o
uppercase letters
.RE
.RS +4
.TP
.ie t \(bu
.el o
lowercase letters
.RE
.SH OPTIONS
.sp
.LP
The following options are supported:
.sp
.ne 2
.na
\fB\fB-a\fR \fIadmprincipal\fR\fR
.ad
.sp .6
.RS 4n
When creating a master KDC, specifies the administrative principal,
\fIadmprincipal\fR, that will be created.
.sp
When creating a slave KDC, \fIadmprincipal\fR is used to authenticate as the
administrative principal.
.sp
If you omit \fB-a\fR, the suggested default administrative principal name is
the output of \fBlogname\fR(1) appended by \fB/admin\fR.
.RE

.sp
.ne 2
.na
\fB\fB-e\fR \fIenctype\fR\fR
.ad
.sp .6
.RS 4n
Specifies the encryption type to be used when creating the key for the master
key, which is used to encrypt all principal keys in the database. The set of
valid encryption types used here are described in \fBkrb5.conf\fR(4) under the
\fBpermitted_enctypes\fR option. Note that the encryption type specified here
must be supported on all KDCs or else they will not be able to decrypt any of
the principal keys. Solaris 9 and earlier releases support only the
\fBdes-cbc-crc\fR encryption type for the master key. Therefore, if any of the
master or slave KDCs are of these older releases, then \fB-e\fR
\fBdes-cbc-crc\fR would need to be specified on all KDCs configured with
\fBkdcmgr\fR.
.sp
The default encryption type is \fBaes128-cts-hmac-sha1-96\fR.
.RE

.sp
.ne 2
.na
\fB\fB-h\fR\fR
.ad
.sp .6
.RS 4n
Displays usage information for \fBkdcmgr\fR.
.RE

.sp
.ne 2
.na
\fB\fB-p\fR \fIpwfile\fR\fR
.ad
.sp .6
.RS 4n
Provides the location of the password file that contains the password used to
create the administrative principal and/or master key.
.sp
\fBWarning:\fR This option should be used with great care. Make sure that this
\fIpwfile\fR is accessible only by a privileged user and on a local file
system. Once the KDC has been configured, you should remove \fIpwfile\fR.
.RE

.sp
.ne 2
.na
\fB\fB-r\fR \fIrealm\fR\fR
.ad
.sp .6
.RS 4n
Set the default realm for this server.
.sp
If the \fB-r\fR option is not specified, \fBkdcmgr\fR attempts to obtain the
machine's local domain name by submitting the canonical form of the machine's
host name to DNS and using the return value to derive the domain name. If
successful, the domain name is converted to uppercase and proposed as the
default realm name.
.RE

.SH SUBCOMMANDS
.sp
.LP
The following subcommands are supported:
.sp
.ne 2
.na
\fB\fBcreate\fR [ \fImaster\fR ]\fR
.ad
.br
.na
\fB\fBcreate\fR [ \fB-m\fR \fImasterkdc\fR ] slave\fR
.ad
.sp .6
.RS 4n
Creates a KDC. If no option is specified, an attempt to create a master KDC is
made.
.sp
.ne 2
.na
\fB\fBcreate\fR [ \fImaster\fR ]\fR
.ad
.sp .6
.RS 4n
Create a master KDC. Upon successful configuration the \fBkrb5kdc\fR(1M) and
\fBkadmind\fR(1M) are enabled on the machine.
.RE

.sp
.ne 2
.na
\fB\fBcreate\fR [ \fB-m\fR \fImasterkdc\fR ] slave\fR
.ad
.sp .6
.RS 4n
Configures a slave KDC. After configuration, the \fBkrb5kdc\fR(1M) and
\fBkpropd\fR(1M) services are enabled on the machine.
.sp
\fImasterkdc\fR specifies the master KDC to authenticate and with which to
perform administrative tasks. If the \fB-m\fR option is not specified, you are
prompted for a master KDC host name.
.RE

.RE

.sp
.ne 2
.na
\fB\fBdestroy\fR\fR
.ad
.sp .6
.RS 4n
Remove all Kerberos configuration and database files associated with the KDC
server. A confirmation is required before these files are deleted.
.RE

.sp
.ne 2
.na
\fB\fBstatus\fR\fR
.ad
.sp .6
.RS 4n
Determines the role of the KDC, master or slave, and outputs this and the state
of such associated processes as:
.RS +4
.TP
.ie t \(bu
.el o
\fBkrb5kdc\fR(1M)
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fBkadmind\fR(1M)
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fBkpropd\fR(1M)
.RE
The subcommand also displays information on incremental propagation if the
configuration has this feature enabled, as well as any issues with dependent
files.
.RE

.SH EXAMPLES
.LP
\fBExample 1 \fRSetting up a Master KDC
.sp
.LP
The following command configures a master KDC with the administrative principal
\fBuser1/admin\fR and with the realm name \fBEXAMPLE.COM\fR:

.sp
.in +2
.nf
$ \fBkdcmgr -a user1/admin -r EXAMPLE.COM create\fR
.fi
.in -2
.sp

.sp
.LP
Note that a password will be required to assign to the newly created
\fBuser1/admin\fR principal. The password for the master key will also need to
be provided.

.LP
\fBExample 2 \fRSetting up a Slave KDC
.sp
.LP
The following command configures a slave KDC, authenticates with the
administrative principal \fBuser1/admin\fR, specifies \fBkdc1\fR as the master,
and uses the \fBEXAMPLE.COM\fR realm name:

.sp
.in +2
.nf
$ \fBkdcmgr -a user1/admin -r EXAMPLE.COM create -m kdc1 slave\fR
.fi
.in -2
.sp

.sp
.LP
Note that you must enter the correct password for \fBuser1/admin\fR and that
the master KDC must already have been created before entering this command. The
correct password for the master key is also required.

.SH FILES
.sp
.ne 2
.na
\fB\fB/etc/krb5/krb5.conf\fR\fR
.ad
.sp .6
.RS 4n
Main Kerberos configuration file.
.RE

.sp
.ne 2
.na
\fB\fB/etc/krb5/kdc.conf\fR\fR
.ad
.sp .6
.RS 4n
KDC configuration, used by both master and slave servers.
.RE

.sp
.ne 2
.na
\fB\fB/etc/krb5/krb5.keytab\fR\fR
.ad
.sp .6
.RS 4n
Default location of the local host's service keys.
.RE

.sp
.ne 2
.na
\fB\fB/etc/krb5/kadm5.acl\fR\fR
.ad
.sp .6
.RS 4n
Kerberos administrative access control list (ACL).
.RE

.sp
.ne 2
.na
\fB\fB/etc/krb5/kadm5.keytab\fR\fR
.ad
.sp .6
.RS 4n
Service keys specific to \fBkadmind\fR(1M).
.RE

.sp
.ne 2
.na
\fB\fB/var/krb5/principal\fR\fR
.ad
.sp .6
.RS 4n
Kerberos principal database.
.RE

.sp
.ne 2
.na
\fB\fB/var/krb5/principal.kadm5\fR\fR
.ad
.sp .6
.RS 4n
Kerberos policy database.
.RE

.sp
.ne 2
.na
\fB\fB/etc/krb5/kpropd.acl\fR\fR
.ad
.sp .6
.RS 4n
Used by slaves to indicate from which server to receive updates.
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	See below
.TE

.sp
.LP
The command line interface (CLI) is Uncommitted. The CLI output is Not an
Interface.
.SH SEE ALSO
.sp
.LP
\fBlogname\fR(1), \fBssh\fR(1), \fBkadmin\fR(1M), \fBkadmind\fR(1M),
\fBkdb5_util\fR(1M), \fBkdb5_ldap_util\fR(1M), \fBkpropd\fR(1M),
\fBkrb5kdc\fR(1M), \fBping\fR(1M), \fBsvcadm\fR(1M), \fBkdc.conf\fR(4),
\fBkrb5.conf\fR(4), \fBattributes\fR(5)