Skip to content
Permalink
Browse files
expand and tidy the WinRM documentation (now split into several pages)
  • Loading branch information
ahgittin committed Sep 6, 2019
1 parent 25a79ea commit 736c9a2ca40910338877853d2e83f3731fba8c64
Showing 5 changed files with 100 additions and 86 deletions.
@@ -33,24 +33,25 @@ and it will be used to instantiate a `org.apache.brooklyn.util.core.internal.win

## WinRM Connectivity Diagnostics

If you are experiencing problems with a Windows blueprint against a jclouds location
where Apache Brooklyn complains about failing to connect to the IP you should check those things.
If you are experiencing problems with a Windows blueprint,
with an error about failing to connect (or about an authorization conduit),
try the following quick list:

1. Apache Brooklyn is using correct username and password
1. Apache Brooklyn can reach the IP of the provisioned machine. WinRM port 5985 or 5986 is also reachable from Apache Brooklyn.
1. Check whether `WinRmMachineLocation#getDefaultUserMetadataString(ConfigurationSupportInternal)` is applied on the VM.
This script should be passed to the cloud and executed in order to configure WinRM according to Apache Brooklyn requirements for authentication.
So far Windows startup script are known to be supported on AWS EC2 and VCloud Director.
If your cloud doesn't use this script then tune WinRM parameters accordingly.
1. Check whether you use WinRM over HTTP or over HTTPS.
1. If you are using WinRM over HTTP then make sure WinRM service on target VM has `AllowUnencrypted = true`
1. Check whether you use WinRM over HTTP or over HTTPS. If you are using WinRM over HTTP then make sure WinRM service on target VM has `AllowUnencrypted = true` (see below).

If the quick list above doesn't help then follow the steps bellow.
If the quick list above doesn't help then follow the steps below.

