Remove NoAuth procedures from Admin Guide
[openafs.git] / doc / xml / AdminGuide / auagd014.xml
index 49ca7a9..70dbde2 100644 (file)
           <listitem>
             <para>In addition to using server encryption keys when communicating with clients, the server processes use them to
             protect communications with other server processes. Therefore, all server machines in your cell must have the same
-            version of the <emphasis role="bold">KeyFile</emphasis> file. The easiest way to maintain consistency (if you run the
-            United States edition of AFS) is to use the Update Server to distribute the contents of the system control machine's
+            version of the <emphasis role="bold">KeyFile</emphasis> file. The easiest way to maintain consistency
+            is to use the Update Server to distribute the contents of the system control machine's
             <emphasis role="bold">/usr/afs/etc</emphasis> directory to all of the other server machines. There are two implications:
             <itemizedlist>
                 <listitem>
                   </indexterm>
                 </listitem>
               </itemizedlist></para>
-
-            <para>If you run the international edition of AFS, do not use the Update Server to distribute the contents of the
-            <emphasis role="bold">/usr/afs/etc</emphasis> directory, particularly the <emphasis role="bold">KeyFile</emphasis> file.
-            The data in the file is too sensitive for transfer in unencrypted form, and because of United States government exports
-            regulations the international edition of AFS does not include the necessary encryption routines in a form that the
-            Update Server can use. You must instead modify the file on each server machine individually, taking care to enter the
-            same key on every server machine.</para>
           </listitem>
 
           <listitem>
       output is complete.</para>
 
       <programlisting>
-   % <emphasis role="bold">bos listkeys fs1.abc.com</emphasis>
+   % <emphasis role="bold">bos listkeys fs1.example.com</emphasis>
    key 0 has cksum 972037177
    key 1 has cksum 2825165022
    Keys last changed on Wed Jan 13 11:20:29 1999. 
 </programlisting></para>
         </listitem>
 
-        <listitem>
-          <para><anchor id="LIWQ364" />Issue the <emphasis role="bold">bos listkeys</emphasis> command to display the key version
+        <listitem id="LIWQ364">
+          <para>Issue the <emphasis role="bold">bos listkeys</emphasis> command to display the key version
           numbers that are already in use, as a first step in choosing the key version number for the new key. <programlisting>
    % <emphasis role="bold">bos listkeys</emphasis> &lt;<replaceable>machine name</replaceable>&gt;
 </programlisting></para>
             </variablelist></para>
         </listitem>
 
-        <listitem>
-          <para><anchor id="LIWQ365" />Choose a key version number for the new key, based on the output from Step <link
+        <listitem id="LIWQ365">
+          <para>Choose a key version number for the new key, based on the output from Step <link
           linkend="LIWQ364">2</link> and the following requirements: <itemizedlist>
               <listitem>
                 <para>A key version number must be an integer between 0 (zero) and 255 to comply with Kerberos standards. It is
           </indexterm>
         </listitem>
 
-        <listitem>
-          <para><anchor id="LIWQ366" />Issue the <emphasis role="bold">bos addkey</emphasis> command to create a new AFS server
+        <listitem id="LIWQ366">
+          <para>Issue the <emphasis role="bold">bos addkey</emphasis> command to create a new AFS server
           encryption key in the <emphasis role="bold">KeyFile</emphasis> file.</para>
 
-          <para>If you run the United States edition of AFS and use the Update Server to distribute the contents of the system
+          <para>If you use the Update Server to distribute the contents of the system
           control machine's <emphasis role="bold">/usr/afs/etc</emphasis> directory, substitute the system control machine for the
           machine name argument. (If you have forgotten which machine is the system control machine, see <link linkend="HDRWQ96">To
           locate the system control machine</link>.)</para>
 
-          <para>If you run the international edition of AFS or do not use the Update Server, repeat the <emphasis role="bold">bos
-          addkey</emphasis> command, substituting each server machine in your cell for the machine name argument in turn.</para>
-
           <para>To avoid visible echoing of the string that corresponds to the new key, omit the <emphasis
           role="bold">-key</emphasis> argument from the command line; instead enter the string at the prompts that appear when you
           omit it, as shown in the following syntax specification.</para>
                 <listitem>
                   <para>Specifies the new key's key version number as an integer from the range 0 (zero) through 255.</para>
 
