add note about pipelining

This commit is contained in:
Michael DeHaan 2014-02-15 14:35:26 -05:00
parent f8f4e180f7
commit 5d686a459c
2 changed files with 33 additions and 1 deletions

View file

@ -561,12 +561,31 @@ cause scp to be used to transfer remote files instead::
There's really no reason to change this unless problems are encountered, and then there's also no real drawback
to managing the switch. Most environments support SFTP by default and this doesn't usually need to be changed.
.. _pipelining:
pipelining
==========
Enabling pipelining reduces the number of SSH operations required to
execute a module on the remote server, by executing many ansible modules without actual file transfer.
This can result in a very significant performance improvement when enabled, however when using "sudo:" operations you must
first disable 'requiretty' in /etc/sudoers on all managed hosts.
By default, this option is disabled to preserve compatibility with
sudoers configurations that have requiretty (the default on many distros), but is highly
recommended if you can enable it, eliminating the need for :doc:`playbooks_acceleration`::
pipelining=False
.. _accelerate_settings:
Accelerate Mode Settings
------------------------
Under the [accelerate] header, the following settings are tunable for :doc:`playbooks_acceleration`
Under the [accelerate] header, the following settings are tunable for :doc:`playbooks_acceleration`. Acceleration is
a useful performance feature to use if you cannot enable :ref:`ssh_pipelining` in your environment, but is probably
not needed if you can.
.. _accelerate_port:

View file

@ -3,6 +3,19 @@ Accelerated Mode
.. versionadded:: 1.3
.. note:
Are you running Ansible 1.5 or later? If so, you may not need accelerate mode due to a new feature called "SSH pipelining"
For users on 1.5 and later, accelerate mode only makes sense if you are (A) are managing from an Enterprise Linux 6 or earlier host
and still are on paramiko, or (B) can't enable TTYs with sudo as described in the pipelining section of
ref:`intro_configuration`.
If you can use it, the pipelining feature in Ansible reduces the amount of files transferred over the wire,
making everything much more efficient. If you can enable pipelining in ansible.cfg, it is
preferable to accelerate mode in most cases and requires fewer moving parts. Accelerate mode remains around in support of EL6
control machines and other constrained environments.
While OpenSSH using the ControlPersist feature is quite fast and scalable, there is a certain small amount of overhead involved in
using SSH connections. While many people will not encounter a need, if you are running on a platform that doesn't have ControlPersist support (such as an EL6 control machine), you'll probably be even more interested in tuning options.