Repository: incubator-brooklyn Updated Branches: refs/heads/master 6aefffd59 -> 8c269d5be
Improve winrm docs Project: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/commit/25af0230 Tree: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/tree/25af0230 Diff: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/diff/25af0230 Branch: refs/heads/master Commit: 25af0230a6115ad4a1e854f4d45c976ecfa1889c Parents: 6aefffd Author: Aled Sage <[email protected]> Authored: Fri Sep 18 13:02:59 2015 +0100 Committer: Aled Sage <[email protected]> Committed: Mon Sep 21 17:50:23 2015 +0100 ---------------------------------------------------------------------- docs/guide/yaml/winrm/index.md | 226 +++++++++++++++++++----- docs/guide/yaml/winrm/re-authentication.md | 36 ---- docs/guide/yaml/winrm/stdout-and-stderr.md | 25 --- 3 files changed, 186 insertions(+), 101 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/25af0230/docs/guide/yaml/winrm/index.md ---------------------------------------------------------------------- diff --git a/docs/guide/yaml/winrm/index.md b/docs/guide/yaml/winrm/index.md index 0f95bd9..e18ae52 100644 --- a/docs/guide/yaml/winrm/index.md +++ b/docs/guide/yaml/winrm/index.md @@ -1,14 +1,11 @@ --- title: Windows Blueprints layout: website-normal -children: -- re-authentication.md -- stdout-and-stderr.md --- -In addition to controlling UNIX-like servers with SSH, Brooklyn has support for blueprints that deploy to Windows -servers using WinRM to run commands. These deployments can be expressed in pure YAML, and utilise PowerShell to install -and manage the software process. +Brooklyn can deploy to Windows servers using WinRM to run commands. These deployments can be +expressed in pure YAML, and utilise PowerShell to install and manage the software process. +This approach is similar to the use of SSH for UNIX-like servers. About WinRM @@ -41,16 +38,7 @@ In particular, you will most likely want to set these properties on your locatio * `templateOptions` - you may also wish to request a larger disk size. This setting is cloud specific; on AWS, you can request a 100GB disk by setting this property to `{mapNewVolumeToDeviceName: ["/dev/sda1", 100, true]}`. -For example, you may place the following in `brooklyn.properties`: - - 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.hardwareId = m3.medium - brooklyn.location.named.AWS\ Oregon\ Win.useJcloudsSshInit=false - brooklyn.location.named.AWS\ Oregon\ Win.templateOptions={mapNewVolumeToDeviceName: ["/dev/sda1", 100, true]} - -Alternatively, in your YAML blueprint: +In your YAML blueprint: ... location: @@ -58,12 +46,24 @@ Alternatively, in your YAML blueprint: region: us-west-2 identity: AKA_YOUR_ACCESS_KEY_ID credential: <access-key-hex-digits> - imageNameRegex: Windows_Server-2012-R2_RTM-English-64Bit-Base + imageNameRegex: Windows_Server-2012-R2_RTM-English-64Bit-Base-.* + imageOwner: 801119661308 hardwareId: m3.medium useJcloudsSshInit: false templateOptions: {mapNewVolumeToDeviceName: ["/dev/sda1", 100, true]} ... +Alternatively, you can define a new named location in `brooklyn.properties`: + + 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]} + + A Sample Blueprint ------------------ @@ -73,7 +73,7 @@ to `VanillaSoftwareProcess`, but adapted to work for Windows and WinRM instead o [documentation for VanillaSoftwareProcess](../custom-entities.html#vanilla-software-using-bash) to find out what you can do with this entity. -For example - here is a blueprint: +For example - here is a simplified blueprint (but see [Tips and Tricks](#tips-and-tricks) below!): name: Server with 7-Zip @@ -82,7 +82,8 @@ For example - here is a blueprint: region: us-west-2 identity: AKA_YOUR_ACCESS_KEY_ID credential: <access-key-hex-digits> - imageNameRegex: Windows_Server-2012-R2_RTM-English-64Bit-Base + imageNameRegex: Windows_Server-2012-R2_RTM-English-64Bit-Base-.* + imageOwner: 801119661308 hardwareId: m3.medium useJcloudsSshInit: false templateOptions: {mapNewVolumeToDeviceName: ["/dev/sda1", 100, true]} @@ -115,40 +116,185 @@ 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 execute 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. + +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. + + +Troubleshooting +--------------- + +Much of the [operations troubleshooting guide](../../ops/troubleshooting/) is applicable for Windows blueprints. ### User metadata service requirement WinRM requires activation and configuration before it will work in a standard Windows Server deployment. To automate this, Brooklyn will place a setup script in the user metadata blob. Services such as Amazon EC2's `Ec2ConfigService` will automatically load and execute this script. If your chosen cloud provider does not support `Ec2ConfigService` or -a similar package, or if you cloud provider does not support user metadata, then you must pre-configure a Windows image +a similar package, or if your cloud provider does not support user metadata, then you must pre-configure a Windows image with the required WinRM setup and make Brooklyn use this image. -### Use of unencrypted HTTP - -Brooklyn is currently using unencrypted HTTP for WinRM communication. This means that the login credentials will be -transmitted in clear text. - -In future we aim to improve Brooklyn to support HTTPS. However this does involve issues are certificate creation and -verification. - -### Standard output and error streams +If the configuration options `userMetadata` or `userMetadataString` are used on the location, then this will override +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. -These are not made available to Brooklyn like they are on Linux. For a workaround, please refer to [Redirecting -stdout/stderr](stdout-and-stderr.html). We hope to resolve this in a future version of Brooklyn. ### Credentials issue requiring special configuration -It appears that when a script is run over WinRM over HTTP, the credentials under which the script are run are marked as +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 [Re-authenticating within a PowerShell script](re-authentication.html). +refer to [How and Why to re-authenticate withing a powershell script](#how-and-why-to-re-authenticate-within-a-powershell-script) above. -Certain registry keys must be reconfigured in order to support re-authentication. Brooklyn will take care of this at -instance boot time. Please ensure that Brooklyn's changes are compatible with your organisation's security policy. +### AMIs not found -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. +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. + +### Windows log files + +Details of the commands executed, and their results, can be found in the Brooklyn log and in the Brooklyn +web-console's activity view. + +There will also be log files on the Windows Server. System errors in Windows are usually reported in the Windows Event Log - +see [https://technet.microsoft.com/en-us/library/cc766042.aspx](https://technet.microsoft.com/en-us/library/cc766042.aspx) +for more information. + +Additional logs may be created by some Windows programs. For example, MSSQL creates a log in +`%programfiles%\Microsoft SQL Server\130\Setup Bootstrap\Log\` - for more information see +[https://msdn.microsoft.com/en-us/library/ms143702.aspx](https://msdn.microsoft.com/en-us/library/ms143702.aspx). + + +Known Limitations +----------------- + +### Use of unencrypted HTTP + +Brooklyn is currently using unencrypted HTTP for WinRM communication. This means that the login credentials will be +transmitted in clear text. + +In future we aim to improve Brooklyn to support HTTPS. However this requires adding support to the underlying +WinRM library, and also involves certificate creation and verification. + +### Install location + +Work is required to better configure a default install location on the VM (e.g. so that +environment variables are set). The installation pattern for linux-based blueprints, +of using brooklyn-managed-processes/installs, is not used or recommended on Windows. +Files will be uploaded to C:\ if no explicit directory is supplied, which is untidy, +unnecessarily exposes the scripts to the user, and could cause conflicts if multiple +entities are installed. + +Blueprint authors are strongly encourages to explicitly specific directories for file +uploads and in their Powershell scripts. http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/25af0230/docs/guide/yaml/winrm/re-authentication.md ---------------------------------------------------------------------- diff --git a/docs/guide/yaml/winrm/re-authentication.md b/docs/guide/yaml/winrm/re-authentication.md deleted file mode 100644 index db7a551..0000000 --- a/docs/guide/yaml/winrm/re-authentication.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: Re-authenticating within a PowerShell script -title_in_menu: Re-authentication -layout: website-normal ---- - -## How and Why to re-authenticate withing 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) - -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 - -It appears that 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 http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/25af0230/docs/guide/yaml/winrm/stdout-and-stderr.md ---------------------------------------------------------------------- diff --git a/docs/guide/yaml/winrm/stdout-and-stderr.md b/docs/guide/yaml/winrm/stdout-and-stderr.md deleted file mode 100644 index 5a27c67..0000000 --- a/docs/guide/yaml/winrm/stdout-and-stderr.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: Redirecting stdout and stderr -title_in_menu: Redirecting stdout/stderr -layout: website-normal ---- - -## Redirecting 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, -which is not currently captured by Brooklyn. In order to facilitate debugging, it is usually possible to redirect -stdout and stderr to a file by using the `Start-Process` scriptlet. So instead of running the following: - - D:\setup.exe /ConfigurationFile=C:\ConfigurationFile.ini - -You would run the following: - - 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. - -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.
