mirror of https://github.com/ansible/ansible.git
You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
410 lines
19 KiB
ReStructuredText
410 lines
19 KiB
ReStructuredText
10 years ago
|
Windows Support
|
||
|
===============
|
||
|
|
||
|
.. contents:: Topics
|
||
|
|
||
|
.. _windows_how_does_it_work:
|
||
|
|
||
|
Windows: How Does It Work
|
||
10 years ago
|
`````````````````````````
|
||
|
|
||
9 years ago
|
As you may have already read, Ansible manages Linux/Unix machines using SSH by default.
|
||
10 years ago
|
|
||
10 years ago
|
Starting in version 1.7, Ansible also contains support for managing Windows machines. This uses
|
||
10 years ago
|
native PowerShell remoting, rather than SSH.
|
||
10 years ago
|
|
||
10 years ago
|
Ansible will still be run from a Linux control machine, and uses the "winrm" Python module to talk to remote hosts.
|
||
10 years ago
|
|
||
10 years ago
|
No additional software needs to be installed on the remote machines for Ansible to manage them, it still maintains the agentless properties that make it popular on Linux/Unix.
|
||
10 years ago
|
|
||
10 years ago
|
Note that it is expected you have a basic understanding of Ansible prior to jumping into this section, so if you haven't written a Linux playbook first, it might be worthwhile to dig in there first.
|
||
|
|
||
10 years ago
|
.. _windows_installing:
|
||
|
|
||
10 years ago
|
Installing on the Control Machine
|
||
10 years ago
|
`````````````````````````````````
|
||
10 years ago
|
|
||
|
On a Linux control machine::
|
||
|
|
||
9 years ago
|
pip install "pywinrm>=0.1.1"
|
||
10 years ago
|
|
||
9 years ago
|
Note:: on distributions with multiple python versions, use pip2 or pip2.x, where x matches the python minor version Ansible is running under.
|
||
|
|
||
9 years ago
|
Active Directory Support
|
||
|
++++++++++++++++++++++++
|
||
10 years ago
|
|
||
8 years ago
|
If you wish to connect to domain accounts published through Active Directory (as opposed to local accounts created on the remote host), you will need to install the "python-kerberos" module on the Ansible control host (and the MIT krb5 libraries it depends on). The Ansible control host also requires a properly configured computer account in Active Directory.
|
||
9 years ago
|
|
||
|
Installing python-kerberos dependencies
|
||
|
---------------------------------------
|
||
|
|
||
|
.. code-block:: bash
|
||
|
|
||
|
# Via Yum
|
||
|
yum -y install python-devel krb5-devel krb5-libs krb5-workstation
|
||
9 years ago
|
|
||
9 years ago
|
# Via Apt (Ubuntu)
|
||
8 years ago
|
sudo apt-get install python-dev libkrb5-dev krb5-user
|
||
9 years ago
|
|
||
9 years ago
|
# Via Portage (Gentoo)
|
||
9 years ago
|
emerge -av app-crypt/mit-krb5
|
||
9 years ago
|
emerge -av dev-python/setuptools
|
||
10 years ago
|
|
||
9 years ago
|
# Via pkg (FreeBSD)
|
||
|
sudo pkg install security/krb5
|
||
9 years ago
|
|
||
9 years ago
|
# Via OpenCSW (Solaris)
|
||
|
pkgadd -d http://get.opencsw.org/now
|
||
|
/opt/csw/bin/pkgutil -U
|
||
9 years ago
|
/opt/csw/bin/pkgutil -y -i libkrb5_3
|
||
|
|
||
9 years ago
|
# Via Pacman (Arch Linux)
|
||
|
pacman -S krb5
|
||
|
|
||
|
Installing python-kerberos
|
||
|
--------------------------
|
||
|
|
||
9 years ago
|
Once you've installed the necessary dependencies, the python-kerberos wrapper can be installed via pip:
|
||
9 years ago
|
|
||
|
.. code-block:: bash
|
||
|
|
||
8 years ago
|
pip install kerberos requests_kerberos
|
||
9 years ago
|
|
||
10 years ago
|
Kerberos is installed and configured by default on OS X and many Linux distributions. If your control machine has not already done this for you, you will need to.
|
||
|
|
||
9 years ago
|
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:
|
||
|
|
||
|
In the section that starts with
|
||
|
|
||
|
.. code-block:: bash
|
||
|
|
||
|
[realms]
|
||
|
|
||
|
add the full domain name and the fully qualified domain names of your primary and secondary Active Directory domain controllers. It should look something like this:
|
||
|
|
||
|
.. code-block:: bash
|
||
|
|
||
|
[realms]
|
||
|
|
||
|
MY.DOMAIN.COM = {
|
||
|
kdc = domain-controller1.my.domain.com
|
||
|
kdc = domain-controller2.my.domain.com
|
||
|
}
|
||
|
|
||
|
|
||
|
and in the [domain_realm] section add a line like the following for each domain you want to access:
|
||
|
|
||
|
.. code-block:: bash
|
||
|
|
||
|
[domain_realm]
|
||
|
.my.domain.com = MY.DOMAIN.COM
|
||
|
|
||
|
You may wish to configure other settings here, such as the default domain.
|
||
|
|
||
|
Testing a kerberos connection
|
||
|
-----------------------------
|
||
|
|
||
|
If you have installed krb5-workstation (yum) or krb5-user (apt-get) you can use the following command to test that you can be authorised by your domain controller.
|
||
|
|
||
|
.. code-block:: bash
|
||
|
|
||
|
kinit user@MY.DOMAIN.COM
|
||
|
|
||
|
Note that the domain part has to be fully qualified and must be in upper case.
|
||
|
|
||
|
To see what tickets if any you have acquired, use the command klist
|
||
|
|
||
|
.. code-block:: bash
|
||
|
|
||
|
klist
|
||
|
|
||
|
|
||
|
Troubleshooting kerberos connections
|
||
|
------------------------------------
|
||
|
|
||
|
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.
|
||
|
|
||
|
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.
|
||
|
|
||
9 years ago
|
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.
|
||
9 years ago
|
|
||
|
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:
|
||
|
|
||
|
|
||
|
.. code-block:: bash
|
||
|
|
||
|
kinit -C user@MY.DOMAIN.COM
|
||
|
klist
|
||
|
|
||
|
If the domain name returned by klist is different from the domain name you requested, you are requesting using an alias, and you need to update your krb5.conf so you are using the fully qualified domain name, not its alias.
|
||
|
|
||
10 years ago
|
.. _windows_inventory:
|
||
|
|
||
|
Inventory
|
||
|
`````````
|
||
|
|
||
10 years ago
|
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::
|
||
10 years ago
|
|
||
|
[windows]
|
||
10 years ago
|
winserver1.example.com
|
||
10 years ago
|
winserver2.example.com
|
||
10 years ago
|
|
||
8 years ago
|
.. include:: ../rst_common/ansible_ssh_changes_note.rst
|
||
9 years ago
|
|
||
8 years ago
|
In group_vars/windows.yml, define the following inventory variables::
|
||
10 years ago
|
|
||
8 years ago
|
# it is suggested that these be encrypted with ansible-vault:
|
||
|
# ansible-vault edit group_vars/windows.yml
|
||
10 years ago
|
|
||
8 years ago
|
ansible_user: Administrator
|
||
|
ansible_password: SecretPasswordGoesHere
|
||
|
ansible_port: 5986
|
||
|
ansible_connection: winrm
|
||
8 years ago
|
# The following is necessary for Python 2.7.9+ (or any older Python that has backported SSLContext, eg, Python 2.7.5 on RHEL7) when using default WinRM self-signed certificates:
|
||
8 years ago
|
ansible_winrm_server_cert_validation: ignore
|
||
10 years ago
|
|
||
9 years ago
|
Attention for the older style variables (``ansible_ssh_*``): ansible_ssh_password doesn't exist, should be ansible_ssh_pass.
|
||
|
|
||
9 years ago
|
Although Ansible is mostly an SSH-oriented system, Windows management will not happen over SSH (`yet <http://blogs.msdn.com/b/powershell/archive/2015/06/03/looking-forward-microsoft-support-for-secure-shell-ssh.aspx>`).
|
||
10 years ago
|
|
||
8 years ago
|
If you have installed the ``kerberos`` module and ``ansible_user`` contains ``@`` (e.g. ``username@realm``), Ansible will first attempt Kerberos authentication. *This method uses the principal you are authenticated to Kerberos with on the control machine and not* ``ansible_user``. If that fails, either because you are not signed into Kerberos on the control machine or because the corresponding domain account on the remote host is not available, then Ansible will fall back to "plain" username/password authentication.
|
||
10 years ago
|
|
||
10 years ago
|
When using your playbook, don't forget to specify --ask-vault-pass to provide the password to unlock the file.
|
||
|
|
||
|
Test your configuration like so, by trying to contact your Windows nodes. Note this is not an ICMP ping, but tests the Ansible
|
||
|
communication channel that leverages Windows remoting::
|
||
|
|
||
10 years ago
|
ansible windows [-i inventory] -m win_ping --ask-vault-pass
|
||
10 years ago
|
|
||
10 years ago
|
If you haven't done anything to prep your systems yet, this won't work yet. This is covered in a later
|
||
10 years ago
|
section about how to enable PowerShell remoting - and if necessary - how to upgrade PowerShell to
|
||
10 years ago
|
a version that is 3 or higher.
|
||
|
|
||
10 years ago
|
You'll run this command again later though, to make sure everything is working.
|
||
10 years ago
|
|
||
8 years ago
|
Since 2.0, the following custom inventory variables are also supported for additional configuration of WinRM connections::
|
||
|
|
||
|
* ``ansible_winrm_scheme``: Specify the connection scheme (``http`` or ``https``) to use for the WinRM connection. Ansible uses ``https`` by default unless the port is 5985.
|
||
|
* ``ansible_winrm_path``: Specify an alternate path to the WinRM endpoint. Ansible uses ``/wsman`` by default.
|
||
|
* ``ansible_winrm_realm``: Specify the realm to use for Kerberos authentication. If the username contains ``@``, Ansible will use the part of the username after ``@`` by default.
|
||
|
* ``ansible_winrm_transport``: Specify one or more transports as a comma-separated list. By default, Ansible will use ``kerberos,plaintext`` if the ``kerberos`` module is installed and a realm is defined, otherwise ``plaintext``.
|
||
|
* ``ansible_winrm_server_cert_validation``: Specify the server certificate validation mode (``ignore`` or ``validate``). Ansible defaults to ``validate`` on Python 2.7.9 and higher, which will result in certificate validation errors against the Windows self-signed certificates. Unless verifiable certificates have been configured on the WinRM listeners, this should be set to ``ignore``
|
||
|
* ``ansible_winrm_*``: Any additional keyword arguments supported by ``winrm.Protocol`` may be provided.
|
||
|
|
||
10 years ago
|
.. _windows_system_prep:
|
||
|
|
||
10 years ago
|
Windows System Prep
|
||
|
```````````````````
|
||
10 years ago
|
|
||
8 years ago
|
In order for Ansible to manage your windows machines, you will have to enable and configure PowerShell remoting.
|
||
10 years ago
|
|
||
8 years ago
|
To automate the setup of WinRM, you can run `this PowerShell script <https://github.com/ansible/ansible/blob/devel/examples/scripts/ConfigureRemotingForAnsible.ps1>`_ on the remote machine.
|
||
10 years ago
|
|
||
9 years ago
|
The example script accepts a few arguments which Admins may choose to use to modify the default setup slightly, which might be appropriate in some cases.
|
||
10 years ago
|
|
||
9 years ago
|
Pass the -CertValidityDays option to customize the expiration date of the generated certificate.
|
||
|
powershell.exe -File ConfigureRemotingForAnsible.ps1 -CertValidityDays 100
|
||
|
|
||
|
Pass the -SkipNetworkProfileCheck switch to configure winrm to listen on PUBLIC zone interfaces. (Without this option, the script will fail if any network interface on device is in PUBLIC zone)
|
||
|
powershell.exe -File ConfigureRemotingForAnsible.ps1 -SkipNetworkProfileCheck
|
||
10 years ago
|
|
||
9 years ago
|
Pass the -ForceNewSSLCert switch to force a new SSL certificate to be attached to an already existing winrm listener. (Avoids SSL winrm errors on syspreped Windows images after the CN changes)
|
||
|
powershell.exe -File ConfigureRemotingForAnsible.ps1 -ForceNewSSLCert
|
||
|
|
||
10 years ago
|
.. note::
|
||
9 years ago
|
On Windows 7 and Server 2008 R2 machines, due to a bug in Windows
|
||
10 years ago
|
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
|
||
9 years ago
|
to have this issue.
|
||
10 years ago
|
|
||
|
Windows 8.1 and Server 2012 R2 are not affected by this issue as they
|
||
|
come with Windows Management Framework 4.0.
|
||
|
|
||
10 years ago
|
.. _getting_to_powershell_three_or_higher:
|
||
|
|
||
10 years ago
|
Getting to PowerShell 3.0 or higher
|
||
10 years ago
|
```````````````````````````````````
|
||
10 years ago
|
|
||
10 years ago
|
PowerShell 3.0 or higher is needed for most provided Ansible modules for Windows, and is also required to run the above setup script. Note that PowerShell 3.0 is only supported on Windows 7 SP1, Windows Server 2008 SP1, and later releases of Windows.
|
||
10 years ago
|
|
||
9 years ago
|
Looking at an Ansible checkout, copy the `examples/scripts/upgrade_to_ps3.ps1 <https://github.com/cchurch/ansible/blob/devel/examples/scripts/upgrade_to_ps3.ps1>`_ script onto the remote host and run a PowerShell console as an administrator. You will now be running PowerShell 3 and can try connectivity again using the win_ping technique referenced above.
|
||
10 years ago
|
|
||
10 years ago
|
.. _what_windows_modules_are_available:
|
||
|
|
||
|
What modules are available
|
||
|
``````````````````````````
|
||
|
|
||
9 years ago
|
Most of the Ansible modules in core Ansible are written for a combination of Linux/Unix machines and arbitrary web services, though there are various
|
||
8 years ago
|
Windows-only modules. These are listed in the `"windows" subcategory of the Ansible module index <http://docs.ansible.com/list_of_windows_modules.html>`_.
|
||
8 years ago
|
|
||
8 years ago
|
In addition, the following core modules work with Windows:
|
||
8 years ago
|
assemble
|
||
|
fetch
|
||
|
raw
|
||
|
script
|
||
|
slurp
|
||
|
template
|
||
|
add_host
|
||
|
assert
|
||
|
debug
|
||
|
fail
|
||
|
group_by
|
||
|
include_vars
|
||
|
meta
|
||
|
pause
|
||
|
set_fact
|
||
10 years ago
|
|
||
|
Browse this index to see what is available.
|
||
|
|
||
10 years ago
|
In many cases, it may not be necessary to even write or use an Ansible module.
|
||
10 years ago
|
|
||
10 years ago
|
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::
|
||
10 years ago
|
|
||
|
- hosts: windows
|
||
|
tasks:
|
||
10 years ago
|
- script: foo.ps1 --argument --other-argument
|
||
|
|
||
8 years ago
|
Note:: There are a few other Ansible modules that don't start with "win" that also function with Windows, including "fetch", "slurp", "raw", and "setup" (which is how fact gathering works).
|
||
10 years ago
|
|
||
10 years ago
|
.. _developers_developers_developers:
|
||
10 years ago
|
|
||
|
Developers: Supported modules and how it works
|
||
|
``````````````````````````````````````````````
|
||
|
|
||
9 years ago
|
Developing Ansible modules are covered in a `later section of the documentation <http://docs.ansible.com/developing_modules.html>`_, with a focus on Linux/Unix.
|
||
|
What if you want to write Windows modules for Ansible though?
|
||
10 years ago
|
|
||
9 years ago
|
For Windows, Ansible modules are implemented in PowerShell. Skim those Linux/Unix module development chapters before proceeding. Windows modules in the core and extras repo live in a "windows/" subdir. Custom modules can go directly into the Ansible "library/" directories or those added in ansible.cfg. Documentation lives in a `.py` file with the same name. For example, if a module is named "win_ping", there will be embedded documentation in the "win_ping.py" file, and the actual PowerShell code will live in a "win_ping.ps1" file. Take a look at the sources and this will make more sense.
|
||
10 years ago
|
|
||
|
Modules (ps1 files) should start as follows::
|
||
|
|
||
|
#!powershell
|
||
10 years ago
|
# <license>
|
||
|
|
||
10 years ago
|
# WANT_JSON
|
||
|
# POWERSHELL_COMMON
|
||
|
|
||
|
# code goes here, reading in stdin as JSON and outputting JSON
|
||
|
|
||
10 years ago
|
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.
|
||
10 years ago
|
|
||
10 years ago
|
What modules you see in windows/ are just a start. Additional modules may be submitted as pull requests to github.
|
||
10 years ago
|
|
||
10 years ago
|
.. _windows_and_linux_control_machine:
|
||
|
|
||
10 years ago
|
Reminder: You Must Have a Linux Control Machine
|
||
|
```````````````````````````````````````````````
|
||
10 years ago
|
|
||
|
Note running Ansible from a Windows control machine is NOT a goal of the project. Refrain from asking for this feature,
|
||
|
as it limits what technologies, features, and code we can use in the main project in the future. A Linux control machine
|
||
|
will be required to manage Windows hosts.
|
||
10 years ago
|
|
||
10 years ago
|
Cygwin is not supported, so please do not ask questions about Ansible running from Cygwin.
|
||
|
|
||
10 years ago
|
.. _windows_facts:
|
||
|
|
||
|
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::
|
||
|
|
||
|
ansible winhost.example.com -m setup
|
||
|
|
||
|
Note that this command invocation is exactly the same as the Linux/Unix equivalent.
|
||
|
|
||
|
.. _windows_playbook_example:
|
||
|
|
||
|
Windows Playbook Examples
|
||
|
`````````````````````````
|
||
|
|
||
|
Look to the list of windows modules for most of what is possible, though also some modules like "raw" and "script" also work on Windows, as do "fetch" and "slurp".
|
||
|
|
||
10 years ago
|
Here is an example of pushing and running a PowerShell script::
|
||
10 years ago
|
|
||
|
- name: test script module
|
||
|
hosts: windows
|
||
|
tasks:
|
||
|
- name: run test script
|
||
|
script: files/test_script.ps1
|
||
|
|
||
|
Running individual commands uses the 'raw' module, as opposed to the shell or command module as is common on Linux/Unix operating systems::
|
||
|
|
||
|
- name: test raw module
|
||
|
hosts: windows
|
||
|
tasks:
|
||
|
- name: run ipconfig
|
||
|
raw: ipconfig
|
||
|
register: ipconfig
|
||
|
- debug: var=ipconfig
|
||
|
|
||
9 years ago
|
Running common DOS commands like 'del", 'move', or 'copy" is unlikely to work on a remote Windows Server using Powershell, but they can work by prefacing the commands with "CMD /C" and enclosing the command in double quotes as in this example::
|
||
|
|
||
|
- name: another raw module example
|
||
|
hosts: windows
|
||
|
tasks:
|
||
|
- name: Move file on remote Windows Server from one location to another
|
||
|
raw: CMD /C "MOVE /Y C:\teststuff\myfile.conf C:\builds\smtp.conf"
|
||
|
|
||
8 years ago
|
You may wind up with a more readable playbook by using the PowerShell equivalents of DOS commands. For example, to achieve the same effect as the example above, you could use::
|
||
8 years ago
|
|
||
|
- name: another raw module example demonstrating powershell one liner
|
||
|
hosts: windows
|
||
|
tasks:
|
||
|
- name: Move file on remote Windows Server from one location to another
|
||
|
raw: Move-Item C:\teststuff\myfile.conf C:\builds\smtp.conf
|
||
|
|
||
8 years ago
|
Bear in mind that using C(raw) will always report "changed", and it is your responsiblity to ensure PowerShell will need to handle idempotency as appropriate (the move examples above are inherently not idempotent), so where possible use (or write) a module.
|
||
8 years ago
|
|
||
8 years ago
|
Here's an example of how to use the win_stat module to test for file existence. Note that the data returned by the win_stat module is slightly different than what is provided by the Linux equivalent::
|
||
10 years ago
|
|
||
|
- name: test stat module
|
||
|
hosts: windows
|
||
|
tasks:
|
||
|
- name: test stat module on file
|
||
|
win_stat: path="C:/Windows/win.ini"
|
||
|
register: stat_file
|
||
|
|
||
|
- debug: var=stat_file
|
||
|
|
||
|
- name: check stat_file result
|
||
10 years ago
|
assert:
|
||
|
that:
|
||
10 years ago
|
- "stat_file.stat.exists"
|
||
|
- "not stat_file.stat.isdir"
|
||
10 years ago
|
- "stat_file.stat.size > 0"
|
||
10 years ago
|
- "stat_file.stat.md5"
|
||
|
|
||
8 years ago
|
Again, recall that the Windows modules are all listed in the Windows category of modules, with the exception that the "raw", "script", "slurp" and "fetch" modules are also available. These modules do not start with a "win" prefix.
|
||
10 years ago
|
|
||
|
.. _windows_contributions:
|
||
|
|
||
|
Windows Contributions
|
||
|
`````````````````````
|
||
|
|
||
8 years ago
|
Windows support in Ansible is still relatively new, and contributions are quite welcome, whether this is in the
|
||
10 years ago
|
form of new modules, tweaks to existing modules, documentation, or something else. Please stop by the ansible-devel mailing list if you would like to get involved and say hi.
|
||
|
|
||
10 years ago
|
.. seealso::
|
||
|
|
||
|
:doc:`developing_modules`
|
||
|
How to write modules
|
||
|
:doc:`playbooks`
|
||
9 years ago
|
Learning Ansible's configuration management language
|
||
10 years ago
|
`List of Windows Modules <http://docs.ansible.com/list_of_windows_modules.html>`_
|
||
10 years ago
|
Windows specific module list, all implemented in PowerShell
|
||
10 years ago
|
`Mailing List <http://groups.google.com/group/ansible-project>`_
|
||
|
Questions? Help? Ideas? Stop by the list on Google Groups
|
||
|
`irc.freenode.net <http://irc.freenode.net>`_
|
||
|
#ansible IRC chat channel
|