# Connection Plugins

- `ssh` plugins
- Adding connection plugins
- Using connection plugins
- Plugin List

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 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.

## Adding 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

You can set the connection plugin globally via configuration, at the command line (`-c`, `--connection`), as a keyword in your play, or by setting a variable, most often in your inventory. For example, for Windows machines you might want to set the winrm plugin as an inventory variable.

Most connection plugins can operate with minimal 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 and paramiko_ssh 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 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.

- buildah – Interact with an existing buildah container
- chroot – Interact with local chroot
- docker – Run tasks in docker containers
- funcd – Use funcd to connect to target
- httpapi – Use httpapi to run command on network appliances
- iocage – Run tasks in iocage jails
- jail – Run tasks in jails
- kubectl – Execute tasks in pods running on Kubernetes
- libvirt_lxc – Run tasks in lxc containers via libvirt
- local – execute on controller
- lxc – Run tasks in lxc containers via lxc python library
- lxd – Run tasks in lxc containers via lxc CLI
- napalm – Provides persistent connection using NAPALM
- netconf – Provides a persistent connection using the netconf protocol
- network_cli – Use network_cli to run command on network appliances
- oc – Execute tasks in pods running on OpenShift
- paramiko_ssh – Run tasks via python ssh (paramiko)
- persistent – Use a persistent unix socket for connection
- podman – Interact with an existing podman container
- psrp – Run tasks over Microsoft PowerShell Remoting Protocol
- qubes – Interact with an existing QubesOS AppVM
- saltstack – Allow ansible to piggyback on salt minions
- ssh – connect via ssh client binary
- vmware_tools – Execute tasks inside a VM via VMware Tools
- winrm – Run tasks over Microsoft’s WinRM
- zone – Run tasks in a zone instance

See also

Working with Playbooks
  An introduction to playbooks
Callback Plugins
  Ansible callback plugins
Filters
  Jinja2 filter plugins
Tests
  Jinja2 test plugins
Lookups
  Jinja2 lookup plugins
Vars Plugins
  Ansible vars plugins
User Mailing List
  Have a question? Stop by the google group!
irc.freenode.net
  #ansible IRC chat channel