doc/xml/AdminGuide/c20494.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <HTML
   3 ><HEAD
   4 ><TITLE
   5 >Managing Server Encryption Keys</TITLE
   6 ><META
   7 NAME="GENERATOR"
   8 CONTENT="Modular DocBook HTML Stylesheet Version 1.7"><LINK
   9 REL="HOME"
  10 TITLE="AFS Administration Guide"
  11 HREF="book1.html"><LINK
  12 REL="UP"
  13 TITLE="Managing File Server Machines"
  14 HREF="p3023.html"><LINK
  15 REL="PREVIOUS"
  16 TITLE="Monitoring and Auditing AFS Performance"
  17 HREF="c18360.html"><LINK
  18 REL="NEXT"
  19 TITLE="Managing Client Machines"
  20 HREF="p21471.html"></HEAD
  21 ><BODY
  22 CLASS="chapter"
  23 BGCOLOR="#FFFFFF"
  24 TEXT="#000000"
  25 LINK="#0000FF"
  26 VLINK="#840084"
  27 ALINK="#0000FF"
  28 ><DIV
  29 CLASS="NAVHEADER"
  30 ><TABLE
  31 SUMMARY="Header navigation table"
  32 WIDTH="100%"
  33 BORDER="0"
  34 CELLPADDING="0"
  35 CELLSPACING="0"
  36 ><TR
  37 ><TH
  38 COLSPAN="3"
  39 ALIGN="center"
  40 >AFS Administration Guide: Version 3.6</TH
  41 ></TR
  42 ><TR
  43 ><TD
  44 WIDTH="10%"
  45 ALIGN="left"
  46 VALIGN="bottom"
  47 ><A
  48 HREF="c18360.html"
  49 ACCESSKEY="P"
  50 >Prev</A
  51 ></TD
  52 ><TD
  53 WIDTH="80%"
  54 ALIGN="center"
  55 VALIGN="bottom"
  56 ></TD
  57 ><TD
  58 WIDTH="10%"
  59 ALIGN="right"
  60 VALIGN="bottom"
  61 ><A
  62 HREF="p21471.html"
  63 ACCESSKEY="N"
  64 >Next</A
  65 ></TD
  66 ></TR
  67 ></TABLE
  68 ><HR
  69 ALIGN="LEFT"
  70 WIDTH="100%"></DIV
  71 ><DIV
  72 CLASS="chapter"
  73 ><H1
  74 ><A
  75 NAME="HDRWQ355"
  76 ></A
  77 >Chapter 9. Managing Server Encryption Keys</H1
  78 ><P
  79 >This chapter explains how to maintain your cell's server encryption keys, which are vital for secure communications in
  80   AFS.</P
  81 ><DIV
  82 CLASS="sect1"
  83 ><H1
  84 CLASS="sect1"
  85 ><A
  86 NAME="HDRWQ356"
  87 >Summary of Instructions</A
  88 ></H1
  89 ><P
  90 >This chapter explains how to perform the following tasks by using the indicated commands:</P
  91 ><DIV
  92 CLASS="informaltable"
  93 ><A
  94 NAME="AEN20500"
  95 ></A
  96 ><TABLE
  97 BORDER="0"
  98 FRAME="void"
  99 CLASS="CALSTABLE"
 100 ><COL
 101 WIDTH="70*"><COL
 102 WIDTH="30*"><TBODY
 103 ><TR
 104 ><TD
 105 >Add a new server encryption key</TD
 106 ><TD
 107 ><SPAN
 108 CLASS="bold"
 109 ><B
 110 CLASS="emphasis"
 111 >bos addkey</B
 112 ></SPAN
 113 > and <SPAN
 114 CLASS="bold"
 115 ><B
 116 CLASS="emphasis"
 117 >kas setpassword</B
 118 ></SPAN
 119 ></TD
 120 ></TR
 121 ><TR
 122 ><TD
 123 >Inspect key checksums in the Authentication Database</TD
 124 ><TD
 125 ><SPAN
 126 CLASS="bold"
 127 ><B
 128 CLASS="emphasis"
 129 >kas examine</B
 130 ></SPAN
 131 ></TD
 132 ></TR
 133 ><TR
 134 ><TD
 135 >Inspect key checksums in the <SPAN
 136 CLASS="bold"
 137 ><B
 138 CLASS="emphasis"
 139 >KeyFile</B
 140 ></SPAN
 141 ></TD
 142 ><TD
 143 ><SPAN
 144 CLASS="bold"
 145 ><B
 146 CLASS="emphasis"
 147 >bos listkeys</B
 148 ></SPAN
 149 ></TD
 150 ></TR
 151 ><TR
 152 ><TD
 153 >Remove an old server encryption key</TD
 154 ><TD
 155 ><SPAN
 156 CLASS="bold"
 157 ><B
 158 CLASS="emphasis"
 159 >bos removekey</B
 160 ></SPAN
 161 ></TD
 162 ></TR
 163 ></TBODY
 164 ></TABLE
 165 ></DIV
 166 ></DIV
 167 ><DIV
 168 CLASS="sect1"
 169 ><H1
 170 CLASS="sect1"
 171 ><A
 172 NAME="HDRWQ358"
 173 >About Server Encryption Keys</A
 174 ></H1
 175 ><P
 176 >An encryption key is a string of octal numbers used to encrypt and decrypt packets of information. In AFS, a server
 177     encryption key is the key used to protect information being transferred between AFS server processes and between them and their
 178     clients. A server encryption key is essentially a password for a server process and like a user password is stored in the
 179     Authentication Database.</P
 180 ><P
 181 >Maintaining your cell's server encryption keys properly is the most basic way to protect the information in your AFS
 182     filespace from access by unauthorized users.</P
 183 ><DIV
 184 CLASS="sect2"
 185 ><H2
 186 CLASS="sect2"
 187 ><A
 188 NAME="Header_412"
 189 >Keys and Mutual Authentication: A Review</A
 190 ></H2
 191 ><P
 192 >Server encryption keys play a central role in the mutual authentication between client and server processes in AFS. For
 193       a more detailed description of mutual authentication, see <A
 194 HREF="c667.html#HDRWQ75"
 195 >A More Detailed Look at Mutual
 196       Authentication</A
 197 >.</P
 198 ><P
 199 >When a client wants to contact an AFS server, it first contacts the Ticket Granting Service (TGS) module of the
 200       Authentication Server. After verifying the client's identity (based indirectly on the password of the human user whom the
 201       client represents), the TGS gives the client a server ticket. This ticket is encrypted with the server's encryption key. (The
 202       TGS also invents a second encryption key, called the session key, to be used only for a single episode of communication
 203       between server and client. The server ticket and session key, together with other pieces of information, are collectively
 204       referred to as a token.)</P
 205 ><P
 206 >The client cannot read the server ticket or token because it does not know the server encryption key. However, the
 207       client sends it to the AFS server along with service requests, because the ticket proves to the AFS server processes that it
 208       has already authenticated with the TGS. AFS servers trust the TGS to grant tickets only to valid clients. The fact that the
 209       client possesses a ticket encrypted with the server's encryption key proves to the server that the client is valid. On the
 210       other hand, the client assumes that only a genuine AFS server knows the server encryption key needed to decrypt the ticket.
 211       The server's ability to decrypt the ticket and understand its contents proves to the client that the server is
 212       legitimate.</P
 213 ></DIV
 214 ><DIV
 215 CLASS="sect2"
 216 ><H2
 217 CLASS="sect2"
 218 ><A
 219 NAME="Header_413"
 220 >Maintaining AFS Server Encryption Keys</A
 221 ></H2
 222 ><P
 223 >As you maintain your cell's server encryption keys, keep the following in mind. <UL
 224 ><LI
 225 ><P
 226 >Change the key frequently to enhance your cell's security. Changing the key at least once a month is strongly
 227             recommended.</P
 228 ></LI
 229 ><LI
 230 ><P
 231 >The AFS server encryption key currently in use is stored in two places. When you add a new key, you must make
 232             changes in both places and make them in the correct order, as instructed in <A
 233 HREF="c20494.html#HDRWQ362"
 234 >Adding Server
 235             Encryption Keys</A
 236 >. Failure to follow the instructions can seriously impair cell functioning, as clients and servers
 237             become unable to communicate. The two storage sites for the current server encryption key are the following:
 238             <OL
 239 TYPE="1"
 240 ><LI
 241 ><P
 242 >The file <SPAN
 243 CLASS="bold"
 244 ><B
 245 CLASS="emphasis"
 246 >/usr/afs/etc/KeyFile</B
 247 ></SPAN
 248 > on the local disk of every file server
 249                   machine. The file can list more than one key, each with an associated numerical identifier, the key version number
 250                   or kvno. A client token records the key version number of the key used to seal it, and the server process
 251                   retrieves the appropriate key from this file when the client presents the token.</P
 252 ></LI
 253 ><LI
 254 ><P
 255 >The <SPAN
 256 CLASS="bold"
 257 ><B
 258 CLASS="emphasis"
 259 >afs</B
 260 ></SPAN
 261 > entry in the Authentication Database. The current server encryption
 262                   key is in the entry's password field, just like an individual user's scrambled password. The Authentication
 263                   Server's Ticket Granting Service (TGS) uses this key to encrypt the tokens it gives to clients. There is only a
 264                   single key in the entry, because the TGS never needs to read existing tokens, but only to generate new ones by
 265                   using the current key.</P
 266 ></LI
 267 ></OL
 268 ></P
 269 ><P
 270 >For instructions on creating the initial <SPAN
 271 CLASS="bold"
 272 ><B
 273 CLASS="emphasis"
 274 >afs</B
 275 ></SPAN
 276 > entry and <SPAN
 277 CLASS="bold"
 278 ><B
 279 CLASS="emphasis"
 280 >KeyFile</B
 281 ></SPAN
 282 > files as you install your cell's first server machine, see the IBM AFS Quick
 283             Beginnings.</P
 284 ></LI
 285 ><LI
 286 ><P
 287 >At any specific time, the tokens that the Authentication Server's Ticket Granting Service gives to clients are
 288             sealed with only one of the server encryption keys, namely the one stored in the <SPAN
 289 CLASS="bold"
 290 ><B
 291 CLASS="emphasis"
 292 >afs</B
 293 ></SPAN
 294 >
 295             entry in the Authentication Database.</P
 296 ></LI
 297 ><LI
 298 ><P
 299 >When you add a new server encryption key, you cannot immediately remove the former key from the <SPAN
 300 CLASS="bold"
 301 ><B
 302 CLASS="emphasis"
 303 >/usr/afs/etc/KeyFile</B
 304 ></SPAN
 305 > file on the local disk of every AFS server machine. Any time that you add a
 306             new key, it is likely that some clients still have valid, unexpired tokens sealed with the previous key. The more
 307             frequently you change the server encryption key, the more such tickets there are likely to be. To be able to grant
 308             service appropriately to clients with such tokens, an AFS server process must still be able to access the server
 309             encryption key used to seal it.</P
 310 ><P
 311 >You can safely delete an old server encryption key only when it is certain that no clients have tokens sealed with
 312             that key. In general, wait a period of time at least as long as the maximum token lifetime in your cell. By default, the
 313             maximum token lifetime for users is 25 hours (except for users whose Authentication Database entries were created by
 314             using the 3.0 version of AFS, for whom the default is 100 hours). You can use the <SPAN
 315 CLASS="bold"
 316 ><B
 317 CLASS="emphasis"
 318 >-lifetime</B
 319 ></SPAN
 320 > argument to the <SPAN
 321 CLASS="bold"
 322 ><B
 323 CLASS="emphasis"
 324 >kas setfields</B
 325 ></SPAN
 326 > command to change this
 327             default.</P
 328 ><P
 329 >Instructions for removing obsolete keys appear in <A
 330 HREF="c20494.html#HDRWQ368"
 331 >Removing Server Encryption
 332             Keys</A
 333 >.</P
 334 ></LI
 335 ><LI
 336 ><P
 337 >You create a new AFS server encryption key in much the same way regular users change their passwords, by providing
 338             a character string that is converted into an encryption key automatically. See <A
 339 HREF="c20494.html#HDRWQ362"
 340 >Adding Server
 341             Encryption Keys</A
 342 >.</P
 343 ></LI
 344 ><LI
 345 ><P
 346 >In addition to using server encryption keys when communicating with clients, the server processes use them to
 347             protect communications with other server processes. Therefore, all server machines in your cell must have the same
 348             version of the <SPAN
 349 CLASS="bold"
 350 ><B
 351 CLASS="emphasis"
 352 >KeyFile</B
 353 ></SPAN
 354 > file. The easiest way to maintain consistency (if you run the
 355             United States edition of AFS) is to use the Update Server to distribute the contents of the system control machine's
 356             <SPAN
 357 CLASS="bold"
 358 ><B
 359 CLASS="emphasis"
 360 >/usr/afs/etc</B
 361 ></SPAN
 362 > directory to all of the other server machines. There are two implications:
 363             <UL
 364 ><LI
 365 ><P
 366 >You must run the <SPAN
 367 CLASS="bold"
 368 ><B
 369 CLASS="emphasis"
 370 >upserver</B
 371 ></SPAN
 372 > process on the system control machine and an
 373                   <SPAN
 374 CLASS="bold"
 375 ><B
 376 CLASS="emphasis"
 377 >upclientetc</B
 378 ></SPAN
 379 > process on all other server machines that references the system
 380                   control machine. The IBM AFS Quick Beginnings explains how to install both processes. For instructions on
 381                   verifying that the Update Server processes are running, see <A
 382 HREF="c6449.html#HDRWQ158"
 383 >Displaying Process Status and
 384                   Information from the BosConfig File</A
 385 >.</P
 386 ></LI
 387 ><LI
 388 ><P
 389 >Change the <SPAN
 390 CLASS="bold"
 391 ><B
 392 CLASS="emphasis"
 393 >KeyFile</B
 394 ></SPAN
 395 > file only on the system control machine (except in the
 396                   types of emergencies discussed in <A
 397 HREF="c20494.html#HDRWQ370"
 398 >Handling Server Encryption Key Emergencies</A
 399 >). Any
 400                   changes you make on other server machines are overwritten the next time the <SPAN
 401 CLASS="bold"
 402 ><B
 403 CLASS="emphasis"
 404 >upclientetc</B
 405 ></SPAN
 406 > process retrieves the contents of the system control machine's <SPAN
 407 CLASS="bold"
 408 ><B
 409 CLASS="emphasis"
 410 >/usr/afs/etc</B
 411 ></SPAN
 412 > directory. By default, this happens every five minutes.</P
 413 ></LI
 414 ></UL
 415 ></P
 416 ><P
 417 >If you run the international edition of AFS, do not use the Update Server to distribute the contents of the
 418             <SPAN
 419 CLASS="bold"
 420 ><B
 421 CLASS="emphasis"
 422 >/usr/afs/etc</B
 423 ></SPAN
 424 > directory, particularly the <SPAN
 425 CLASS="bold"
 426 ><B
 427 CLASS="emphasis"
 428 >KeyFile</B
 429 ></SPAN
 430 > file.
 431             The data in the file is too sensitive for transfer in unencrypted form, and because of United States government exports
 432             regulations the international edition of AFS does not include the necessary encryption routines in a form that the
 433             Update Server can use. You must instead modify the file on each server machine individually, taking care to enter the
 434             same key on every server machine.</P
 435 ></LI
 436 ><LI
 437 ><P
 438 >Never edit the <SPAN
 439 CLASS="bold"
 440 ><B
 441 CLASS="emphasis"
 442 >KeyFile</B
 443 ></SPAN
 444 > directly with a text editor. Instead, always use the
 445             appropriate <SPAN
 446 CLASS="bold"
 447 ><B
 448 CLASS="emphasis"
 449 >bos</B
 450 ></SPAN
 451 > commands as instructed in <A
 452 HREF="c20494.html#HDRWQ362"
 453 >Adding Server
 454             Encryption Keys</A
 455 > and <A
 456 HREF="c20494.html#HDRWQ368"
 457 >Removing Server Encryption Keys</A
 458 >.</P
 459 ></LI
 460 ></UL
 461 ></P
 462 ></DIV
 463 ></DIV
 464 ><DIV
 465 CLASS="sect1"
 466 ><H1
 467 CLASS="sect1"
 468 ><A
 469 NAME="HDRWQ359"
 470 >Displaying Server Encryption Keys</A
 471 ></H1
 472 ><P
 473 >To display the server encryption keys in the <SPAN
 474 CLASS="bold"
 475 ><B
 476 CLASS="emphasis"
 477 >/usr/afs/etc/KeyFile</B
 478 ></SPAN
 479 > file on any file server
 480     machine, use the <SPAN
 481 CLASS="bold"
 482 ><B
 483 CLASS="emphasis"
 484 >bos listkeys</B
 485 ></SPAN
 486 > command. Use the <SPAN
 487 CLASS="bold"
 488 ><B
 489 CLASS="emphasis"
 490 >kas examine</B
 491 ></SPAN
 492 >
 493     command to display the key in the Authentication Database's <SPAN
 494 CLASS="bold"
 495 ><B
 496 CLASS="emphasis"
 497 >afs</B
 498 ></SPAN
 499 > entry.</P
 500 ><P
 501 >By default the commands do not display the actual string of octal digits that constitute a key, but rather a checksum, a
 502     decimal number derived by encrypting a constant with the key. This prevents unauthorized users from easily accessing the actual
 503     key, which they can then use to falsify or eavesdrop on protected communications. The <SPAN
 504 CLASS="bold"
 505 ><B
 506 CLASS="emphasis"
 507 >bos
 508     listkeys</B
 509 ></SPAN
 510 > and <SPAN
 511 CLASS="bold"
 512 ><B
 513 CLASS="emphasis"
 514 >kas examine</B
 515 ></SPAN
 516 > commands generate the same checksum for a given key, so
 517     displaying checksums rather than actual keys is generally sufficient. If you suspect that the keys differ in a way that the
 518     checksums are not revealing, then you are probably experiencing authentication problems throughout your cell. The easiest
 519     solution is to create a new server encryption key following the instructions in <A
 520 HREF="c20494.html#HDRWQ362"
 521 >Adding Server
 522     Encryption Keys</A
 523 > or <A
 524 HREF="c20494.html#HDRWQ370"
 525 >Handling Server Encryption Key Emergencies</A
 526 >. Another common reason to
 527     issue the <SPAN
 528 CLASS="bold"
 529 ><B
 530 CLASS="emphasis"
 531 >bos listkeys</B
 532 ></SPAN
 533 > command is to display the key version numbers currently in use, in
 534     preparation for choosing the next one; here, the checksum is sufficient because the key itself is irrelevant.</P
 535 ><P
 536 >If it is important to display the actual octal digits, include the <SPAN
 537 CLASS="bold"
 538 ><B
 539 CLASS="emphasis"
 540 >-showkey</B
 541 ></SPAN
 542 > argument to
 543     both the <SPAN
 544 CLASS="bold"
 545 ><B
 546 CLASS="emphasis"
 547 >bos listkeys</B
 548 ></SPAN
 549 > and <SPAN
 550 CLASS="bold"
 551 ><B
 552 CLASS="emphasis"
 553 >kas examine</B
 554 ></SPAN
 555 > commands.</P
 556 ><DIV
 557 CLASS="sect2"
 558 ><H2
 559 CLASS="sect2"
 560 ><A
 561 NAME="HDRWQ360"
 562 >To display the KeyFile file</A
 563 ></H2
 564 ><OL
 565 TYPE="1"
 566 ><LI
 567 ><P
 568 >Verify that you are authenticated as a user listed in the <SPAN
 569 CLASS="bold"
 570 ><B
 571 CLASS="emphasis"
 572 >/usr/afs/etc/UserList</B
 573 ></SPAN
 574 >
 575           file. If necessary, issue the <SPAN
 576 CLASS="bold"
 577 ><B
 578 CLASS="emphasis"
 579 >bos listusers</B
 580 ></SPAN
 581 > command, which is fully described in <A
 582 HREF="c32432.html#HDRWQ593"
 583 >To display the users in the UserList file</A
 584 >. <PRE
 585 CLASS="programlisting"
 586 >&#13;   % <SPAN
 587 CLASS="bold"
 588 ><B
 589 CLASS="emphasis"
 590 >bos listusers</B
 591 ></SPAN
 592 > &#60;<VAR
 593 CLASS="replaceable"
 594 >machine name</VAR
 595 >&#62;
 596 </PRE
 597 ></P
 598 ></LI
 599 ><LI
 600 ><P
 601 >Issue the <SPAN
 602 CLASS="bold"
 603 ><B
 604 CLASS="emphasis"
 605 >bos listkeys</B
 606 ></SPAN
 607 > command to display the contents of one machine's <SPAN
 608 CLASS="bold"
 609 ><B
 610 CLASS="emphasis"
 611 >/usr/afs/etc/KeyFile</B
 612 ></SPAN
 613 > file. <PRE
 614 CLASS="programlisting"
 615 >&#13;   % <SPAN
 616 CLASS="bold"
 617 ><B
 618 CLASS="emphasis"
 619 >bos listkeys</B
 620 ></SPAN
 621 > &#60;<VAR
 622 CLASS="replaceable"
 623 >machine name</VAR
 624 >&#62; [<SPAN
 625 CLASS="bold"
 626 ><B
 627 CLASS="emphasis"
 628 >-showkey</B
 629 ></SPAN
 630 >]
 631 </PRE
 632 ></P
 633 ><P
 634 >where <DIV
 635 CLASS="variablelist"
 636 ><DL
 637 ><DT
 638 ><SPAN
 639 CLASS="bold"
 640 ><B
 641 CLASS="emphasis"
 642 >listk</B
 643 ></SPAN
 644 ></DT
 645 ><DD
 646 ><P
 647 >Is the shortest acceptable abbreviation of <SPAN
 648 CLASS="bold"
 649 ><B
 650 CLASS="emphasis"
 651 >listkeys</B
 652 ></SPAN
 653 >.</P
 654 ></DD
 655 ><DT
 656 ><SPAN
 657 CLASS="bold"
 658 ><B
 659 CLASS="emphasis"
 660 >machine name</B
 661 ></SPAN
 662 ></DT
 663 ><DD
 664 ><P
 665 >Names a file server machine. In the normal case, it is acceptable to name any machine, because correct cell
 666                   functioning requires that the <SPAN
 667 CLASS="bold"
 668 ><B
 669 CLASS="emphasis"
 670 >KeyFile</B
 671 ></SPAN
 672 > file be the same on all of them.</P
 673 ></DD
 674 ><DT
 675 ><SPAN
 676 CLASS="bold"
 677 ><B
 678 CLASS="emphasis"
 679 >-showkey</B
 680 ></SPAN
 681 ></DT
 682 ><DD
 683 ><P
 684 >Displays the octal digits that constitute each key.</P
 685 ></DD
 686 ></DL
 687 ></DIV
 688 ></P
 689 ></LI
 690 ></OL
 691 ><P
 692 >In the following example, the output displays a checksum for each server encryption key rather than the actual octal
 693       digits. The penultimate line indicates when an administrator last changed the file, and the final line confirms that the
 694       output is complete.</P
 695 ><PRE
 696 CLASS="programlisting"
 697 >&#13;   % <SPAN
 698 CLASS="bold"
 699 ><B
 700 CLASS="emphasis"
 701 >bos listkeys fs1.abc.com</B
 702 ></SPAN
 703 >
 704    key 0 has cksum 972037177
 705    key 1 has cksum 2825165022
 706    Keys last changed on Wed Jan 13 11:20:29 1999.
 707    All done.
 708 </PRE
 709 ></DIV
 710 ><DIV
 711 CLASS="sect2"
 712 ><H2
 713 CLASS="sect2"
 714 ><A
 715 NAME="HDRWQ361"
 716 >To display the afs key from the Authentication Database</A
 717 ></H2
 718 ><OL
 719 TYPE="1"
 720 ><LI
 721 ><P
 722 >Issue the <SPAN
 723 CLASS="bold"
 724 ><B
 725 CLASS="emphasis"
 726 >kas examine</B
 727 ></SPAN
 728 > command to display the <SPAN
 729 CLASS="bold"
 730 ><B
 731 CLASS="emphasis"
 732 >afs</B
 733 ></SPAN
 734 >
 735           entry in the Authentication Database.</P
 736 ><P
 737 >The Authentication Server performs its own authentication rather than accepting your existing AFS token. By default,
 738           it authenticates your local (UNIX) identity, which possibly does not correspond to an AFS-privileged administrator.
 739           Include the <SPAN
 740 CLASS="bold"
 741 ><B
 742 CLASS="emphasis"
 743 >-admin</B
 744 ></SPAN
 745 > argument to name an identity that has the
 746           <SAMP
 747 CLASS="computeroutput"
 748 >ADMIN</SAMP
 749 > flag on its Authentication Database entry. To verify that an entry has the flag,
 750           issue the <SPAN
 751 CLASS="bold"
 752 ><B
 753 CLASS="emphasis"
 754 >kas examine</B
 755 ></SPAN
 756 > command as described in <A
 757 HREF="c32432.html#HDRWQ590"
 758 >To check if the
 759           ADMIN flag is set</A
 760 >.</P
 761 ><PRE
 762 CLASS="programlisting"
 763 >&#13;   % <SPAN
 764 CLASS="bold"
 765 ><B
 766 CLASS="emphasis"
 767 >kas examine afs</B
 768 ></SPAN
 769 > [<SPAN
 770 CLASS="bold"
 771 ><B
 772 CLASS="emphasis"
 773 >-showkey</B
 774 ></SPAN
 775 >]  \
 776                  <SPAN
 777 CLASS="bold"
 778 ><B
 779 CLASS="emphasis"
 780 >-admin</B
 781 ></SPAN
 782 >  &#60;<VAR
 783 CLASS="replaceable"
 784 >admin principal to use for authentication</VAR
 785 >&#62;
 786    Administrator's (admin_user) password: &#60;<VAR
 787 CLASS="replaceable"
 788 >admin_password</VAR
 789 >&#62;
 790 </PRE
 791 ><P
 792 >where <DIV
 793 CLASS="variablelist"
 794 ><DL
 795 ><DT
 796 ><SPAN
 797 CLASS="bold"
 798 ><B
 799 CLASS="emphasis"
 800 >e</B
 801 ></SPAN
 802 ></DT
 803 ><DD
 804 ><P
 805 >Is the shortest acceptable abbreviation of <SPAN
 806 CLASS="bold"
 807 ><B
 808 CLASS="emphasis"
 809 >examine</B
 810 ></SPAN
 811 >.</P
 812 ></DD
 813 ><DT
 814 ><SPAN
 815 CLASS="bold"
 816 ><B
 817 CLASS="emphasis"
 818 >afs</B
 819 ></SPAN
 820 ></DT
 821 ><DD
 822 ><P
 823 >Designates the <SPAN
 824 CLASS="bold"
 825 ><B
 826 CLASS="emphasis"
 827 >afs</B
 828 ></SPAN
 829 > entry.</P
 830 ></DD
 831 ><DT
 832 ><SPAN
 833 CLASS="bold"
 834 ><B
 835 CLASS="emphasis"
 836 >-showkey</B
 837 ></SPAN
 838 ></DT
 839 ><DD
 840 ><P
 841 >Displays the octal digits that constitute the key.</P
 842 ></DD
 843 ><DT
 844 ><SPAN
 845 CLASS="bold"
 846 ><B
 847 CLASS="emphasis"
 848 >-admin</B
 849 ></SPAN
 850 ></DT
 851 ><DD
 852 ><P
 853 >Names an administrative account with the <SAMP
 854 CLASS="computeroutput"
 855 >ADMIN</SAMP
 856 > flag on its Authentication
 857                   Database entry, such as <SPAN
 858 CLASS="bold"
 859 ><B
 860 CLASS="emphasis"
 861 >admin</B
 862 ></SPAN
 863 >. The password prompt echoes it as admin_user. Enter
 864                   the appropriate password as admin_password.</P
 865 ></DD
 866 ></DL
 867 ></DIV
 868 ></P
 869 ></LI
 870 ></OL
 871 ><P
 872 >In the following example, the <SPAN
 873 CLASS="bold"
 874 ><B
 875 CLASS="emphasis"
 876 >admin</B
 877 ></SPAN
 878 > user displays the <SPAN
 879 CLASS="bold"
 880 ><B
 881 CLASS="emphasis"
 882 >afs</B
 883 ></SPAN
 884 > entry without using the <SPAN
 885 CLASS="bold"
 886 ><B
 887 CLASS="emphasis"
 888 >-showkey</B
 889 ></SPAN
 890 > flag. The second line shows the
 891       key version number in parentheses and the key's checksum. The line that begins with the string <SAMP
 892 CLASS="computeroutput"
 893 >last
 894       mod</SAMP
 895 > reports the date on which the indicated administrator changed the key. There is no necessary relationship
 896       between this date and the date reported by the <SPAN
 897 CLASS="bold"
 898 ><B
 899 CLASS="emphasis"
 900 >bos listkeys</B
 901 ></SPAN
 902 > command, because the latter date
 903       changes for any type of change to the <SPAN
 904 CLASS="bold"
 905 ><B
 906 CLASS="emphasis"
 907 >KeyFile</B
 908 ></SPAN
 909 > file, not just a key addition. For a
 910       description of the other lines in the output from the <SPAN
 911 CLASS="bold"
 912 ><B
 913 CLASS="emphasis"
 914 >kas examine</B
 915 ></SPAN
 916 > command, see its reference
 917       page in the IBM AFS Administration Reference.</P
 918 ><PRE
 919 CLASS="programlisting"
 920 >&#13;   % <SPAN
 921 CLASS="bold"
 922 ><B
 923 CLASS="emphasis"
 924 >kas examine afs  -admin admin</B
 925 ></SPAN
 926 >
 927    Administrator's (admin) password: &#60;<VAR
 928 CLASS="replaceable"
 929 >admin_password</VAR
 930 >&#62;
 931    User data for afs
 932     key (1) cksum is 2825165022, last cpw: no date
 933     password will never expire.
 934     An unlimited number of unsuccessful authentications is permitted.
 935     entry expires on never. Max ticket lifetime 100.00 hours.
 936     last mod on Wed Jan 13 11:21:36 1999 by admin
 937     permit password reuse
 938 </PRE
 939 ></DIV
 940 ></DIV
 941 ><DIV
 942 CLASS="sect1"
 943 ><H1
 944 CLASS="sect1"
 945 ><A
 946 NAME="HDRWQ362"
 947 >Adding Server Encryption Keys</A
 948 ></H1
 949 ><P
 950 >As noted, AFS records server encryption keys in two separate places: <OL
 951 TYPE="1"
 952 ><LI
 953 ><P
 954 >In the file <SPAN
 955 CLASS="bold"
 956 ><B
 957 CLASS="emphasis"
 958 >/usr/afs/etc/KeyFile</B
 959 ></SPAN
 960 > on the local disk of each server machine, for use
 961           by the AFS server processes running on the machine</P
 962 ></LI
 963 ><LI
 964 ><P
 965 >In the <SPAN
 966 CLASS="bold"
 967 ><B
 968 CLASS="emphasis"
 969 >afs</B
 970 ></SPAN
 971 > entry in the Authentication Database, for use by the Ticket Granting
 972           Service (TGS) when creating tokens</P
 973 ></LI
 974 ></OL
 975 ></P
 976 ><P
 977 >To ensure that server processes and the TGS share the same AFS server encryption key, execute all the steps in this
 978     section without interruption.</P
 979 ><P
 980 >The following instructions include a step in which you restart the database server processes (the Authentication, Backup,
 981     Protection, and Volume Location Server processes) on all database server machines. As a database server process starts, it reads
 982     in the server encryption key that has the highest key version number in the <SPAN
 983 CLASS="bold"
 984 ><B
 985 CLASS="emphasis"
 986 >KeyFile</B
 987 ></SPAN
 988 > file and
 989     uses it to protect the messages that it sends for synchronizing the database and maintaining quorum. It uses the same key
 990     throughout its lifetime, which can be for an extended period, even if you remove the key from the <SPAN
 991 CLASS="bold"
 992 ><B
 993 CLASS="emphasis"
 994 >KeyFile</B
 995 ></SPAN
 996 > file. However, if one of the peer database server processes restarts and the others do not,
 997     quorum and database synchronization break down because the processes are no longer using the same key: the restarted process is
 998     using the key that currently has the highest key version number, and the other processes are still using the key they read in
 999     when they originally started. To avoid this problem, it is safest to restart all of the database server processes when adding a
