ansible/docs/docsite/rst/plugins/connection.rst

Topics

Connection Plugins

Connection plugins allow Ansible to connect to the target hosts so it can execute tasks on them. Ansible ships with many connection plugins, but only one can be used per host at a time.

By default, Ansible ships with several plugins. The most commonly used are the 'paramiko' SSH, native ssh (just called 'ssh'), and 'local' connection types. 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 ../intro_getting_started section.

ssh Plugins

Because ssh is the default protocol used in system administration and the protocol most used in Ansible, ssh options are included in the command line tools. See ../ansible-playbook for more details.

Enabling Connection Plugins

You can extend Ansible to support other transports (such as SNMP or message bus) by dropping a custom plugin into the connection_plugins directory.

Using Connection Plugins

The transport can be changed via configuration <../config>, in the command line (-c, --connection), as a keyword (connection) in your play, or by setting the a connection variable (ansible_connection), most often in your inventory. For example, for Windows machines you might want to use the winrm <connection/winrm> plugin.

Most connection plugins can operate with a minimum configuration. By default they use the inventory_hostname and defaults to find the target host.

Plugins are self-documenting. Each plugin should document its configuration options. The following are connection variables common to most connection plugins:

ansible_host

The name of the host to connect to, if different from the inventory_hostname.

ansible_port

The ssh port number, for ssh <connection/ssh> and paramiko <connection/paramiko> it defaults to 22.

ansible_user

The default user name to use for log in. Most plugins default to the 'current user running Ansible'.

Each plugin might also have a specific version of a variable that overrides the general version. For example, ansible_ssh_host for the ssh <connection/ssh> plugin.

Plugin List

You can use ansible-doc -t connection -l to see the list of available plugins. Use ansible-doc -t connection <plugin name> to see detailed documentation and examples.

maxdepth

1

connection/*

../playbooks

An introduction to playbooks

callback

Ansible callback plugins

../playbooks_filters

Jinja2 filter plugins

../playbooks_tests

Jinja2 test plugins

../playbooks_lookups

Jinja2 lookup plugins

vars

Ansible vars plugins

User Mailing List

Have a question? Stop by the google group!

irc.freenode.net

#ansible IRC chat channel