misc doc updates for 0.5

rst/bestpractices.rst

@@ -72,6 +72,12 @@ Until then, to manage your entire site, simply execute all of your playbooks tog
 You don't have to do this though. It's fine to select sections of your infrastructure to manage at a single time.
 You may wish to construct simple shell scripts to wrap calls to ansible-playbook.
 
+Bundling Ansible Modules With Playbooks
++++++++++++++++++++++++++++++++++++++++
+
+In version 0.5 and later, if a playbook has a "./library" directory relative to it's YAML file, this directory can be used to add ansible modules that will automatically be in the ansible module path.  This is a great way to keep modules that
+go with a playbook together.
+
 Miscellaneous Tips
 ++++++++++++++++++
 

rst/faq.rst

@@ -50,8 +50,7 @@ vs Func?
 Ansible uses SSH by default instead of SSL and custom daemons, and requires
 no extra software to run on managed machines.  You can also write modules
 in any language as long as they return JSON.  Ansible's API, of course, is
-heavily inspired by Func.   Some features, like delegation hierarchies, are
+heavily inspired by Func.   Ansible also adds
-not supported, but Ansible does have an async mode.  Ansible also adds
 a configuration management and multinode orchestration layer (:doc:`playbooks`) 
 that Func didn't have.
 
@@ -70,7 +69,7 @@ There is no central server subject to thundering herd problems, and Ansible is
 also designed with multi-node deployment in mind from day-one -- something that is difficult
 for Puppet because of the pull architecture.  Ansible is push based,
 so you can do things in an ordered fashion, addressing batches of servers
-at one time, and you do not have to contend with the DAG.  It's also extensible in any language
+at one time, and you do not have to contend with the dependency graph.  It's also extensible in any language
 and the source is designed so that you don't have to be an expert programmer to submit a patch.
 
 Ansible's resources are heavily inspired by Puppet, with the "state" keyword being a more or less
@@ -167,10 +166,13 @@ Ansible, it is not consuming any resources, and you don't have to contend
 with a herd of machines all knocking at the door of your management server
 all at once.
 
-If you have 10,000 systems, running a single ansible playbook against all of
+The SSH connection type (paramiko is the default, binary openssh is an option) 
-them probably isn't appropriate, which is why ansible-pull exists.
+can also make use of "ControlMaster" features in SSH, which reuses network
+connections.
 
-This tool is designed for running out of git and cron, and can scale to any
+If you have 10,000 systems, running a single ansible playbook against all of
+them probably isn't appropriate, which is why ansible-pull exists.  This tool 
+is designed for running out of git and cron, and can scale to any
 number of hosts.  Ansible-pull uses local connections versus SSH, but can be
 easily bootstrapped or reconfigured just using SSH.  There is more information
 available about this in the :doc:`playbooks2` section.  The self-bootstrapping
@@ -182,8 +184,8 @@ If you'd like to discuss scaling strategies further, please hop on the mailing l
 Are transports other than SSH supported?
 ++++++++++++++++++++++++++++++++++++++++
 
-Currently SSH and local connections are supported.  In 0.5, we'll also be including
+Currently SSH (you can choose between paramiko or the openssh binaries)
-a faster SSH transport.  The interface is actually pluggable so a 
+and local connections are supported.  The interface is actually pluggable so a 
 small patch could bring transport over message bus or XMPP as an option.
 
 Stop by the mailing list if you have ideas.  The connection-specific parts of Ansible

rst/gettingstarted.rst

@@ -21,7 +21,7 @@ also need:
 
 * ``python-simplejson`` 
 
-NOTE: Ansible 0.4 will have ways to remote bootstrap this, using Ansible itself.  Stay tuned.
+(Note that even that's not quite true.  Ansible's "raw" module (for executing commands in a quick and dirty way) and the copy module -- some of the most basic features in ansible don't even need that.  So technically, you can use Ansible to install python-simplejson using the raw module, which then allows you to use everything else.  That's jumping ahead though.)
 
 Python 2.6 EPEL instructions for RHEL and CentOS 5
 ``````````````````````````````````````````````````
@@ -128,6 +128,24 @@ project page:
 
 * `Ansible/downloads <https://github.com/ansible/ansible/downloads>`_
 