1000     new key.</P
1001 ><P
1002 >After adding a new key, you can remove obsolete keys from the <SPAN
1003 CLASS="bold"
1004 ><B
1005 CLASS="emphasis"
1006 >KeyFile</B
1007 ></SPAN
1008 > file to prevent it
1009     from becoming cluttered. However, you must take care not to remove keys that client or server processes are still using. For
1010     discussion and instructions, see <A
1011 HREF="c20494.html#HDRWQ368"
1012 >Removing Server Encryption Keys</A
1013 >.</P
1014 ><DIV
1015 CLASS="sect2"
1016 ><H2
1017 CLASS="sect2"
1018 ><A
1019 NAME="HDRWQ363"
1020 >To add a new server encryption key</A
1021 ></H2
1022 ><OL
1023 TYPE="1"
1024 ><LI
1025 ><P
1026 >Verify that you are authenticated as a user listed in the <SPAN
1027 CLASS="bold"
1028 ><B
1029 CLASS="emphasis"
1030 >/usr/afs/etc/UserList</B
1031 ></SPAN
1032 >
1033           file. If necessary, issue the <SPAN
1034 CLASS="bold"
1035 ><B
1036 CLASS="emphasis"
1037 >bos listusers</B
1038 ></SPAN
1039 > command, which is fully described in <A
1040 HREF="c32432.html#HDRWQ593"
1041 >To display the users in the UserList file</A
1042 >. <PRE
1043 CLASS="programlisting"
1044 >&#13;   % <SPAN
1045 CLASS="bold"
1046 ><B
1047 CLASS="emphasis"
1048 >bos listusers</B
1049 ></SPAN
1050 > &#60;<VAR
1051 CLASS="replaceable"
1052 >machine name</VAR
1053 >&#62;
1054 </PRE
1055 ></P
1056 ></LI
1057 ><LI
1058 ><P
1059 ><A
1060 NAME="LIWQ364"
1061 ></A
1062 >Issue the <SPAN
1063 CLASS="bold"
1064 ><B
1065 CLASS="emphasis"
1066 >bos listkeys</B
1067 ></SPAN
1068 > command to display the key version
1069           numbers that are already in use, as a first step in choosing the key version number for the new key. <PRE
1070 CLASS="programlisting"
1071 >&#13;   % <SPAN
1072 CLASS="bold"
1073 ><B
1074 CLASS="emphasis"
1075 >bos listkeys</B
1076 ></SPAN
1077 > &#60;<VAR
1078 CLASS="replaceable"
1079 >machine name</VAR
1080 >&#62;
1081 </PRE
1082 ></P
1083 ><P
1084 >where <DIV
1085 CLASS="variablelist"
1086 ><DL
1087 ><DT
1088 ><SPAN
1089 CLASS="bold"
1090 ><B
1091 CLASS="emphasis"
1092 >listk</B
1093 ></SPAN
1094 ></DT
1095 ><DD
1096 ><P
1097 >Is the shortest acceptable abbreviation of <SPAN
1098 CLASS="bold"
1099 ><B
1100 CLASS="emphasis"
1101 >listkeys</B
1102 ></SPAN
1103 >.</P
1104 ></DD
1105 ><DT
1106 ><SPAN
1107 CLASS="bold"
1108 ><B
1109 CLASS="emphasis"
1110 >machine name</B
1111 ></SPAN
1112 ></DT
1113 ><DD
1114 ><P
1115 >Names any file server machine.</P
1116 ></DD
1117 ></DL
1118 ></DIV
1119 ></P
1120 ></LI
1121 ><LI
1122 ><P
1123 ><A
1124 NAME="LIWQ365"
1125 ></A
1126 >Choose a key version number for the new key, based on the output from Step <A
1127 HREF="c20494.html#LIWQ364"
1128 >2</A
1129 > and the following requirements: <UL
1130 ><LI
1131 ><P
1132 >A key version number must be an integer between 0 (zero) and 255 to comply with Kerberos standards. It is
1133                 simplest if you keep your key version numbers in sequence by choosing a key version number one greater than the
1134                 largest existing one.</P
1135 ></LI
1136 ><LI
1137 ><P
1138 >Do not reuse a key version number currently found in the <SPAN
1139 CLASS="bold"
1140 ><B
1141 CLASS="emphasis"
1142 >KeyFile</B
1143 ></SPAN
1144 > file,
1145                 particularly if it is also the one in the Authentication Database <SPAN
1146 CLASS="bold"
1147 ><B
1148 CLASS="emphasis"
1149 >afs</B
1150 ></SPAN
1151 > entry. Client
1152                 processes possibly still have tickets sealed with the key that originally had that key version number, but the
1153                 server processes start using the new key marked with that key version number. Because the keys do not match, the
1154                 server processes refuse requests from clients who hold legitimate tokens.</P
1155 ></LI
1156 ></UL
1157 ></P
1158 ></LI
1159 ><LI
1160 ><P
1161 ><A
1162 NAME="LIWQ366"
1163 ></A
1164 >Issue the <SPAN
1165 CLASS="bold"
1166 ><B
1167 CLASS="emphasis"
1168 >bos addkey</B
1169 ></SPAN
1170 > command to create a new AFS server
1171           encryption key in the <SPAN
1172 CLASS="bold"
1173 ><B
1174 CLASS="emphasis"
1175 >KeyFile</B
1176 ></SPAN
1177 > file.</P
1178 ><P
1179 >If you run the United States edition of AFS and use the Update Server to distribute the contents of the system
1180           control machine's <SPAN
1181 CLASS="bold"
1182 ><B
1183 CLASS="emphasis"
1184 >/usr/afs/etc</B
1185 ></SPAN
1186 > directory, substitute the system control machine for the
1187           machine name argument. (If you have forgotten which machine is the system control machine, see <A
1188 HREF="c3025.html#HDRWQ96"
1189 >To
1190           locate the system control machine</A
1191 >.)</P
1192 ><P
1193 >If you run the international edition of AFS or do not use the Update Server, repeat the <SPAN
1194 CLASS="bold"
1195 ><B
1196 CLASS="emphasis"
1197 >bos
1198           addkey</B
1199 ></SPAN
1200 > command, substituting each server machine in your cell for the machine name argument in turn.</P
1201 ><P
1202 >To avoid visible echoing of the string that corresponds to the new key, omit the <SPAN
1203 CLASS="bold"
1204 ><B
1205 CLASS="emphasis"
1206 >-key</B
1207 ></SPAN
1208 > argument from the command line; instead enter the string at the prompts that appear when you
1209           omit it, as shown in the following syntax specification.</P
1210 ><PRE
1211 CLASS="programlisting"
1212 >&#13;   % <SPAN
1213 CLASS="bold"
1214 ><B
1215 CLASS="emphasis"
1216 >bos addkey  -server</B
1217 ></SPAN
1218 > &#60;<VAR
1219 CLASS="replaceable"
1220 >machine name</VAR
1221 >&#62; <SPAN
1222 CLASS="bold"
1223 ><B
1224 CLASS="emphasis"
1225 >-kvno</B
1226 ></SPAN
1227 > &#60;<VAR
1228 CLASS="replaceable"
1229 >key version number</VAR
1230 >&#62;
1231    input key: &#60;<VAR
1232 CLASS="replaceable"
1233 >afs_password</VAR
1234 >&#62;
1235    Retype input key: &#60;<VAR
1236 CLASS="replaceable"
1237 >afs_password</VAR
1238 >&#62;
1239 </PRE
1240 ><P
1241 >where <DIV
1242 CLASS="variablelist"
1243 ><DL
1244 ><DT
1245 ><SPAN
1246 CLASS="bold"
1247 ><B
1248 CLASS="emphasis"
1249 >addk</B
1250 ></SPAN
1251 ></DT
1252 ><DD
1253 ><P
1254 >Is the shortest acceptable abbreviation of <SPAN
1255 CLASS="bold"
1256 ><B
1257 CLASS="emphasis"
1258 >addkey</B
1259 ></SPAN
1260 >.</P
1261 ></DD
1262 ><DT
1263 ><SPAN
1264 CLASS="bold"
1265 ><B
1266 CLASS="emphasis"
1267 >-server</B
1268 ></SPAN
1269 ></DT
1270 ><DD
1271 ><P
1272 >Names the cell's system control machine if you are using the Update Server, or each server machine in turn
1273                   if you are not.</P
1274 ></DD
1275 ><DT
1276 ><SPAN
1277 CLASS="bold"
1278 ><B
1279 CLASS="emphasis"
1280 >-kvno</B
1281 ></SPAN
1282 ></DT
1283 ><DD
1284 ><P
1285 >Specifies the new key's key version number as an integer from the range 0 (zero) through 255.</P
1286 ><P
1287 >Remember the number. You need to use it again in Step <A
1288 HREF="c20494.html#LIWQ367"
1289 >6</A
1290 >. If you are using the
1291                   international edition of AFS, be sure to type the same number each time you issue this command.</P
1292 ></DD
1293 ><DT
1294 ><SPAN
1295 CLASS="bold"
1296 ><B
1297 CLASS="emphasis"
1298 >afs_password</B
1299 ></SPAN
1300 ></DT
1301 ><DD
1302 ><P
1303 >Is a character string similar to a user password, of any length from one to about 1,000 characters. To
1304                   improve security, include nonalphabetic characters and make the string as long as is practical (you need to type
1305                   it only in this step and in Step <A
1306 HREF="c20494.html#LIWQ367"
1307 >6</A
1308 >). If you are using the international edition of
1309                   AFS, be sure to type the same string each time you issue this command.</P
1310 ><P
1311 >Do not enter an octal string directly. The BOS Server scrambles the character string into an octal string
1312                   appropriate for use as an encryption key before recording it in the <SPAN
1313 CLASS="bold"
1314 ><B
1315 CLASS="emphasis"
1316 >KeyFile</B
1317 ></SPAN
1318 >
1319                   file.</P
1320 ></DD
1321 ></DL
1322 ></DIV
1323 ></P
1324 ></LI
1325 ><LI
1326 ><P
1327 >If you are using the Update Server, wait for a few minutes while the Update Server distributes the new <SPAN
1328 CLASS="bold"
1329 ><B
1330 CLASS="emphasis"
1331 >KeyFile</B
1332 ></SPAN
1333 > file to all server machines. The maximum necessary waiting period is the largest value
1334           provided for the <SPAN
1335 CLASS="bold"
1336 ><B
1337 CLASS="emphasis"
1338 >-t</B
1339 ></SPAN
1340 > argument to the <SPAN
1341 CLASS="bold"
1342 ><B
1343 CLASS="emphasis"
1344 >upclientetc</B
1345 ></SPAN
1346 >
1347           process's initialization command used on any of the server machines; the default time is five minutes.</P
1348 ><P
1349 >To be certain that all machines have the same <SPAN
1350 CLASS="bold"
1351 ><B
1352 CLASS="emphasis"
1353 >KeyFile</B
1354 ></SPAN
1355 > file, issue the <SPAN
1356 CLASS="bold"
1357 ><B
1358 CLASS="emphasis"
1359 >bos listkeys</B
1360 ></SPAN
1361 > command for every file server machine and verify that the checksum for the new key is
1362           the same on all machines.</P
1363 ><PRE
1364 CLASS="programlisting"
1365 >&#13;   % <SPAN
1366 CLASS="bold"
1367 ><B
1368 CLASS="emphasis"
1369 >bos listkeys</B
1370 ></SPAN
1371 > &#60;<VAR
1372 CLASS="replaceable"
1373 >machine name</VAR
1374 >&#62;
1375 </PRE
1376 ><P
1377 >If you are not using the Update Server, try to complete Step <A
1378 HREF="c20494.html#LIWQ366"
1379 >4</A
1380 > within five
1381           minutes.</P
1382 ></LI
1383 ><LI
1384 ><P
1385 ><A
1386 NAME="LIWQ367"
1387 ></A
1388 >Issue the <SPAN
1389 CLASS="bold"
1390 ><B
1391 CLASS="emphasis"
1392 >kas setpassword</B
1393 ></SPAN
1394 > command to enter the same key in
1395           the <SPAN
1396 CLASS="bold"
1397 ><B
1398 CLASS="emphasis"
1399 >afs</B
1400 ></SPAN
1401 > entry in the Authentication Database.</P
1402 ><P
1403 >The Authentication Server performs its own authentication rather than accepting your existing AFS token. By default,
1404           it authenticates your local (UNIX) identity, which possibly does not correspond to an AFS-privileged administrator.
1405           Include the <SPAN
1406 CLASS="bold"
1407 ><B
1408 CLASS="emphasis"
1409 >-admin</B
1410 ></SPAN
1411 > argument to name an identity that has the
1412           <SAMP
1413 CLASS="computeroutput"
1414 >ADMIN</SAMP
1415 > flag on its Authentication Database entry. To verify that an entry has the flag,
1416           issue the <SPAN
1417 CLASS="bold"
1418 ><B
1419 CLASS="emphasis"
1420 >kas examine</B
1421 ></SPAN
1422 > command as described in <A
1423 HREF="c32432.html#HDRWQ590"
1424 >To check if the
1425           ADMIN flag is set</A
1426 >.</P
1427 ><PRE
1428 CLASS="programlisting"
1429 >&#13;   % <SPAN
1430 CLASS="bold"
1431 ><B
1432 CLASS="emphasis"
1433 >kas setpassword -name afs -kvno</B
1434 ></SPAN
1435 > &#60;<VAR
1436 CLASS="replaceable"
1437 >kvno</VAR
1438 >&#62;  \
1439                      <SPAN
1440 CLASS="bold"
1441 ><B
1442 CLASS="emphasis"
1443 >-admin</B
1444 ></SPAN
1445 >  &#60;<VAR
1446 CLASS="replaceable"
1447 >admin principal to use for authentication</VAR
1448 >&#62;
1449    Administrator's (admin_user) password: &#60;<VAR
1450 CLASS="replaceable"
1451 >admin_password</VAR
1452 >&#62;
1453    new_password: afs_password
1454    Verifying, please re-enter new_password: &#60;<VAR
1455 CLASS="replaceable"
1456 >admin_password</VAR
1457 >&#62;
1458 </PRE
1459 ><P
1460 >where <DIV
1461 CLASS="variablelist"
1462 ><DL
1463 ><DT
1464 ><SPAN
1465 CLASS="bold"
1466 ><B
1467 CLASS="emphasis"
1468 >sp</B
1469 ></SPAN
1470 ></DT
1471 ><DD
1472 ><P
1473 >Is an acceptable alias for <SPAN
1474 CLASS="bold"
1475 ><B
1476 CLASS="emphasis"
1477 >setpassword</B
1478 ></SPAN
1479 > (<SPAN
1480 CLASS="bold"
1481 ><B
1482 CLASS="emphasis"
1483 >setp</B
1484 ></SPAN
1485 > is the shortest acceptable abbreviation).</P
1486 ></DD
1487 ><DT
1488 ><SPAN
1489 CLASS="bold"
1490 ><B
1491 CLASS="emphasis"
1492 >-name afs</B
1493 ></SPAN
1494 ></DT
1495 ><DD
1496 ><P
1497 >Creates the new key in the <SPAN
1498 CLASS="bold"
1499 ><B
1500 CLASS="emphasis"
1501 >afs</B
1502 ></SPAN
1503 > entry.</P
1504 ></DD
1505 ><DT
1506 ><SPAN
1507 CLASS="bold"
1508 ><B
1509 CLASS="emphasis"
1510 >-kvno</B
1511 ></SPAN
1512 ></DT
1513 ><DD
1514 ><P
1515 >Specifies the same key version number as in Step <A
1516 HREF="c20494.html#LIWQ366"
1517 >4</A
1518 >.</P
1519 ></DD
1520 ><DT
1521 ><SPAN
1522 CLASS="bold"
1523 ><B
1524 CLASS="emphasis"
1525 >-admin</B
1526 ></SPAN
1527 ></DT
1528 ><DD
1529 ><P
1530 >Names an administrative account with the <SAMP
1531 CLASS="computeroutput"
1532 >ADMIN</SAMP
1533 > flag on its Authentication
1534                   Database entry, such as <SPAN
1535 CLASS="bold"
1536 ><B
1537 CLASS="emphasis"
1538 >admin</B
1539 ></SPAN
1540 >. The password prompt echoes it as admin_user. Enter
1541                   the appropriate password as admin_password.</P
1542 ></DD
1543 ><DT
1544 ><SPAN
1545 CLASS="bold"
1546 ><B
1547 CLASS="emphasis"
1548 >afs_password</B
1549 ></SPAN
1550 ></DT
1551 ><DD
1552 ><P
1553 >Is the same character string you entered in Step <A
1554 HREF="c20494.html#LIWQ366"
1555 >4</A
1556 >.</P
1557 ></DD
1558 ></DL
1559 ></DIV
1560 ></P
1561 ></LI
1562 ><LI
1563 ><P
1564 ><SPAN
1565 CLASS="bold"
1566 ><B
1567 CLASS="emphasis"
1568 >(Optional.)</B
1569 ></SPAN
1570 > If you want to verify that the keys you just created in the <SPAN
1571 CLASS="bold"
1572 ><B
1573 CLASS="emphasis"
1574 >KeyFile</B
1575 ></SPAN
1576 > file and the Authentication Database <SPAN
1577 CLASS="bold"
1578 ><B
1579 CLASS="emphasis"
1580 >afs</B
1581 ></SPAN
1582 > entry are
1583           identical and have the same key version number, follow the instructions in <A
1584 HREF="c20494.html#HDRWQ359"
1585 >Displaying Server
1586           Encryption Keys</A
1587 >.</P
1588 ></LI
1589 ><LI
1590 ><P
1591 >Issue the <SPAN
1592 CLASS="bold"
1593 ><B
1594 CLASS="emphasis"
1595 >bos restart</B
1596 ></SPAN
1597 > command to restart the database server processes on all
1598           database server machines. This forces them to start using the key in the <SPAN
1599 CLASS="bold"
1600 ><B
1601 CLASS="emphasis"
1602 >KeyFile</B
1603 ></SPAN
1604 > file
1605           that currently has the highest key version number.</P
1606 ><P
1607 >Repeat this command in quick succession for each database server machine, starting with the machine that has the
1608           lowest IP address.</P
1609 ><PRE
1610 CLASS="programlisting"
1611 >&#13;   % <SPAN
1612 CLASS="bold"
1613 ><B
1614 CLASS="emphasis"
1615 >bos restart</B
1616 ></SPAN
1617 >  &#60;<VAR
1618 CLASS="replaceable"
1619 >machine name</VAR
1620 >&#62; <SPAN
1621 CLASS="bold"
1622 ><B
1623 CLASS="emphasis"
1624 >buserver kaserver ptserver vlserver</B
1625 ></SPAN
1626 >
1627 </PRE
1628 ><P
1629 >where <DIV
1630 CLASS="variablelist"
1631 ><DL
1632 ><DT
1633 ><SPAN
1634 CLASS="bold"
1635 ><B
1636 CLASS="emphasis"
1637 >res</B
1638 ></SPAN
1639 ></DT
1640 ><DD
1641 ><P
1642 >Is the shortest acceptable abbreviation of <SPAN
1643 CLASS="bold"
1644 ><B
1645 CLASS="emphasis"
1646 >restart</B
1647 ></SPAN
1648 >.</P
1649 ></DD
1650 ><DT
1651 ><SPAN
1652 CLASS="bold"
1653 ><B
1654 CLASS="emphasis"
1655 >machine name</B
1656 ></SPAN
1657 ></DT
1658 ><DD
1659 ><P
1660 >Names each database server machine in turn.</P
1661 ></DD
1662 ><DT
1663 ><SPAN
1664 CLASS="bold"
1665 ><B
1666 CLASS="emphasis"
1667 >buserver kaserver ptserver vlserver</B
1668 ></SPAN
1669 ></DT
1670 ><DD
1671 ><P
1672 >Designates the Backup Server, Authentication Server, Protection Server, and Volume Location (VL) Server,
1673                   respectively.</P
1674 ></DD
1675 ></DL
1676 ></DIV
1677 ></P
1678 ></LI
1679 ></OL
1680 ></DIV
1681 ></DIV
1682 ><DIV
1683 CLASS="sect1"
1684 ><H1
1685 CLASS="sect1"
1686 ><A
1687 NAME="HDRWQ368"
1688 >Removing Server Encryption Keys</A
1689 ></H1
1690 ><P
1691 >You can periodically remove old keys from the <SPAN
1692 CLASS="bold"
1693 ><B
1694 CLASS="emphasis"
1695 >/usr/afs/etc/KeyFile</B
1696 ></SPAN
1697 > file to keep it to a
1698     reasonable size. To avoid disturbing cell functioning, do not remove an old key until all tokens sealed with the key and held by
1699     users or client processes have expired. After adding a new key, wait to remove old keys at least as long as the longest token
1700     lifetime you use in your cell. For Authentication Database user entries created under AFS version 3.1 or higher, the default
1701     token lifetime is 25 hours; for entries created under AFS version 3.0, it is 100 hours.</P
1702 ><P
1703 >There is no command for removing the key from the <SPAN
1704 CLASS="bold"
1705 ><B
1706 CLASS="emphasis"
1707 >afs</B
1708 ></SPAN
1709 > entry in the Authentication
1710     Database, because the key field in that entry must never be empty. Use the <SPAN
1711 CLASS="bold"
1712 ><B
1713 CLASS="emphasis"
1714 >kas setpassword</B
1715 ></SPAN
1716 >
1717     command to replace the <SPAN
1718 CLASS="bold"
1719 ><B
1720 CLASS="emphasis"
1721 >afs</B
1722 ></SPAN
1723 > key, but only as part of the complete procedure detailed in <A
1724 HREF="c20494.html#HDRWQ363"
1725 >To add a new server encryption key</A
1726 >.</P
1727 ><P
1728 >Never remove from the <SPAN
1729 CLASS="bold"
1730 ><B
1731 CLASS="emphasis"
1732 >KeyFile</B
1733 ></SPAN
1734 > file the key that is currently in the <SPAN
1735 CLASS="bold"
1736 ><B
1737 CLASS="emphasis"
1738 >afs</B
1739 ></SPAN
1740 > entry in the Authentication Database. AFS server processes become unable to decrypt the tickets that
1741     clients present to them.</P
1742 ><DIV
1743 CLASS="sect2"
1744 ><H2
1745 CLASS="sect2"
1746 ><A
1747 NAME="HDRWQ369"
1748 >To remove a key from the KeyFile file</A
1749 ></H2
1750 ><OL
1751 TYPE="1"
1752 ><LI
1753 ><P
1754 >Verify that you are authenticated as a user listed in the <SPAN
1755 CLASS="bold"
1756 ><B
1757 CLASS="emphasis"
1758 >/usr/afs/etc/UserList</B
1759 ></SPAN
1760 >
1761           file. If necessary, issue the <SPAN
1762 CLASS="bold"
1763 ><B
1764 CLASS="emphasis"
1765 >bos listusers</B
1766 ></SPAN
1767 > command, which is fully described in <A
1768 HREF="c32432.html#HDRWQ593"
1769 >To display the users in the UserList file</A
1770 >. <PRE
1771 CLASS="programlisting"
1772 >&#13;   % <SPAN
1773 CLASS="bold"
1774 ><B
1775 CLASS="emphasis"
1776 >bos listusers</B
1777 ></SPAN
1778 > &#60;<VAR
1779 CLASS="replaceable"
1780 >machine name</VAR
1781 >&#62;
1782 </PRE
1783 ></P
1784 ></LI
1785 ><LI
1786 ><P
1787 >Issue the <SPAN
1788 CLASS="bold"
1789 ><B
1790 CLASS="emphasis"
1791 >bos listkeys</B
1792 ></SPAN
1793 > command to display the key version number of each key you
1794           want to remove. The output also reveals whether it has been at least 25 hours since a new key was placed in the <SPAN
1795 CLASS="bold"
1796 ><B
1797 CLASS="emphasis"
1798 >KeyFile</B
1799 ></SPAN
1800 > file. For complete instructions for the <SPAN
1801 CLASS="bold"
1802 ><B
1803 CLASS="emphasis"
1804 >bos listkeys</B
1805 ></SPAN
1806 >
1807           command, see <A
1808 HREF="c20494.html#HDRWQ360"
1809 >To display the KeyFile file</A
1810 >. <PRE
1811 CLASS="programlisting"
1812 >&#13;   % <SPAN
1813 CLASS="bold"
1814 ><B
1815 CLASS="emphasis"
1816 >bos listkeys</B
1817 ></SPAN
1818 > &#60;<VAR
1819 CLASS="replaceable"
1820 >machine name</VAR
1821 >&#62;
1822 </PRE
1823 ></P
1824 ></LI
1825 ><LI
1826 ><P
1827 >Issue the <SPAN
1828 CLASS="bold"
1829 ><B
1830 CLASS="emphasis"
1831 >kas examine</B
1832 ></SPAN
1833 > command to verify that the key currently in the
1834           Authentication Database's <SPAN
1835 CLASS="bold"
1836 ><B
1837 CLASS="emphasis"
1838 >afs</B
1839 ></SPAN
1840 > entry does not have the same key version number as any of
1841           the keys you are removing from the <SPAN
1842 CLASS="bold"
1843 ><B
1844 CLASS="emphasis"
1845 >KeyFile</B
1846 ></SPAN
1847 > file. For detailed instructions for the
1848           <SPAN
1849 CLASS="bold"
1850 ><B
1851 CLASS="emphasis"
1852 >kas examine</B
1853 ></SPAN
1854 > command, see <A
1855 HREF="c20494.html#HDRWQ361"
1856 >To display the afs key from the
1857           Authentication Database</A
1858 >. <PRE
1859 CLASS="programlisting"
1860 >&#13;   % <SPAN
1861 CLASS="bold"
1862 ><B
1863 CLASS="emphasis"
1864 >kas examine afs  -admin</B
1865 ></SPAN
1866 > &#60;<VAR
1867 CLASS="replaceable"
1868 >admin principal to use for authentication</VAR
1869 >&#62;
1870    Administrator's (admin_user) password: &#60;<VAR
1871 CLASS="replaceable"
1872 >admin_password</VAR
1873 >&#62;
1874 </PRE
1875 ></P
1876 ></LI
1877 ><LI
1878 ><P
1879 >Issue the <SPAN
1880 CLASS="bold"
1881 ><B
1882 CLASS="emphasis"
1883 >bos removekey</B
1884 ></SPAN
1885 > command to remove one or more server encryption keys from
1886           the <SPAN
1887 CLASS="bold"
1888 ><B
1889 CLASS="emphasis"
1890 >KeyFile</B
1891 ></SPAN
1892 > file.</P
1893 ><P
1894 >If you run the United States edition of AFS and use the Update Server to distribute the contents of the system
1895           control machine's <SPAN
1896 CLASS="bold"
1897 ><B
1898 CLASS="emphasis"
1899 >/usr/afs/etc</B
1900 ></SPAN
1901 > directory, substitute the system control machine for the
1902           machine name argument. (If you have forgotten which machine is the system control machine, see <A
1903 HREF="c3025.html#HDRWQ96"
1904 >To
1905           locate the system control machine</A
1906 >.)</P
1907 ><P
1908 >If you run the international edition of AFS or do not use the Update Server, repeat the <SPAN
1909 CLASS="bold"
1910 ><B
1911 CLASS="emphasis"
1912 >bos
1913           removekey</B
1914 ></SPAN
1915 > command, substituting each server machine in your cell for the machine name argument in turn.</P
1916 ><PRE
1917 CLASS="programlisting"
1918 >&#13;   % <SPAN
1919 CLASS="bold"
1920 ><B
1921 CLASS="emphasis"
1922 >bos removekey</B
1923 ></SPAN
1924 > &#60;<VAR
1925 CLASS="replaceable"
1926 >machine name</VAR
1927 >&#62; &#60;<VAR
1928 CLASS="replaceable"
1929 >key version number</VAR
1930 >&#62;
1931 </PRE
1932 ><P
1933 >where <DIV
1934 CLASS="variablelist"
1935 ><DL
1936 ><DT
1937 ><SPAN
1938 CLASS="bold"
1939 ><B
1940 CLASS="emphasis"
1941 >removek</B
1942 ></SPAN
1943 ></DT
1944 ><DD
1945 ><P
1946 >Is the shortest acceptable abbreviation of <SPAN
1947 CLASS="bold"
1948 ><B
1949 CLASS="emphasis"
1950 >removekey</B
1951 ></SPAN
1952 >.</P
1953 ></DD
1954 ><DT
1955 ><SPAN
1956 CLASS="bold"
1957 ><B
1958 CLASS="emphasis"
1959 >machine name</B
1960 ></SPAN
1961 ></DT
1962 ><DD
1963 ><P
1964 >Names the cell's system control machine if you are using the Update Server, or each server machine in turn
1965                   if you are not.</P
1966 ></DD
1967 ><DT
1968 ><SPAN
1969 CLASS="bold"
1970 ><B
1971 CLASS="emphasis"
1972 >key version number</B
1973 ></SPAN
1974 ></DT
1975 ><DD
1976 ><P
1977 >Specifies the key version number of each key to remove.</P
1978 ></DD
1979 ></DL
1980 ></DIV
1981 ></P
1982 ></LI
1983 ></OL
1984 ></DIV
1985 ></DIV
1986 ><DIV
1987 CLASS="sect1"
1988 ><H1
1989 CLASS="sect1"
1990 ><A
1991 NAME="HDRWQ370"
1992 >Handling Server Encryption Key Emergencies</A
1993 ></H1
1994 ><P
1995 >In rare circumstances, the AFS server processes can become unable to decrypt the server tickets that clients or peer
1996     server processes are presenting. Activity in your cell can come to a halt, because the server processes believe that the tickets
1997     are forged or expired, and refuse to execute any actions. This can happen on one machine or several; the effect is more serious
1998     when more machines are involved.</P
1999 ><P
2000 >One common cause of server encryption key problems is that the client's ticket is encrypted with a key that the server
2001     process does not know. Usually this means that the <SPAN
2002 CLASS="bold"
2003 ><B
2004 CLASS="emphasis"
2005 >/usr/afs/etc/KeyFile</B
2006 ></SPAN
2007 > on the server machine
2008     does not include the key in the <SPAN
2009 CLASS="bold"
2010 ><B
2011 CLASS="emphasis"
2012 >afs</B
2013 ></SPAN
2014 > Authentication Database entry, which the Authentication
2015     Server's Ticket Granting Service (TGS) module is using to encrypt server tickets.</P
2016 ><P
2017 >Another possibility is that the <SPAN
2018 CLASS="bold"
2019 ><B
2020 CLASS="emphasis"
2021 >KeyFile</B
2022 ></SPAN
2023 > files on different machines do not contain the
2024     same keys. In this case, communications among server processes themselves become impossible. For instance, AFS's replicated
2025     database mechanism (Ubik) breaks down if the instances of a database server process on the different database server machines
2026     are not using the same key.</P
2027 ><P
2028 >The appearance of the following error message when you direct a <SPAN
2029 CLASS="bold"
2030 ><B
2031 CLASS="emphasis"
2032 >bos</B
2033 ></SPAN
2034 > command to a file
2035     server machine in the local cell is one possible symptom of server encryption key mismatch. (Note, however, that you can also
2036     get this message if you forget to include the <SPAN
2037 CLASS="bold"
2038 ><B
2039 CLASS="emphasis"
2040 >-cell</B
2041 ></SPAN
2042 > argument when directing the <SPAN
2043 CLASS="bold"
2044 ><B
2045 CLASS="emphasis"
2046 >bos</B
2047 ></SPAN
2048 > command to a file server machine in a foreign cell.)</P
2049 ><PRE
2050 CLASS="programlisting"
2051 >&#13;   bos: failed to contact host's bosserver (security object was passed a bad ticket).
2052 </PRE
2053 ><P
2054 >The solution to server encryption key emergencies is to put a new AFS server encryption key in both the Authentication
2055     Database and the <SPAN
2056 CLASS="bold"
2057 ><B
2058 CLASS="emphasis"
2059 >KeyFile</B
2060 ></SPAN
2061 > file on every server machine, so that the TGS and all server processes
2062     again share the same key.</P
2063 ><P
2064 >Handling key emergencies requires some unusual actions. The reasons for these actions are explained in the following
2065     sections; the actual procedures appear in the subsequent instructions.</P
2066 ><DIV
2067 CLASS="sect2"
2068 ><H2
2069 CLASS="sect2"
2070 ><A
2071 NAME="HDRWQ371"
2072 >Prevent Mutual Authentication</A
2073 ></H2
2074 ><P
2075 >It is necessary to prevent the server processes from trying to mutually authenticate with you as you deal with a key
2076       emergency, because they possibly cannot decrypt your token. When you do not mutually authenticate, the server processes assign
2077       you the identity <SPAN
2078 CLASS="bold"
2079 ><B
2080 CLASS="emphasis"
2081 >anonymous</B
2082 ></SPAN
2083 >. To prevent mutual authentication, use the <SPAN
2084 CLASS="bold"
2085 ><B
2086 CLASS="emphasis"
2087 >unlog</B
2088 ></SPAN
2089 > command to discard your tokens and include the <SPAN
2090 CLASS="bold"
2091 ><B
2092 CLASS="emphasis"
2093 >-noauth</B
2094 ></SPAN
2095 > flag on
2096       every command where it is available.</P
2097 ></DIV
2098 ><DIV
2099 CLASS="sect2"
2100 ><H2
2101 CLASS="sect2"
2102 ><A
2103 NAME="Header_423"
2104 >Disable Authorization Checking by Hand</A
2105 ></H2
2106 ><P
2107 >Because the server processes recognize you as the user <SPAN
2108 CLASS="bold"
2109 ><B
2110 CLASS="emphasis"
2111 >anonymous</B
2112 ></SPAN
2113 > when you do not
2114       mutually authenticate, you must turn off authorization checking. Only with authorization checking disabled do the server
2115       processes allow the <SPAN
2116 CLASS="bold"
2117 ><B
2118 CLASS="emphasis"
2119 >anonymous</B
2120 ></SPAN
2121 > user to perform privileged actions such as key creation.</P
2122 ><P
2123 >In an emergency, disable authorization checking by creating the file <SPAN
2124 CLASS="bold"
2125 ><B
2126 CLASS="emphasis"
2127 >/usr/afs/local/NoAuth</B
2128 ></SPAN
2129 > by hand. In normal circumstances, use the <SPAN
2130 CLASS="bold"
2131 ><B
2132 CLASS="emphasis"
2133 >bos
2134       setauth</B
2135 ></SPAN
2136 > command instead.</P
2137 ></DIV
2138 ><DIV
2139 CLASS="sect2"
2140 ><H2
2141 CLASS="sect2"
2142 ><A
2143 NAME="Header_424"
2144 >Work Quickly on Each Machine</A
2145 ></H2
2146 ><P
2147 >Disabling authorization checking is a serious security exposure, because server processes on the affected machine
2148       perform any action for anyone. Disable authorization checking only for as long as necessary, completing all steps in an
2149       uninterrupted session and as quickly as possible.</P
2150 ></DIV
2151 ><DIV
2152 CLASS="sect2"
2153 ><H2
2154 CLASS="sect2"
2155 ><A
2156 NAME="Header_425"
2157 >Work at the Console</A
2158 ></H2
2159 ><P
2160 >Working at the console of each server machine on which you disable authorization checking ensures that no one else logs
2161       onto the console while you are working there. It does not prevent others from connecting to the machine remotely (using the
2162       <SPAN
2163 CLASS="bold"
2164 ><B
2165 CLASS="emphasis"
2166 >telnet</B
2167 ></SPAN
2168 > program, for example), which is why it is important to work quickly. The only way to
2169       ensure complete security is to disable network traffic, which is not a viable option in many environments. You can improve
2170       security in general by limiting the number of people who can connect remotely to your server machines at any time, as
2171       recommended in <A
2172 HREF="c667.html#HDRWQ74"
2173 >Improving Security in Your Cell</A
2174 >.</P
2175 ></DIV
2176 ><DIV
2177 CLASS="sect2"
2178 ><H2
2179 CLASS="sect2"
2180 ><A
2181 NAME="HDRWQ372"
2182 >Change Individual KeyFile Files</A
2183 ></H2
2184 ><P
2185 >If you use the Update Server to distribute the contents of the <SPAN
2186 CLASS="bold"
2187 ><B
2188 CLASS="emphasis"
2189 >/usr/afs/etc</B
2190 ></SPAN
2191 > directory,
2192       an emergency is the only time when it is appropriate to change the <SPAN
2193 CLASS="bold"
2194 ><B
2195 CLASS="emphasis"
2196 >KeyFile</B
2197 ></SPAN
2198 > file on individual
2199       machines instead. Updating each machine's file is necessary because mismatched keys can prevent the system control machine's
2200       <SPAN
2201 CLASS="bold"
2202 ><B
2203 CLASS="emphasis"
2204 >upserver</B
2205 ></SPAN
2206 > process from mutually authenticating with <SPAN
2207 CLASS="bold"
2208 ><B
2209 CLASS="emphasis"
2210 >upclientetc</B
2211 ></SPAN
2212 > processes on other server machines, in which case the <SPAN
2213 CLASS="bold"
2214 ><B
2215 CLASS="emphasis"
2216 >upserver</B
2217 ></SPAN
2218 > process refuses to distribute its <SPAN
2219 CLASS="bold"
2220 ><B
2221 CLASS="emphasis"
2222 >KeyFile</B
2223 ></SPAN
2224 > file to
2225       them.</P
2226 ><P
2227 >Even if it appears that the Update Server is working correctly, the only way to verify that is to change the key on the
2228       system control machine and wait the standard delay period to see if the <SPAN
2229 CLASS="bold"
2230 ><B
2231 CLASS="emphasis"
2232 >upclientetc</B
2233 ></SPAN
2234 > processes
2235       retrieve the key. During an emergency, it does not usually make sense to wait the standard delay period. It is more efficient
2236       simply to update the file on each server machine separately. Also, even if the Update Server can distribute the file
2237       correctly, other processes can have trouble because of mismatched keys. The following instructions add the new key file on the
2238       system control machine first. If the Update Server is working, then it is distributing the same change as you are making on
2239       each server machine individually.</P
2240 ><P
2241 >If your cell does not use the Update Server, or uses the international edition of AFS, you always change keys on server
2242       machines individually. The following instructions are also appropriate for you.</P
2243 ></DIV
2244 ><DIV
2245 CLASS="sect2"
2246 ><H2
2247 CLASS="sect2"
2248 ><A
2249 NAME="Header_427"
2250 >Two Component Procedures</A
2251 ></H2
2252 ><P
2253 >There are two subprocedures used frequently in the following instructions: disabling authorization checking and
2254       reenabling it. For the sake of clarity, the procedures are detailed here; the instructions refer to them as necessary.</P
2255 ><DIV
2256 CLASS="sect3"
2257 ><H3
2258 CLASS="sect3"
2259 ><A
2260 NAME="HDRWQ373"
2261 >Disabling Authorization Checking in an Emergency</A
2262 ></H3
2263 ><OL
2264 TYPE="1"
2265 ><LI
2266 ><P
2267 >Become the local superuser <SPAN
2268 CLASS="bold"
2269 ><B
2270 CLASS="emphasis"
2271 >root</B
2272 ></SPAN
2273 > on the machine, if you are not already, by
2274             issuing the <SPAN
2275 CLASS="bold"
2276 ><B
2277 CLASS="emphasis"
2278 >su</B
2279 ></SPAN
2280 > command. <PRE
2281 CLASS="programlisting"
2282 >&#13;   % <SPAN
2283 CLASS="bold"
2284 ><B
2285 CLASS="emphasis"
2286 >su root</B
2287 ></SPAN
2288 >
2289    Password: &#60;<VAR
2290 CLASS="replaceable"
2291 >root_password</VAR
2292 >&#62;
2293 </PRE
2294 ></P
2295 ></LI
2296 ><LI
2297 ><P
2298 ><A
2299 NAME="LIWQ374"
2300 ></A
2301 >Create the file <SPAN
2302 CLASS="bold"
2303 ><B
2304 CLASS="emphasis"
2305 >/usr/afs/local/NoAuth</B
2306 ></SPAN
2307 > to disable
2308             authorization checking. <PRE
2309 CLASS="programlisting"
2310 >&#13;   # <SPAN
2311 CLASS="bold"
2312 ><B
2313 CLASS="emphasis"
2314 >touch /usr/afs/local/NoAuth</B
2315 ></SPAN
2316 >
2317 </PRE
2318 ></P
2319 ></LI
2320 ><LI
2321 ><P
2322 >Discard your tokens, in case they were sealed with an incompatible key, which can prevent some commands from
2323             executing. <PRE
2324 CLASS="programlisting"
2325 >&#13;   # <SPAN
2326 CLASS="bold"
2327 ><B
2328 CLASS="emphasis"
2329 >unlog</B
2330 ></SPAN
2331 >
2332 </PRE
2333 ></P
2334 ></LI
2335 ></OL
2336 ></DIV
2337 ><DIV
2338 CLASS="sect3"
2339 ><H3
2340 CLASS="sect3"
2341 ><A
2342 NAME="HDRWQ375"
2343 >Reenabling Authorization Checking in an Emergency</A
2344 ></H3
2345 ><OL
2346 TYPE="1"
2347 ><LI
2348 ><P
2349 >Become the local superuser <SPAN
2350 CLASS="bold"
2351 ><B
2352 CLASS="emphasis"
2353 >root</B
2354 ></SPAN
2355 > on the machine, if you are not already, by
2356             issuing the <SPAN
2357 CLASS="bold"
2358 ><B
2359 CLASS="emphasis"
2360 >su</B
2361 ></SPAN
2362 > command. <PRE
2363 CLASS="programlisting"
2364 >&#13;   % <SPAN
2365 CLASS="bold"
2366 ><B
2367 CLASS="emphasis"
2368 >su root</B
2369 ></SPAN
2370 >
2371    Password: &#60;<VAR
2372 CLASS="replaceable"
2373 >root_password</VAR
2374 >&#62;
2375 </PRE
2376 ></P
2377 ></LI
2378 ><LI
2379 ><P
2380 >Remove the <SPAN
2381 CLASS="bold"
2382 ><B
2383 CLASS="emphasis"
2384 >/usr/afs/local/NoAuth</B
2385 ></SPAN
2386 > file. <PRE
2387 CLASS="programlisting"
2388 >&#13;   # <SPAN
2389 CLASS="bold"
2390 ><B
2391 CLASS="emphasis"
2392 >rm /usr/afs/local/NoAuth</B
2393 ></SPAN
2394 >
2395 </PRE
2396 ></P
2397 ></LI
2398 ><LI
2399 ><P
2400 >Authenticate as an administrative identity that belongs to the <SPAN
2401 CLASS="bold"
2402 ><B
2403 CLASS="emphasis"
2404 >system:administrators</B
2405 ></SPAN
2406 > group and is listed in the <SPAN
2407 CLASS="bold"
2408 ><B
2409 CLASS="emphasis"
2410 >/usr/afs/etc/UserList</B
2411 ></SPAN
2412 > file. <PRE
2413 CLASS="programlisting"
2414 >&#13;   # <SPAN
2415 CLASS="bold"
2416 ><B
2417 CLASS="emphasis"
2418 >klog</B
2419 ></SPAN
2420 > &#60;<VAR
2421 CLASS="replaceable"
2422 >admin_user</VAR
2423 >&#62;
2424    Password: &#60;<VAR
2425 CLASS="replaceable"
2426 >admin_password</VAR
2427 >&#62;
2428 </PRE
2429 ></P
2430 ></LI
2431 ><LI
2432 ><P
2433 >If appropriate, log out from the console (or close the remote connection you are using), after issuing the
2434             <SPAN
2435 CLASS="bold"
2436 ><B
2437 CLASS="emphasis"
2438 >unlog</B
2439 ></SPAN
2440 > command to destroy your tokens.</P
2441 ></LI
2442 ></OL
2443 ></DIV
2444 ></DIV
2445 ><DIV
2446 CLASS="sect2"
2447 ><H2
2448 CLASS="sect2"
2449 ><A
2450 NAME="Header_430"
2451 >To create a new server encryption key in emergencies</A
2452 ></H2
2453 ><OL
2454 TYPE="1"
2455 ><LI
2456 ><P
2457 ><A
2458 NAME="LIWQ376"
2459 ></A
2460 ><SPAN
2461 CLASS="bold"
2462 ><B
2463 CLASS="emphasis"
2464 >On the system control machine</B
2465 ></SPAN
2466 >, disable authorization
2467           checking as instructed in <A
2468 HREF="c20494.html#HDRWQ373"
2469 >Disabling Authorization Checking in an Emergency</A
2470 >.</P
2471 ></LI
2472 ><LI
2473 ><P
2474 ><A
2475 NAME="LIWQ377"
2476 ></A
2477 >Issue the <SPAN
2478 CLASS="bold"
2479 ><B
2480 CLASS="emphasis"
2481 >bos listkeys</B
2482 ></SPAN
2483 > command to display the key version
2484           numbers already in use in the <SPAN
2485 CLASS="bold"
2486 ><B
2487 CLASS="emphasis"
2488 >KeyFile</B
2489 ></SPAN
2490 > file, as a first step in choosing the new key's key
2491           version number. <PRE
2492 CLASS="programlisting"
2493 >&#13;   # <SPAN
2494 CLASS="bold"
2495 ><B
2496 CLASS="emphasis"
2497 >bos listkeys</B
2498 ></SPAN
2499 > &#60;<VAR
2500 CLASS="replaceable"
2501 >machine name</VAR
2502 >&#62; <SPAN
2503 CLASS="bold"
2504 ><B
2505 CLASS="emphasis"
2506 >-noauth</B
2507 ></SPAN
2508 >
2509 </PRE
2510 ></P
2511 ><P
2512 >where <DIV
2513 CLASS="variablelist"
2514 ><DL
2515 ><DT
2516 ><SPAN
2517 CLASS="bold"
2518 ><B
2519 CLASS="emphasis"
2520 >listk</B
2521 ></SPAN
2522 ></DT
2523 ><DD
2524 ><P
2525 >Is the shortest acceptable abbreviation of <SPAN
2526 CLASS="bold"
2527 ><B
2528 CLASS="emphasis"
2529 >listkeys</B
2530 ></SPAN
2531 >.</P
2532 ></DD
2533 ><DT
2534 ><SPAN
2535 CLASS="bold"
2536 ><B
2537 CLASS="emphasis"
2538 >machine name</B
2539 ></SPAN
2540 ></DT
2541 ><DD
2542 ><P
2543 >Specifies a file server machine.</P
2544 ></DD
2545 ><DT
2546 ><SPAN
2547 CLASS="bold"
2548 ><B
2549 CLASS="emphasis"
2550 >-noauth</B
2551 ></SPAN
2552 ></DT
2553 ><DD
2554 ><P
2555 >Bypasses mutual authentication with the BOS Server. Include it in case the key emergency is preventing
2556                   successful mutual authentication.</P
2557 ></DD
2558 ></DL
2559 ></DIV
2560 ></P
2561 ></LI
2562 ><LI
2563 ><P
2564 ><A
2565 NAME="LIWQ378"
2566 ></A
2567 >Choose a key version number for the new key, based on what you learned in Step <A
2568 HREF="c20494.html#LIWQ377"
2569 >2</A
2570 > plus the following requirements: <UL
2571 ><LI
2572 ><P
2573 >It is best to keep your key version numbers in sequence by choosing a key version number one greater than the
2574                 largest existing one.</P
2575 ></LI
2576 ><LI
2577 ><P
2578 >Key version numbers must be integers between 0 and 255 to comply with Kerberos standards.</P
2579 ></LI
2580 ><LI
2581 ><P
2582 >Do not reuse a key version number currently listed in the <SPAN
2583 CLASS="bold"
2584 ><B
2585 CLASS="emphasis"
2586 >KeyFile</B
2587 ></SPAN
2588 >
2589                 file.</P
2590 ></LI
2591 ></UL
2592 ></P
2593 ></LI
2594 ><LI
2595 ><P
2596 ><A
2597 NAME="LIWQ379"
2598 ></A
2599 ><SPAN
2600 CLASS="bold"
2601 ><B
2602 CLASS="emphasis"
2603 >On the system control machine</B
2604 ></SPAN
2605 >, issue the <SPAN
2606 CLASS="bold"
2607 ><B
2608 CLASS="emphasis"
2609 >bos addkey</B
2610 ></SPAN
2611 > command to create a new AFS server encryption key in the <SPAN
2612 CLASS="bold"
2613 ><B
2614 CLASS="emphasis"
2615 >KeyFile</B
2616 ></SPAN
2617 > file. <PRE
2618 CLASS="programlisting"
2619 >&#13;   # <SPAN
2620 CLASS="bold"
2621 ><B
2622 CLASS="emphasis"
2623 >bos addkey</B
2624 ></SPAN
2625 > &#60;<VAR
2626 CLASS="replaceable"
2627 >machine name</VAR
2628 >&#62; <SPAN
2629 CLASS="bold"
2630 ><B
2631 CLASS="emphasis"
2632 >-kvno</B
2633 ></SPAN
2634 > &#60;<VAR
2635 CLASS="replaceable"
2636 >key version number</VAR
2637 >&#62; <SPAN
2638 CLASS="bold"
2639 ><B
2640 CLASS="emphasis"
2641 >-noauth</B
2642 ></SPAN
2643 >
2644    input key: &#60;<VAR
2645 CLASS="replaceable"
2646 >afs_password</VAR
2647 >&#62;
2648    Retype input key: &#60;<VAR
2649 CLASS="replaceable"
2650 >afs_password</VAR
2651 >&#62;
2652 </PRE
2653 ></P
2654 ><P
2655 >where <DIV
2656 CLASS="variablelist"
2657 ><DL
2658 ><DT
2659 ><SPAN
2660 CLASS="bold"
2661 ><B
2662 CLASS="emphasis"
2663 >addk</B
2664 ></SPAN
2665 ></DT
2666 ><DD
2667 ><P
2668 >Is the shortest acceptable abbreviation of <SPAN
2669 CLASS="bold"
2670 ><B
2671 CLASS="emphasis"
2672 >addkey</B
2673 ></SPAN
2674 >.</P
2675 ></DD
2676 ><DT
2677 ><SPAN
2678 CLASS="bold"
2679 ><B
2680 CLASS="emphasis"
2681 >machine name</B
2682 ></SPAN
2683 ></DT
2684 ><DD
2685 ><P
2686 >Names the file server machine on which to define the new key in the <SPAN
2687 CLASS="bold"
2688 ><B
2689 CLASS="emphasis"
2690 >KeyFile</B
2691 ></SPAN
2692 >
2693                   file.</P
2694 ></DD
2695 ><DT
2696 ><SPAN
2697 CLASS="bold"
2698 ><B
2699 CLASS="emphasis"
2700 >-kvno</B
2701 ></SPAN
2702 ></DT
2703 ><DD
2704 ><P
2705 >Specifies the key version number you chose in Step <A
2706 HREF="c20494.html#LIWQ378"
2707 >3</A
2708 >, an integer in the range
2709                   0 (zero) through 255. You must specify the same number in Steps <A
2710 HREF="c20494.html#LIWQ382"
2711 >7</A
2712 >, <A
2713 HREF="c20494.html#LIWQ383"
2714 >8</A
2715 >, and <A
2716 HREF="c20494.html#LIWQ386"
2717 >13</A
2718 >.</P
2719 ></DD
2720 ><DT
2721 ><SPAN
2722 CLASS="bold"
2723 ><B
2724 CLASS="emphasis"
2725 >-noauth</B
2726 ></SPAN
2727 ></DT
2728 ><DD
2729 ><P
2730 >Bypasses mutual authentication with the BOS Server. Include it in case the key emergency is preventing
2731                   successful mutual authentication.</P
2732 ></DD
2733 ><DT
2734 ><SPAN
2735 CLASS="bold"
2736 ><B
2737 CLASS="emphasis"
2738 >afs_password</B
2739 ></SPAN
2740 ></DT
2741 ><DD
2742 ><P
2743 >Is a character string similar to a user password, of any length from one to about 1,000 characters. To
2744                   improve security, make the string as long as is practical, and include nonalphabetic characters.</P
2745 ><P
2746 >Do not type an octal string directly. The BOS Server scrambles the character string into an octal string
2747                   appropriate for use as an encryption key before recording it in the <SPAN
2748 CLASS="bold"
2749 ><B
2750 CLASS="emphasis"
2751 >KeyFile</B
2752 ></SPAN
2753 >
2754                   file.</P
2755 ><P
2756 >Remember the string. You need to use it again in Steps <A
2757 HREF="c20494.html#LIWQ382"
2758 >7</A
2759 >, <A
2760 HREF="c20494.html#LIWQ383"
2761 >8</A
2762 >, and <A
2763 HREF="c20494.html#LIWQ386"
2764 >13</A
2765 >.</P
2766 ></DD
2767 ></DL
2768 ></DIV
2769 ></P
2770 ></LI
2771 ><LI
2772 ><P
2773 ><A
2774 NAME="LIWQ380"
2775 ></A
2776 ><SPAN
2777 CLASS="bold"
2778 ><B
2779 CLASS="emphasis"
2780 >On every database server machine in your cell</B
2781 ></SPAN
2782 > (other than
2783           the system control machine), disable authorization checking as instructed in <A
2784 HREF="c20494.html#HDRWQ373"
2785 >Disabling
2786           Authorization Checking in an Emergency</A
2787 >. Do not repeat the procedure on the system control machine, if it is a
2788           database server machine, because you already disabled authorization checking in Step <A
2789 HREF="c20494.html#LIWQ376"
2790 >1</A
2791 >. (If
2792           you need to learn which machines are database server machines, use the <SPAN
2793 CLASS="bold"
2794 ><B
2795 CLASS="emphasis"
2796 >bos listhosts</B
2797 ></SPAN
2798 >
2799           command as described in <A
2800 HREF="c3025.html#HDRWQ95"
2801 >To locate database server machines</A
2802 >.)</P
2803 ></LI
2804 ><LI
2805 ><P
2806 ><A
2807 NAME="LIWQ381"
2808 ></A
2809 >Wait at least 90 seconds after finishing Step <A
2810 HREF="c20494.html#LIWQ380"
2811 >5</A
2812 >, to allow each
2813           of the database server processes (the Authentication, Backup, Protection and Volume Location Servers) to finish electing a
2814           new sync site. Then issue the <SPAN
2815 CLASS="bold"
2816 ><B
2817 CLASS="emphasis"
2818 >udebug</B
2819 ></SPAN
2820 > command to verify that the election worked properly.
2821           Issue the following commands, substituting each database server machine's name for server machine in turn. Include the
2822           system control machine if it is a database server machine. <PRE
2823 CLASS="programlisting"
2824 >&#13;   # <SPAN
2825 CLASS="bold"
2826 ><B
2827 CLASS="emphasis"
2828 >udebug</B
2829 ></SPAN
2830 > &#60;<VAR
2831 CLASS="replaceable"
2832 >server machine</VAR
2833 >&#62; <SPAN
2834 CLASS="bold"
2835 ><B
2836 CLASS="emphasis"
2837 >buserver</B
2838 ></SPAN
2839 >
2840    # <SPAN
2841 CLASS="bold"
2842 ><B
2843 CLASS="emphasis"
2844 >udebug</B
2845 ></SPAN
2846 > &#60;<VAR
2847 CLASS="replaceable"
2848 >server machine</VAR
2849 >&#62; <SPAN
2850 CLASS="bold"
2851 ><B
2852 CLASS="emphasis"
2853 >kaserver</B
2854 ></SPAN
2855 >
2856    # <SPAN
2857 CLASS="bold"
2858 ><B
2859 CLASS="emphasis"
2860 >udebug</B
2861 ></SPAN
2862 > &#60;<VAR
2863 CLASS="replaceable"
2864 >server machine</VAR
2865 >&#62; <SPAN
2866 CLASS="bold"
2867 ><B
2868 CLASS="emphasis"
2869 >ptserver</B
2870 ></SPAN
2871 >
2872    # <SPAN
2873 CLASS="bold"
2874 ><B
2875 CLASS="emphasis"
2876 >udebug</B
2877 ></SPAN
2878 > &#60;<VAR
2879 CLASS="replaceable"
2880 >server machine</VAR
2881 >&#62; <SPAN
2882 CLASS="bold"
2883 ><B
2884 CLASS="emphasis"
2885 >vlserver</B
2886 ></SPAN
2887 >
2888 </PRE
2889 ></P
2890 ><P
2891 >For each process, the output from all of the database server machines must agree on which one is the sync site for
2892           the process. It is not, however, necessary that the same machine serves as the sync site for each of the four processes.
2893           For each process, the output from only one machine must include the following string:</P
2894 ><PRE
2895 CLASS="programlisting"
2896 >&#13;   I am sync site ...
2897 </PRE
2898 ><P
2899 >The output on the other machines instead includes the following line</P
2900 ><PRE
2901 CLASS="programlisting"
2902 >&#13;   I am not sync site
2903 </PRE
2904 ><P
2905 >and a subsequent line that begins with the string <SAMP
2906 CLASS="computeroutput"
2907 >Sync host</SAMP
2908 > and specifies the IP
2909           address of the machine claiming to be the sync site.</P
2910 ><P
2911 >If the output does not meet these requirements or seems abnormal in another way, contact AFS Product Support for
2912           assistance.</P
2913 ></LI
2914 ><LI
2915 ><P
2916 ><A
2917 NAME="LIWQ382"
2918 ></A
2919 ><SPAN
2920 CLASS="bold"
2921 ><B
2922 CLASS="emphasis"
2923 >On every database server machine in your cell</B
2924 ></SPAN
2925 > (other than
2926           the system control machine), issue the <SPAN
2927 CLASS="bold"
2928 ><B
2929 CLASS="emphasis"
2930 >bos addkey</B
2931 ></SPAN
2932 > command described in Step <A
2933 HREF="c20494.html#LIWQ379"
2934 >4</A
2935 >. Be sure to use the same values for afs_password and kvno as you used in that step.</P
2936 ></LI
2937 ><LI
2938 ><P
2939 ><A
2940 NAME="LIWQ383"
2941 ></A
2942 >Issue the <SPAN
2943 CLASS="bold"
2944 ><B
2945 CLASS="emphasis"
2946 >kas setpassword</B
2947 ></SPAN
2948 > command to define the new key in
2949           the Authentication Database's <SPAN
2950 CLASS="bold"
2951 ><B
2952 CLASS="emphasis"
2953 >afs</B
2954 ></SPAN
2955 > entry. It must match the key you created in Step <A
2956 HREF="c20494.html#LIWQ379"
2957 >4</A
2958 > and Step <A
2959 HREF="c20494.html#LIWQ382"
2960 >7</A
2961 >. <PRE
2962 CLASS="programlisting"
2963 >&#13;   # <SPAN
2964 CLASS="bold"
2965 ><B
2966 CLASS="emphasis"
2967 >kas setpassword  -name afs</B
2968 ></SPAN
2969 >  <SPAN
2970 CLASS="bold"
2971 ><B
2972 CLASS="emphasis"
2973 >-kvno</B
2974 ></SPAN
2975 > &#60;<VAR
2976 CLASS="replaceable"
2977 >key version number</VAR
2978 >&#62; <SPAN
2979 CLASS="bold"
2980 ><B
2981 CLASS="emphasis"
2982 >-noauth</B
2983 ></SPAN
2984 >
2985    new_password: &#60;<VAR
2986 CLASS="replaceable"
2987 >afs_password</VAR
2988 >&#62;
2989    Verifying, please re-enter new_password: &#60;<VAR
2990 CLASS="replaceable"
2991 >afs_password</VAR
2992 >&#62;
2993 </PRE
2994 ></P
2995 ><P
2996 >where <DIV
2997 CLASS="variablelist"
2998 ><DL
2999 ><DT
3000 ><SPAN
3001 CLASS="bold"
3002 ><B
3003 CLASS="emphasis"
3004 >sp</B
3005 ></SPAN
3006 ></DT
3007 ><DD
3008 ><P
3009 >Is an acceptable alias for <SPAN
3010 CLASS="bold"
3011 ><B
3012 CLASS="emphasis"
3013 >setpassword</B
3014 ></SPAN
3015 > (<SPAN
3016 CLASS="bold"
3017 ><B
3018 CLASS="emphasis"
3019 >setp</B
3020 ></SPAN
3021 > is the shortest acceptable abbreviation).</P
3022 ></DD
3023 ><DT
3024 ><SPAN
3025 CLASS="bold"
3026 ><B
3027 CLASS="emphasis"
3028 >-kvno</B
3029 ></SPAN
3030 ></DT
3031 ><DD
3032 ><P
3033 >Is the same key version number you specified in Step <A
3034 HREF="c20494.html#LIWQ379"
3035 >4</A
3036 >.</P
3037 ></DD
3038 ><DT
3039 ><SPAN
3040 CLASS="bold"
3041 ><B
3042 CLASS="emphasis"
3043 >afs_password</B
3044 ></SPAN
3045 ></DT
3046 ><DD
3047 ><P
3048 >Is the same character string you specified as afs_password in Step <A
3049 HREF="c20494.html#LIWQ379"
3050 >4</A
3051 >. It does
3052                   not echo visibly.</P
3053 ></DD
3054 ></DL
3055 ></DIV
3056 ></P
3057 ></LI
3058 ><LI
3059 ><P
3060 ><A
3061 NAME="LIWQ384"
3062 ></A
3063 ><SPAN
3064 CLASS="bold"
3065 ><B
3066 CLASS="emphasis"
3067 >On every database server machine in your cell</B
3068 ></SPAN
3069 > (including the
3070           system control machine if it is a database server machine), reenable authorization checking as instructed in <A
3071 HREF="c20494.html#HDRWQ375"
3072 >Reenabling Authorization Checking in an Emergency</A
3073 >. If the system control machine is not a
3074           database server machine, do not perform this procedure until Step <A
3075 HREF="c20494.html#LIWQ385"
3076 >11</A
3077 >.</P
3078 ></LI
3079 ><LI
3080 ><P
3081 >Repeat Step <A
3082 HREF="c20494.html#LIWQ381"
3083 >6</A
3084 > to verify that each database server process has properly elected a sync
3085           site after being restarted in Step <A
3086 HREF="c20494.html#LIWQ384"
3087 >9</A
3088 >.</P
3089 ></LI
3090 ><LI
3091 ><P
3092 ><A
3093 NAME="LIWQ385"
3094 ></A
3095 ><SPAN
3096 CLASS="bold"
3097 ><B
3098 CLASS="emphasis"
3099 >On the system control machine</B
3100 ></SPAN
3101 > (if it is not a database
3102           server machine), reenable authorization checking as instructed in <A
3103 HREF="c20494.html#HDRWQ375"
3104 >Reenabling Authorization
3105           Checking in an Emergency</A
3106 >. If it is a database server machine, you already performed the procedure in Step <A
3107 HREF="c20494.html#LIWQ384"
3108 >9</A
3109 >.</P
3110 ></LI
3111 ><LI
3112 ><P
3113 ><SPAN
3114 CLASS="bold"
3115 ><B
3116 CLASS="emphasis"
3117 >On all remaining (simple) file server machines</B
3118 ></SPAN
3119 >, disable authorization checking as
3120           instructed in <A
3121 HREF="c20494.html#HDRWQ373"
3122 >Disabling Authorization Checking in an Emergency</A
3123 >.</P
3124 ></LI
3125 ><LI
3126 ><P
3127 ><A
3128 NAME="LIWQ386"
3129 ></A
3130 ><SPAN
3131 CLASS="bold"
3132 ><B
3133 CLASS="emphasis"
3134 >On all remaining (simple) file server machines</B
3135 ></SPAN
3136 >, issue the
3137           <SPAN
3138 CLASS="bold"
3139 ><B
3140 CLASS="emphasis"
3141 >bos addkey</B
3142 ></SPAN
3143 > command described in Step <A
3144 HREF="c20494.html#LIWQ379"
3145 >4</A
3146 >. Be sure to use the
3147           same values for afs_password and kvno as you used in that step.</P
3148 ></LI
3149 ><LI
3150 ><P
3151 ><SPAN
3152 CLASS="bold"
3153 ><B
3154 CLASS="emphasis"
3155 >On all remaining (simple) file server machines</B
3156 ></SPAN
3157 >, reenable authorization checking as
3158           instructed in <A
3159 HREF="c20494.html#HDRWQ375"
3160 >Reenabling Authorization Checking in an Emergency</A
3161 >.</P
3162 ></LI
3163 ></OL
3164 ></DIV
3165 ></DIV
3166 ></DIV
3167 ><DIV
3168 CLASS="NAVFOOTER"
3169 ><HR
3170 ALIGN="LEFT"
3171 WIDTH="100%"><TABLE
3172 SUMMARY="Footer navigation table"
3173 WIDTH="100%"
3174 BORDER="0"
3175 CELLPADDING="0"
3176 CELLSPACING="0"
3177 ><TR
3178 ><TD
3179 WIDTH="33%"
3180 ALIGN="left"
3181 VALIGN="top"
3182 ><A
3183 HREF="c18360.html"
3184 ACCESSKEY="P"
3185 >Prev</A
3186 ></TD
3187 ><TD
3188 WIDTH="34%"
3189 ALIGN="center"
3190 VALIGN="top"
3191 ><A
3192 HREF="book1.html"
3193 ACCESSKEY="H"
3194 >Home</A
3195 ></TD
3196 ><TD
3197 WIDTH="33%"
3198 ALIGN="right"
3199 VALIGN="top"
3200 ><A
3201 HREF="p21471.html"
3202 ACCESSKEY="N"
3203 >Next</A
3204 ></TD
3205 ></TR
3206 ><TR
3207 ><TD
3208 WIDTH="33%"
3209 ALIGN="left"
3210 VALIGN="top"
3211 >Monitoring and Auditing AFS Performance</TD
3212 ><TD
3213 WIDTH="34%"
3214 ALIGN="center"
3215 VALIGN="top"
3216 ><A
3217 HREF="p3023.html"
3218 ACCESSKEY="U"
3219 >Up</A
3220 ></TD
3221 ><TD
3222 WIDTH="33%"
3223 ALIGN="right"
3224 VALIGN="top"
3225 >Managing Client Machines</TD
3226 ></TR
3227 ></TABLE
3228 ></DIV
3229 ></BODY
3230 ></HTML
3231 >