This is an automated email from the ASF dual-hosted git repository. heneveld pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/brooklyn-docs.git
commit 736c9a2ca40910338877853d2e83f3731fba8c64 Author: Alex Heneveld <[email protected]> AuthorDate: Fri Sep 6 16:05:32 2019 +0100 expand and tidy the WinRM documentation (now split into several pages) --- guide/blueprints/winrm/client.md | 32 ++++++++++++----------- guide/blueprints/winrm/index.md | 48 +++++++++++++++------------------- guide/blueprints/winrm/limitations.md | 15 +++++------ guide/blueprints/winrm/tips.md | 48 ++++++++++++++++++---------------- guide/blueprints/winrm/troubleshoot.md | 43 +++++++++++++++++++++--------- 5 files changed, 100 insertions(+), 86 deletions(-) diff --git a/guide/blueprints/winrm/client.md b/guide/blueprints/winrm/client.md index 2d4dee3..037fd75 100644 --- a/guide/blueprints/winrm/client.md +++ b/guide/blueprints/winrm/client.md @@ -33,8 +33,9 @@ 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. @@ -42,15 +43,15 @@ where Apache Brooklyn complains about failing to connect to the IP you should ch 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 diff --git a/guide/blueprints/winrm/index.md b/guide/blueprints/winrm/index.md index 3c9fe36..44e3115 100644 --- a/guide/blueprints/winrm/index.md +++ b/guide/blueprints/winrm/index.md @@ -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,26 +74,17 @@ 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 @@ -103,7 +92,7 @@ For example - here is a simplified blueprint (but see [Tips and Tricks](#tips-an 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) + diff --git a/guide/blueprints/winrm/limitations.md b/guide/blueprints/winrm/limitations.md index 6d6add7..50f89fe 100644 --- a/guide/blueprints/winrm/limitations.md +++ b/guide/blueprints/winrm/limitations.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. diff --git a/guide/blueprints/winrm/tips.md b/guide/blueprints/winrm/tips.md index ad9ff55..85c3bf7 100644 --- a/guide/blueprints/winrm/tips.md +++ b/guide/blueprints/winrm/tips.md @@ -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. - diff --git a/guide/blueprints/winrm/troubleshoot.md b/guide/blueprints/winrm/troubleshoot.md index 2a96b40..3424e91 100644 --- a/guide/blueprints/winrm/troubleshoot.md +++ b/guide/blueprints/winrm/troubleshoot.md @@ -1,7 +1,16 @@ -Troubleshooting ---------------- +--- +title: Troubleshooting +--- + +Note: in addition to the Windows-specific points here, +much of the [operations troubleshooting guide]({{book.path.docs}}/ops/troubleshooting/index.md) is applicable for Windows blueprints. + + +### WinRM Basics + +If you can't get WinRM to work at all, see the notes on [the Winrm4j client](client.md) which includes detailed troubleshooting +for basic connectivity. -Much of the [operations troubleshooting guide]({{book.path.docs}}/ops/troubleshooting/index.md) is applicable for Windows blueprints. ### User metadata service requirement @@ -15,20 +24,26 @@ If the configuration options `userMetadata` or `userMetadataString` are used on the default setup script. This allows one to supply a custom setup script. However, if userMetadata contains something else then the setup will not be done and the VM may not not be accessible remotely over WinRM. -### Credentials issue requiring special configuration + +### Credentials and privileges requiring special configuration When a script is run over WinRM over HTTP, the credentials under which the script are run are marked as 'remote' credentials, which are prohibited from running certain security-related operations. This may prevent certain operations. The installer from Microsoft SQL Server is known to fail in this case, for example. For a workaround, please -refer to [How and Why to re-authenticate withing a PowerShell script](#how-and-why-to-re-authenticate-within-a-powershell-script) +refer to [How and Why to re-authenticate withing a PowerShell script](tips.md#how-and-why-to-re-authenticate-within-a-powershell-script) above. +In some cases 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. + + ### WebServiceException: Could not send Message We detected a `WebServiceException` and different `SocketException` -during deployment of long lasting Application Blueprint against VcloudDirector. +during deployment of long-lasting Application Blueprint against VcloudDirector. -Launching the blueprint bellow was giving constantly this type of error on launch step. +Launching the blueprint below was giving constantly this type of error on launch step. services: type: org.apache.brooklyn.entity.software.base.VanillaWindowsProcess @@ -46,7 +61,7 @@ Launching the blueprint bellow was giving constantly this type of error on launc stop.command: echo stopCommand With series of tests we concluded that on the Vcloud Director environment we were using -a restart was happening ~2 minutes after the VM is provisioned. +a restart was happening about 2 minutes after the VM is provisioned. Logging in the host and search for System event of type 1074 in Windows Event Viewer, we found two 1074 events where the second one was The process C:\Windows\system32\winlogon.exe (W2K12-STD) has initiated the restart of computer WIN-XXXX on behalf of user @@ -68,13 +83,14 @@ If the description above matches your case and you are getting **connection fail a restart probably occurred and you should try this parameter. Before using this parameter we advice to check whether this is really your case. -To verify the behavior check as described above. + ### AMIs not found If using the imageId of a Windows community AMI, you may find that the AMI is deleted after a few weeks. See [Windows AMIs on AWS](#windows-amis-on-aws) above. + ### VM Provisioning Times Out In some environments, provisioning of Windows VMs can take a very long time to return a usable VM. @@ -87,11 +103,12 @@ several times) before the VM is usable. This could cause the WinRM connection attempts to timeout. The location configuration option `waitForWinRmAvailable` defaults to `30m` (i.e. 30 minutes). This can be increased if required. -Incorrectly prepared Windows template can cause the deployment to time-out expecting an interaction by the user. -You can verify if this is the case by RDP to the deployment which is taking to much time to complete. -It is recommended to manually deploy a single VM for every newly created Windows template to verify that it can be +Incorrectly prepared Windows templates can cause the deployment to time-out expecting an interaction by the user. +You can verify if this is the case by RDPing to the in-progress deployment. +It is recommended that any new Windows template be tested with a manually deployment to verify that it can be used for unattended installations and it doesn't wait and/or require an input by the user. -See [Windows template settings for an Unattended Installation](#windows-template-settings-for-an-unattended-installation) under Known Limitations below. +See [Windows template settings for an Unattended Installation](limitations.md#windows-template-settings-for-an-unattended-installation) under Known Limitations below. + ### Windows log files