-                  <para>Remember the number. You need to use it again in Step <link linkend="LIWQ367">6</link>. If you are using the
-                  international edition of AFS, be sure to type the same number each time you issue this command.</para>
+                  <para>Remember the number. You need to use it again in Step <link linkend="LIWQ367">6</link>.</para>
                 </listitem>
               </varlistentry>
 
                 <listitem>
                   <para>Is a character string similar to a user password, of any length from one to about 1,000 characters. To
                   improve security, include nonalphabetic characters and make the string as long as is practical (you need to type
-                  it only in this step and in Step <link linkend="LIWQ367">6</link>). If you are using the international edition of
-                  AFS, be sure to type the same string each time you issue this command.</para>
+                  it only in this step and in Step <link linkend="LIWQ367">6</link>).</para>
 
                   <para>Do not enter an octal string directly. The BOS Server scrambles the character string into an octal string
                   appropriate for use as an encryption key before recording it in the <emphasis role="bold">KeyFile</emphasis>
           </indexterm>
         </listitem>
 
-        <listitem>
-          <para><anchor id="LIWQ367" />Issue the <emphasis role="bold">kas setpassword</emphasis> command to enter the same key in
+        <listitem id="LIWQ367">
+          <para>Issue the <emphasis role="bold">kas setpassword</emphasis> command to enter the same key in
           the <emphasis role="bold">afs</emphasis> entry in the Authentication Database.</para>
 
           <para>The Authentication Server performs its own authentication rather than accepting your existing AFS token. By default,
           <para>Issue the <emphasis role="bold">bos removekey</emphasis> command to remove one or more server encryption keys from
           the <emphasis role="bold">KeyFile</emphasis> file.</para>
 
-          <para>If you run the United States edition of AFS and use the Update Server to distribute the contents of the system
+          <para>If you use the Update Server to distribute the contents of the system
           control machine's <emphasis role="bold">/usr/afs/etc</emphasis> directory, substitute the system control machine for the
           machine name argument. (If you have forgotten which machine is the system control machine, see <link linkend="HDRWQ96">To
           locate the system control machine</link>.)</para>
 
-          <para>If you run the international edition of AFS or do not use the Update Server, repeat the <emphasis role="bold">bos
-          removekey</emphasis> command, substituting each server machine in your cell for the machine name argument in turn.</para>
-
           <programlisting>
    % <emphasis role="bold">bos removekey</emphasis> &lt;<replaceable>machine name</replaceable>&gt; &lt;<replaceable>key version number</replaceable>&gt;
 </programlisting>
     Database and the <emphasis role="bold">KeyFile</emphasis> file on every server machine, so that the TGS and all server processes
     again share the same key.</para>
 
