Resolving Ansible installation failures on a VirtualBox Windows guest typically requires verifying WinRM connectivity, ensuring the target machine is configured for remote management, and checking network adapter settings. This guide details the diagnostic steps to establish a stable connection between your host and the virtual machine, allowing successful IIS deployment.
Verifying WinRM Configuration
The most common cause of Ansible failure in this environment is an improperly configured Windows Remote Management (WinRM) service. Ansible relies on PowerShell or CMD over WinRM to execute commands on the target node. If this service is not listening on the correct port or uses the wrong authentication method, the connection will time out or fail immediately.
To verify the configuration, you must access the command line within the VirtualBox Windows instance. Open PowerShell as an administrator and run the following command to check the current listener status:
winrm enumerate winrm/config/listenerYou should see a listener configured for HTTPS or HTTP on port 5985 or 5986. If no listeners are present, or if they are restricted to localhost only, Ansible cannot reach the machine from your host system. A standard setup for development environments often uses HTTP on port 5985 with basic authentication. You can configure this automatically by running:
winrm quickconfig -qThis command prompts for permission to start the service and add firewall exceptions. Accept all defaults unless you have specific security constraints. After running this, verify that the listener appears in the enumeration output again. Ensure that the Transport is set to HTTP or HTTPS and that the Address is set to * or the specific IP address of the virtual machine.
Checking Network Connectivity and VirtualBox Settings
Even with correct WinRM settings, network isolation in VirtualBox can prevent communication. The default NAT network allows outbound traffic but blocks inbound connections from the host by default. To allow Ansible on your host to reach the Windows guest, you need to adjust the network adapter settings.
Navigate to the VirtualBox Manager, select your Windows VM, and go to Settings > Network. Change the "Attached to" dropdown from NAT to Host-only Adapter or Bridged Adapter. Host-only adapters create a private network between the host and the guest, which is ideal for isolated testing. Bridged adapters connect the guest directly to your physical network, giving it an IP address assigned by your router.
If you switch to a Host-only Adapter, you may encounter issues where the virtual machine does not receive an IP address after a Windows update or reboot. In such cases, refer to our guide on Fixing VirtualBox Host-only Network: No IP Address After Windows Update to restore connectivity. Once the network type is changed, ensure that the Windows Firewall inside the guest allows incoming connections on port 5985 (for HTTP) or 5986 (for HTTPS).
You can test connectivity from your host machine using the ping command against the guest's IP address. If ping fails, check the VirtualBox network settings again. If ping succeeds but Ansible still fails, the issue is likely authentication or WinRM protocol related.
Configuring Ansible Inventory and Variables
With the network and WinRM services verified, you must ensure your Ansible inventory file correctly points to the virtual machine. The inventory file defines the target hosts and their connection variables. For a Windows host, you must specify the connection type as winrm.
Create or edit your hosts file in the Ansible project directory. Add an entry for your Windows VM under a group, such as [windows]. Define the necessary variables to handle authentication and SSL verification. Since many local setups use self-signed certificates or plain HTTP, you must disable strict SSL verification to avoid certificate errors.
[windows]
192.168.56.101 ansible_connection=winrm ansible_user=Administrator ansible_password=YourPassword ansible_winrm_server_cert_validation=ignore ansible_winrm_transport=basicReplace 192.168.56.101 with the actual IP address of your VirtualBox guest. The variable ansible_winrm_server_cert_validation=ignore is crucial for local development environments where valid certificates are rarely installed. The transport method basic is widely supported but less secure; consider using ntlm if your domain environment supports it.
After updating the inventory, test the connection using the Ansible ad-hoc command. Run the following command from your terminal:
ansible windows -m win_ping -i hostsA successful response returns {"changed": false, "ping": "pong"}. If you receive a timeout error, double-check the firewall rules on the Windows guest. If you receive an authentication error, verify the username and password. Note that the Administrator account must have a password set; blank passwords are rejected by WinRM by default.
Deploying IIS Web-Server
Once the win_ping module confirms connectivity, you can proceed with installing the IIS Web-Server role. Use the windows_feature module, which is designed specifically for managing Windows roles and features.
Create a simple playbook named iis_install.yml:
- name: Install IIS Web Server
hosts: windows
tasks:
- name: Install IIS Feature
windows_feature:
name: Web-Server
state: presentRun this playbook using the command ansible-playbook iis_install.yml -i hosts. Ansible will connect to the Windows guest, install the IIS components, and report the result. If the installation fails, check the Windows Event Viewer on the guest machine for detailed error logs related to Windows Feature installation.
Frequently Asked Questions
Why does Ansible timeout when connecting to my VirtualBox VM?
A timeout usually indicates that the host cannot reach the guest's IP address or that the WinRM port is blocked. Verify that the VirtualBox network adapter is set to Host-only or Bridged mode and that the Windows Firewall allows inbound traffic on port 5985 or 5986. Additionally, ensure the WinRM service is actually running on the guest.
How do I fix a blank password authentication error in Ansible?
WinRM rejects connections with blank passwords for security reasons. You must set a strong password for the Administrator account on the Windows guest before Ansible can authenticate. Alternatively, you can enable unsigned scripts and configure WinRM to accept empty credentials, but this is not recommended for production environments.
What should I do if the win_ping module fails with a certificate error?
Certificate errors occur when Ansible validates the SSL certificate presented by the WinRM service. In local development, you can bypass this by setting ansible_winrm_server_cert_validation=ignore in your inventory file. This tells Ansible to trust the connection regardless of the certificate validity.
Can I use SSH instead of WinRM for Ansible on Windows?
While possible, SSH support on Windows is more complex to configure than WinRM. You would need to install an SSH server like OpenSSH Server on the Windows guest and configure key-based authentication. WinRM is the native and recommended protocol for Ansible on Windows because it integrates directly with PowerShell.
How do I troubleshoot IIS installation failures via Ansible?
If the windows_feature module fails, check the Windows Event Viewer on the guest machine under Applications and Services Logs > Microsoft > Windows > ServerManager. Look for errors related to dependency packages or disk space. Ensuring the Windows Update service is running can also resolve missing dependency issues.