From d002c2d907cbd8bce562a671e8f6ffd6758c1c35 Mon Sep 17 00:00:00 2001 From: Michael DeHaan Date: Thu, 4 Jul 2013 19:10:28 -0400 Subject: [PATCH] Document 'smart' option and connection type default changes. --- docsite/latest/rst/api.rst | 6 +++--- docsite/latest/rst/faq.rst | 3 ++- docsite/latest/rst/glossary.rst | 23 +++++++++++++---------- docsite/latest/rst/patterns.rst | 2 +- 4 files changed, 19 insertions(+), 15 deletions(-) diff --git a/docsite/latest/rst/api.rst b/docsite/latest/rst/api.rst index a726fc0f429..1a7b806f310 100644 --- a/docsite/latest/rst/api.rst +++ b/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 -------------- diff --git a/docsite/latest/rst/faq.rst b/docsite/latest/rst/faq.rst index b1f1e87d1df..a0304c35a8d 100644 --- a/docsite/latest/rst/faq.rst +++ b/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 diff --git a/docsite/latest/rst/glossary.rst b/docsite/latest/rst/glossary.rst index 1cfa6347acd..e70eca3f25f 100644 --- a/docsite/latest/rst/glossary.rst +++ b/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 ++++ diff --git a/docsite/latest/rst/patterns.rst b/docsite/latest/rst/patterns.rst index 3a6ea6c5dec..fc58eed7620 100644 --- a/docsite/latest/rst/patterns.rst +++ b/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