Home

Awesome

Vagrant-Windows

Build Status Code Climate Gem Version

This plugin is deprecated, please use Vagrant 1.6+ which natively supports Windows guests over WinRM.

This Vagrant plugin allows you to standup Windows guests using WinRM instead of SSH on older versions of Vagrant.

Getting Started

  1. Install the vagrant-windows plugin.
  2. Create and configure a Windows guest base box.
  3. Create a Vagrantfile.
  4. vagrant up

Installation

Vagrant 1.6 will natively support Windows guests, this plugin should not be used with Vagrant 1.6 or later.

Creating a Base Box

Supported Guest Operating Systems:

Windows Server 2003 and Windows XP are not supported by the maintainers of this project. Any issues regarding any unsupported guest OS will be closed. If you still insist on using XP or Server 2003, this may help.

You'll need to create a new Vagrant base box. Create a new Windows VM in VirtualBox, configure some Windows settings (see below) then follow the Vagrant packaging instructions.

WinRM Configuration

These commands assume you're running from a regular command window and not PowerShell.

   winrm quickconfig -q
   winrm set winrm/config/winrs @{MaxMemoryPerShellMB="512"}
   winrm set winrm/config @{MaxTimeoutms="1800000"}
   winrm set winrm/config/service @{AllowUnencrypted="true"}
   winrm set winrm/config/service/auth @{Basic="true"}
   sc config WinRM start= auto

NOTE: For the WinRM service to work in Windows 7, the network profile has to be changed from Public to Work. To ensure that networks added later (i.e. through the Vagrantfile) also are made non-public, add the following to your Vagrantfile:

# Ensure that all networks are set to private
config.windows.set_work_network = true

Additional WinRM 1.1 Configuration

These additional configuration steps are specific to Windows Server 2008 (WinRM 1.1). For Windows Server 2008 R2, Windows 7 and later versions of Windows you can ignore this section.

  1. Ensure the Windows PowerShell feature is installed
  2. Change the default WinRM port (see below) or upgrade to WinRM 2.0.
netsh firewall add portopening TCP 5985 "Port 5985"
winrm set winrm/config/listener?Address=*+Transport=HTTP @{Port="5985"}

Required Windows Services

If you like to turn off optional Windows services you'll need to ensure you leave these services enabled for vagrant-windows to continue to work:

The Vagrant File

Add the following to your Vagrantfile

config.vm.guest = :windows
config.vm.network :forwarded_port, guest: 5985, host: 5985, id: "winrm", auto_correct: true

Example:

Vagrant.configure("2") do |config|

  # Configure base box parameters
  config.vm.box = "vagrant-windows2008r2"
  config.vm.box_url = "./vagrant-windows2008r2.box"
  config.vm.guest = :windows

  # Port forward WinRM and RDP
  config.vm.network :forwarded_port, guest: 3389, host: 3389
  config.vm.network :forwarded_port, guest: 5985, host: 5985, id: "winrm", auto_correct: true
  
end

Available Config Parameters:

Note - You need to ensure you specify a config.windows and a config.winrm in your Vagrantfile. Currently there's a problem where Vagrant will not load the plugin config even with defaults if at least one of its values doesn't exist in the Vagrantfile.

What Works?

Troubleshooting

When I run the winrm command I get: "Error: Invalid use of command line. Type "winrm -?" for help."

   winrm set winrm/config/winrs '@{MaxMemoryPerShellMB="512"}'

I get a 401 auth error from WinRM

I get a non-401 error from WinRM waiting for the VM to boot

SQL Server cookbook fails to install through Vagrant

If all else fails try running vagrant with debug logging, perhaps that will give you enough insight to fix the problem or file an issue.

Contributing

  1. Fork it.
  2. Create a branch (git checkout -b my_feature_branch)
  3. Commit your changes (git commit -am "Added a sweet feature")
  4. Push to the branch (git push origin my_feature_branch)
  5. Create a pull requst from your branch into master (Please be sure to provide enough detail for us to cipher what this change is doing)

Development

Clone this repository and use Bundler to get the dependencies:

$ bundle install

Once you have the dependencies, you can run the tests with rake:

$ bundle exec rake spec

If those pass, you're ready to start developing the plugin. You can test the plugin without installing it into your Vagrant environment by just creating a Vagrantfile in the top level of this directory (it is gitignored) that uses it, and use bundler to execute Vagrant:

$ bundle exec vagrant up

Installing Vagrant-Windows From Source

If you want to globally install your locally built plugin from source, use the following method (this would be for 1.2.0):

 bundle install
 bundle exec rake build
 vagrant plugin install pkg/vagrant-windows-1.2.0.gem

Keep in mind you should have Ruby 1.9.3 and Ruby DevKit installed. Check out the following gist that can get you what you need (from blank system to fully ready): Install Vagrant Windows Plugin From Source Gist.

References and Shout Outs