+Choosing Between Paramiko and Native SSH
+````````````````````````````````````````
+
+By default, ansible uses paramiko to talk to managed nodes over SSH.  Paramiko is fast, works
+very transparently, requires no configuration, and is a good choice for most users.
+However, it does not support some advanced SSH features that folks will want to use.
+
+Starting in version 0.5, if you want to leverage more advanced SSH features (such as Kerberized SSH or jump hosts), 
+pass the flag "--connection=ssh" to any ansible command, or set the
+ANSIBLE_TRANSPORT environment variable to 'ssh'. This will cause Ansible to use openssh
+tools instead.  
+
+If ANSIBLE_SSH_ARGS are not set, ansible will try to use some sensible ControlMaster options
+by default.  You are free to override this environment variable, but should still pass ControlMaster
+options to ensure performance of this transport.  With ControlMaster in use, both transports
+are roughly the same speed.  Without CM, the binary ssh transport is signficantly slower.
+
+If none of this makes sense to you, the default paramiko option is probably fine.
 
 Your first commands
 ```````````````````
@@ -146,10 +164,24 @@ Set up SSH agent to avoid retyping passwords::
     ssh-agent bash
     ssh-add ~/.ssh/id_rsa
 
+(Depending on your setup, you may wish to ansible's --private-key-file option to specify a pem file instead)
+
 Now ping all your nodes::
 
     ansible all -m ping
 
+If you want to access machines remotely as a different user than root, you will want to 
+specify the '-u' option to ansible.  If you would like to access sudo mode, there are also flags to do that::
+
+    # as bruce
+    ansible all -m ping -u bruce
+
+    # as bruce, sudoing to root
+    ansible all -m ping -u bruce --sudo 
+  
+    # as bruce, sudoing to batman
+    ansible all -m ping -u bruce --sudo --sudo-user batman
+
 Now run a live command on all of your nodes::
   
     ansible all -a "/bin/echo hello"

rst/index.rst

@@ -7,7 +7,7 @@ and command execution framework. Other tools in this space have been too
 complicated for too long, require too much bootstrapping, and have too
 much learning curve.  Ansible is dead simple and painless to extend.
 For comparison, Puppet and Chef have about 60k lines of code. 
-Ansible's core is a little over 1000 lines.
+Ansible's core is a little over 2000 lines..
 
 Ansible isn't just for idempotent configuration -- it's also great for ad-hoc
 tasks, quickly firing off commands against nodes.  See :doc:`examples`.
@@ -68,6 +68,7 @@ Features
 * Dead simple setup
 * Super fast & parallel by default
 * No server or client daemons; use existing SSHd out of the box
+* Supports Kerberized SSH, jump hosts, forwarding, etc
 * No additional software required on client boxes
 * Can be easily run from a checkout, no installation required
 * Modules are idempotent, but you can also easily use shell commands

rst/modules.rst

@@ -73,8 +73,56 @@ Example action from Ansible :doc:`playbooks`::
     apt pkg=foo=1.00 state=installed
     apt pkg=nginx state=latest default-release=squeeze-backports update-cache=yes
 
+. _assemble:
+
+assemble
+````````
+
+(new in 0.5) Assembles a configuration file from fragments.   Often a particular program will take a single configuration file
+and does not support a conf.d style structure where it is easy to build up the configuration from multiple sources.
+Assmeble will take a directory of files that have already been transferred to the system, and concatenate them
+together to produce a destination file.  Files are assembled in string sorting order.   Puppet calls this idea
+"fragments".
+
+*src*:
+
+* An already existing directory full of source files.
+
+*dest*:
+
+* A file to create using the concatenation of all of the source files.
+
+Example action from Ansible :doc:`playbooks`::
+
+    assemble src=/etc/someapp/fragments dest=/etc/someapp/someapp.conf
+
+
+_authorized_key:
+
+authorized_key
+``````````````
+
+(new in 0.5).  Adds or removes an authorized key for a user from a remote host.
+
+*user*:
+
+* Name of the user who access is being granted or remoted to.
+
+*state*:
+
+* Either 'absent' or 'present', this is whether the given key should be in the authorized keys file or not.
+
+*key*:
+
+* The actual key, as a string.  
+
+Example action from Ansible :doc:`playbooks`::
+
+    authorized_key user=charlie key="ssh-dss ASDF1234L+8BTwaRYr/rycsBF1D8e5pTxEsXHQs4iq+mZdyWqlW++L6pMiam1A8yweP+rKtgjK2httVS6GigVsuWWfOd7/sdWippefq74nppVUELHPKkaIOjJNN1zUHFoL/YMwAAAEBALnAsQN10TNGsRDe5arBsW8cTOjqLyYBcIqgPYTZW8zENErFxt7ij3fW3Jh/sCpnmy8rkS7FyK8ULX0PEy/2yDx8/5rXgMIICbRH/XaBy9Ud5bRBFVkEDu/r+rXP33wFPHjWjwvHAtfci1NRBAudQI/98DbcGQw5HmE89CjgZRo5ktkC5yu/8agEPocVjdHyZr7PaHfxZGUDGKtGRL2QzRYukCmWo1cZbMBHcI5FzImvTHS9/8B3SATjXMPgbfBuEeBwuBK5EjL+CtHY5bWs9kmYjmeo0KfUMH8hY4MAXDoKhQ7DhBPIrcjS5jPtoGxIREZjba67r6/P2XKXaCZH6Fc= charlie@example.org 2011-01-17"
+
 .. _command:
 
+
 command
 ```````
 
