Skip to main content
System StatusContact Support
VersionOne Community

Tasks, Basic Windows Automation

Overview

Continuum Automate interacts with Microsoft Windows servers using the Windows Remote Management (WinRM) service which is Microsoft’s implementation of the WS-Management protocol. WinRM is served via a web service that resides on the target server and can run Windows command line commands as well as PowerShell scripts.

More information on WinRM from the Microsoft MSDN Library:

https://msdn.microsoft.com/en-us/library/aa384426(v=vs.85).aspx

Setup

For Continuum to interact with a Windows server via WinRM there are two main requirements: the service must be enabled and configured properly and credentials. This section describes these requirements.

Enabling WinRM on the Windows Server

Typically, WinRM is not enabled by default, or is tightly locked down rendering it unusable when attempting to access via Linux. Therefore the first thing to do is configure the WinRM service on Windows.

These next few steps require administrator privileges. Also, some of these settings can be considered insecure on a permanent basis. More secure settings require further setup and are out of scope of a tutorial.

Start a Remote Desktop session on the target Windows server, and log in as a user with administrator level privileges. Open a Command Line shell.

1) Setup WinRM to receive requests and open the firewall using the WinRM quickconfigure command:

winrm qc -q

2) Allow basic authentication (more on this later):

winrm set winrm/config/client/auth @{Basic="true"}
winrm set winrm/config/service/auth @{Basic="true"}

3) Allow non-https connections (more on https later):

winrm set winrm/config/client @{AllowUnencrypted="true"}
winrm set winrm/config/service @{AllowUnencrypted="true"}

4) The default timeout on a remote session is set to 60 seconds. Often, commands or PowerShell scripts may run for much longer. The following bumps the timeout up to 10 minutes. Sadly, as of this writing, there is no known way to change this setting at runtime, so we will set a reasonable number here.

winrm set winrm/config @{MaxTimeoutms="600000"}

5) We want the WinRM service to start immediately when the system boots.

powershell.exe -command {Set-ItemProperty -path "HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\services\WinRM" -name "DelayedAutoStart" -value "0"}

6) Finally, test that Automate can access WinRM (and the required port). SSH onto the Continuum server, and test with the following command:

curl -v http://:5985/wsman

The command should return immediately with an HTTP 405 response. This means that the network route to the Windows server worked and no firewall issues as well as the service is up and responding. If you receive a timeout, check the Windows firewall or network routing for port 5985.

Additional testing (and even basic commands) can be executed using the following Continuum command at the Linux shell:

ctm-winrm -s -u -p -c'dir'

Allowing Non-Administrators to Execute WinRM

To execute commands remotely using WinRM, the user account used must have certain privileges. The easiest and most common way to run remote commands is using a local Windows account in the Administrators group.

If using a local admin account won't work in your organization, the following steps can set up a lower privilege account for WinRM.

To be clear, the following instructions require a local account and local security settings. This cannot be configured to use an Active Directory account. There is different configuration and setup for that scenario which is outside of scope of this tutorial.

1) Create a local user account with no special groups or settings. In this example we're using the account name continuum. This account won't be tied to an actual user, but can be thought of as an application or service account. Make sure to set the password to something that conforms to security policy. If the security policy requires an initial password change, you need to override that policy, or log in manually and reset the password.

The security policy is the most common cause of WinRM connectivity errors. It is crucial the password be set to never expire and to not require changing upon login.

2) Add continuum to the WinRMRemoteWMIUsers__ security group. This can be done at the command line via the following command:

net localgroup WinRMRemoteWMIUsers__ continuum /add

3) Obtain continuum's SID. (An internal Windows identifier.) Get it using the following command:

wmic useraccount where name="USER" get sid

The wmic command will return a lot of users and may be slow. The SID will be the long string with random letters and numbers. For example:

S-1-5-21-3071543043-3935569508-1802104949-1007

4) Configure WinRM to allow continuum to run remote commands and Powershell scripts. The following command is confusing to look at, but it's basically just Window's way of assigning some permissions.

Once you've found the SID for continuum, copy and pasted it into the following, replacing SID with the value.

NOTE: the following command and the example next are intended to be run as a single command on a single line, not multiple lines as they appear in this document.

winrm set winrm/config/service @{RootSDDL="O:NSG:BAD:P(A;;GA;;;BA)(A;;GA;;;**SID**)S:P(AU;FA;GA;;;WD)(AU;SA;GWGX;;;WD)"}

Here's what it should look like:

winrm set winrm/config/service @{RootSDDL="O:NSG:BAD:P(A;;GA;;;BA)(A;;GA;;;S-1-5-21-3071543043-3935569508-1802104949-1007)S:P(AU;FA;GA;;;WD)(AU;SA;GWGX;;;WD)"}

That's it! WinRM should now be available to the continuum user.

Return to the Continuum server command line and run the following command to test connectivity and permissions for the continuum user.

    ctm-winrm -s -ucontinuum -p -c'dir'

If you receive a 401 Unauthorized then you have a credentials or permissions issue that will need to be resolved.

Windows Automation

Assuming that WinRM is now configured on the target server we will setup Continuum to interact with it.

A First Task

Tasks are essentially scripts that Continuum Automate uses to interact with external systems and are fully customizable. Tasks are created and edited through the Continuum Automate user interface. Use the following tutorial to create your first hello world Task and then return to this document to continue with WinRM.

http://continuumdocs.versionone.com/docs/automate/tutorials/hello-world.html

A WinRM Task

We will want to import a sample task for WinRM in Github. First read the README at the following link that covers all the sample tasks and how to import them.

https://github.com/clearcode-labs/automate-samples

The WinRM sample is located here:

https://github.com/clearcode-labs/automate-samples/tree/master/winrm

The winrm README explains what the task does and how to import just this task. Once the Task is imported and the README is read, edit the Task and run it. You will be prompted for an address, user and password. Use the Windows account and password you created in a previous step of this tutorial.

Next Steps

Since the Windows server requires prior setup for WinRM to be used, if the server is part of a virtual environment and will be dynamically provisioned by Continuum, it is recommended that you bake in the WinRM setup in the server image. Methods of doing this will vary, contact support@versionone.com for more information.

  • Was this article helpful?