@ -33,7 +33,7 @@ The following checklist items are important guidelines for people who want to c
'supported_by': 'community',
'metadata_version': '1.1'}
Read the complete :ref:`module metadata specification <ansible-metadata-block>` for more information.
Read the complete :ref:`module metadata specification <ansible_metadata_block>` for more information.
* Documentation: Make sure it exists
* Module documentation should briefly and accurately define what each module and option does, and how it works with others in the underlying system. Documentation should be written for broad audience--readable both by experts and non-experts. This documentation is not meant to teach a total novice, but it also should not be reserved for the Illuminati (hard balance).
* Do not use wildcards for importing other python modules (ex: ``from ansible.module_utils.basic import *``). This used to be required for code imported from ``ansible.module_utils`` but, from Ansible-2.1 onwards, it's just an outdated and bad practice.
* The module must have a `main` function that wraps the normal execution.
* Call your :func:`main` from a conditional so that it would be possible to
An `example file is available on Github <https://raw.github.com/ansible/ansible/devel/examples/ansible.cfg>`_.
For more details and a full listing of available configurations go to :ref:`configuration_settings`. Starting with Ansible version 2.4, you can use the :ref:`ansible-config` command line utility to list your available options and inspect the current values.
For more details and a full listing of available configurations go to :ref:`configuration_settings<ansible_configuration_settings>`. Starting with Ansible version 2.4, you can use the :ref:`ansible-config` command line utility to list your available options and inspect the current values.
For in-depth details, see :ref:`ansible_configuration_settings`.
Never store passwords in plain text. We recommend using SSH keys to authenticate SSH connections. Ansible supports ssh-agent to manage your SSH keys. If you must use passwords to authenticate SSH connections, we recommend encrypting them with :ref:`Ansible Vault <playbooks_vault>`.
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 :ref:`getting started<intro_getting_started>` section.
By default, Ansible ships with several plugins. The most commonly used are the :ref:`paramiko SSH<paramiko_ssh_connection>`, native ssh (just called :ref:`ssh<ssh_connection>`), and :ref:`local<local_connection>` connection types. All of these can be used in playbooks and with :command:`/usr/bin/ansible` to decide how you want to talk to remote machines.
The basics of these connection types are covered in the :ref:`getting started<intro_getting_started>` section.
.._ssh_plugins:
@ -26,28 +24,26 @@ 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:
Using Connection Plugins
++++++++++++++++++++++++
The transport can be changed via :ref:`configuration<ansible_configuration_settings>`, in the command line (``-c``, ``--connection``), as a :ref:`keyword<playbooks_keywords>`)
in your play, or by setting a :ref:`variable<behavioral_parameters>`, most often in your inventory.
The transport can be changed via :ref:`configuration<ansible_configuration_settings>`, at the command line (``-c``, ``--connection``), as a :ref:`keyword <playbooks_keywords>` in your play, or by setting a :ref:`variable<behavioral_parameters>`, most often in your inventory.
For example, for Windows machines you might want to use the :doc:`winrm<connection/winrm>` plugin.
Most connection plugins can operate with a minimum configuration. By default they use the :ref:`inventory hostname<inventory_hostname>` and defaults to find the target host.
Most connection plugins can operate with a minimum configuration. By default they use the :ref:`inventory hostname<inventory_hostnames_lookup>` 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:
:ref:`ansible_host<ansible_host>`
The name of the host to connect to, if different from the :ref:`inventory hostname<inventory_hostname>`.
:ref:`ansible_port<ansible_port>`
The ssh port number, for :doc:`ssh <connection/ssh>` and :doc:`paramiko_ssh <connection/paramiko_ssh>` it defaults to 22.
:ref:`ansible_user<ansible_user>`
:ref:`ansible_host<magic_variables_and_hostvars>`
The name of the host to connect to, if different from the :ref:`inventory <intro_inventory>` hostname.
:ref:`ansible_port<faq_setting_users_and_ports>`
The ssh port number, for :ref:`ssh <ssh_connection>` and :ref:`paramiko_ssh <paramiko_ssh_connection>` it defaults to 22.
:ref:`ansible_user<faq_setting_users_and_ports>`
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, :ref:`ansible_ssh_host<ansible_ssh_host>` for the :doc:`ssh <connection/ssh>` plugin.
Each plugin might also have a specific version of a variable that overrides the general version. For example, ``ansible_ssh_host`` for the :ref:`ssh <ssh_connection>` plugin.
@ -8,7 +8,7 @@ Vars plugins inject additional variable data into Ansible runs that did not come
Vars plugins were partially implemented in Ansible 2.0 and rewritten to be fully implemented starting with Ansible 2.4.
The :doc:`host_group_vars <vars/host_group_vars>` plugin shipped with Ansible enables reading variables from :ref:`host_vars` and :ref:`group_vars`.
The :ref:`host_group_vars <host_group_vars_vars>` plugin shipped with Ansible enables reading variables from :ref:`host_variables` and :ref:`group_variables`.
.._enable_vars:
@ -16,7 +16,7 @@ The :doc:`host_group_vars <vars/host_group_vars>` plugin shipped with Ansible en
Enabling Vars Plugins
+++++++++++++++++++++
You can activate a custom vars plugins by either dropping it into a ``vars_plugins`` directory adjacent to your play, inside a role, or by putting it in one of the directory sources configured in :ref:`ansible.cfg <ansible_configuration_settings>`.
You can activate a custom vars plugin by either dropping it into a ``vars_plugins`` directory adjacent to your play, inside a role, or by putting it in one of the directory sources configured in :ref:`ansible.cfg <ansible_configuration_settings>`.
@ -111,7 +111,7 @@ In addition to the deprecation warnings, many new tests have been introduced tha
when: result is successful
See :ref:`playbook_tests` for more information.
See :ref:`playbooks_tests` for more information.
Additionally, a script was created to assist in the conversion for tests using filter syntax to proper jinja test syntax. This script has been used to convert all of the Ansible integration tests to the correct format. There are a few limitations documented, and all changes made by this script should be evaluated for correctness before executing the modified playbooks. The script can be found at `https://github.com/ansible/ansible/blob/devel/hacking/fix_test_syntax.py <https://github.com/ansible/ansible/blob/devel/hacking/fix_test_syntax.py>`_.
@ -140,7 +140,7 @@ The following modules no longer exist:
* :ref:`cl_license <cl_license_module>` use :ref:`nclu <nclu_module>` instead
* :ref:`cl_interface <cl_interface_module>` use :ref:`nclu <nclu_module>` instead
* :ref:`cl_bond <cl_bond_module>` use :ref:`nclu <nclu_module>` instead
* :ref:`ec2_vpc <ec2_vpc_module>` use :ref:`ec2_vpc_net <ec2_vpc_net_module>` along with supporting modules :ref:`ec2_vpc_igw <ec2_vpc_igw_module>`, :ref:`ec2_vpc_route_table <ec2_vpc_route_table_module>`, :ref:`ec2_vpc_subnet <ec2_vpc_subnet_module>`, :ref:`ec2_vpc_dhcp_options <ec2_vpc_dhcp_options_module>`, :ref:`ec2_vpc_nat_gateway <ec2_vpc_nat_gateway_module>`, :ref:`ec2_vpc_nacl <ec2_vpc_nacl_module>` instead.
* :ref:`ec2_vpc <ec2_vpc_module>` use :ref:`ec2_vpc_net <ec2_vpc_net_module>` along with supporting modules :ref:`ec2_vpc_igw <ec2_vpc_igw_module>`, :ref:`ec2_vpc_route_table <ec2_vpc_route_table_module>`, :ref:`ec2_vpc_subnet <ec2_vpc_subnet_module>`, :ref:`ec2_vpc_dhcp_option <ec2_vpc_dhcp_option_module>`, :ref:`ec2_vpc_nat_gateway <ec2_vpc_nat_gateway_module>`, :ref:`ec2_vpc_nacl <ec2_vpc_nacl_module>` instead.
* :ref:`ec2_ami_search <ec2_ami_search_module>` use :ref:`ec2_ami_facts <ec2_ami_facts_module>` instead
* :ref:`docker <docker_module>` use :ref:`docker_container <docker_container_module>` and :ref:`docker_image <docker_image_module>` instead
* In the :ref:`nxos_igmp_interface <nxos_igmp_interface>` module, `oif_prefix` and `oif_source` properties are deprecated. Use
`ois_ps` parameter with a dictionary of prefix and source to values instead.
* In the :ref:`nxos_igmp_interface module<nxos_igmp_interface_module>`, ``oif_prefix`` and ``oif_source`` properties are deprecated. Use ``ois_ps`` parameter with a dictionary of prefix and source to values instead.
@ -19,6 +19,7 @@ Setting environment variables can be done with the `environment` keyword. It can
..note:: starting in 2.0.1 the setup task from gather_facts also inherits the environment directive from the play, you might need to use the `|default` filter to avoid errors if setting this at play level.
.._faq_setting_users_and_ports:
How do I handle different machines needing different user accounts or ports to log in with?
@ -185,12 +186,12 @@ By default, Solaris 10 and earlier run a non-POSIX shell which does not correctl
tmp directory Ansible uses ( :file:`~/.ansible/tmp`). If you see module failures on Solaris machines, this
is likely the problem. There are several workarounds:
* You can set :ref:`remote_tmp` to a path that will expand correctly with the Solaris shell. For
* You can set ``remote_tmp`` to a path that will expand correctly with the shell you are using (see the plugin documentation for :ref:`C shell<csh_shell>`, :ref:`fish shell<fish_shell>`, and :ref:`Powershell<powershell_shell>`). For
example, in the ansible config file you can set::
remote_tmp=$HOME/.ansible/tmp
In Ansible 2.5 and later, you can also set it per-host like this::
In Ansible 2.5 and later, you can also set it per-host in inventory like this::
@ -10,13 +10,13 @@ To help identify maintainers and understand how the included modules are officia
Core
````
:ref:`core_supported`. These are maintained by the Ansible Engineering Team.
:ref:`Core Maintained<core_supported>` modules are maintained by the Ansible Engineering Team.
These modules are integral to the basic foundations of the Ansible distribution.
Network
```````
:ref:`network_supported`. These are maintained by the Ansible Network Team. Please note there are additional networking modules that are categorized as Certified or Community not maintained by Ansible.
:ref:`Network Maintained<network_supported>` modules are are maintained by the Ansible Network Team. Please note there are additional networking modules that are categorized as Certified or Community not maintained by Ansible.
Certified
@ -27,7 +27,7 @@ Certified modules are part of a future planned program currently in development.
Community
`````````
:ref:`community_supported`. These are submitted and maintained by the Ansible community. These modules are not maintained by Ansible, and are included as a convenience.
:ref:`Community Maintained<community_supported>` modules are submitted and maintained by the Ansible community. These modules are not maintained by Ansible, and are included as a convenience.
Alicia Cozine
7 years ago
committed by