To speed up diagnosing the problem we advice to trigger a deployment with the JcloudsLocation flag `destroyOnFailure: false` so you can check status of the provisioned machine
To speed up diagnosing the problem if you don't already have a static machine to target,
we advise to trigger a deployment with the JcloudsLocation flag `destroyOnFailure: false` so you can check status of the provisioned machine
or try later different WinRM parameters with a Apache Brooklyn [BYON Location]({{book.path.docs}}/locations/index.md#byon).

After you determined what is the username and the password you can proceed with next steps.
After you determine what is the username and the password you can proceed with next steps.
*(Notice that for cloud providers which use Auto Generated password will not be logged.
For these cases use Java Debug to retrieve ot or provision a VM manually with the same parameters when using Apache Brooklyn to provision a jclouds location.)*

@@ -102,8 +103,9 @@ Use an Apache Brooklyn BYON blueprint to try easily other connection options.

1. Check IP is reachable from Apache Brooklyn instance
Check whether `telnet 10.0.0.1 5985` makes successfully a socket.
1. If AllowUnencrypted is false and you are using WinRM over HTTP then apply `winrm set winrm/config/service @{AllowUnencrypted="true"}`
*If jclouds or the cloud provider doesn't support passing `sysprep-specialize-script-cmd` then consider modifying Windows VM Image.*
1. Check that WinRM works, before delving deep in to the client: `Test-WSMan TARGET` and/or `winrs -r:10.0.2.15 -unencrypted -u:Administrator -p:pa55w0rd ipconfig`;
many of the tips below will fix underlying WinRM problems, not just Winrm4j.
*If the cloud provider doesn't support passing `sysprep-specialize-script-cmd` it may be necessary to modify the source Windows VM image to enable WinRM.*
1. Check your username and password. Notice in Windows passwords are case sensitive.
Here is how it looks log from a wrong password:

@@ -113,12 +115,12 @@ Use an Apache Brooklyn BYON blueprint to try easily other connection options.
org.apache.cxf.interceptor.Fault: Could not send Message.
at org.apache.cxf.interceptor.MessageSenderInterceptor$MessageSenderEndingInterceptor.handleMessage(MessageSenderInterceptor.java:64)

1. When having wrong password you may want to try logging on a different domain
This is possible from `brooklyn.winrm.config.winrm.computerName` location config.
1. Try `./User` instead of `User`.
1. Check whether you need to specify a different domain: this is possible from `brooklyn.winrm.config.winrm.computerName` location config.
1. Ensure all windows machines consider the other side a "trusted host". On a private subnet, it may be appropriate to run: `Set-Item wsman:\localhost\client\trustedhosts *`
whereas in other environments you will need to specify the list of machines.
1. Restart WinRM on both machines (some changes need a restart to take effect): `Restart-Service WinRM`
1. If you want to configure Windows target host with HTTPS then check the article [Configuring WINRM for HTTPS](https://support.microsoft.com/en-us/kb/2019527)
1. If you are still seeing authorization errors then try connecting via WinRM with the embedded winrs client.
First make sure you have the server in trusted hosts.

Then execute a simple command like
In some cases the problems may be outwith the client, and it might be useful to look at [Troubleshooting](troubleshooting.md).

winrs -r:10.0.2.15 -unencrypted -u:Administrator -p:pa55w0rd ipconfig
@@ -39,7 +39,6 @@ In particular, you will most likely want to set these properties on your locatio

In your YAML blueprint:

...
location:
jclouds:aws-ec2:
region: us-west-2
@@ -50,17 +49,16 @@ In your YAML blueprint:
hardwareId: m3.medium
useJcloudsSshInit: false
templateOptions: {mapNewVolumeToDeviceName: ["/dev/sda1", 100, true]}
...

Alternatively, you can define a new named location in `brooklyn.properties`:
Or for an existing Windows machine:

brooklyn.location.named.AWS\ Oregon\ Win = jclouds:aws-ec2:us-west-2
brooklyn.location.named.AWS\ Oregon\ Win.displayName = AWS Oregon (Windows)
brooklyn.location.named.AWS\ Oregon\ Win.imageNameRegex = Windows_Server-2012-R2_RTM-English-64Bit-Base-.*
brooklyn.location.named.AWS\ Oregon\ Win.imageOwner = 801119661308
brooklyn.location.named.AWS\ Oregon\ Win.hardwareId = m3.medium
brooklyn.location.named.AWS\ Oregon\ Win.useJcloudsSshInit = false
brooklyn.location.named.AWS\ Oregon\ Win.templateOptions = {mapNewVolumeToDeviceName: ["/dev/sda1", 100, true]}
location:
byon:
hosts:
- winrm: 10.0.0.1
user: Administrator
password: pa55w0rd
osFamily: windows



@@ -76,34 +74,25 @@ Entity authors are strongly encouraged to write Windows PowerShell or Batch scri
files, to configure these to be uploaded, and then to configure the appropriate command as a
single line that executes given script.

For example - here is a simplified blueprint (but see [Tips and Tricks](#tips-and-tricks) below!):
For example here is a simplified blueprint:

name: Server with 7-Zip

location:
jclouds:aws-ec2:
region: us-west-2
identity: AKA_YOUR_ACCESS_KEY_ID
credential: <access-key-hex-digits>
imageNameRegex: Windows_Server-2012-R2_RTM-English-64Bit-Base-.*
imageOwner: 801119661308
hardwareId: m3.medium
useJcloudsSshInit: false
templateOptions: {mapNewVolumeToDeviceName: ["/dev/sda1", 100, true]}
location: windows-machine # register this, or inject the above instead

services:
- type: org.apache.brooklyn.entity.software.base.VanillaWindowsProcess
brooklyn.config:
templates.preinstall:
file:///Users/richard/install7zip.ps1: "C:\\install7zip.ps1"
/path/to/install7zip.ps1: "C:\\install7zip.ps1"
install.command: powershell -command "C:\\install7zip.ps1"
customize.command: echo true
launch.command: echo true
stop.command: echo true
checkRunning.command: echo true
installer.download.url: http://www.7-zip.org/a/7z938-x64.msi

The installation script - referred to as `/Users/richard/install7zip.ps1` in the example above - is:
The installation script - referred to as `/path/to/install7zip.ps1` in the example above (but put this on your Brooklyn server or in the bundle classpath) - is:

$Path = "C:\InstallTemp"
New-Item -ItemType Directory -Force -Path $Path
@@ -115,11 +104,16 @@ The installation script - referred to as `/Users/richard/install7zip.ps1` in the

Start-Process "msiexec" -ArgumentList '/qn','/i',$Dl -RedirectStandardOutput ( [System.IO.Path]::Combine($Path, "stdout.txt") ) -RedirectStandardError ( [System.IO.Path]::Combine($Path, "stderr.txt") ) -Wait

Where security-related operation are to be executed, it may require the use of `CredSSP` to obtain
the correct Administrator privileges: you may otherwise get an access denied error. See the sub-section
[How and Why to re-authenticate within a PowerShell script](#how-and-why-to-re-authenticate-within-a-powershell-script) for more details.

This is only a very simple example. A more complex example can be found in the [Microsoft SQL Server blueprint in the
Brooklyn source code]({{book.url.brooklyn_library_git}}/{{"master" if 'SNAPSHOT' in book.brooklyn_version else book.brooklyn_version}}/software/database/src/main/resources/org/apache/brooklyn/entity/database/mssql).


Learn More
----------

A few other WinRM resources are available:

* [Tips and Tricks](tips.md)
* [About the Winrm4j Client](client.md)
* [Troubleshooting](troubleshoot.md)

@@ -43,14 +43,11 @@ is not respected. For example, the command below will receive an exit code of 0.

##### Non-zero Exit Code Returned as One

If a batch or PowerShell file exits with an exit code greater than one (or negative), this will
be reported as 1 over WinRM.

We advise you to use native commands (non-PowerShell ones) since executing it as a native command
will return the exact exit code rather than 1.
For instance if you have installmssql.ps1 script use `install.command: powershell -command "C:\\installmssql.ps1"`
rather than using `install.powershell.command: "C:\\installmssql.ps1"`
The first will give you an exact exit code rather than 1
In some configurations, scripts can report any non-zero exit code as `1`.
It may be possible to workaround this where the exit code is needeed by using
e.g. `install.command: powershell -command "C:\\installmssql.ps1"`
instead of `install.powershell.command: "C:\\installmssql.ps1"`
If this is problematic, please consider submitting a patch to `VanillaWindowsProcess`!

### PowerShell "Preparing modules for first use"

@@ -110,7 +107,7 @@ uploads and in their PowerShell scripts.

### Windows template settings for an Unattended Installation

Windows template needs certain configuration to be applied to prevent Windows setup UI from being displayed.
Windows template needs certain configuration to be applied to prevent windows setup UI from being displayed.
The default behavior is to display it if there are incorrect or empty settings. Showing Setup UI will prevent the proper
deployment, because it will expect interaction by the user such as agreeing on the license agreement or some of the setup dialogs.

@@ -1,14 +1,6 @@
Tips and Tricks
---------------

The best practices for other entities (e.g. using [VanillaSoftwareProcess]({{book.path.docs}}/blueprints/custom-entities.md#vanilla-software-using-bash))
apply for WinRM as well.

### Execution Phases

Blueprint authors are strongly encouraged to provide an implementation for install, launch, stop
and checkRunning. These are vital for the generic effectors such as stopping and restarting the
process.
---
title: WinRM Tips and Tricks
---

### PowerShell

@@ -17,6 +9,18 @@ PowerShell commands can be supplied using config options such as `launch.powersh
This is an alternative to supplying a standard batch command using config such as `launch.command`.
For a given phase, only one of the commands (PowerShell or Batch) should be supplied.


### Execution Phases

Bear in mind that
the best practices for other entities (e.g. using [VanillaSoftwareProcess]({{book.path.docs}}/blueprints/custom-entities.md#vanilla-software-using-bash))
apply for WinRM as well.

Blueprint authors are strongly encouraged to provide an implementation for install, launch, stop
and checkRunning. These are vital for the generic effectors such as stopping and restarting the
process.


### Getting the Right Exit Codes

WinRM (or at least the chosen WinRM client!) can return a zero exit code even on error in certain
@@ -46,7 +50,8 @@ command line or in a script, cmdlet, or provider, such as the
errors generated by the Write-Error cmdlet.
https://technet.microsoft.com/en-us/library/hh847796.aspx

See [Incorrect Exit Codes](#incorrect-exit-codes) under Known Limitations below.
See [Incorrect Exit Codes](limitations.md#incorrect-exit-codes) under Known Limitations.


### Executing Scripts From Batch Commands

@@ -104,8 +109,9 @@ config like `pre.install.reboot.required` and `install.reboot.required`. If requ
installation commands can be split between the pre-install, install and post-install phases
in order to do a reboot at the appropriate point of the VM setup.

We strongly recommend to **write blueprints in a way that they do NOT restart automatically Windows** and
use one of the `pre.install.reboot.required` or `install.reboot.required` parameters to perform restart.
We strongly recommend to **write blueprints in a way that they do NOT restart automatically windows** and
use one of the `pre.install.reboot.required` or `install.reboot.required` parameters to perform restart,
as script and Brooklyn connectivity behaviour is difficult to continue across reboots!

### Install Location

@@ -143,9 +149,7 @@ All the above requirements are enabled in Apache Brooklyn through [brooklyn-serv
script which enables executing commands with CredSSP in the general case.
The script works for most of the Windows images out there version 2008 and later.

Please ensure that Brooklyn's changes are compatible with your organisation's security policy.

Check Microsoft Documentation for more information about [Negotiate authenticate mechanism on technet.microsoft.com](https://msdn.microsoft.com/en-us/library/windows/desktop/aa378748(v=vs.85).aspx)
Check Microsoft Documentation for more information on how to [negotiate authenticate mechanisms](https://msdn.microsoft.com/en-us/library/windows/desktop/aa378748(v=vs.85).aspx)

Re-authentication also requires that the password credentials are passed in plain text within the
script. Please be aware that it is normal for script files - and therefore the plaintext password -
@@ -202,10 +206,11 @@ always picked up. If an image id is used, it may fail as Amazon will delete thei
If using an image regex, it is recommended to include the image owner in case someone else uploads
a similarly named AMI. For example:

brooklyn.location.named.AWS\ Oregon\ Win = jclouds:aws-ec2:us-west-2
brooklyn.location.named.AWS\ Oregon\ Win.imageNameRegex = Windows_Server-2012-R2_RTM-English-64Bit-Base-.*
brooklyn.location.named.AWS\ Oregon\ Win.imageOwner = 801119661308
...
location:
jclouds:aws-ec2:us-west-2
imageNameRegex = Windows_Server-2012-R2_RTM-English-64Bit-Base-.*
imageOwner = 801119661308
...

## stdout and stderr in a PowerShell script

@@ -231,4 +236,3 @@ The `-ArgumentList` is simply the arguments that are to be passed to the executa
Further details can be found on the [Start-Process documentation page](https://technet.microsoft.com/en-us/library/hh849848.aspx)
on the Microsoft TechNet site.


0 comments on commit 736c9a2

Please sign in to comment.