Document 'smart' option and connection type default changes.

docsite/latest/rst/api.rst

@@ -313,12 +313,12 @@ system, or even (yes, really) making sound effects.  Some examples are contained
 Connection Type Plugins
 -----------------------
 
-By default, ansible ships with a 'paramiko' SSH, native ssh (just called 'ssh'), and 'local' connection type.  Release 0.8 also
-added an accelerated connection type named 'fireball'.  All of these can be used
+By default, ansible ships with a 'paramiko' SSH, native ssh (just called 'ssh'), and 'local' connection type, and an accelerated connection type named 'fireball'.  All of these can be used
 in playbooks and with /usr/bin/ansible to decide how you want to talk to remote machines.  The basics of these connection types
 are covered in the 'getting started' section.  Should you want to extend Ansible to support other transports (SNMP? Message bus?
 Carrier Pigeon?) it's as simple as copying the format of one of the existing modules and dropping it into the connection plugins
-directory.
+directory.   The value of 'smart' for a connection allows selection of paramiko or openssh based on system capabilities, and chooses
+'ssh' if OpenSSH supports ControlPersist, in Ansible 1.2.1 an later.  Previous versions did not support 'smart'.
 
 Lookup Plugins
 --------------

docsite/latest/rst/faq.rst

@@ -34,7 +34,8 @@ How do I get ansible to reuse connections, enable Kerberized SSH, or have Ansibl
 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
 Switch your default connectiont type in the configuration file to 'ssh', or use '-c ssh' to use
-Native OpenSSH for connections instead of the python paramiko library.
+Native OpenSSH for connections instead of the python paramiko library.  In Ansible 1.2.1 and later, 'ssh' will be used
+by default if OpenSSH is new enough to support ControlPersist as an option.
 
 Paramiko is great for starting out, but the OpenSSH type offers many advanced options.  You will want to run Ansible
 from a machine new enough to support ControlPersist, if you are using this connection type.  You can still manage

docsite/latest/rst/glossary.rst

@@ -48,10 +48,12 @@ systems).  Use this to get an idea what might happen, but is not a substitute fo
 Connection Type, Connection Plugin
 ++++++++++++++++++++++++++++++++++
 
-Ansible by default talks to remote machines over SSH using a library called 'paramiko'.  It also supports using native OpenSSH,
-which if you have a new-enough open SSH, is equally fast, but also enables some features like Kereberos and jump hosts.  This is
-govered in the getting started section.  There are also other connection types like 'fireball' mode, which must be bootstrapped
-over SSH but is very fast, and local mode, which acts on the local system.  Users can also write their own connection plugins.
+Ansible by default talks to remote machines through pluggable libraries.  Ansible supports native OpenSSH ('ssh'), or a python
+implementation called 'paramiko'.  OpenSSH is preferred if you have a new-enough open SSH, and also enables some features 
+like Kereberos and jump hosts.  This is covered in the getting started section.  
+There are also other connection types like 'fireball' mode, which must be bootstrapped
+over one of the SSH based types but is very fast, and local mode, which acts on the local system.  
+Users can also write their own connection plugins.
 
 Conditionals
 ++++++++++++
@@ -85,8 +87,9 @@ docs section.
 Fireball Mode
 +++++++++++++
 
-By default Ansible uses SSH for connections -- either Paramiko (the actual default) or a common alternative, native Open SSH.  Some users
-may want to execute operations even faster though, and they can if they opt in on running an ephmeral message bus.  What happens is Ansible
+By default Ansible uses SSH for connections -- either Paramiko or a common alternative, native Open SSH.  (Ansible tries to use
+'ssh' by default if possible in Ansible 1.2.1 and later, and before defaulted to Paramiko).  Some users
+may want to execute operations even faster though, and they can if they opt in on running an ephmeral message bus, 'fireball'.  What happens is Ansible
 will start talking to a node over SSH, and then set up a temporary secured message bus good only to talk from one machine, that will
 self destruct after a set period of time.  This means the bus does not allow management of any kind after the time interval has expired.
 
@@ -379,10 +382,10 @@ file transfer) can be achieved with Ansible's copy, template, and fetch resource
 SSH (Native)
 ++++++++++++
 
-Ansible by default uses Paramiko.  Native openssh is specified with "-c ssh" (or a config file, or a directive in the playbook)
-and can be useful if wanting to login via Kerberized SSH or use SSH jump hosts, etc.  Using a client that supports ControlMaster
-and ControlPersist is recommended for maximum performance -- if you don't have that and don't need Kerberos, jump hosts, or other
-features, paramiko (the default) is a fine choice.  Ansible will warn you if it doesn't detect ControlMaster/ControlPersist capability.
+Native openssh as an Ansible tranpsort is specified with "-c ssh" (or a config file, or a directive in the playbook)
+and can be useful if wanting to login via Kerberized SSH or use SSH jump hosts, etc.  In 1.2.1, 'ssh' will be used if the OpenSSH
+on the control machine is sufficiently new, by default.  Previously Ansible selected 'paramiko' as a default.  
+Using a client that supports ControlMaster and ControlPersist is recommended for maximum performance -- if you don't have that and don't need Kerberos, jump hosts, or other features, paramiko (the default) is a good choice.  Ansible will warn you if it doesn't detect ControlMaster/ControlPersist capability.
 
 Tags
 ++++

docsite/latest/rst/patterns.rst

@@ -83,7 +83,7 @@ ansible_ssh_user
 ansible_ssh_pass
   The ssh password to use (this is insecure, we strongly recommend using --ask-pass or SSH keys)
 ansible_connection
-  Connection type of the host. Candidates are local, ssh or paramiko.  Default is paramiko
+  Connection type of the host. Candidates are local, ssh or paramiko.  The default is paramiko before Ansible 1.2, and 'smart' afterwards which detects whether usage of 'ssh' would be feasible based on whether ControlPersist is supported.
 ansible_ssh_private_key_file
   Private key file used by ssh.  Useful if using multiple keys and you don't want to use SSH agent.
 ansible_syslog_facility