[Cluster-devel] conga/luci/docs user_manual.html

[rmccabe@sourceware.org <rmccabe@sourceware.org>]

CVSROOT:	/cvs/cluster
Module name:	conga
Changes by:	rmccabe at sourceware.org	2007-01-15 20:26:02

Modified files:
	luci/docs      : user_manual.html 

Log message:
	- updated the document to reflect the policy for adding an existing cluster with one or more non-functional nodes
	- clarified the exposition of a man-in-the-middle attack and how to defeat it

Patches:
http://sourceware.org/cgi-bin/cvsweb.cgi/conga/luci/docs/user_manual.html.diff?cvsroot=cluster&r1=1.13&r2=1.14

--- conga/luci/docs/user_manual.html	2007/01/15 20:03:45	1.13
+++ conga/luci/docs/user_manual.html	2007/01/15 20:26:02	1.14
@@ -48,7 +48,7 @@
 
   <ul><li>backup:  This option backs the luci server up to a file.</li>
       <li>restore: This restores a luci site from a backup file.</li>
-      <li>init: This option regenerates ssl certs.</li>
+      <li>init: This option regenerates SSL certs.</li>
       <li>help: Shows usage</li>
   </ul>
     <h4>Logging In</h4>
@@ -113,7 +113,7 @@
   <b>Figure #3: Add a System</b>
   <p/>
   <p/>
-  The fully qualified domain name OR IP Address of the system is entered in the
+  The fully qualified domain name OR IP address of the system is entered in the
   System Hostname field. The root password for the system is entered in the
   adjacent field. As a convenience for adding multiple systems at once, and Add
   Another Entry button is provided. When this button is clicked and at least
@@ -138,13 +138,14 @@
   For most typical datacenter deployments of conga, the luci server will
   reside on a system within the confines of the datacenter network, and 
   the datacenter systems can pretty safely be assumed to be trustworthy.
-  If a luci server is used to connect to systems across the open internet,
-  the user <i>could</i> be vulnerable to a form of security assault known
-  as the 'Man in the Middle' attack; wherein a hostile party spoofs the 
-  hostname or IP address of a system to be added to a luci server.
+  If a luci server is used to connect to systems across the open Internet,
+  the user <i>could</i> be vulnerable to a form of security attack known
+  as a 'Man in the Middle' attack; wherein a hostile party sits between
+  the client and server and intercepts any data exchanged while masquerading
+  to its peers as a legitimate party.
   <p/>
   If the user would like to verify the certificate of a ricci agent before 
-  authenticating to it (avoiding a 'Man in the Middle' form of attack), the 
+  authenticating to it (avoiding a 'Man in the Middle' attack), the 
   checkbox marked <b>Verify system certificates before sending any 
   passwords</b> should be checked. With this box checked, clicking submit 
   retrieves the certificate information for all systems listed, and provides 
@@ -152,7 +153,7 @@
   be sent without the trust box checked. To add the system or systems,
   click the 'Trust' checkboxes for each row desired and click submit again.
    Mousing over the lock icon for 
-  a row entry will display the certificate information for just that system.
+  a row entry will display the certificate information for just that system. It is important to note that in order to defend against this type of attack, the user must know the certificate fingerprints of client systems prior to the initial key exchange. When the client systems are added, the user can then compare the known certificate fingerprints with the fingerprints displayed by the luci server to verify they match. A mismatch indicates the possibility of an attack.
   <p/>
   <img src="./addsys_33.png"/><br/>
   <b>Figure #5: Certificate Verification Page</b>
@@ -174,11 +175,9 @@
   authenticated. The cluster and subsequent nodes are only added after the
   entire list has been submitted with the Submit button, and all nodes
   authenticate.  <p/>
-
+<p>
 If any nodes fail to authenticate, they appear in the list in red font, so that
-  the password can be corrected and the node list submitted again. Luci has a
-  strict policy about adding a cluster to be managed: A cluster cannot be added
-  unless ALL nodes can be reached and authenticated. 
+  the password can be corrected and the node list submitted again. Luci allows an existing cluster to be added even if one or more nodes is down, unreachable or otherwise non-operational. If any nodes are not authenticated at the time their cluster is added, they must be authenticated when possible, via the "Reauthenticate to Storage or Cluster Systems" form in the "Manage Systems" section located in the "Homebase" tab.</p>
   <p/>When a cluster is added to a luci server, all nodes are also added as general systems so that storage may be managed on them. If this is not desired, the individual systems may be removed from luci, while remote cluster management capability is maintained.<p/>
   NOTE: If an administrator desires to create a new cluster, this capability is
   available on the Cluster tab. This task link is only for adding and managing
@@ -329,7 +328,7 @@
   <p/> 
   <p/> 
   The Add a Node page is similar in look and function to the Add a System
-  page available in the Homebase tab. The system hostname of IP Address is
+  page available in the Homebase tab. The system hostname of IP address is
   entered in the appropriate field along with the password for the
   system. Multiple nodes may be added at once. The user is offered the
   chance to verify the certificate for the new node to be added, just as