javadoc and code tidy around admin/user setup

scriptbuilder/src/main/java/org/jclouds/scriptbuilder/statements/login/AdminAccess.java

@@ -46,17 +46,26 @@ import com.google.inject.ImplementedBy;
  * Controls the administrative access to a node. By default, it will perform the following:
  * 
  * <ul>
- * <li>setup a new admin user which folks should use as opposed to the built-in vcloud account</li>
+ *   <li>setup a new admin user which folks should use as opposed to any built-in account</li>
- * <ul>
+ *   <ul>
- * <li>associate a random password to account</li>
+ *     <li>associate a random (or given) password to that account
- * <ul>
+ *     <ul>
- * <li>securely ( use sha 512 on client side and literally rewrite the shadow entry, rather than
+ *       <li>securely (using sha 512 on client side and literally rewriting the shadow entry, 
- * pass password to OS in a script )</li>
+ *           rather than sending password plaintext to OS in a script)</li>
+ *       <li>but note password access is often blocked in any case, see below</li>
+ *     </ul>
+ *     <li>associate the users' ssh public key with the account for login</li> 
+ *     <li>associate it with the os group wheel</li> 
+ *   </ul> 
+ *   <li>set up sudoers for password-less access to root for this user (shouldGrantSudo)</li>
+ *   <ul>
+ *     <li>creating os group wheel and assigning the new admin user to it</li> 
+ *     <li>create (overwriting) sudoers file to grant root access for wheel members</li>
+ *   </ul>
+ *   <li>reset password for the user logging in (e.g. root, because root password is 
+ *   sometimes known to the provider), securely and randomly as described above (resetLoginPassword)</li>
+ *   <li>lockdown sshd_config for no root login, nor passwords allowed (lockSsh)</li> 
  * </ul>
- * <li>associate the users' ssh public key with the account for login</li> <li>
- * associate it with the os group wheel</li> </ul> <li>create os group wheel</li> <li>add sudoers
- * for nopassword access to root by group wheel</li> <li>reset root password securely</li> <li>
- * lockdown sshd_config for no root login, nor passwords allowed</li> </ul>
  * 
  * @author Adrian Cole
  */

scriptbuilder/src/main/java/org/jclouds/scriptbuilder/statements/login/DefaultConfiguration.java

@@ -51,9 +51,9 @@ public class DefaultConfiguration implements Configuration {
       @Override
       public Map<String, String> get() {
          try {
-            return ImmutableMap.of("public",
+            return ImmutableMap.of(
-                  Files.toString(new File(System.getProperty("user.home") + "/.ssh/id_rsa.pub"), UTF_8), "private",
+                  "public", Files.toString(new File(System.getProperty("user.home") + "/.ssh/id_rsa.pub"), UTF_8), 
-                  Files.toString(new File(System.getProperty("user.home") + "/.ssh/id_rsa"), UTF_8));
+                  "private", Files.toString(new File(System.getProperty("user.home") + "/.ssh/id_rsa"), UTF_8));
          } catch (IOException e) {
             return SshKeys.generate();
          }

scriptbuilder/src/main/java/org/jclouds/scriptbuilder/statements/login/UserAdd.java

@@ -43,6 +43,13 @@ import com.google.common.collect.Lists;
 import com.google.inject.Inject;
 
 /**
+ * Creates a statement that will add a given user to a machine ("login"), with optional 
+ * password, groups, private key, and authorized keys.
+ * <p>
+ * This is supported on most *nix environments. Not currently supported on Windows.
+ * <p>
+ * Note that some places where this is used may have stricter requirements on the parameters
+ * (for example {@link AdminAccess} requires password and keys).  
  * 
  * @author Adrian Cole
  */
@@ -65,11 +72,13 @@ public class UserAdd implements Statement {
          return this;
       }
 
+      /** the username of the user to add (not the login to use when performing the add) */
       public UserAdd.Builder login(String login) {
          this.login = login;
          return this;
       }
 
+      /** the password to add for the user (not the password to use when logging in to perform the add) */
       public UserAdd.Builder password(String password) {
          this.password = password;
          return this;