Github user bostko commented on a diff in the pull request:
https://github.com/apache/incubator-brooklyn/pull/907#discussion_r39851174
--- Diff: docs/guide/yaml/winrm/index.md ---
@@ -115,40 +116,172 @@ This is only a very simple example. A core complex
example can be found in the [
Brooklyn source code]({{ site.brooklyn.url.git
}}/software/database/src/main/resources/org/apache/brooklyn/entity/database/mssql).
-Known Limitations and Special Cases
------------------------------------
+Tips and Tricks
+---------------
+
+The best practices for other entities (e.g. using
[VanillaSoftwareProcess](../custom-entities.html#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.
+
+### Powershell
+
+Powershell commands can be supplied directly using config options such as
`launch.powershell.command`.
+
+### Rebooting
+
+Where a reboot is required as part of the entity setup, this can be
configured using
+config like `pre.install.reboot.required` and `install.reboot.required`.
If required, the
+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.
+
+## Powershell scripts and configuration files on classpath
+
+Often, blueprints will require that (parameterized) scripts and
configuration files are available to be copied to the
+target VM. These must be URLs resolvable from the Brooklyn instance, or on
the Brooklyn classpath. One simple way
+to achieve this is to compile the support files into a .jar, which is then
added to AMP's 'dropins' folder. Alternatively,
+an OSGi bundle can be used, referenced from the catalog item.
+
+Ensure that these scripts end each line with "\r\n", rather than just "\n".
+
+### Install Location
+
+Blueprint authors are encouraged to explicitly specify the full path for
file uploads, and
+for paths in their Powershell scripts (e.g. for installation,
configuration files, log files, etc).
+
+
+### How and Why to re-authenticate within a powershell script
+
+Brooklyn will run powershell scripts by making a WinRM call over HTTP. For
most scripts this will work, however for
+some scripts (e.g. MSSQL installation), this will fail even if the script
can be run locally (e.g. by using RDP to
+connect to the machine and running the script manually)
+
+For example in the case of MS SQL server installation, there was no clear
indication of why this would not work.
+The only clue was a security exception in the installation log.
+
+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. The solution was to obtain
+a new set of credentials within the script and use those credentials to
exeute the installer, so this:
+
+ ( $driveLetter + "setup.exe")
/ConfigurationFile=C:\ConfigurationFile.ini
+
+became this:
+
+ $pass = '${attribute['windows.password']}'
+ $secpasswd = ConvertTo-SecureString $pass -AsPlainText -Force
+ $mycreds = New-Object System.Management.Automation.PSCredential
($($env:COMPUTERNAME + "\Administrator"), $secpasswd)
+
+ Invoke-Command -ComputerName localhost -credential $mycreds
-scriptblock {
+ param($driveLetter)
+ Start-Process ( $driveLetter + "setup.exe") -ArgumentList
"/ConfigurationFile=C:\ConfigurationFile.ini" -RedirectStandardOutput
"C:\sqlout.txt" -RedirectStandardError "C:\sqlerr.txt" -Wait
+ } -Authentication CredSSP -argumentlist $driveLetter
+
+The `$pass=` line simply reads the Windows password from the entity before
the script is copied to the server. This is
+then encrypted on the next line before being used to create a new
credential object. Then, rather than calling the executable
+directly, the `Start-Process` scriptlet is used. This allows us to pass in
the newly created credentials, under which
+the process will be run.
+
+Certain registry keys must be reconfigured in order to support
re-authentication. Brooklyn will take care of this at
+instance boot time, as part of the setup script. Please ensure that
Brooklyn's changes are compatible with your
+organisation's security policy.
+
+Re-authentication also requires that the password credentials are passed
in plain text in the blueprint's script files.
+Please be aware that it is normal for script files - and therefore the
plaintext password - to be saved to the VM's
+disk.
+
+### Windows AMIs on AWS
+
+Windows AMIs in AWS change regularly (to include the latest Windows
updates). If using the community
+AMI, it is recommended to use an AMI name regex, rather than an image id,
so that the latest AMI is
+always picked up. If an image id is used, it may fail as Amazon will
delete their old Windows AMIs.
+
+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
+ ...
+
+## stdout and stderr in a PowerShell script
+
+When calling an executable in a PowerShell script, the stdout and stderr
will usually be output to the console.
+This is captured by Brooklyn, and shown in the activities view under the
specific tasks.
+
+An alternative is to redirect stdout and stderr to a file on the VM, which
can be helpful if one expects sys admins
+to log into the VM. However, be warned that this would hide the
stdout/stderr from Brooklyn's activities view.
+
+For example, instead of running the following:
+
+ D:\setup.exe /ConfigurationFile=C:\ConfigurationFile.ini
+
+ The redirect can be achieved by using the `Start-Process` scriptlet:
+
+ Start-Process D:\setup.exe -ArgumentList
"/ConfigurationFile=C:\ConfigurationFile.ini" -RedirectStandardOutput
"C:\sqlout.txt" -RedirectStandardError "C:\sqlerr.txt" -PassThru -Wait
+
+The `-ArgumentList` is simply the arguments that are to be passed to the
executable, `-RedirectStandardOutput` and
+`RedirectStandardError` take file locations for the output (if the file
already exists, it will be overwritten). The
+`-PassThru` argument indicates that PowerShell should write to the file
*in addition* to the console, rather than
+*instead* of the console. The `-Wait` argument will cause the scriptlet to
block until the process is complete.
+
--- End diff --
Additions I found:
You can also check the logs inside `%programfiles%\Microsoft SQL
Server\130\Setup Bootstrap\Log\` for more information check
https://msdn.microsoft.com/en-us/library/ms143702.aspx.
Other system errors in Windows are usually reported in the Windows Event
Log check https://technet.microsoft.com/en-us/library/cc766042.aspx for more
information
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at [email protected] or file a JIRA ticket
with INFRA.
---
