1 # 2 # CDDL HEADER START 3 # 4 # The contents of this file are subject to the terms of the 5 # Common Development and Distribution License (the "License"). 6 # You may not use this file except in compliance with the License. 7 # 8 # You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 9 # or http://www.opensolaris.org/os/licensing. 10 # See the License for the specific language governing permissions 11 # and limitations under the License. 12 # 13 # When distributing Covered Code, include this CDDL HEADER in each 14 # file and include the License file at usr/src/OPENSOLARIS.LICENSE. 15 # If applicable, add the following below this CDDL HEADER, with the 16 # fields enclosed by brackets "[]" replaced with your own identifying 17 # information: Portions Copyright [yyyy] [name of copyright owner] 18 # 19 # CDDL HEADER END 20 # 21 22 # 23 # Copyright 2008 Sun Microsystems, Inc. All rights reserved. 24 # Use is subject to license terms. 25 # 26 # ident "@(#)README 1.8 08/11/21 SMI" 27 # 28 29 This directory contains a set of tools to set up Kerberos V5 30 environment for testing purposes. This file describes what they 31 are, how to use them, how to install them, etc. 32 33 Krb5tools 34 ========= 35 36 krb5tools includes the following tools currently: 37 38 kdccfg - set up specified host as KDC 39 kdc_clientcfg - set up specified host as KDC client 40 krb5nfscfg - set up specified host for kerberized NFS 41 princadm - create or delete principals 42 kinfo - print Kerberos configuration, principals, 43 cached tickets, and logs, etc. 44 45 These tools can work on either localhost or a remote host. If a host 46 is specified, the requested operation is performed on that host; 47 otherwise, localhost is used. 48 49 For flexibility, each tool focuses on a single task and can be used 50 together. For example, kdc_clientcfg uses an existing KDC and sets 51 up a host as that KDC's client. It is user's responsibility to 52 set up that KDC, That can be done, e.g., by calling kdccfg. 53 54 For another example, krb5nfscfg enables kerverized NFS support on 55 a KDC client. It is user's responsibility to set up that host as 56 a KDC client before calling krb5nfscfg. That can be done, e.g., by 57 calling kdc_clientcfg. 58 59 That is, conceptually, these tools are designed to be stacked atop 60 each other, as illustrated in the diagram below: 61 62 +-----------------+ 63 | krb5nfscfg | 64 +-----------------+ 65 | kdc_clientcfg | 66 +-----------------+ 67 | kdccfg | 68 +-----------------+ 69 70 User are supposed to use these tool from bottom up when setting up 71 a host, and from top down when cleaning up that host. 72 73 74 Synopses and Usages 75 =================== 76 77 All tools (except kinfo) have -s and -c option, which means setup 78 and cleanup, respectively. User should specify either -s or -c 79 to use them; otherwise it is considered as an usage error. 80 81 Below are the detailed description for each tool: 82 83 1) kdccfg 84 85 kdccfg <-s|-c> [-d domain_list] [host] 86 -s set up the host as KDC 87 -c clean up the host with previous KDC configuration 88 -d a comma separated list of additional DNS domains that 89 will be mapped to the same realm. This is optional. 90 It is only needed if the realm contains multiple domains. 91 host the host to be set up as KDC (if -s is specified) or 92 to be clean up (if -c is specified). This is optional. 93 If no host is specified, localhost will be used. 94 95 kdccfg sets up the specified host as KDC. If the host isn't 96 specified, localhost is used. 97 98 To set up KDC, the tool does the following: 99 100 - create /etc/resolv.conf if it doesn't exist 101 - create krb5.conf, kdc.conf, kadm.conf under /etc/krb5 102 - create principal database 103 - create a user principal for database admin 104 - add principals used by kadmin into its keytab 105 - start krb5kdc and kadmin service 106 107 Examples: 108 109 The command below sets up KDC on localhost: 110 111 snake # kdccfg -s 112 113 The command below sets up KDC on a remote host: 114 115 snake # kdccfg -s deadduck 116 117 The command below sets up KDC on localhost (snake.sfbay), and maps 118 not only sfbay.sun.com domain, but also central.sfbay.com, prc.sun.com 119 to ACME.COM realm (the default one). 120 121 snake # kdccfg -s -d central.sfbay.com,prc.sun.com 122 123 2) kdc_clientcfg 124 125 kdc_clientcfg <-s|-c> <-k kdc> [-p princ] ... [host] 126 -s set up the host as Kerberos client 127 -c clean up the host with previous Kerberos client 128 configuration 129 -k kdc KDC server 130 -p princ a principal to be created (if -s is specified) 131 or deleted (if -c is specified). princ argument 132 has the following format: 133 134 principal_name,attr1=value1,attr2=value2,... 135 136 Currently supported attributes include: 137 138 password 139 the password for user principal. This 140 attribute is optional. If it is not 141 specified, the principal will be 142 considered as a service principal. 143 enctype 144 the encryption type of the key for the 145 principal in KDB. This attribute is 146 optional. If it is not specified, for 147 each supported encryptiion type, a key 148 will be generated in KDB 149 150 If the operation is to delete a principal, all 151 attributes associated with that principal are 152 ignored and thus no need to specify them. 153 154 There can be multiple -p options. 155 host the host to be set up as KDC client (if -s is 156 specified) or to be clean up (if -c is specified) 157 This is optional. If no host is specified, 158 localhost will be used. 159 160 kdc_clientcfg sets up the specified host as Kerberos client, using 161 a previously configured KDC. If the host isn't specified, localhost 162 is used. 163 164 To set up KDC client, the tool does the following: 165 166 - synchronize system time with KDC 167 - create /etc/resolv.conf if it doesn't exist 168 - create /etc/krb5.conf 169 - create principals user passed with -p options 170 171 Note that, although it works, there is no need to run kdc_clientcfg 172 on a KDC. A KDC is its own client by nature. If you need to create 173 service principals for the host on which KDC is running, you can use 174 princadm tool. 175 176 Examples: 177 178 The commands below set up a remote host (deadduck) as KDC, and creates 179 a host principal on the remote host. Then it sets up localhost (snake) 180 as KDC client, and creates a user principal and a host principal on 181 localhost (snake): 182 183 snake # kdccfg -s deadduck 184 snake # princadm -s -p host/deadduck.sfbay.sun.com deadduck 185 snake # kdc_clientcfg -s -k deadduck -p test001,password=l1admin \ 186 -p host/snake.sfbay.sun.com 187 188 The command below calls kdc_clientcfg with -c to clean up the setup 189 on localhost in above example. Note it uses -p option to remove 190 principals it created during setup: 191 192 snake # kdc_clientcfg -c -p test001 -p host/snake.sfbay.sun.com 193 194 195 3) krb5nfscfg 196 197 krb5nfscfg <-s|-c> [host] 198 -s set up the host for kerberized NFS 199 -c clean up the host with previous kerberized NFS 200 configuration 201 host the host to be set up for kerberized NFS (if -s is 202 specified) or to be clean up (if -c is specified). 203 This is optional. If no host is specified, localhost 204 will be used. 205 206 This tool sets up kerberized NFS on the specified host. If the host 207 isn't specified, localhost is used. 208 209 To set up NFS support for Kerberos, the tool does the following: 210 211 - modify /etc/nfssec.conf 212 - make sure rpc/gss service is online 213 - create nfs/$fqdn principal, which is needed by nfs service 214 215 Examples: 216 217 The commands below set up a remote host (deadduck) as KDC, and 218 localhost (snake) as KDC client, and enable kerberized NFS on both 219 hosts: 220 221 snake # kdccfg -s deadduck 222 snake # kdc_clientcfg -s -k deadduck -p host/snake.sfbay.sun.com 223 snake # krb5nfscfg -s deadduck 224 snake # krb5nfscfg -s 225 226 4) princadm 227 228 princadm <-s|-c> <-p princ>... [host] 229 -s create principals specified with -p option(s) 230 -c delete principals specified with -p option(s) 231 -p princ a principal to be created (if -s is specified) 232 or deleted (if -c is specified). princ argument 233 has the following format: 234 235 principal_name,attr1=value1,attr2=value2,... 236 237 Currently supported attributes include: 238 239 password 240 the password for user principal. This 241 attribute is optional. If it is not 242 specified, the principal will be 243 considered as a service principal. 244 enctype 245 the encryption type of the key for the 246 principal in KDB. This attribute is 247 optional. If it is not specified, for 248 each supported encryptiion type, a key 249 will be generated in KDB 250 251 If the operation is to delete a principal, all 252 attributes associated with that principal are 253 ignored and thus no need to specify them. 254 255 There can be multiple -p options. 256 host the host for which service principals will be 257 created or deleted. If host is not specified, 258 localhost will be used. 259 260 This tool creates/deletes specified principals in/from krb5 database 261 and/or keytab. The principals are specified with -p options. 262 263 When creating/deleting principals, the tool automatically adds/removes 264 those principals into/from keytab. 265 266 - When creating a principal, if user doesn't provide password for 267 it, the principal will be considered as a service principal. 268 Its keys will be generated automatically by krb5, and the tool 269 will add them into keytab. 270 271 - When deleting a principal, if there are keys for the the 272 principal in keytab, the tool will remove them from keytab. 273 274 Because services principals (including host principal) are host specific, 275 they should only be added into the keytab of the host where those 276 services are running. The tool checks this by comparing host component 277 of user passed service principals with FQDN of the target host (either 278 localhost or the remote host user specified). 279 280 Examples: 281 282 The command below creates nfs/snake.sfbay.sun.com and test001 principals, 283 note the usage of password and enctype attributes. Because 284 nfs/snake.sfbay.sun.com is a service principal, the tool also adds its 285 keys into keytab on localhost. 286 287 snake # princadm -s \ 288 -p nfs/snake.sfbay.sun.com,enctype=aes128-cts-hmac-sha1-96 \ 289 -p test001,password=l1admin,enctype=des-cbc-crc 290 291 The command below deletes nfs/snake.sfbay.sun.com and hx156269 principals. 292 It also removes nfs/snake.sfbay.sun.com from keytab on localhost: 293 294 snake # princadm -c -p nfs/snake.sfbay.sun.com -p hx156269 295 296 The command below creates nfs/deadduck.sfbay.sun.com principal and adds 297 it into keytab on deadduck host: 298 299 snake # princadm -s -p nfs/deadduck.sfbay.sun.com deadduck 300 301 5) kinfo 302 303 kinfo <config | princ | ccache | log | all> [host] 304 config print system configuration information that help 305 to debug setup issues. It includes hostname, OS 306 version, system time, installed packages, DNS 307 setup, and Kerveros configuration information 308 like realm, kdc, and the mapped domains. 309 princ print all principals in Kerberos database. 310 ccache print cached tickets saved in credentials cache file. 311 log print the last 10 lines in /var/krb5/kdc.log if 312 the host is KDC, and the last 10 lines of 313 /var/adm/messages. 314 all print all the above information. 315 316 This tool prints information (ie., configuration, existing principals, 317 cached tickets, error messagesin log files, etc) that helps to debug 318 issues. 319 320 Examples: 321 322 The following command prints system configuration which may help to debug 323 Kerberos issues: 324 325 snake # kinfo config 326 327 The following command prints all principals on KDC: 328 329 snake # kinfo princ 330 331 The following command prints all contents in credentials cache file: 332 333 snake # kinfo ccache 334 335 336 Prerequisites 337 ============= 338 339 Before you use these tools, you need to check the following things: 340 341 1) You can use the tools over the network. A copy of these tools is 342 available in the STC gate under $GATE/proto/tools/krb5tools, where 343 $GATE represents the path to the location of the gate. To use the 344 tools, add the bin subdir into your PATH environment variable. 345 For example: 346 347 # export PATH=/ws/stcnv-gate/proto/tools/krb5tools/bin:$PATH 348 349 You can also install these tools on your host. For installation 350 instructions, see Installation section. 351 352 2) You need to be root to run these tools 353 354 3) If you want to use these tools to configure a remote host, you 355 need to make sure you have rsh or ssh access to that remote 356 host as root. 357 358 Notes: rsh is used by default. If you want to use ssh, you need 359 to set RSH to "ssh". 360 361 To enable rsh access to the remote host, you need to do the 362 following on that remote host: 363 364 - create ~root/.rhosts file on the remote host, which contains a line 365 like "+ +" 366 - comment out "CONSOLE=/dev/console" line in /etc/default/login 367 on that remote host 368 369 To enable ssh access to the remote host, please refer to Appendix 370 A for the detailed steps to do that. 371 372 4) Customize environment variables if necessary. Below are variables 373 used by krb5tools. Among them, the only one you need to check 374 is DNS_SERVER. If you want to output more debug information, 375 you also need to set KRB5TOOLS_DEBUG. For all the others 376 variables, they should just work fine. 377 378 DNS_SERVER - IP address of your dns server. Default value 379 is 129.145.155.226 (only valid within Sun). 380 If that doesn't work for your domain, you 381 need to change it. 382 383 KRB5TOOLS_DEBUG - debugging flag. Default value is 0, which 384 means no debug information. See more details 385 in "How to Debug These Tools" section. 386 387 REALM - kerberos realm. Default value is ACME.COM. 388 389 KDB_PASSWD - master password for krb5 database, used by 390 kdb5_util(1M). Default value is abc123. 391 392 ADMIN_USER - krb5 database administration principal, used 393 by kamdin(1M). Default value is test. 394 395 ADMIN_PASSWD - password for $ADMIN_USER. Default value is 396 abc123. 397 398 TMPDIR - directory to place temporary files. Default 399 value is /usr/tmp. 400 401 RSH - remote shell to use. Valid values are "rsh" and 402 "ssh". Default value is "rsh". 403 404 5) These tools need to get FQDN for the host they run on or they 405 try to set up. So it is recommended that all hosts should have 406 reverse DNS lookup. If this can't be satisfied, then user needs 407 pass FQDN for the remote host, for example: 408 409 # kdccfg -s cruse.prc.sun.com. 410 411 Note the trailing dot, this is required so that tools can detect 412 that a FQDN is passed. 413 414 If the host to be set up is localhost, then just call these tools 415 as usual, for example: 416 417 # kdccfg -s 418 419 In this case, the tool will use NIS domainname to try to generate 420 a valid FQDN for localhost. 421 422 423 How to Debug 424 ============ 425 426 By default, all tools print out error messages for diagnosis if 427 something went wrong. In most cases, these message should be enough 428 to help users to find the cause for failures. 429 430 In some cases, however, if those information is not enough, or if 431 one needs to debug the tools themselves, one can set KRB5TOOLS_DEBUG 432 environment variable before running these tools. Currently this 433 variable can have three values: 434 435 0 - no debugging information. This is the default value. 436 1 - print some debugging information. This help to identify what 437 went wrong quickly. 438 2 - print all debugging information. The output is very verbose. 439 440 441 Installation 442 ============ 443 444 You can install the tools on your localhost, using the following 445 steps: 446 447 # pkgadd -d <package location> SUNWstc-krb5tools 448 449 The default installation location is /opt/SUNWstc-krb5tools. To use the 450 tools from this location, add /opt/SUNWstc-krb5tools/bin to your PATH 451 environment variable: 452 453 # export PATH=$PATH:/opt/SUNWstc-krb5tools/bin 454 455 456 Building Tools from Source 457 ========================== 458 459 The krb5tools package can be built from source. To do this, place the 460 the source code in an STC workspace and invoke 'stf_build'. An example 461 build recipe: 462 463 # cd <WS_ROOT>/usr/src/tools/krb5tools 464 # stf_build package 465 466 where <WS_ROOT> represents the root of the STC workspace being built. 467 'stf_build' is part of the SUNWstc-stf package. These commands will 468 create an installable package directory at 469 <WS_ROOT>/packages/`uname -p`/SUNWstc-krb5tools 470 which can be installed as described in the "Installation" section above. 471 472 473 Appendix A: How to Set Up Password-less SSH Access for Root 474 =========================================================== 475 476 1) generate RSA authentication keys for root on localhost, keep 477 pressing Return key when prompted 478 479 localhost# ssh-keygen -t rsa 480 481 This will generate public key in ~root/.ssh/id_rsa.pub and private 482 key in ~root/.ssh/id_rsa. 483 484 2) add the root's public key in ~root/.ssh/authorized_keys on the remote 485 host 486 487 a) transfer ~root/.ssh/id_rsa.pub on localhost to the remote host. 488 Suppose it is saved under /tmp. 489 490 b) add public key contained in that file into ~root/.ssh/authorized_keys 491 492 remotehost# cat >> ~root/.ssh/authorized_keys < /tmp/id_rsa.pub 493 494 c) make sure ~root/.ssh/authorized_keys file permission is 644. 495 496 3) modify /etc/ssh/sshd_config on remote host to allow public key 497 authentication for root. The line for PermitRootLogin should be 498 like the following: 499 500 remotehost# grep "^PermitRootLogin" /etc/ssh/sshd_config 501 PermitRootLogin without-password 502 503 4) start ssh-agent on localhost host and call ssh-add to load root's 504 private key 505 506 localhost# [[ -n $SSH_AUTH_SOCK ]] && ssh-agent -k 507 localhost# eval `ssh-agent -s` 508 localhost# ssh-add 509 510 use the following command to verify the key has been loaded 511 successfully. 512 513 localhost# ssh-add -l 514 515 5) get public key of the remote host and save it into ~root/.ssh/known_hosts 516 on localhost. This is done automatically when you connect to 517 the remote host via SSH for the first time. Type "yes" and press 518 Return key when prompted. 519 520 localhost# ssh dubya 521 The authenticity of host 'dubya (10.4.196.208)' can't be established. 522 RSA key fingerprint is 09:53:a6:16:6f:1b:49:38:ca:06:63:6e:16:ef:c7:69. 523 Are you sure you want to continue connecting (yes/no)? yes 524 Warning: Permanently added 'dubya,10.4.196.208' (RSA) to the list of 525 known hosts. 526 Last login: Thu Mar 8 21:23:44 2007 from assassin 527 Sun Microsystems Inc. SunOS 5.11 snv_59 October 2007 528 # 529 530 Note: the host key for remote host may change if it is reinstalled. 531 In that event, the one cached in ~root/.ssh/known_hosts on localhost is 532 stale and the above ssh command will fail, printing a diagnostic 533 message. 534 535 If the diagnostic message indicates that the failure may be related 536 to a changed host key, you can remove the line for the remote machine 537 from ~root/.ssh/known_hosts and try ssh command again. 538 539 6) now everything is done and you should be able to ssh the remote 540 host as root. 541 542 localhost# ssh dubya 543 Last login: Thu Mar 8 22:34:43 2007 from assassin 544 Sun Microsystems Inc. SunOS 5.11 snv_59 October 2007 545 # 546
Indexes created Thu Nov 26 20:23:21 UTC 2009
Terms of Use |
Privacy |
Trademarks |
Copyright Policy |
Site Guidelines |
Help
Your use of this web site or any of its content or software indicates your agreement to be bound by these Terms of Use.
Copyright © 1995-2008 Sun Microsystems, Inc.