Github user bostko commented on a diff in the pull request:
https://github.com/apache/incubator-brooklyn/pull/907#discussion_r39849538
--- 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:
--- End diff --
type "execute"
---
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.
---
