diff --git a/docsite/latest/rst/playbooks2.rst b/docsite/latest/rst/playbooks2.rst index 5b8a30b8c32..1f8fa9213e8 100644 --- a/docsite/latest/rst/playbooks2.rst +++ b/docsite/latest/rst/playbooks2.rst @@ -937,10 +937,71 @@ Here is an example:: Note that you must have passphrase-less SSH keys or an ssh-agent configured for this to work, otherwise rsync will need to ask for a passphrase. +Accelerated Mode +```````````````` + +.. versionadded:: 1.3 + +While SSH using the ControlPersist feature is quite fast and scalable, there is a certain amount of overhead involved in +creating connections. This can become something of a bottleneck when the number of hosts grows into the hundreds or +thousands. To help overcome this, Ansible offers an accelerated connection option. Accelerated mode can be anywhere from +2-6x faster than SSH with ControlPersist enabled, and 10x faster than paramiko. + +Accelerated mode works by launching a temporary daemon over SSH. Once the daemon is running, Ansible will connect directly +to it via a raw socket connection. Ansible secures this communication by using a temporary AES key that is uploaded during +the SSH connection (this key is different for every host, and is also regenerated every time the daemon is started). By default, +Ansible will use port 5099 for the accelerated connection, though this is configurable. Once running, the daemon will accept +connections for 30 minutes, after which time it will terminate itself and need to be restarted over SSH. + +Accelerated mode offers several improvments over the original fireball mode: + +* No bootstrapping is required, only a single line needs to be added to each play you wish to run in accelerated mode. +* Support for sudo commands (see below for more details and caveats). +* Fewer requirements! ZeroMQ is no longer required, nor are there any special packages beyond python-keyczar. + +In order to use accelerated mode, simply add `accelerate: true` to your play:: + + --- + - hosts: all + accelerate: true + tasks: + - name: some task + command: echo {{ item }} + with_items: + - foo + - bar + - baz + +If you wish to change the port Ansible will use for the accelerated connection, just add the `accelerated_port` option:: + + --- + - hosts: all + accelerate: true + # default port is 5099 + accelerate_port: 10000 + +The `accelerate_port` option can also be specified in the environment variable ACCELERATE_PORT, or in your `ansible.cfg` configuration:: + + [accelerate] + accelerate_port = 5099 + +As noted above, accelerated mode also supports running tasks via sudo, however there are two important caveats: + +* You must remove requiretty from your sudoers options. +* Prompting for the sudo password is not yet supported, so the NOPASSWD option is required for commands. + + + Fireball Mode ````````````` -.. versionadded:: 0.8 +.. versionadded:: 0.8 (deprecated as of 1.3) + +.. note:: + + The following section has been deprecated as of Ansible 1.3 in favor of the accelerated mode described above. This + documentation is here for users who may still be using the original fireball connection method only, and should not + be used for any new deployments. Ansible's core connection types of 'local', 'paramiko', and 'ssh' are augmented in version 0.8 and later by a new extra-fast connection type called 'fireball'. It can only be used with playbooks and does require some additional setup