* Windows
* Oxford comma
* defaults to
* periods
* none in see also
* after etc.
* at end of definition
* not doubled
* Ansible
* authenticate
* verifies your
* to configure
* past tense agreement
* Spelling: CoreOS
* only use instead once
* backticks for file path
* not to be
* onward
@ -8,7 +8,7 @@ Ansible can use existing privilege escalation systems to allow a user to execute
Become
``````
Ansible allows you to 'become' another user, different from the user that logged into the machine (remote user). This is done using existing
privilege escalation tools, which you probably already use or have configured, like `sudo`, `su`, `pfexec`, `doas`, `pbrun`, `dzdo`, `ksu` and others.
privilege escalation tools, which you probably already use or have configured, like `sudo`, `su`, `pfexec`, `doas`, `pbrun`, `dzdo`, `ksu`, and others.
..note:: Before 1.9 Ansible mostly allowed the use of `sudo` and a limited use of `su` to allow a login/remote user to become a different user
@ -60,7 +60,7 @@ Individuals with direct commit access to ansible/ansible are entrusted with powe
- Discuss with other committers, specially when you are unsure of something.
- Document! If your PR is a new feature or a change to behavior, make sure you've updated all associated documentation or have notified the right people to do so. It also helps to add the version of Core against which this documentation is compatible (to avoid confusion with stable versus devel docs, for backwards compatibility, etc.).
- Consider scope, sometimes a fix can be generalized
- Keep it simple, then things are maintainable, debuggable and intelligible.
- Keep it simple, then things are maintainable, debuggable, and intelligible.
Committers are expected to continue to follow the same community and contribution guidelines followed by the rest of the Ansible community.
@ -274,7 +274,7 @@ Alternatively, the role_skeleton and ignoring of files can be configured via ans
Search for Roles
----------------
Search the Galaxy database by tags, platforms, author and multiple keywords. For example:
Search the Galaxy database by tags, platforms, author, and multiple keywords. For example:
::
@ -361,7 +361,7 @@ Use ``remove`` to delete a role from *roles_path*:
Authenticate with Galaxy
------------------------
Using the ``import``, ``delete`` and ``setup`` commands to manage your roles on the Galaxy website requires authentication, and the ``login`` command
Using the ``import``, ``delete``, and ``setup`` commands to manage your roles on the Galaxy website requires authentication, and the ``login`` command
can be used to do just that. Before you can use the ``login`` command, you must create an account on the Galaxy website.
The ``login`` command requires using your GitHub credentials. You can use your username and password, or you can create a `personal access token <https://help.github.com/articles/creating-an-access-token-for-command-line-use/>`_. If you choose to create a token, grant minimal access to the token, as it is used just to verify identify.
@ -382,8 +382,8 @@ The following shows authenticating with the Galaxy website using a GitHub userna
Password for dsmith:
Successfully logged into Galaxy as dsmith
When you choose to use your username and password, your password is not sent to Galaxy. It is used to authenticates with GitHub and create a personal access token.
It then sends the token to Galaxy, which in turn verifies that your identity and returns a Galaxy access token. After authentication completes the GitHub token is
When you choose to use your username and password, your password is not sent to Galaxy. It is used to authenticate with GitHub and create a personal access token.
It then sends the token to Galaxy, which in turn verifies your identity and returns a Galaxy access token. After authentication completes the GitHub token is
destroyed.
If you do not wish to use your GitHub password, or if you have two-factor authentication enabled with GitHub, use the *--github-token* option to pass a personal access token
Since Ansible 2.3 it is possible to use environment variables for domain (``CLOUDSTACK_DOMAIN``), account (``CLOUDSTACK_ACCOUNT``), project (``CLOUDSTACK_PROJECT``), VPC (``CLOUDSTACK_VPC``) and zone (``CLOUDSTACK_ZONE``). This simplifies the tasks by not repeating the arguments for every tasks.
Since Ansible 2.3 it is possible to use environment variables for domain (``CLOUDSTACK_DOMAIN``), account (``CLOUDSTACK_ACCOUNT``), project (``CLOUDSTACK_PROJECT``), VPC (``CLOUDSTACK_VPC``), and zone (``CLOUDSTACK_ZONE``). This simplifies the tasks by not repeating the arguments for every tasks.
Below you see an example how it can be used in combination with Ansible's block feature:
@ -197,7 +197,7 @@ This is how our inventory looks like:
As you can see, the public IPs for our web servers and jumphost has been assigned as variable ``public_ip`` directly in the inventory.
The configure the jumphost, web servers and database servers, we use ``group_vars``. The ``group_vars`` directory contains 4 files for configuration of the groups: cloud-vm, jumphost, webserver and db-server. The cloud-vm is there for specifying the defaults of our cloud infrastructure.
To configure the jumphost, web servers, and database servers, we use ``group_vars``. The ``group_vars`` directory contains 4 files for configuration of the groups: cloud-vm, jumphost, webserver, and db-server. The cloud-vm is there for specifying the defaults of our cloud infrastructure.
..code-block:: yaml
@ -262,9 +262,9 @@ Now to the fun part. We create a playbook to create our infrastructure we call i
In the above play we defined 3 tasks and use the group ``cloud-vm`` as target to handle all VMs in the cloud but instead SSH to these VMs, we use ``connection=local`` to execute the API calls locally from our workstation.
In the above play we defined 3 tasks and used the group ``cloud-vm`` as target to handle all VMs in the cloud but instead SSH to these VMs, we use ``connection=local`` to execute the API calls locally from our workstation.
In the first task, we ensure we have a running VM created with the Debian template. If the VM is already created but stopped, it would just start it. If you like to change the offering on an existing VM, you must add ``force: yes`` to the task, which would stop the VM, change the offering and start the VM again.
In the first task, we ensure we have a running VM created with the Debian template. If the VM is already created but stopped, it would just start it. If you like to change the offering on an existing VM, you must add ``force: yes`` to the task, which would stop the VM, change the offering, and start the VM again.
In the second task we ensure the ports are opened if we give a public IP to the VM.
`Packet.net <https://packet.net>`_ is a bare metal infrastructure host that's supported by Ansible (>=2.3) via a dynamic inventory script and two cloud modules. The two modules are:
- packet_sshkey: adds a public SSH key from file or value to the Packet infrastructure. Every subsequently-created device will have this public key installed in .ssh/authorized_keys.
- packet_device: manages servers on Packet. You can use this module to create, restart and delete devices.
- packet_device: manages servers on Packet. You can use this module to create, restart, and delete devices.
Note, this guide assumes you are familiar with Ansible and how it works. If you're not, have a look at their `docs <http://docs.ansible.com/>`_ before getting started.
@ -183,7 +183,7 @@ The following playbook will create an SSH key, 3 Packet servers, and then wait u
As with most Ansible modules, the default states of the Packet modules are idempotent, meaning the resources in your project will remain the same after re-runs of a playbook. Thus, we can keep the ``packet_sshkey`` module call in our playbook. If the public key is already in your Packet account, the call will have no effect.
The second module call provisions 3 Packet Type 0 (specified using the 'plan' parameter) servers in the project identified via the 'project_id' parameter. The servers are all provisioned with CoresOS beta (the 'operating_system' parameter) and are customized with cloud-config user data passed to the 'user_data' parameter.
The second module call provisions 3 Packet Type 0 (specified using the 'plan' parameter) servers in the project identified via the 'project_id' parameter. The servers are all provisioned with CoreOS beta (the 'operating_system' parameter) and are customized with cloud-config user data passed to the 'user_data' parameter.
The ``packet_device`` module has a boolean 'wait' parameter that defaults to 'false'. If set to 'true', Ansible will wait until the GET API call for a device will contain an Internet-routeable IP address. The 'wait' parameter allows us to use the IP address of the device as soon as it's available.
@ -66,7 +66,7 @@ Using BSD as the control machine is as simple as installing the Ansible package
BSD Facts
`````````
Ansible gathers facts from the BSDs in a similar manner to Linux machines, but since the data, names and structures can vary for network, disks and other devices, one should expect the output to be slightly different yet still familiar to a BSD administrator.
Ansible gathers facts from the BSDs in a similar manner to Linux machines, but since the data, names, and structures can vary for network, disks, and other devices, one should expect the output to be slightly different yet still familiar to a BSD administrator.
Each instance can have a variety of key/value pairs associated with it called Tags. The most common tag key is 'Name', though anything is possible. Each key/value pair is its own group of instances, again with special characters converted to underscores, in the format ``tag_KEY_VALUE``
Each instance can have a variety of key/value pairs associated with it called Tags. The most common tag key is 'Name', though anything is possible. Each key/value pair is its own group of instances, again with special characters converted to underscores, in the format ``tag_KEY_VALUE``.
An OpenStack RC file contains the environment variables required by the client tools to establish a connection with the cloud provider, such as the authentication URL, user name, password and region name. For more information on how to download, create or source an OpenStack RC file, please refer to `Set environment variables using the OpenStack RC file <http://docs.openstack.org/user-guide/common/cli_set_environment_variables_using_openstack_rc.html>`_.
An OpenStack RC file contains the environment variables required by the client tools to establish a connection with the cloud provider, such as the authentication URL, user name, password, and region name. For more information on how to download, create or source an OpenStack RC file, please refer to `Set environment variables using the OpenStack RC file <http://docs.openstack.org/user-guide/common/cli_set_environment_variables_using_openstack_rc.html>`_.
You can confirm the file has been successfully sourced by running a simple command, such as `nova list` and ensuring it return no errors.
@ -286,13 +286,13 @@ Once you confirm the dynamic inventory script is working as expected, you can te
Implicit use of inventory script
++++++++++++++++++++++++++++++++
Download the latest version of the OpenStack dynamic inventory script, make it executable and copy it to `/etc/ansible/hosts`::
Download the latest version of the OpenStack dynamic inventory script, make it executable, and copy it to `/etc/ansible/hosts`::
Readers that use virtualenv can also install Ansible under virtualenv, though we'd recommend to not worry about it and just install Ansible globally. Do not use easy_install to install ansible directly.
Readers that use virtualenv can also install Ansible under virtualenv, though we'd recommend to not worry about it and just install Ansible globally. Do not use easy_install to install Ansible directly.
@ -11,7 +11,7 @@ which defaults to being saved in the location ``/etc/ansible/hosts``.
You can specify a different inventory file using the ``-i <path>`` option on the command line.
Not only is this inventory configurable, but you can also use multiple inventory files at the same time and
pull inventory from dynamic or cloud sources or different formats (YAML, ini, etc), as described in :doc:`intro_dynamic_inventory`.
pull inventory from dynamic or cloud sources or different formats (YAML, ini, etc.), as described in :doc:`intro_dynamic_inventory`.
Introduced in version 2.4, Ansible has inventory plugins to make this flexible and customizable.
.._inventoryformat:
@ -319,7 +319,7 @@ General for all connections:
ansible_host
The name of the host to connect to, if different from the alias you wish to give to it.
ansible_port
The ssh port number, if not 22
The ssh port number, if not 22.
ansible_user
The default ssh user name to use.
@ -327,7 +327,7 @@ ansible_user
Specific to the SSH connection:
ansible_ssh_pass
The ssh password to use (never store this variable in plain text; always use a vault. See :ref:`best_practices_for_variables_and_vaults`)
The ssh password to use (never store this variable in plain text; always use a vault. See :ref:`best_practices_for_variables_and_vaults`).
ansible_ssh_private_key_file
Private key file used by ssh. Useful if using multiple keys and you don't want to use SSH agent.
ansible_ssh_common_args
@ -349,17 +349,17 @@ ansible_ssh_executable (added in version 2.2)
Privilege escalation (see :doc:`Ansible Privilege Escalation<become>` for further details):
ansible_become
Equivalent to ``ansible_sudo`` or ``ansible_su``, allows to force privilege escalation
Equivalent to ``ansible_sudo`` or ``ansible_su``, allows to force privilege escalation.
ansible_become_method
Allows to set privilege escalation method
Allows to set privilege escalation method.
ansible_become_user
Equivalent to ``ansible_sudo_user`` or ``ansible_su_user``, allows to set the user you become through privilege escalation
Equivalent to ``ansible_sudo_user`` or ``ansible_su_user``, allows to set the user you become through privilege escalation.
ansible_become_pass
Equivalent to ``ansible_sudo_pass`` or ``ansible_su_pass``, allows you to set the privilege escalation password (never store this variable in plain text; always use a vault. See :ref:`best_practices_for_variables_and_vaults`)
Equivalent to ``ansible_sudo_pass`` or ``ansible_su_pass``, allows you to set the privilege escalation password (never store this variable in plain text; always use a vault. See :ref:`best_practices_for_variables_and_vaults`).
ansible_become_exe
Equivalent to ``ansible_sudo_exe`` or ``ansible_su_exe``, allows you to set the executable for the escalation method selected
Equivalent to ``ansible_sudo_exe`` or ``ansible_su_exe``, allows you to set the executable for the escalation method selected.
ansible_become_flags
Equivalent to ``ansible_sudo_flags`` or ``ansible_su_flags``, allows you to set the flags passed to the selected escalation method. This can be also set globally in :file:`ansible.cfg` in the ``sudo_flags`` option
Equivalent to ``ansible_sudo_flags`` or ``ansible_su_flags``, allows you to set the flags passed to the selected escalation method. This can be also set globally in :file:`ansible.cfg` in the ``sudo_flags`` option.
Remote host environment parameters:
@ -384,7 +384,7 @@ ansible_shell_executable
overrides ``executable`` in :file:`ansible.cfg` which defaults to
:command:`/bin/sh`. You should really only change it if is not possible
to use :command:`/bin/sh` (i.e. :command:`/bin/sh` is not installed on the target
machine or cannot be run from sudo.).
machine or cannot be run from sudo).
Examples from an Ansible-INI host file::
@ -449,7 +449,7 @@ Here is an example of how to instantly deploy to created containers::
:doc:`intro_adhoc`
Examples of basic commands
:doc:`playbooks`
Learning Ansible's configuration, deployment, and orchestration language.
Learning Ansible's configuration, deployment, and orchestration language
`Mailing List <http://groups.google.com/group/ansible-project>`_
Questions? Help? Ideas? Stop by the list on Google Groups
@ -59,7 +59,7 @@ Once WSL is enabled, you can open the Bash terminal. At the prompt, you can quic
# https://github.com/Microsoft/BashOnWindows/issues/816#issuecomment-301216901 for details
source ~/.profile
After you've successfully run these commands, you can start to create your inventory, write example playbooks and start targeting systems using the plethora of available Windows modules.
After you've successfully run these commands, you can start to create your inventory, write example playbooks, and start targeting systems using the plethora of available Windows modules.
If you want to run Ansible from source for development purposes, simply uninstall the pip-installed version (which will leave all the necessary dependencies behind), then clone the Ansible source, and run the hacking script to configure it to run from source::
@ -94,7 +94,7 @@ You can specify which authentication option you wish to use by setting it to the
Certificate
+++++++++++
Certificate authentication is similar to SSH where a certificate is assigned to a local user and instead of using a password to authenticate a certificate is used instead.
Certificate authentication is similar to SSH where a certificate is assigned to a local user and instead of using a password to authenticate a certificate is used.
Kerberos
@ -142,7 +142,7 @@ Kerberos is installed and configured by default on OS X and many Linux distribut
Configuring Kerberos
--------------------
Edit your /etc/krb5.conf (which should be installed as a result of installing packages above) and add the following information for each domain you need to connect to:
Edit your `/etc/krb5.conf` (which should be installed as a result of installing packages above) and add the following information for each domain you need to connect to:
In the section that starts with
@ -204,13 +204,13 @@ If you unable to connect using kerberos, check the following:
Ensure that forward and reverse DNS lookups are working properly on your domain.
To test this, ping the windows host you want to control by name then use the ip address returned with nslookup. You should get the same name back from DNS when you use nslookup on the ip address.
To test this, ping the Windows host you want to control by name then use the ip address returned with nslookup. You should get the same name back from DNS when you use nslookup on the ip address.
If you get different hostnames back than the name you originally pinged, speak to your active directory administrator and get them to check that DNS Scavenging is enabled and that DNS and DHCP are updating each other.
Ensure that the Ansible controller has a properly configured computer account in the domain.
Check your Ansible controller's clock is synchronised with your domain controller. Kerberos is time sensitive and a little clock drift can cause tickets not be granted.
Check your Ansible controller's clock is synchronised with your domain controller. Kerberos is time sensitive and a little clock drift can cause tickets not to be granted.
Check you are using the real fully qualified domain name for the domain. Sometimes domains are commonly known to users by aliases. To check this run:
@ -242,7 +242,7 @@ To install credssp you can use pip to install the requests-credssp library:
CredSSP and TLS 1.2
-------------------
CredSSP requires the remote host to have TLS 1.2 configured or else the connection will fail. TLS 1.2 is installed by default from Server 2012 and Windows 8 onwards. For Server 2008, 2008 R2 and Windows 7 you can add TLS 1.2 support by:
CredSSP requires the remote host to have TLS 1.2 configured or else the connection will fail. TLS 1.2 is installed by default from Server 2012 and Windows 8 onward. For Server 2008, 2008 R2, and Windows 7 you can add TLS 1.2 support by:
* Installing the `TLS 1.2 update from Microsoft <https://support.microsoft.com/en-us/help/3080079/update-to-add-rds-support-for-tls-1.1-and-tls-1.2-in-windows-7-or-windows-server-2008-r2>`_
* Adding the TLS 1.2 registry keys as shown on this `page <https://technet.microsoft.com/en-us/library/dn786418.aspx#BKMK_SchannelTR_TLS12>`_
@ -255,7 +255,7 @@ If you need to interact with a remote resource or run a process that requires th
Inventory
`````````
Ansible's windows support relies on a few standard variables to indicate the username, password, and connection type (windows) of the remote hosts. These variables are most easily set up in inventory. This is used instead of SSH-keys or passwords as normally fed into Ansible::
Ansible's Windows support relies on a few standard variables to indicate the username, password, and connection type (Windows) of the remote hosts. These variables are most easily set up in inventory. This is used instead of SSH-keys or passwords as normally fed into Ansible::
[windows]
winserver1.example.com
@ -311,7 +311,7 @@ Since 2.0, the following custom inventory variables are also supported for addit
Windows System Prep
```````````````````
In order for Ansible to manage your windows machines, you will have to enable and configure PowerShell remoting.
In order for Ansible to manage your Windows machines, you will have to enable and configure PowerShell remoting.
To automate the setup of WinRM, you can run the `examples/scripts/ConfigureRemotingForAnsible.ps1 <https://github.com/ansible/ansible/blob/devel/examples/scripts/ConfigureRemotingForAnsible.ps1>`_ script on the remote machine in a PowerShell console as an administrator.
@ -340,7 +340,7 @@ To troubleshoot the ``ConfigureRemotingForAnsible.ps1`` writes every change it m
Management Framework 3.0, it may be necessary to install this
hotfix http://support.microsoft.com/kb/2842230 to avoid receiving
out of memory and stack overflow exceptions. Newly-installed Server 2008
R2 systems which are not fully up to date with windows updates are known
R2 systems which are not fully up to date with Windows updates are known
to have this issue.
Windows 8.1 and Server 2012 R2 are not affected by this issue as they
@ -386,9 +386,9 @@ In addition, the following core modules/action-plugins work with Windows:
* template (also: win_template)
* wait_for_connection
Some modules can be utilised in playbooks that target windows by delegating to localhost, depending on what you are
Some modules can be utilised in playbooks that target Windows by delegating to localhost, depending on what you are
attempting to achieve. For example, ``assemble`` can be used to create a file on your ansible controller that is then
sent to your windows targets using ``win_copy``.
sent to your Windows targets using ``win_copy``.
In many cases, there is no need to use or write an Ansible module. In particular, the ``script`` module can be used to run arbitrary PowerShell scripts, allowing Windows administrators familiar with PowerShell a very native way to do things, as in the following playbook::
@ -425,7 +425,7 @@ Modules (ps1 files) should start as follows::
# code goes here, reading in stdin as JSON and outputting JSON
The above magic is necessary to tell Ansible to mix in some common code and also know how to push modules out. The common code contains some nice wrappers around working with hash data structures and emitting JSON results, and possibly a few more useful things. Regular Ansible has this same concept for reusing Python code - this is just the windows equivalent.
The above magic is necessary to tell Ansible to mix in some common code and also know how to push modules out. The common code contains some nice wrappers around working with hash data structures and emitting JSON results, and possibly a few more useful things. Regular Ansible has this same concept for reusing Python code - this is just the Windows equivalent.
What modules you see in ``windows/`` are just a start. Additional modules may be submitted as pull requests to github.
@ -434,7 +434,7 @@ What modules you see in ``windows/`` are just a start. Additional modules may b
Windows Facts
`````````````
Just as with Linux/Unix, facts can be gathered for windows hosts, which will return things such as the operating system version. To see what variables are available about a windows host, run the following::
Just as with Linux/Unix, facts can be gathered for Windows hosts, which will return things such as the operating system version. To see what variables are available about a Windows host, run the following::
@ -171,7 +171,7 @@ Here are some corner cases encountered when updating. These are mostly caused by
with_items: myvar_{{rest_of_name}}
This worked 'by accident' as the errors were retemplated and ended up resolving the variable, it was never intended as valid syntax and now properly returns an error, use the following instead.::
This worked 'by accident' as the errors were retemplated and ended up resolving the variable, it was never intended as valid syntax and now properly returns an error, use the following instead::
@ -287,7 +287,7 @@ Since the ansible-2.0 plugin system is more advanced, it is easier to adapt your
You may find the following tips useful:
* Check whether the ansible-2.0 class(es) are available and if they are missing (ansible-1.9.x) mimic them with the needed methods (e.g. ``__init__``)
* Check whether the ansible-2.0 class(es) are available and if they are missing (ansible-1.9.x) mimic them with the needed methods (e.g. ``__init__``).
* When ansible-2.0 python modules are imported, and they fail (ansible-1.9.x), catch the ``ImportError`` exception and perform the equivalent imports for ansible-1.9.x. With possible translations (e.g. importing specific methods).
@ -297,7 +297,7 @@ You may find the following tips useful:
* When doing plugin development, it is very useful to have the ``warning()`` method during development, but it is also important to emit warnings for deadends (cases that you expect should never be triggered) or corner cases (e.g. cases where you expect misconfigurations).
* It helps to look at other plugins in ansible-1.9.x and ansible-2.0 to understand how the API works and what modules, classes and methods are available.
* It helps to look at other plugins in ansible-1.9.x and ansible-2.0 to understand how the API works and what modules, classes, and methods are available.
Josh Soref
8 years ago
committed by