From 189fd3246b86071998c43cbe571a97710dda485d Mon Sep 17 00:00:00 2001 From: Shawn Neal Date: Thu, 16 Oct 2014 08:11:38 -0700 Subject: [PATCH 1/4] Added basic WinRM config website docs --- website/docs/source/layouts/layout.erb | 1 + .../v2/vagrantfile/winrm_settings.html.md | 45 +++++++++++++++++++ 2 files changed, 46 insertions(+) create mode 100644 website/docs/source/v2/vagrantfile/winrm_settings.html.md diff --git a/website/docs/source/layouts/layout.erb b/website/docs/source/layouts/layout.erb index 029d39fad..8d6dcd261 100644 --- a/website/docs/source/layouts/layout.erb +++ b/website/docs/source/layouts/layout.erb @@ -150,6 +150,7 @@ >Tips & Tricks >config.vm >config.ssh + >config.winrm >config.vagrant <% end %> diff --git a/website/docs/source/v2/vagrantfile/winrm_settings.html.md b/website/docs/source/v2/vagrantfile/winrm_settings.html.md new file mode 100644 index 000000000..93489ce60 --- /dev/null +++ b/website/docs/source/v2/vagrantfile/winrm_settings.html.md @@ -0,0 +1,45 @@ +--- +page_title: "config.winrm - Vagrantfile" +sidebar_current: "vagrantfile-winrm" +--- + +# WinRM Settings + +**Config namespace: `config.winrm`** + +The settings within `config.winrm` relate to configuring how Vagrant +will access your Windows guest over WinRM. As with most Vagrant settings, the +defaults are typically fine, but you can fine tune whatever you'd like. + +These settings are only used if you've set your communicator type to `:winrm`. + +## Available Settings + +`config.winrm.username` - This sets the username that Vagrant will use +to login to the WinRM web service by default. Providers are free to override +this if they detect a more appropriate user. By default this is "vagrant," +since that is what most public boxes are made as. + +
+ +`config.winrm.password` - This sets a password that Vagrant will use to +authenticate the WinRM user. By default this is "vagrant," since that is +what most public boxes are made as. + +
+ +`config.winrm.host` - The hostname or IP to SSH into. By default this is +empty, because the provider usually figures this out for you. + +
+ +`config.winrm.port` - The port to SSH into. By default this is port 22. + +
+ +`config.winrm.guest_port` - The port on the guest that SSH is running on. This +is used by some providers to detect forwarded ports for SSH. For example, if +this is set to 22 (the default), and Vagrant detects a forwarded port to +port 22 on the guest from port 4567 on the host, Vagrant will attempt +to use port 4567 to talk to the guest if there is no other option. + From e91cc1e0dfcfe759fe38435e6e686da4e40c9a02 Mon Sep 17 00:00:00 2001 From: Shawn Neal Date: Thu, 16 Oct 2014 08:16:01 -0700 Subject: [PATCH 2/4] Added communicator to config docs, specifically for winrm --- website/docs/source/v2/vagrantfile/machine_settings.html.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/website/docs/source/v2/vagrantfile/machine_settings.html.md b/website/docs/source/v2/vagrantfile/machine_settings.html.md index cfcca719b..b68d6f49a 100644 --- a/website/docs/source/v2/vagrantfile/machine_settings.html.md +++ b/website/docs/source/v2/vagrantfile/machine_settings.html.md @@ -85,6 +85,12 @@ constraints.
+`config.vm.communicator` - The communicator type to use to connect to the +guest box. By default this is `:ssh`, but should be changed to `:winrm` for +Windows guests. + +
+ `config.vm.graceful_halt_timeout` - The time in seconds that Vagrant will wait for the machine to gracefully halt when `vagrant halt` is called. Defaults to 60 seconds. From 7ff755c0dac699800e6329b3ba06999a421b76e0 Mon Sep 17 00:00:00 2001 From: Shawn Neal Date: Thu, 16 Oct 2014 08:56:30 -0700 Subject: [PATCH 3/4] Added Windows base box creation docs --- website/docs/source/v2/boxes/base.html.md | 50 +++++++++++++++++++++++ 1 file changed, 50 insertions(+) diff --git a/website/docs/source/v2/boxes/base.html.md b/website/docs/source/v2/boxes/base.html.md index 2ea27c6cf..7e34bf1b5 100644 --- a/website/docs/source/v2/boxes/base.html.md +++ b/website/docs/source/v2/boxes/base.html.md @@ -157,6 +157,56 @@ in the SSH server configuration. This avoids a reverse DNS lookup on the connecting SSH client which can take many seconds. +## Windows Boxes + +Supported Windows guest operating systems: +- Windows 7 +- Windows 8 +- Windows Server 2008 +- Windows Server 2008 R2 +- Windows Server 2012 +- Windows Server 2012 R2 + +Windows Server 2003 and Windows XP are _not_ supported, but if you're a die +hard XP fan [this](http://stackoverflow.com/a/18593425/18475) may help you. + +### Base Windows Configuration + + - Turn off UAC + - Disable complex passwords + - Disable "Shutdown Tracker" + - Disable "Server Manager" starting at login (for non-Core) + +### Base WinRM Configuration + +To enable and configure WinRM you'll need to set the WinRM service to +auto-start and allow unencrypted basic auth (obviously this is not secure). +Run the following commands from a regular Windows command prompt: +``` +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 +``` + +### 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 WinRM port to 5985 or upgrade to WinRM 2.0 + +The following commands will change the WinRM 1.1 port to what's expected by +Vagrant: +``` +netsh firewall add portopening TCP 5985 "Port 5985" +winrm set winrm/config/listener?Address=*+Transport=HTTP @{Port="5985"} +``` + ## Other Software At this point, you have all the common software you absolutely _need_ for From c0db48b0ab7a674357f98766b24f59631507acab Mon Sep 17 00:00:00 2001 From: Shawn Neal Date: Thu, 16 Oct 2014 09:00:08 -0700 Subject: [PATCH 4/4] Fixed the WinRM config documentation --- .../source/v2/vagrantfile/winrm_settings.html.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/website/docs/source/v2/vagrantfile/winrm_settings.html.md b/website/docs/source/v2/vagrantfile/winrm_settings.html.md index 93489ce60..462ccf56e 100644 --- a/website/docs/source/v2/vagrantfile/winrm_settings.html.md +++ b/website/docs/source/v2/vagrantfile/winrm_settings.html.md @@ -28,18 +28,19 @@ what most public boxes are made as.
-`config.winrm.host` - The hostname or IP to SSH into. By default this is -empty, because the provider usually figures this out for you. +`config.winrm.host` - The hostname or IP to connect to the WinRM service. +By default this is empty, because the provider usually figures this out for +you.
-`config.winrm.port` - The port to SSH into. By default this is port 22. +`config.winrm.port` - The WinRM port to connect to, by default 5985.
-`config.winrm.guest_port` - The port on the guest that SSH is running on. This -is used by some providers to detect forwarded ports for SSH. For example, if -this is set to 22 (the default), and Vagrant detects a forwarded port to -port 22 on the guest from port 4567 on the host, Vagrant will attempt +`config.winrm.guest_port` - The port on the guest that WinRM is running on. +This is used by some providers to detect forwarded ports for WinRM. For +example, if this is set to 5985 (the default), and Vagrant detects a forwarded +port to port 5985 on the guest from port 4567 on the host, Vagrant will attempt to use port 4567 to talk to the guest if there is no other option.