-    <para>Handling key emergencies requires some unusual actions. The reasons for these actions are explained in the following
-    sections; the actual procedures appear in the subsequent instructions.</para>
-
-    <sect2 id="HDRWQ371">
-      <title>Prevent Mutual Authentication</title>
-
-      <para>It is necessary to prevent the server processes from trying to mutually authenticate with you as you deal with a key
-      emergency, because they possibly cannot decrypt your token. When you do not mutually authenticate, the server processes assign
-      you the identity <emphasis role="bold">anonymous</emphasis>. To prevent mutual authentication, use the <emphasis
-      role="bold">unlog</emphasis> command to discard your tokens and include the <emphasis role="bold">-noauth</emphasis> flag on
-      every command where it is available.</para>
-    </sect2>
-
-    <sect2 id="Header_423">
-      <title>Disable Authorization Checking by Hand</title>
-
-      <para>Because the server processes recognize you as the user <emphasis role="bold">anonymous</emphasis> when you do not
-      mutually authenticate, you must turn off authorization checking. Only with authorization checking disabled do the server
-      processes allow the <emphasis role="bold">anonymous</emphasis> user to perform privileged actions such as key creation.</para>
-
-      <para>In an emergency, disable authorization checking by creating the file <emphasis
-      role="bold">/usr/afs/local/NoAuth</emphasis> by hand. In normal circumstances, use the <emphasis role="bold">bos
-      setauth</emphasis> command instead.</para>
-    </sect2>
-
-    <sect2 id="Header_424">
-      <title>Work Quickly on Each Machine</title>
-
-      <para>Disabling authorization checking is a serious security exposure, because server processes on the affected machine
-      perform any action for anyone. Disable authorization checking only for as long as necessary, completing all steps in an
-      uninterrupted session and as quickly as possible.</para>
-    </sect2>
-
-    <sect2 id="Header_425">
-      <title>Work at the Console</title>
-
-      <para>Working at the console of each server machine on which you disable authorization checking ensures that no one else logs
-      onto the console while you are working there. It does not prevent others from connecting to the machine remotely (using the
-      <emphasis role="bold">telnet</emphasis> program, for example), which is why it is important to work quickly. The only way to
-      ensure complete security is to disable network traffic, which is not a viable option in many environments. You can improve
-      security in general by limiting the number of people who can connect remotely to your server machines at any time, as
-      recommended in <link linkend="HDRWQ74">Improving Security in Your Cell</link>.</para>
-    </sect2>
-
-    <sect2 id="HDRWQ372">
-      <title>Change Individual KeyFile Files</title>
-
-      <para>If you use the Update Server to distribute the contents of the <emphasis role="bold">/usr/afs/etc</emphasis> directory,
-      an emergency is the only time when it is appropriate to change the <emphasis role="bold">KeyFile</emphasis> file on individual
-      machines instead. Updating each machine's file is necessary because mismatched keys can prevent the system control machine's
-      <emphasis role="bold">upserver</emphasis> process from mutually authenticating with <emphasis
-      role="bold">upclientetc</emphasis> processes on other server machines, in which case the <emphasis
-      role="bold">upserver</emphasis> process refuses to distribute its <emphasis role="bold">KeyFile</emphasis> file to
-      them.</para>
-
-      <para>Even if it appears that the Update Server is working correctly, the only way to verify that is to change the key on the
-      system control machine and wait the standard delay period to see if the <emphasis role="bold">upclientetc</emphasis> processes
-      retrieve the key. During an emergency, it does not usually make sense to wait the standard delay period. It is more efficient
-      simply to update the file on each server machine separately. Also, even if the Update Server can distribute the file
-      correctly, other processes can have trouble because of mismatched keys. The following instructions add the new key file on the
-      system control machine first. If the Update Server is working, then it is distributing the same change as you are making on
-      each server machine individually.</para>
-
-      <para>If your cell does not use the Update Server, or uses the international edition of AFS, you always change keys on server
-      machines individually. The following instructions are also appropriate for you.</para>
-    </sect2>
-
-    <sect2 id="Header_427">
-      <title>Two Component Procedures</title>
-
-      <para>There are two subprocedures used frequently in the following instructions: disabling authorization checking and
-      reenabling it. For the sake of clarity, the procedures are detailed here; the instructions refer to them as necessary.</para>
-
-      <sect3 id="HDRWQ373">
-        <title>Disabling Authorization Checking in an Emergency</title>
-
-        <orderedlist>
-          <listitem>
-            <para>Become the local superuser <emphasis role="bold">root</emphasis> on the machine, if you are not already, by
-            issuing the <emphasis role="bold">su</emphasis> command. <programlisting>
-   % <emphasis role="bold">su root</emphasis>
-   Password: &lt;<replaceable>root_password</replaceable>&gt;
-</programlisting></para>
-
-            <indexterm>
-              <primary>NoAuth file</primary>
-
-              <secondary>creating in emergencies</secondary>
-            </indexterm>
-          </listitem>
-
-          <listitem>
-            <para><anchor id="LIWQ374" />Create the file <emphasis role="bold">/usr/afs/local/NoAuth</emphasis> to disable
-            authorization checking. <programlisting>
-   # <emphasis role="bold">touch /usr/afs/local/NoAuth</emphasis>
-</programlisting></para>
-
-            <indexterm>
-              <primary>unlog command</primary>
-
-              <secondary>when handling key emergency</secondary>
-            </indexterm>
-          </listitem>
-
-          <listitem>
-            <para>Discard your tokens, in case they were sealed with an incompatible key, which can prevent some commands from
-            executing. <programlisting>
-   # <emphasis role="bold">unlog</emphasis>
-</programlisting></para>
-          </listitem>
-        </orderedlist>
-      </sect3>
-
-      <sect3 id="HDRWQ375">
-        <title>Reenabling Authorization Checking in an Emergency</title>
-
-        <orderedlist>
-          <listitem>
-            <para>Become the local superuser <emphasis role="bold">root</emphasis> on the machine, if you are not already, by
-            issuing the <emphasis role="bold">su</emphasis> command. <programlisting>
-   % <emphasis role="bold">su root</emphasis>
-   Password: &lt;<replaceable>root_password</replaceable>&gt;
-</programlisting></para>
-          </listitem>
-
-          <listitem>
-            <para>Remove the <emphasis role="bold">/usr/afs/local/NoAuth</emphasis> file. <programlisting>
-   # <emphasis role="bold">rm /usr/afs/local/NoAuth</emphasis>
-</programlisting></para>
-
-            <indexterm>
-              <primary>klog command</primary>
-
-              <secondary>when handling key emergency</secondary>
-            </indexterm>
-          </listitem>
-
-          <listitem>
-            <para>Authenticate as an administrative identity that belongs to the <emphasis
-            role="bold">system:administrators</emphasis> group and is listed in the <emphasis
-            role="bold">/usr/afs/etc/UserList</emphasis> file. <programlisting>
-   # <emphasis role="bold">klog</emphasis> &lt;<replaceable>admin_user</replaceable>&gt;
-   Password: &lt;<replaceable>admin_password</replaceable>&gt;
-</programlisting></para>
-          </listitem>
-
-          <listitem>
-            <para>If appropriate, log out from the console (or close the remote connection you are using), after issuing the
-            <emphasis role="bold">unlog</emphasis> command to destroy your tokens.</para>
-          </listitem>
-        </orderedlist>
-      </sect3>
+    <para>Installing a new server encryption key involves logging in to each
+    server machine as root and confirming that the correct (i.e., new) key
+    are in place in the <emphasis role="bold">KeyFileExt</emphasis> or
+    <emphasis role="bold">rxkad.keytab</emphasis> (for OpenAFS 1.8.x
+    releases).  The same keys must be installed on all servers in the cell,
+    and when Kerberos is used for authentication, must match the key in the
+    Kerberos database.</para>
+
+    <para>While the keys are being installed, remote operations using
+    regular authentication mechanisms, even with administrator credentials,
+    may (continue to) fail.  Similarly, the ubik synchronization protocol
+    among database servers may fail to synchronize due to the servers not
+    being able to authenticate each other, making write operations to the
+    database impossible.  In order to interact with individual server
+    processes, the <emphasis role="bold">-localauth</emphasis> flag is used,
+    allowing commands that are run on a system that has the cell's key (such
+    as the server itself) to successfully authenticate as an administrator.
+    Once the new keys are installed on all database servers and the
+    90-second ubik recovery time has passed, the database servers should have
+    elected a new coordinator, allowing write transactions to proceed
+    again.</para>
     </sect2>
 
     <sect2 id="Header_430">
       <title>To create a new server encryption key in emergencies</title>
 
       <orderedlist>
