| blob | 6f3115ccd82d01f3795a57850998c78cebb2bbc1 |
1 '\" te
2 .\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved
3 .\" 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.
4 .\" 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.
5 .\" 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]
6 .TH KDCMGR 8 "Sep 19, 2007"
7 .SH NAME
8 kdcmgr \- set up a Kerberos Key Distribution Center (KDC)
9 .SH SYNOPSIS
10 .LP
11 .nf
12 \fB/usr/sbin/kdcmgr\fR [\fB-a\fR \fIadmprincipal\fR] [\fB-e\fR \fIenctype\fR]
13 [\fB-h\fR] [\fB-p\fR \fIpwfile\fR] [\fB-r\fR \fIrealm\fR] \fIsubcommand\fR
14 .fi
16 .SH DESCRIPTION
17 .sp
18 .LP
19 Use the \fBkdcmgr\fR utility to do the following:
20 .RS +4
21 .TP
22 .ie t \(bu
23 .el o
24 Configure a master Key Distribution Center (KDC) server.
25 .RE
26 .RS +4
27 .TP
28 .ie t \(bu
29 .el o
30 Configure a slave KDC. This assumes that a master KDC has already been
31 configured. The default propagation method configured is incremental
32 propagation. See \fBkpropd\fR(8).
33 .RE
34 .RS +4
35 .TP
36 .ie t \(bu
37 .el o
38 Specify a list of slave KDCs to configure service principals and create access
39 control list for those slaves on the master KDC.
40 .RE
41 .sp
42 .LP
43 If you specify no options, \fBkdcmgr\fR prompts you for required information,
44 including a password to generate the master key and a password for the
45 administrative principal. When you specify sufficient options, you are still
46 prompted for these passwords, unless you specified the \fB-p\fR \fIpwfile\fR
47 option.
48 .sp
49 .LP
50 The \fBkdcmgr\fR utility must be run as superuser or by someone who has the
51 Primary Administrator role. The command must be run on the server from which it
52 is invoked.
53 .sp
54 .LP
55 Note that \fBkdcmgr\fR requires the user to enter sensitive information, such
56 as the password used to generate the database's master key and the password for
57 the administrative principal. Great care must be taken to ensure that the
58 connection to the server is secured over the network, by using a protocol such
59 as \fBssh\fR(1).
60 .sp
61 .LP
62 You must also exercise great care when selecting the administrative and master
63 key passwords. They should be derived from non-dictionary words and a long
64 string of characters consisting of all of the following character classes:
65 .RS +4
66 .TP
67 .ie t \(bu
68 .el o
69 special characters (for example, !@#$%^&*)
70 .RE
71 .RS +4
72 .TP
73 .ie t \(bu
74 .el o
75 numerals (0-9)
76 .RE
77 .RS +4
78 .TP
79 .ie t \(bu
80 .el o
81 uppercase letters
82 .RE
83 .RS +4
84 .TP
85 .ie t \(bu
86 .el o
87 lowercase letters
88 .RE
89 .SH OPTIONS
90 .sp
91 .LP
92 The following options are supported:
93 .sp
94 .ne 2
95 .na
96 \fB\fB-a\fR \fIadmprincipal\fR\fR
97 .ad
98 .sp .6
99 .RS 4n
100 When creating a master KDC, specifies the administrative principal,
101 \fIadmprincipal\fR, that will be created.
102 .sp
103 When creating a slave KDC, \fIadmprincipal\fR is used to authenticate as the
104 administrative principal.
105 .sp
106 If you omit \fB-a\fR, the suggested default administrative principal name is
107 the output of \fBlogname\fR(1) appended by \fB/admin\fR.
108 .RE
110 .sp
111 .ne 2
112 .na
113 \fB\fB-e\fR \fIenctype\fR\fR
114 .ad
115 .sp .6
116 .RS 4n
117 Specifies the encryption type to be used when creating the key for the master
118 key, which is used to encrypt all principal keys in the database. The set of
119 valid encryption types used here are described in \fBkrb5.conf\fR(4) under the
120 \fBpermitted_enctypes\fR option. Note that the encryption type specified here
121 must be supported on all KDCs or else they will not be able to decrypt any of
122 the principal keys. Solaris 9 and earlier releases support only the
123 \fBdes-cbc-crc\fR encryption type for the master key. Therefore, if any of the
124 master or slave KDCs are of these older releases, then \fB-e\fR
125 \fBdes-cbc-crc\fR would need to be specified on all KDCs configured with
126 \fBkdcmgr\fR.
127 .sp
128 The default encryption type is \fBaes128-cts-hmac-sha1-96\fR.
129 .RE
131 .sp
132 .ne 2
133 .na
134 \fB\fB-h\fR\fR
135 .ad
136 .sp .6
137 .RS 4n
138 Displays usage information for \fBkdcmgr\fR.
139 .RE
141 .sp
142 .ne 2
143 .na
144 \fB\fB-p\fR \fIpwfile\fR\fR
145 .ad
146 .sp .6
147 .RS 4n
148 Provides the location of the password file that contains the password used to
149 create the administrative principal and/or master key.
150 .sp
151 \fBWarning:\fR This option should be used with great care. Make sure that this
152 \fIpwfile\fR is accessible only by a privileged user and on a local file
153 system. Once the KDC has been configured, you should remove \fIpwfile\fR.
154 .RE
156 .sp
157 .ne 2
158 .na
159 \fB\fB-r\fR \fIrealm\fR\fR
160 .ad
161 .sp .6
162 .RS 4n
163 Set the default realm for this server.
164 .sp
165 If the \fB-r\fR option is not specified, \fBkdcmgr\fR attempts to obtain the
166 machine's local domain name by submitting the canonical form of the machine's
167 host name to DNS and using the return value to derive the domain name. If
168 successful, the domain name is converted to uppercase and proposed as the
169 default realm name.
170 .RE
172 .SH SUBCOMMANDS
173 .sp
174 .LP
175 The following subcommands are supported:
176 .sp
177 .ne 2
178 .na
179 \fB\fBcreate\fR [ \fImaster\fR ]\fR
180 .ad
181 .br
182 .na
183 \fB\fBcreate\fR [ \fB-m\fR \fImasterkdc\fR ] slave\fR
184 .ad
185 .sp .6
186 .RS 4n
187 Creates a KDC. If no option is specified, an attempt to create a master KDC is
188 made.
189 .sp
190 .ne 2
191 .na
192 \fB\fBcreate\fR [ \fImaster\fR ]\fR
193 .ad
194 .sp .6
195 .RS 4n
196 Create a master KDC. Upon successful configuration the \fBkrb5kdc\fR(8) and
197 \fBkadmind\fR(8) are enabled on the machine.
198 .RE
200 .sp
201 .ne 2
202 .na
203 \fB\fBcreate\fR [ \fB-m\fR \fImasterkdc\fR ] slave\fR
204 .ad
205 .sp .6
206 .RS 4n
207 Configures a slave KDC. After configuration, the \fBkrb5kdc\fR(8) and
208 \fBkpropd\fR(8) services are enabled on the machine.
209 .sp
210 \fImasterkdc\fR specifies the master KDC to authenticate and with which to
211 perform administrative tasks. If the \fB-m\fR option is not specified, you are
212 prompted for a master KDC host name.
213 .RE
215 .RE
217 .sp
218 .ne 2
219 .na
220 \fB\fBdestroy\fR\fR
221 .ad
222 .sp .6
223 .RS 4n
224 Remove all Kerberos configuration and database files associated with the KDC
225 server. A confirmation is required before these files are deleted.
226 .RE
228 .sp
229 .ne 2
230 .na
231 \fB\fBstatus\fR\fR
232 .ad
233 .sp .6
234 .RS 4n
235 Determines the role of the KDC, master or slave, and outputs this and the state
236 of such associated processes as:
237 .RS +4
238 .TP
239 .ie t \(bu
240 .el o
241 \fBkrb5kdc\fR(8)
242 .RE
243 .RS +4
244 .TP
245 .ie t \(bu
246 .el o
247 \fBkadmind\fR(8)
248 .RE
249 .RS +4
250 .TP
251 .ie t \(bu
252 .el o
253 \fBkpropd\fR(8)
254 .RE
255 The subcommand also displays information on incremental propagation if the
256 configuration has this feature enabled, as well as any issues with dependent
257 files.
258 .RE
260 .SH EXAMPLES
261 .LP
262 \fBExample 1 \fRSetting up a Master KDC
263 .sp
264 .LP
265 The following command configures a master KDC with the administrative principal
266 \fBuser1/admin\fR and with the realm name \fBEXAMPLE.COM\fR:
268 .sp
269 .in +2
270 .nf
271 $ \fBkdcmgr -a user1/admin -r EXAMPLE.COM create\fR
272 .fi
273 .in -2
274 .sp
276 .sp
277 .LP
278 Note that a password will be required to assign to the newly created
279 \fBuser1/admin\fR principal. The password for the master key will also need to
280 be provided.
282 .LP
283 \fBExample 2 \fRSetting up a Slave KDC
284 .sp
285 .LP
286 The following command configures a slave KDC, authenticates with the
287 administrative principal \fBuser1/admin\fR, specifies \fBkdc1\fR as the master,
288 and uses the \fBEXAMPLE.COM\fR realm name:
290 .sp
291 .in +2
292 .nf
293 $ \fBkdcmgr -a user1/admin -r EXAMPLE.COM create -m kdc1 slave\fR
294 .fi
295 .in -2
296 .sp
298 .sp
299 .LP
300 Note that you must enter the correct password for \fBuser1/admin\fR and that
301 the master KDC must already have been created before entering this command. The
302 correct password for the master key is also required.
304 .SH FILES
305 .sp
306 .ne 2
307 .na
308 \fB\fB/etc/krb5/krb5.conf\fR\fR
309 .ad
310 .sp .6
311 .RS 4n
312 Main Kerberos configuration file.
313 .RE
315 .sp
316 .ne 2
317 .na
318 \fB\fB/etc/krb5/kdc.conf\fR\fR
319 .ad
320 .sp .6
321 .RS 4n
322 KDC configuration, used by both master and slave servers.
323 .RE
325 .sp
326 .ne 2
327 .na
328 \fB\fB/etc/krb5/krb5.keytab\fR\fR
329 .ad
330 .sp .6
331 .RS 4n
332 Default location of the local host's service keys.
333 .RE
335 .sp
336 .ne 2
337 .na
338 \fB\fB/etc/krb5/kadm5.acl\fR\fR
339 .ad
340 .sp .6
341 .RS 4n
342 Kerberos administrative access control list (ACL).
343 .RE
345 .sp
346 .ne 2
347 .na
348 \fB\fB/etc/krb5/kadm5.keytab\fR\fR
349 .ad
350 .sp .6
351 .RS 4n
352 Service keys specific to \fBkadmind\fR(8).
353 .RE
355 .sp
356 .ne 2
357 .na
358 \fB\fB/var/krb5/principal\fR\fR
359 .ad
360 .sp .6
361 .RS 4n
362 Kerberos principal database.
363 .RE
365 .sp
366 .ne 2
367 .na
368 \fB\fB/var/krb5/principal.kadm5\fR\fR
369 .ad
370 .sp .6
371 .RS 4n
372 Kerberos policy database.
373 .RE
375 .sp
376 .ne 2
377 .na
378 \fB\fB/etc/krb5/kpropd.acl\fR\fR
379 .ad
380 .sp .6
381 .RS 4n
382 Used by slaves to indicate from which server to receive updates.
383 .RE
385 .SH ATTRIBUTES
386 .sp
387 .LP
388 See \fBattributes\fR(5) for descriptions of the following attributes:
389 .sp
391 .sp
392 .TS
393 box;
394 c | c
395 l | l .
396 ATTRIBUTE TYPE ATTRIBUTE VALUE
397 _
398 Interface Stability See below
399 .TE
401 .sp
402 .LP
403 The command line interface (CLI) is Uncommitted. The CLI output is Not an
404 Interface.
405 .SH SEE ALSO
406 .sp
407 .LP
408 \fBlogname\fR(1), \fBssh\fR(1), \fBkadmin\fR(8), \fBkadmind\fR(8),
409 \fBkdb5_util\fR(8), \fBkdb5_ldap_util\fR(8), \fBkpropd\fR(8),
410 \fBkrb5kdc\fR(8), \fBping\fR(8), \fBsvcadm\fR(8), \fBkdc.conf\fR(4),
411 \fBkrb5.conf\fR(4), \fBattributes\fR(5)