decelerate docs!
This commit is contained in:
Brian Coca
Brian Coca
parent
2f67dd1e0f
commit
5220f30244
4 changed files with 3 additions and 155 deletions
|
|
@ -9,7 +9,7 @@ Welcome to the Ansible documentation!
|
|||
Ansible is an IT automation tool. It can configure systems, deploy software, and orchestrate more advanced IT tasks
|
||||
such as continuous deployments or zero downtime rolling updates.
|
||||
|
||||
Ansible's main goals are simplicity and ease-of-use. It also has a strong focus on security and reliability, featuring a minimum of moving parts, usage of OpenSSH for transport (with an accelerated socket mode and pull modes as alternatives), and a language that is designed around auditability by humans--even those not familiar with the program.
|
||||
Ansible's main goals are simplicity and ease-of-use. It also has a strong focus on security and reliability, featuring a minimum of moving parts, usage of OpenSSH for transport (with other transports and pull modes as alternatives), and a language that is designed around auditability by humans--even those not familiar with the program.
|
||||
|
||||
We believe simplicity is relevant to all sizes of environments, so we design for busy users of all types: developers, sysadmins, release engineers, IT managers, and everyone in between. Ansible is appropriate for managing all environments, from small setups with a handful of instances to enterprise environments with many thousands of instances.
|
||||
|
||||
|
|
|
|||
|
|
@ -1172,7 +1172,7 @@ 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`::
|
||||
recommended if you can enable it.
|
||||
|
||||
pipelining = False
|
||||
|
||||
|
|
@ -1189,76 +1189,6 @@ This is the location of the ssh binary. It defaults to ``ssh`` which will use th
|
|||
|
||||
This option is usually not required, it might be useful when access to system ssh is restricted, or when using ssh wrappers to connect to remote hosts.
|
||||
|
||||
.. _accelerate_settings:
|
||||
|
||||
Accelerated Mode Settings
|
||||
-------------------------
|
||||
|
||||
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:`pipelining` in your environment, but is probably
|
||||
not needed if you can.
|
||||
|
||||
.. _accelerate_port:
|
||||
|
||||
accelerate_port
|
||||
===============
|
||||
|
||||
.. versionadded:: 1.3
|
||||
|
||||
This is the port to use for accelerated mode::
|
||||
|
||||
accelerate_port = 5099
|
||||
|
||||
.. _accelerate_timeout:
|
||||
|
||||
accelerate_timeout
|
||||
==================
|
||||
|
||||
.. versionadded:: 1.4
|
||||
|
||||
This setting controls the timeout for receiving data from a client. If no data is received during this time, the socket connection will be closed. A keepalive packet is sent back to the controller every 15 seconds, so this timeout should not be set lower than 15 (by default, the timeout is 30 seconds)::
|
||||
|
||||
accelerate_timeout = 30
|
||||
|
||||
.. _accelerate_connect_timeout:
|
||||
|
||||
accelerate_connect_timeout
|
||||
==========================
|
||||
|
||||
.. versionadded:: 1.4
|
||||
|
||||
This setting controls the timeout for the socket connect call, and should be kept relatively low. The connection to the `accelerate_port` will be attempted 3 times before Ansible will fall back to ssh or paramiko (depending on your default connection setting) to try and start the accelerate daemon remotely. The default setting is 1.0 seconds::
|
||||
|
||||
accelerate_connect_timeout = 1.0
|
||||
|
||||
Note, this value can be set to less than one second, however it is probably not a good idea to do so unless you're on a very fast and reliable LAN. If you're connecting to systems over the internet, it may be necessary to increase this timeout.
|
||||
|
||||
.. _accelerate_daemon_timeout:
|
||||
|
||||
accelerate_daemon_timeout
|
||||
=========================
|
||||
|
||||
.. versionadded:: 1.6
|
||||
|
||||
This setting controls the timeout for the accelerated daemon, as measured in minutes. The default daemon timeout is 30 minutes::
|
||||
|
||||
accelerate_daemon_timeout = 30
|
||||
|
||||
Note, prior to 1.6, the timeout was hard-coded from the time of the daemon's launch. For version 1.6+, the timeout is now based on the last activity to the daemon and is configurable via this option.
|
||||
|
||||
.. _accelerate_multi_key:
|
||||
|
||||
accelerate_multi_key
|
||||
====================
|
||||
|
||||
.. versionadded:: 1.6
|
||||
|
||||
If enabled, this setting allows multiple private keys to be uploaded to the daemon. Any clients connecting to the daemon must also enable this option::
|
||||
|
||||
accelerate_multi_key = yes
|
||||
|
||||
New clients first connect to the target node over SSH to upload the key, which is done via a local socket file, so they must have the same access as the user that launched the daemon originally.
|
||||
|
||||
.. _selinux_settings:
|
||||
|
||||
Selinux Specific Settings
|
||||
|
|
|
|||
|
|
@ -26,7 +26,7 @@ machines over SSH.
|
|||
|
||||
By default, Ansible 1.3 and later will try to use native
|
||||
OpenSSH for remote communication when possible. This enables ControlPersist (a performance feature), Kerberos, and options in ``~/.ssh/config`` such as Jump Host setup. However, when using Enterprise Linux 6 operating systems as the control machine (Red Hat Enterprise Linux and derivatives such as CentOS), the version of OpenSSH may be too old to support ControlPersist. On these operating systems, Ansible will fallback into using a high-quality Python implementation of
|
||||
OpenSSH called 'paramiko'. If you wish to use features like Kerberized SSH and more, consider using Fedora, OS X, or Ubuntu as your control machine until a newer version of OpenSSH is available for your platform -- or engage 'accelerated mode' in Ansible. See :doc:`playbooks_acceleration`.
|
||||
OpenSSH called 'paramiko'. If you wish to use features like Kerberized SSH and more, consider using Fedora, OS X, or Ubuntu as your control machine until a newer version of OpenSSH is available for your platform.
|
||||
|
||||
In releases up to and including Ansible 1.2, the default was strictly paramiko. Native SSH had to be explicitly selected with the ``-c`` ssh option or set in the configuration file.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,82 +0,0 @@
|
|||
Accelerated Mode
|
||||
================
|
||||
|
||||
.. versionadded:: 1.3
|
||||
|
||||
.. note::
|
||||
|
||||
Accelerated mode is deprecated. Consider using SSH with ControlPersist and pipelining enabled instead. This feature will be removed in a future release. Deprecation warnings can be disabled by setting :code:`deprecation_warnings=False` in :code:`ansible.cfg`.
|
||||
|
||||
You Might Not Need This!
|
||||
````````````````````````
|
||||
|
||||
Are you running Ansible 1.5 or later? If so, you may not need accelerated mode due to a new feature called "SSH pipelining" and should read the :ref:`pipelining` section of the documentation.
|
||||
|
||||
For users on 1.5 and later, accelerated mode only makes sense if you (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 docs.
|
||||
|
||||
If you can use pipelining, Ansible will reduce the amount of files transferred over the wire,
|
||||
making everything much more efficient, and performance will be on par with accelerated mode in nearly all cases, possibly excluding very large file transfer. Because less moving parts are involved, pipelining is better than accelerated mode for nearly all use cases.
|
||||
|
||||
Accelerated mode remains around in support of EL6
|
||||
control machines and other constrained environments.
|
||||
|
||||
Accelerated Mode Details
|
||||
````````````````````````
|
||||
|
||||
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.
|
||||
|
||||
Accelerated mode is there to help connections work faster, but still uses SSH for initial secure key exchange. There is no
|
||||
additional public key infrastructure to manage, and this does not require things like NTP or even DNS.
|
||||
|
||||
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 socket connection. Ansible secures this communication by using a temporary AES key that is exchanged during
|
||||
the SSH connection (this key is different for every host, and is also regenerated periodically).
|
||||
|
||||
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.
|
||||
|
||||
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 `accelerate_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 :envvar:`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 sudo'ed commands.
|
||||
|
||||
As of Ansible version `1.6`, you can also allow the use of multiple keys for connections from multiple Ansible management nodes. To do so, add the following option
|
||||
to your `ansible.cfg` configuration::
|
||||
|
||||
accelerate_multi_key = yes
|
||||
|
||||
When enabled, the daemon will open a UNIX socket file (by default `$ANSIBLE_REMOTE_TEMP/.ansible-accelerate/.local.socket`). New connections over SSH can
|
||||
use this socket file to upload new keys to the daemon.
|
||||
|
||||
Loading…
Reference in a new issue