password lookup plugin, with working tests and documentation

docsite/rst/playbooks2.rst

@@ -209,14 +209,14 @@ some other options, but otherwise works equivalently::
        prompt: "Product release version"
        private: no
 
-If `Passlib <http://pythonhosted.org/passlib/>`_ is installed, vars_prompt can also crypt the 
+If `Passlib <http://pythonhosted.org/passlib/>`_ is installed, vars_prompt can also crypt the
 entered value so you can use it, for instance, with the user module to define a password::
 
    vars_prompt:
      - name: "my_password2"
        prompt: "Enter password2"
        private: yes
-       encrypt: "md5_crypt" 
+       encrypt: "md5_crypt"
        confirm: yes
        salt_size: 7
 
@@ -241,7 +241,7 @@ You can use any crypt scheme supported by `Passlib <http://pythonhosted.org/pass
 - *bsd_nthash* - FreeBSD’s MCF-compatible nthash encoding
 
 However, the only parameters accepted are 'salt' or 'salt_size'. You can use you own salt using
-'salt', or have one generated automatically using 'salt_size'. If nothing is specified, a salt 
+'salt', or have one generated automatically using 'salt_size'. If nothing is specified, a salt
 of size 8 will be generated.
 
 Passing Variables On The Command Line
@@ -605,6 +605,44 @@ Negative numbers are not supported.  This works as follows::
         - group: name=group${item} state=present
           with_sequence: count=4
 
+.. versionadded: 1.1
+
+'with_password' and associated macro "$PASSWORD" generate a random plaintext password and store it in
+a file at a given filepath. If the file exists previously, "$PASSWORD"/'with_password' will retrieve its contents,
+behaving just like $FILE/'with_file'.
+
+Generated passwords contain a random mix of upper and lower case letters in the ASCII alphabets, the
+numbers 0-9 and the punctuation signs ".,:-_". The default length of a generated password is 30 characters.
+This gives us ~ 180 bits of entropy. However, this length can be changed by passing an extra parameter.
+
+This is how it all works, with an exemplary use case, which is generating a different random password for every
+mysql database in a given server pool:
+
+    ---
+    - hosts: all
+
+      tasks:
+
+        # create a mysql user with a random password:
+        - mysql_user: name=$client
+                      password=$PASSWORD(credentials/$client/$tier/$role/mysqlpassword)
+                      priv=$client_$tier_$role.*:ALL
+
+        (...)
+
+        # dump a mysql database with a given password
+        - mysql_db: name=$client_$tier_$role
+                    login_user=$client
+                    login_password=$item
+                    state=dump
+                    target=/tmp/$client_$tier_$role_backup.sql
+          with_password: credentials/$client/$tier/$role/mysqlpassword
+
+        # make a longer or shorter password by appending a length parameter:
+        - mysql_user: name=who_cares
+                      password=$item
+          with_password: files/same/password/everywhere length=4
+
 Setting the Environment (and Working With Proxies)
 ``````````````````````````````````````````````````
 
@@ -1013,7 +1051,7 @@ number of modules (the CloudFormations module is one) actually require complex a
 You can of course use variables inside these, as noted above.
 
 If using local_action, you can do this::
-      
+
     - name: call a module that requires some complex arguments
       local_action:
         module: foo_module