-        <listitem>
-          <para><anchor id="LIWQ376" /><emphasis role="bold">On the system control machine</emphasis>, disable authorization
+        <listitem id="LIWQ376">
+          <para><emphasis role="bold">On the system control machine</emphasis>, disable authorization
           checking as instructed in <link linkend="HDRWQ373">Disabling Authorization Checking in an Emergency</link>.</para>
         </listitem>
 
-        <listitem>
-          <para><anchor id="LIWQ377" />Issue the <emphasis role="bold">bos listkeys</emphasis> command to display the key version
+        <listitem id="LIWQ377">
+          <para>Issue the <emphasis role="bold">bos listkeys</emphasis> command to display the key version
           numbers already in use in the <emphasis role="bold">KeyFile</emphasis> file, as a first step in choosing the new key's key
           version number. <programlisting>
    # <emphasis role="bold">bos listkeys</emphasis> &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">-noauth</emphasis>
             </variablelist></para>
         </listitem>
 
-        <listitem>
-          <para><anchor id="LIWQ378" />Choose a key version number for the new key, based on what you learned in Step <link
+        <listitem id="LIWQ378">
+          <para>Choose a key version number for the new key, based on what you learned in Step <link
           linkend="LIWQ377">2</link> plus the following requirements: <itemizedlist>
               <listitem>
                 <para>It is best to keep your key version numbers in sequence by choosing a key version number one greater than the
           </indexterm>
         </listitem>
 
-        <listitem>
-          <para><anchor id="LIWQ379" /><emphasis role="bold">On the system control machine</emphasis>, issue the <emphasis
+        <listitem id="LIWQ379">
+          <para><emphasis role="bold">On the system control machine</emphasis>, issue the <emphasis
           role="bold">bos addkey</emphasis> command to create a new AFS server encryption key in the <emphasis
           role="bold">KeyFile</emphasis> file. <programlisting>
    # <emphasis role="bold">bos addkey</emphasis> &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">-kvno</emphasis> &lt;<replaceable>key version number</replaceable>&gt; <emphasis
             </variablelist></para>
         </listitem>
 