@@ -566,6 +614,10 @@ Creates user accounts, manipulates existing user accounts, and removes user acco
 
 * Whether to create the user's home directory.  Takes 'yes', or 'no'.  The default is 'yes'.
    
+*home=*:
+
+* Specifies where the user's home directory should be, if not in /home/$username.
+ 
 *password*:
 
 * Sets the user's password to this crypted value.  Pass in a result from crypt.  See the users example in the github examples directory for what this looks like in a playbook.

rst/patterns.rst

@@ -67,6 +67,10 @@ with the aforementioned bracket headers in the inventory file::
     webservers
     webservers:dbservers
 
+In 0.5 and later, you can exclude groups as well, for instance, all webservers not in Phoenix::
+
+    webservers:!phoenix
+
 Individual host names (or IPs), but not groups, can also be referenced using
 wildcards::
 
@@ -77,13 +81,13 @@ It's also ok to mix wildcard patterns and groups at the same time::
 
     one*.com:dbservers
 
+
 Easy enough.  See :doc:`examples` and then :doc:`playbooks` for how to do things to selected hosts.
 
 Host Variables
 ++++++++++++++
 
-Using the 0.4 branch of Ansible, it is easy to assign variables to hosts that will be used
+It is easy to assign variables to hosts that will be used later in playbooks::
-later in playbooks::
  
    [atlanta]
    host1 http_port=80 maxRequestsPerChild=808
@@ -93,7 +97,7 @@ later in playbooks::
 Group Variables
 +++++++++++++++
 
-Using the 0.4 branch of Ansible, variables can also be applied to an entire group at once::
+Variables can also be applied to an entire group at once::
 
    [atlanta]
    host1
@@ -137,7 +141,7 @@ variables to groups.  These variables can be used by /usr/bin/ansible-playbook,
 YAML Inventory Format
 +++++++++++++++++++++
 
-For people using 0.3, or those that prefer to use it, the inventory file can also be expressed in
+For that prefer to use it, the inventory file can also be expressed in
 YAML::
 
     ---
@@ -175,6 +179,9 @@ YAML::
       vars:
         - asdf: 1234
 
+Tip: If you ever have two python interpreters on a system, set a variable called 'ansible_python_interpreter' to
+the Python interpreter path you would like to use.  (This is available in version 0.5 and later)
+
 Tip: Be sure to start your YAML file with the YAML record designator ``---``.
 
 .. seealso::

rst/playbooks.rst

@@ -103,7 +103,7 @@ These variables can be used later in the playbook like this::
 
 The later is useful in the event you need to do something like ${other}_concatenated_value.
 
-In templates, the full power of the Jinja2 templating language is also available, which looks like this::
+The full power of the Jinja2 templating language is also available (note: in 0.4, this is only true inside of templates), which looks like this::
 
     {{ varname }}
 
@@ -298,6 +298,19 @@ Let's run a playbook using a parallelism level of 10::
 
     ansible-playbook playbook.yml -f 10
 
+Tips and Tricks
+```````````````
+
+Look at the bottom of the playbook execution for a summary of the nodes that were executed
+and how they performed.   General failures and fatal "unreachable" communication attempts are 
+kept seperate in the counts.
+
+If you ever want to see detailed output from successful modules as well as unsuccessful ones,
+use the '--verbose' flag.  This is available in Ansible 0.5 and later.
+
+Also, in version 0.5 and later, Ansible playbook output is vastly upgraded if the cowsay 
+package is installed.  Try it!
+
 .. seealso::
 
    :doc:`YAMLSyntax`