cloudsoft.io

WinRM4j Tips and Tricks

PowerShell

PowerShell commands can be supplied using config options such as launch.powershell.command.

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) 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 circumstances. It is therefore advisable to follow the guidelines below.

For a given command, write the PowerShell or Batch script as a separate multi-command file. Upload this (e.g. by including it in the files.preinstall configuration). For the configuration of the given command, execute the file.

When you have a command inside the PowerShell script which want to report its non zero exiting, please consider adding a check for its exit code after it. Example:

& "C:\install.exe"
If ($lastexitcode -ne 0) {
    exit $lastexitcode
}

For PowerShell files, consider including

$ErrorActionPreference = "Stop"

at the start of the file. $ErrorActionPreference Determines how Windows PowerShell responds to a non-terminating error (an error that does not stop the cmdlet processing) at the 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 under Known Limitations.

Executing Scripts From Batch Commands

In a batch command, you can execute a batch file or PowerShell file. For example:

install.command: powershell -NonInteractive -NoProfile -Command "C:\\install7zip.ps1"

Or alternatively:

install.command: C:\\install7zip.bat

Executing Scripts From PowerShell

In a PowerShell command, you can execute a batch file or PowerShell file. There are many ways to do this (see official PowerShell docs). For example:

install.powershell.command: "& C:\\install7zip.ps1"

Or alternatively:

install.powershell.command: "& C:\\install7zip.bat"

Note the quotes around the command. This is because the “&” has special meaning in a YAML value.

Parameterised Scripts

Calling parameterised Batch and PowerShell scripts is done in the normal Windows way - see offical Microsoft docs. For example:

install.command: "c:\\myscript.bat myarg1 myarg2"

Or as a PowerShell example:

install.powershell.command: "& c:\\myscript.ps1 -key1 myarg1 -key2 myarg2"

It is also possible to construct the script parameters by referencing attributes of this or other entities using the standard attributeWhenReady mechanism. For example:

install.command: $brooklyn:formatString("c:\\myscript.bat %s", component("db").attributeWhenReady("datastore.url"))

PowerShell - Using Start-Process

When you are invoking a command from a PowerShell script with Start-Process cmdlet, please use the -Wait and the -PassThru arguments. Example Start-Process C:\mycommand -Wait -PassThru

Using -Wait guarantees that the script process and its children and thus the WinRM session won’t be terminated until it is finished. -PassThru Returns a process object for each process that the cmdlet started. By default, this cmdlet does not generate any output. See https://technet.microsoft.com/en-us/library/hh849848.aspx

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.

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 AMP connectivity behaviour is difficult to continue across reboots!

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

Some installation scripts require the use of security-related operations. In some environments,
these fail by default when executed over WinRM, even though the script may succeed when run locally
(e.g. by using RDP to connect to the machine and running the script manually). There may be no
clear indication from Windows why it failed (e.g. for MSSQL install, the only clue is a
security exception in the installation log).

When a script is run over WinRM, the credentials under which the script are run are marked as ‘remote’ credentials, which are prohibited from running certain security-related operations. The solution is to obtain a new set of credentials within the script and use those credentials to required commands.

The WinRM client uses Negotiate+NTLM to authenticate against the machine. This mechanism applies certain restrictions to executing commands on the Windows host.

For this reason you should enable CredSSP on the Windows host which grants all privileges available to the user. https://technet.microsoft.com/en-us/library/hh849719.aspx#sectionSection4

To use Invoke-Command -Authentication CredSSP the Windows Machine has to have:

  • Up and running WinRM over HTTP. The custom-enable-credssp.ps1 script enables WinRM over HTTP because Invoke-Command use WinRM over HTTP by default. Invoke-Command can be used with -UseSSL option but this will lead to modifying PowerShell scripts. With always enabling WinRM over HTTP on the host, blueprint’s PowerShell scripts remain consistent and not depend on the WinRM HTTPS/HTTP environments. We hope future versions of winrm4j will support CredSSP out of the box and wrapping commands in Invoke-Command will not be needed.
  • Added trusted host entries which will use Invoke-Command
  • Allowed CredSSP

All the above requirements are enabled in Cloudsoft AMP through brooklyn-server/software/base/src/main/resources/org/apache/brooklyn/software/base/custom-enable-credssp.ps1 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.

Check Microsoft Documentation for more information on how to negotiate authenticate mechanisms

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 - to be saved to the VM’s disk. The scripts are also accessible via the AMP web-console’s activity view. Access to the latter can be controlled via Entitlements.

As an example (taken from MSSQL install), the command below works when run locally, but fails over WinRM:

( $driveLetter + "setup.exe") /ConfigurationFile=C:\ConfigurationFile.ini

The code below can be used instead (note this example uses Freemarker templating):

& winrm set winrm/config/service/auth '@{CredSSP="true"}'
& winrm set winrm/config/client/auth '@{CredSSP="true"}'
#
$pass = '${attribute['windows.password']}'
$secpasswd = ConvertTo-SecureString $pass -AsPlainText -Force
$mycreds = New-Object System.Management.Automation.PSCredential ($($env:COMPUTERNAME + "\${location.user}"), $secpasswd)
#
$exitCode = Invoke-Command -ComputerName $env:COMPUTERNAME -Credential $mycreds -ScriptBlock {
    param($driveLetter)
    $process = Start-Process ( $driveLetter + "setup.exe") -ArgumentList "/ConfigurationFile=C:\ConfigurationFile.ini" -RedirectStandardOutput "C:\sqlout.txt" -RedirectStandardError "C:\sqlerr.txt" -Wait -PassThru -NoNewWindow
    $process.ExitCode
} -Authentication CredSSP -ArgumentList $driveLetter
#
exit $exitCode

In this example, the ${...} format is FreeMarker templating. Those sections will be substituted before the script is uploaded for execution. To explain this example in more detail:

  • ${attribute['windows.password']} is substituted for the entity’s attribute “windows.password”. This (clear-text) password is sent as part of the script. Assuming that HTTPS and NTLM is used, the script will be encrypted while in-flight.

  • The ${location.user} gets (from the entity’s machine location) the username, substituting this text for the actual username. In many cases, this will be “Administrator”. However, on some
    clouds a different username (with admin privileges) will be used.

  • The username and password are used to create a new credential object (having first converted the password to a secure string).

  • Credential Security Service Provider (CredSSP) is used for authentication, to pass the explicit
    credentials when using Invoke-Command.

To avoid the inclusion of clear-text passwords in the scripts, we recommend the use of a secure keystore such as Vault, which can be used by the script to retrieve sensitive data such as credentials.

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:

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

When calling an executable in a PowerShell script, the stdout and stderr will usually be output to the console. This is captured by AMP, 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 AMP’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 on the Microsoft TechNet site.

AMP and Maeztro are developed and supported by Cloudsoft Corporation.