-        <listitem>
-          <para><anchor id="LIWQ380" /><emphasis role="bold">On every database server machine in your cell</emphasis> (other than
+        <listitem id="LIWQ380">
+          <para><emphasis role="bold">On every database server machine in your cell</emphasis> (other than
           the system control machine), disable authorization checking as instructed in <link linkend="HDRWQ373">Disabling
           Authorization Checking in an Emergency</link>. Do not repeat the procedure on the system control machine, if it is a
           database server machine, because you already disabled authorization checking in Step <link linkend="LIWQ376">1</link>. (If
           command as described in <link linkend="HDRWQ95">To locate database server machines</link>.)</para>
         </listitem>
 
-        <listitem>
-          <para><anchor id="LIWQ381" />Wait at least 90 seconds after finishing Step <link linkend="LIWQ380">5</link>, to allow each
+        <listitem id="LIWQ381">
+          <para>Wait at least 90 seconds after finishing Step <link linkend="LIWQ380">5</link>, to allow each
           of the database server processes (the Authentication, Backup, Protection and Volume Location Servers) to finish electing a
           new sync site. Then issue the <emphasis role="bold">udebug</emphasis> command to verify that the election worked properly.
           Issue the following commands, substituting each database server machine's name for server machine in turn. Include the
           assistance.</para>
         </listitem>
 
-        <listitem>
-          <para><anchor id="LIWQ382" /><emphasis role="bold">On every database server machine in your cell</emphasis> (other than
+        <listitem id="LIWQ382">
+          <para><emphasis role="bold">On every database server machine in your cell</emphasis> (other than
           the system control machine), issue the <emphasis role="bold">bos addkey</emphasis> command described in Step <link
           linkend="LIWQ379">4</link>. Be sure to use the same values for afs_password and kvno as you used in that step.</para>
 
           </indexterm>
         </listitem>
 
-        <listitem>
-          <para><anchor id="LIWQ383" />Issue the <emphasis role="bold">kas setpassword</emphasis> command to define the new key in
+        <listitem id="LIWQ383">
+          <para>Issue the <emphasis role="bold">kas setpassword</emphasis> command to define the new key in
           the Authentication Database's <emphasis role="bold">afs</emphasis> entry. It must match the key you created in Step <link
           linkend="LIWQ379">4</link> and Step <link linkend="LIWQ382">7</link>. <programlisting>
    # <emphasis role="bold">kas setpassword  -name afs</emphasis>  <emphasis role="bold">-kvno</emphasis> &lt;<replaceable>key version number</replaceable>&gt; <emphasis
             </variablelist></para>
         </listitem>
 
-        <listitem>
-          <para><anchor id="LIWQ384" /><emphasis role="bold">On every database server machine in your cell</emphasis> (including the
+        <listitem id="LIWQ384">
+          <para><emphasis role="bold">On every database server machine in your cell</emphasis> (including the
           system control machine if it is a database server machine), reenable authorization checking as instructed in <link
           linkend="HDRWQ375">Reenabling Authorization Checking in an Emergency</link>. If the system control machine is not a
           database server machine, do not perform this procedure until Step <link linkend="LIWQ385">11</link>.</para>
           site after being restarted in Step <link linkend="LIWQ384">9</link>.</para>
         </listitem>
 
-        <listitem>
-          <para><anchor id="LIWQ385" /><emphasis role="bold">On the system control machine</emphasis> (if it is not a database
+        <listitem id="LIWQ385">
+          <para><emphasis role="bold">On the system control machine</emphasis> (if it is not a database
           server machine), reenable authorization checking as instructed in <link linkend="HDRWQ375">Reenabling Authorization
           Checking in an Emergency</link>. If it is a database server machine, you already performed the procedure in Step <link
           linkend="LIWQ384">9</link>.</para>
           instructed in <link linkend="HDRWQ373">Disabling Authorization Checking in an Emergency</link>.</para>
         </listitem>
 
-        <listitem>
-          <para><anchor id="LIWQ386" /><emphasis role="bold">On all remaining (simple) file server machines</emphasis>, issue the
+        <listitem id="LIWQ386">
+          <para><emphasis role="bold">On all remaining (simple) file server machines</emphasis>, issue the
           <emphasis role="bold">bos addkey</emphasis> command described in Step <link linkend="LIWQ379">4</link>. Be sure to use the
           same values for afs_password and kvno as you used in that step.</para>
         </listitem>
       </orderedlist>
     </sect2>
   </sect1>
-</chapter>
\ No newline at end of file
+</chapter>