| blob | 276c0055cfcdf726b1b91494764ab76ad1227b2a |
1 '\" te
2 .\" Copyright (c) 2008, 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 KCLIENT 1M "May 27, 2009"
7 .SH NAME
8 kclient \- set up a machine as a Kerberos client
9 .SH SYNOPSIS
10 .LP
11 .nf
12 \fB/usr/sbin/kclient\fR [\fB-n\fR] [\fB-R\fR \fIrealm\fR] [\fB-k\fR \fIkdc\fR] [\fB-a\fR \fIadminuser\fR]
13 [\fB-c\fR \fIfilepath\fR] [\fB-d\fR \fIdnsarg\fR] [\fB-f\fR \fIfqdn_list\fR] [\fB-h\fR \fIlogical_host_name\fR]
14 [\fB-k\fR \fIkdc_list\fR] [\fB-m\fR \fImaster_kdc\fR] [\fB-p\fR \fIprofile\fR] [\fB-s\fR \fIpam_service\fR]
15 [\fB-T\fR \fIkdc_vendor\fR]
16 .fi
18 .SH DESCRIPTION
19 .sp
20 .LP
21 By specifying the various command options, you can use the \fBkclient\fR
22 utility to:
23 .RS +4
24 .TP
25 .ie t \(bu
26 .el o
27 Configure a machine as a Kerberos client for a specified realm and for KDC by
28 setting up \fBkrb5.conf\fR(4).
29 .RE
30 .RS +4
31 .TP
32 .ie t \(bu
33 .el o
34 Add the Kerberos host principal to the local host's \fBkeytab\fR file
35 (\fB/etc/krb5/krb5.keytab\fR).
36 .RE
37 .RS +4
38 .TP
39 .ie t \(bu
40 .el o
41 Set up the machine to do kerberized NFS.
42 .RE
43 .RS +4
44 .TP
45 .ie t \(bu
46 .el o
47 Bring over a master \fBkrb5.conf\fR copy from a specified pathname.
48 .RE
49 .RS +4
50 .TP
51 .ie t \(bu
52 .el o
53 Setup a machine to do server and/or host/domain name-to-realm mapping lookups
54 by means of DNS.
55 .RE
56 .RS +4
57 .TP
58 .ie t \(bu
59 .el o
60 Configure a Kerberos client to use an MS Active Directory server. This
61 generates a \fBkeytab\fR file with the Kerberos client's service keys
62 populated.
63 .RE
64 .RS +4
65 .TP
66 .ie t \(bu
67 .el o
68 Setup a Kerberos client that has no service keys. This is useful when the
69 client does not require service keys, because the client does not wish to host
70 a service that uses Kerberos for security.
71 .RE
72 .RS +4
73 .TP
74 .ie t \(bu
75 .el o
76 Configure a Kerberos client that is part of a cluster. This option requires the
77 logical host name of the cluster so that the proper service keys are created
78 and populated in the client's \fBkeytab\fR file.
79 .RE
80 .RS +4
81 .TP
82 .ie t \(bu
83 .el o
84 Setup a Kerberos client to join an environment that consists of Kerberos
85 servers that are non-Solaris and non-MS Active Directory servers.
86 .RE
87 .RS +4
88 .TP
89 .ie t \(bu
90 .el o
91 Configure \fBpam.conf\fR(4) to use Kerberos authentication for specified
92 services.
93 .RE
94 .RS +4
95 .TP
96 .ie t \(bu
97 .el o
98 Configure the client as a simple NTP broadcast/multicast client.
99 .RE
100 .RS +4
101 .TP
102 .ie t \(bu
103 .el o
104 Specify custom domain/host name-to-realm name mappings.
105 .RE
106 .RS +4
107 .TP
108 .ie t \(bu
109 .el o
110 Setup the Kerberos client to use multiple KDC servers.
111 .RE
112 .sp
113 .LP
114 The \fBkclient\fR utility needs to be run on the client machine with root
115 permission and can be run either interactively or non-interactively. In the
116 non-interactive mode, the user feeds in the required inputs by means of a
117 profile, command-line options, or a combination of profile and command-line
118 options. The user is prompted for "required" parameter values (\fBrealm\fR and
119 \fBadminuser\fR), if found missing in the non-interactive run. The interactive
120 mode is invoked when the utility is run without any command-line arguments.
121 .sp
122 .LP
123 Both the interactive and non-interactive forms of \fBkclient\fR can add the
124 \fBhost/fqdn\fR entry to the local host's \fBkeytab\fR file. They also can
125 require the user to enter the password for the administrative user requested,
126 to obtain the Kerberos Ticket Granting Ticket (TGT) for \fBadminuser\fR. The
127 \fBhost/fqdn\fR, \fBnfs/fqdn\fR, and \fBroot/fqdn\fR principals can be added to
128 the KDC database (if not already present) before their possible addition to the
129 local host's \fBkeytab\fR.
130 .sp
131 .LP
132 The \fBkclient\fR utility assumes that the local host has been setup for DNS
133 and requires the presence of a valid \fBresolv.conf\fR(4). Also, \fBkclient\fR
134 can fail if the localhost time is not synchronized with that of the KDC. For
135 Kerberos to function the localhost time must be within five minutes of that of
136 the KDC. It is advised that both systems run some form of time synchronization
137 protocol, such as the Network Time Protocol (NTP). See the \fBntpd\fR man page,
138 delivered in the \fBSUNWntpu\fR package (not a SunOS man page).
139 .SH OPTIONS
140 .sp
141 .LP
142 The non-interactive mode supports the following options:
143 .sp
144 .ne 2
145 .na
146 \fB\fB-n\fR\fR
147 .ad
148 .sp .6
149 .RS 4n
150 Set up the machine for kerberized NFS. This involves making changes to
151 \fBkrb5*\fR security flavors in \fBnfssec.conf\fR(4). This option will also add
152 \fBnfs/fqdn\fR and \fBroot/fqdn\fR entries to the local host's \fBkeytab\fR
153 file if the \fB-K\fR option has not been specified.
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 Specifies the Kerberos realm.
164 .RE
166 .sp
167 .ne 2
168 .na
169 \fB\fB-k\fR \fIkdc_list\fR\fR
170 .ad
171 .sp .6
172 .RS 4n
173 The \fB-k\fR option specifies the KDC host names for the Kerberos client.
174 \fIkdc_list\fR is a comma-separated list of KDCs. If the \fB-m\fR option is not
175 used, it is assumed that the first (or only) host in \fIkdc_list\fR is the
176 master KDC host name. Note that the list specified is used verbatim. This is
177 helpful when specifying non-fully qualified KDC host names that can be
178 canonicalized by DNS.
179 .RE
181 .sp
182 .ne 2
183 .na
184 \fB\fB-a\fR [ \fIadminuser\fR ]\fR
185 .ad
186 .sp .6
187 .RS 4n
188 Specifies the Kerberos administrative user.
189 .RE
191 .sp
192 .ne 2
193 .na
194 \fB\fB-T\fR \fIkdc_vendor\fR\fR
195 .ad
196 .sp .6
197 .RS 4n
198 Configure the Kerberos client to associate with a third party server. Valid
199 \fIkdc_vendor\fR currently supported are:
200 .sp
201 .ne 2
202 .na
203 \fB\fBms_ad\fR\fR
204 .ad
205 .sp .6
206 .RS 4n
207 Microsoft Active Directory
208 .RE
210 .sp
211 .ne 2
212 .na
213 \fB\fBmit\fR\fR
214 .ad
215 .sp .6
216 .RS 4n
217 MIT KDC server
218 .RE
220 .sp
221 .ne 2
222 .na
223 \fB\fBheimdal\fR\fR
224 .ad
225 .sp .6
226 .RS 4n
227 Heimdal KDC server
228 .RE
230 .sp
231 .ne 2
232 .na
233 \fB\fBshishi\fR\fR
234 .ad
235 .sp .6
236 .RS 4n
237 Shishi KDC server
238 .RE
240 Knowing the administrative password will be required to associate the client
241 with the server if the \fBms_ad\fR option is specified.
242 .RE
244 .sp
245 .ne 2
246 .na
247 \fB\fB-c\fR [ \fIfilepath\fR ]\fR
248 .ad
249 .sp .6
250 .RS 4n
251 Specifies the pathname to the \fBkrb5.conf\fR(4) master file, to be copied over
252 to the local host. The path specified normally points to a master copy on a
253 remote host and brought over to the local host by means of NFS.
254 .RE
256 .sp
257 .ne 2
258 .na
259 \fB\fB-d\fR [ \fIdnsarg\fR ]\fR
260 .ad
261 .sp .6
262 .RS 4n
263 Specifies the DNS lookup option to be used and specified in the
264 \fBkrb5.conf\fR(4) file. Valid \fIdnsarg\fR entries are: \fBnone\fR,
265 \fBdns_lookup_kdc\fR, \fBdns_lookup_realm\fR and \fBdns_fallback\fR. Any other
266 entry is considered invalid. The latter three \fIdnsarg\fR values assume the
267 same meaning as those described in \fBkrb5.conf\fR. \fBdns_lookup_kdc\fR
268 implies DNS lookups for the KDC and the other servers. \fBdns_lookup_realm\fR
269 is for host/domain name-to-realm mapping by means of DNS. \fBdns_fallback\fR is
270 a superset and does DNS lookups for both the servers and the host/domain
271 name-to-realm mapping. A lookup option of \fBnone\fR specifies that DNS is not
272 be used for any kind of mapping lookup.
273 .RE
275 .sp
276 .ne 2
277 .na
278 \fB\fB-D\fR \fIdomain_list\fR\fR
279 .ad
280 .sp .6
281 .RS 4n
282 Specifies the host and/or domain names to be mapped to the Kerberos client's
283 default realm name. \fIdomain_list\fR is a comma-separated list, for example
284 "\fBexample.com,host1.example.com\fR". If the \fB-D\fR option is not used, then
285 only the client's domain is used for this mapping. For example, if the client
286 is \fBhost1.eng.example.com\fR, then the domain that is mapped to the
287 \fBEXAMPLE.COM\fR realm is \fBexample.com\fR.
288 .RE
290 .sp
291 .ne 2
292 .na
293 \fB\fB-K\fR\fR
294 .ad
295 .sp .6
296 .RS 4n
297 Configure the Kerberos client without service keys, which are usually stored in
298 \fB/etc/krb5/krb5.keytab\fR. This is useful in the following scenarios:
299 .RS +4
300 .TP
301 .ie t \(bu
302 .el o
303 The client IP address is dynamically assigned and therefore does not host
304 Kerberized services.
305 .RE
306 .RS +4
307 .TP
308 .ie t \(bu
309 .el o
310 Client has a static IP address, but does not want to host any Kerberized
311 services.
312 .RE
313 .RS +4
314 .TP
315 .ie t \(bu
316 .el o
317 Client has a static IP address, but the local administrator does not currently
318 have service keys available for the machine. It is expected that, at a later
319 time, these keys will be installed on the machine.
320 .RE
321 .RE
323 .sp
324 .ne 2
325 .na
326 \fB\fB-f\fR [ \fIfqdn_list\fR ]\fR
327 .ad
328 .sp .6
329 .RS 4n
330 This option creates a service principal entry (host/nfs/root) associated with
331 each of the listed fqdn's, if required, and subsequently adds the entries to
332 the local host's \fBkeytab\fR.
333 .sp
334 \fIfqdn_list\fR is a comma-separated list of one or more fully qualified DNS
335 domain names.
336 .sp
337 This option is especially useful in Kerberos realms having systems offering
338 kerberized services, but situated in multiple different DNS domains.
339 .RE
341 .sp
342 .ne 2
343 .na
344 \fB\fB-h\fR \fIlogical_host_name\fR\fR
345 .ad
346 .sp .6
347 .RS 4n
348 Specifies that the Kerberos client is a node in a cluster. The
349 \fIlogical_host_name\fR is the logical host name given to the cluster. The
350 resulting \fB/etc/krb5/krb5.conf\fR and \fB/etc/krb5/krb5.keytab\fR files must
351 be manually copied over to the other members of the cluster.
352 .RE
354 .sp
355 .ne 2
356 .na
357 \fB\fB-m\fR \fImaster_kdc\fR\fR
358 .ad
359 .sp .6
360 .RS 4n
361 This option specifies the master KDC to be used by the Kerberos client.
362 \fImaster_kdc\fR is the host name of the master KDC for the client. If the
363 \fB-m\fR option is not used, then it is assumed that the first KDC host name
364 listed with the \fB-k\fR option is the master KDC.
365 .RE
367 .sp
368 .ne 2
369 .na
370 \fB\fB-p\fR [ \fIprofile\fR ]\fR
371 .ad
372 .sp .6
373 .RS 4n
374 Specifies the profile to be used to enable the reading in of the values of all
375 the parameters required for setup of the machine as a Kerberos client.
376 .sp
377 The profile should have entries in the format:
378 .sp
379 .in +2
380 .nf
381 \fIPARAM\fR \fI<value>\fR
382 .fi
383 .in -2
384 .sp
386 Valid \fIPARAM\fR entries are: \fBREALM\fR, \fBKDC\fR, \fBADMIN\fR,
387 \fBFILEPATH\fR, \fBNFS\fR, \fBDNSLOOKUP\fR, \fBFQDN\fR, \fBNOKEY\fR,
388 \fBNOSOL\fR, \fBLHN\fR, \fBKDCVENDOR\fR, \fBRMAP\fR, \fBMAS\fR, and \fBPAM\fR.
389 .sp
390 These profile entries correspond to the \fB-R\fR [\fIrealm\fR], \fB-k\fR
391 [\fIkdc\fR], \fB-a\fR [\fIadminuser\fR], \fB-c\fR [\fIfilepath\fR], \fB-n\fR,
392 \fB-d\fR [\fIdnsarg\fR], \fB-f\fR [\fIfqdn_list\fR], \fB-K\fR, \fB-h\fR
393 [\fIlogical_host_name\fR], \fB-T\fR [\fIkdc_vendor\fR], \fB-D\fR
394 [\fIdomain_list\fR], \fB-m\fR [\fImaster_kdc\fR], and \fB-s\fR
395 [\fIpam_service\fR] command-line options, respectively. Any other \fIPARAM\fR
396 entry is considered invalid and is ignored.
397 .sp
398 The NFS profile entry can have a value of 0 (do nothing) or 1 (operation is
399 requested). Any other value is considered invalid and is ignored.
400 .sp
401 Keep in mind that the command line options override the \fIPARAM\fR values
402 listed in the profile.
403 .RE
405 .sp
406 .ne 2
407 .na
408 \fB\fB-s\fR \fIpam_service\fR\fR
409 .ad
410 .sp .6
411 .RS 4n
412 Specifies that the PAM service names, listed in \fIpam_service\fR, are
413 authenticated through Kerberos before any other type of authentication. Using
414 this option updates \fBpam.conf\fR(4) to include \fBpam_krb5\fR(5) to existing
415 authentication stacks for the specified service(s) in \fIpam_service\fR. An
416 example of a possible \fIpam_service\fR value is: \fBdtlogin,sshd-kbdint\fR.
417 .RE
419 .SH EXAMPLES
420 .LP
421 \fBExample 1 \fRSetting Up a Kerberos Client Using Command-Line Options
422 .sp
423 .LP
424 To setup a Kerberos client using the \fBclntconfig/admin\fR administrative
425 principal for realm \fB\&'ABC.COM', kdc `example1.com'\fR and that also does
426 kerberized NFS, enter:
428 .sp
429 .in +2
430 .nf
431 # /usr/sbin/kclient -n -R ABC.COM -k example1.com -a clntconfig
432 .fi
433 .in -2
434 .sp
436 .sp
437 .LP
438 Alternatively, to set up a Kerberos client using the \fBclntconfig/admin\fR
439 administrative principal for the realm \fB`EAST.ABC.COM', kdc
440 `example2.east.abc.com'\fR and that also needs service principal(s) created
441 and/or added to the local \fBkeytab\fR for multiple DNS domains, enter:
443 .sp
444 .in +2
445 .nf
446 # /usr/sbin/kclient -n -R EAST.ABC.COM -k example2.east.abc.com \e
447 -f west.abc.com,central.abc.com -a clntconfig
448 .fi
449 .in -2
451 .sp
452 .LP
453 Note that the \fBkrb5\fR administrative principal used by the administrator
454 needs to have only \fBadd\fR, \fBinquire\fR, \fBchange-pwd\fR and \fBmodify\fR
455 privileges (for the principals in the KDC database) in order for the
456 \fBkclient\fR utility to run. A sample \fBkadm5.acl\fR(4) entry is:
458 .sp
459 .in +2
460 .nf
461 clntconfig/admin@ABC.COM acmi
462 .fi
463 .in -2
464 .sp
466 .LP
467 \fBExample 2 \fRSetting Up a Kerberos Client Using the Profile Option
468 .sp
469 .LP
470 To setup a Kerberos client using the \fBclntconfig/admin\fR administrative
471 principal for realm \fB`ABC.COM', kdc `example1.com'\fR and that also copies
472 over the master \fBkrb5.conf\fR from a specified location, enter:
474 .sp
475 .in +2
476 .nf
477 # /usr/sbin/kclient -p /net/example1.com/export/profile.krb5
478 .fi
479 .in -2
480 .sp
482 .sp
483 .LP
484 The contents of \fBprofile.krb5\fR:
486 .sp
487 .in +2
488 .nf
489 REALM ABC.COM
490 KDC example1
491 ADMIN clntconfig
492 FILEPATH /net/example1.com/export/krb5.conf
493 NFS 0
494 DNSLOOKUP none
495 .fi
496 .in -2
497 .sp
499 .LP
500 \fBExample 3 \fRSetting Up a Kerberos Client That Has a Dynamic IP Address
501 .sp
502 .LP
503 In this example a Kerberos client is a DHCP client that has a dynamic IP
504 address. This client does not wish to host any Kerberized services and
505 therefore does not require a \fBkeytab\fR (\fB/etc/krb5/krb5.keytab\fR) file.
507 .sp
508 .LP
509 For this type of client the administrator would issue the following command to
510 configure this machine to be a Kerberos client of the \fBABC.COM\fR realm with
511 the KDC server \fBkdc1.example.com\fR:
513 .sp
514 .in +2
515 .nf
516 # \fB/usr/sbin/kclient -K -R EXAMPLE.COM -k kdc1.example.com\fR
517 .fi
518 .in -2
519 .sp
521 .SH FILES
522 .sp
523 .ne 2
524 .na
525 \fB\fB/etc/krb5/kadm5.acl\fR\fR
526 .ad
527 .sp .6
528 .RS 4n
529 Kerberos access control list (ACL) file.
530 .RE
532 .sp
533 .ne 2
534 .na
535 \fB\fB/etc/krb5/krb5.conf\fR\fR
536 .ad
537 .sp .6
538 .RS 4n
539 Default location for the local host's configuration file.
540 .RE
542 .sp
543 .ne 2
544 .na
545 \fB\fB/etc/krb5/krb5.keytab\fR\fR
546 .ad
547 .sp .6
548 .RS 4n
549 Default location for the local host's \fBkeytab\fR file.
550 .RE
552 .sp
553 .ne 2
554 .na
555 \fB\fB/etc/nfssec.conf\fR\fR
556 .ad
557 .sp .6
558 .RS 4n
559 File listing NFS security modes.
560 .RE
562 .sp
563 .ne 2
564 .na
565 \fB\fB/etc/resolv.conf\fR\fR
566 .ad
567 .sp .6
568 .RS 4n
569 DNS resolver configuration file.
570 .RE
572 .SH ATTRIBUTES
573 .sp
574 .LP
575 See \fBattributes\fR(5) for descriptions of the following attributes:
576 .sp
578 .sp
579 .TS
580 box;
581 c | c
582 l | l .
583 ATTRIBUTE TYPE ATTRIBUTE VALUE
584 _
585 Interface Stability Committed
586 .TE
588 .SH SEE ALSO
589 .sp
590 .LP
591 \fBencrypt\fR(1), \fBksh93\fR(1), \fBldapdelete\fR(1), \fBldapmodify\fR(1),
592 \fBldapsearch\fR(1), \fBdd\fR(1M), \fBsmbadm\fR(1M), \fBkadm5.acl\fR(4),
593 \fBkrb5.conf\fR(4), \fBnfssec.conf\fR(4), \fBpam.conf\fR(4),
594 \fBresolv.conf\fR(4), \fBattributes\fR(5), \fBpam_krb5\fR(5)
595 .SH NOTES
596 .sp
597 .LP
598 \fBfqdn\fR stands for the Fully Qualified Domain Name of the local host. The
599 \fBkclient\fR utility saves copies of both the \fBkrb5.conf\fR(4) and
600 \fBnfssec.conf\fR(4) files to files with corresponding names and \fB\&.sav\fR
601 extensions. The optional copy of the \fBkrb5.conf\fR(4) master file is neither
602 encrypted nor integrity-protected and it takes place over regular NFS.