Diagnosing Packer Provisioner Connectivity Failures: SSH and WinRM

The Problem: Provisioner Connection Timeouts

A Packer build often fails during the transition from the 'builder' phase to the 'provisioner' phase. You will see an error stating that Packer cannot connect to the instance, typically resulting in a timeout or an authentication failure. This happens because the builder has successfully launched the VM, but the communicator (the mechanism Packer uses to send commands) cannot establish a stable handshake with the guest OS.

Quick Diagnostic Matrix

Symptom	Likely Cause	Primary Check
Timeout after several minutes	Guest OS not booted or Firewall blocking port	Security Group / Firewall rules
"Permission denied (publickey)"	Wrong SSH key or user mismatch	SSH key permissions and username
WinRM 401 Unauthorized	Credential mismatch or listener config	WinRM User/Password in HCL
WinRM Connection Refused	WinRM service not started/listening	Bootstrapper script execution

Step-by-Step Connectivity Troubleshooting

To isolate the failure, run your build with the debug flag to see the raw handshake attempts:

# Run from your local terminal
packer build -debug template.pkr.hcl

1. Network and Firewall Validation

Packer requires a clear network path to the instance. If you are using a cloud provider (AWS, Azure, GCP), the security group must allow inbound traffic from the Packer host's IP address.

• Linux: Ensure Port 22 (SSH) is open.
• Windows: Ensure Port 5985 (HTTP) or 5986 (HTTPS) is open.

Verification: Attempt a manual connection from the same machine running Packer using a standard client (e.g., ssh user@ip or Enter-PSSession -ComputerName ip). If the manual connection fails, the issue is network-level, not Packer-level.

2. SSH Key and User Permissions

For Linux images, Packer often fails if the private key on the host machine is too permissive. SSH clients will reject keys that are world-readable.

The Fix: Ensure your private key has the correct permissions (Unix-like systems):

# Run on the Packer host machine
chmod 400 /path/to/your/private_key.pem

Additionally, verify that the ssh_username defined in your HCL matches the default user of the image (e.g., ubuntu for Ubuntu images, ec2-user for Amazon Linux).

3. WinRM Listener Configuration

Windows instances require the WinRM service to be configured before Packer can connect. This is usually handled by a bootstrapper script. If the script fails or the listener is bound to the wrong interface, Packer will timeout.

Configuration Example: When using self-signed certificates for WinRM HTTPS, you must explicitly tell Packer to ignore certificate validation to avoid SSL handshake errors.

# Example WinRM communicator block in HCL
communicator = "winrm"
winrm_username = "Administrator"
winrm_use_ssl = true
winrm_insecure_connection = true # Required for self-signed certs

4. Timing and Boot Delays

Some heavy images take longer to initialize the SSH/WinRM daemon than the default Packer timeout allows. While increasing ssh_timeout or winrm_timeout can help, excessively high values may hide a kernel panic or a boot loop.

Diagnostic Check: Check the serial console logs of your cloud instance. If the OS is still performing "cloud-init" or running updates, the communicator will be unavailable.

Rollback and Recovery

Because connectivity failures occur during the build process, there is no state to "roll back" within the image. However, to prevent orphaned instances from incurring costs during failed debug sessions, ensure you use the -on-error=abort flag (default) or manually terminate the instance via your cloud console if the build crashes before the cleanup phase.

Escalation Criteria

If you have verified the following and the build still fails, the issue likely resides in the base image's OS configuration rather than Packer:

• Manual SSH/WinRM connection works from the host.
• Security groups allow traffic on the required ports.
• The -debug output shows the server is reachable but rejecting the specific authentication method.
• The instance serial console shows a successful boot to login prompt.