Introduction to the Windows PowerShell Automations PowerPack

Download this manual as a PDF file

This section describes how to use the run book automation policies, run book actions, and custom action types found in the "Windows PowerShell Automations" PowerPack.

What is the Windows PowerShell Automations PowerPack?

The "Windows PowerShell Automations" PowerPack includes:

  • A custom action type for running PowerShell commands on remote devices
  • A device group with rules that include only Windows devices
  • A set of run book actions that run diagnostic commands on Windows systems via PowerShell
  • A set of run book automation policies that tie events from monitoring PowerPacks to the run book actions

The run book automation actions for this PowerPack are executed on the SL1 All-In-One Appliance or Data Collector.

In addition to using the standard content, you can use the content in the "Windows PowerShell Automations" PowerPack to:

  • Create your own run book automation policies that include the pre-defined actions that run different sets of diagnostic commands.
  • Use the supplied "Execute PowerShell Request" custom action type to configure your own run book action by supplying a set of commands to be executed via PowerShell.

Version 105 and later of this PowerPack supports Python 3.6.

Installing the Windows PowerShell Automations PowerPack

Before completing the steps in this section, you must import and install the latest version of the "Windows PowerShell Automations" PowerPack.

You must install the "Datacenter Automation Utilities" PowerPack version 201 or later before using this release of the "Windows PowerShell Automations" PowerPack.

The "Windows PowerShell Automations" PowerPack requires SL1 version 12.1.2 or later. For details on upgrading SL1, see the appropriate SL1Release Notes.

By default, installing a new version of a PowerPack overwrites all content from a previous version of that PowerPack that has already been installed on the target system. You can use the Enable Selective PowerPack Field Protection setting in the Behavior Settings page (System > Settings > Behavior) to prevent new PowerPacks from overwriting local changes for some commonly customized fields. For more information, see the section on Global Settings.

For details on upgrading SL1, see the relevant SL1 Platform Release Notes.

To download and install the PowerPack:

  1. Search for and download the PowerPack from the PowerPacks page (Product Downloads > PowerPacks & SyncPacks) at the ScienceLogic Support Site.
  2. In SL1, go to the PowerPacks page (System > Manage > PowerPacks).
  3. Click the Actions button and choose Import PowerPack. The Import PowerPack dialog box appears.
  4. Click [Browse] and navigate to the PowerPack file from step 1.
  5. Select the PowerPack file and click Import. The PowerPack Installer modal displays a list of the PowerPack contents.
  6. Click Install. The PowerPack is added to the PowerPacks page.

If you exit the PowerPack Installer modal without installing the imported PowerPack, the imported PowerPack will not appear in the PowerPacks page. However, the imported PowerPack will appear in the Imported PowerPacks modal. This page appears when you click the Actions menu and select Install PowerPack.

Creating a Credential for Windows PowerShell

If you do not have the "Microsoft: Windows Server" PowerPack installed, you must create a credential that includes the username and password to communicate with your Windows devices.

To prepare your Windows systems for monitoring, follow the instructions in Configuring Windows Servers for Monitoring with PowerShell.

If you have the "Microsoft: Windows Server" PowerPack installed and configured, you may skip this section.

To define a PowerShell credential in SL1, you will need the following information:

  • The username and password for a user on the Windows device.
  • If the user is an Active Directory account, the hostname or IP address of the Active Directory server and the domain.
  • Determine if an encrypted connection should be used.
  • If you are using a Windows Management Proxy, the hostname or IP address of the proxy server.

To create a PowerShell credential:

  1. Go to the Credentials page (Manage > Credentials).
  2. Click the Create New button and then select Create Powershell Credential. The Create Credential modal page appears:

An image of the powershell Create Credential page.

  1. Supply values in the following fields:
  • Name. Name of the credential. Can be any combination of alphanumeric characters, up to 64 characters. This field is required.
  • All Organizations. Toggle on (blue) to align the credential to all organizations, or toggle off (gray) and then select one or more specific organizations from the What organization manages this service? drop-down field to align the credential with those specific organizations. This field is required.

    To learn more about credentials and organizations, see the section Aligning Organizations With a Credential.

  • Timeout (ms). Time, in milliseconds, after which SL1 will stop trying to communicate with the authenticating server. For collection to be successful, SL1 must connect to the authenticating server, execute the PowerShell command, and receive a response within the amount of time specified in this field.
  • Hostname/IP. Hostname or IP address of the device from which you want to retrieve data. This field is required.
  • You can include the variable %D in this field. SL1 will replace the variable with the IP address of the device that is currently using the credential.
  • You can include the variable %N in this field. SL1 will replace the variable with the hostname of the device that is currently using the credential. If SL1 cannot determine the hostname, SL1 will replace the variable with the primary, management IP address for the current device.
  • You can include the prefix HOST or WSMAN before the variable %D in this field if the device you want to monitor uses a service principal name (for example, "HOST://%D" or "WSMAN://%D"). SL1 will use the WinRM service HOST or WSMan instead of HTTP and replace the variable with the IP address of the device that is currently using the credential.
  • Port. Type the port number used by the WinRM service on the Windows device. This field is required.
  • Username. Type the username for an account on the Windows device to be monitored or on the proxy server. This field is required.

    NOTE: The user should not include the domain name prefix in the username for Active Directory accounts. For example, use "em7admin" instead of "MSDOMAIN\em7admin".

  • Password. Type the password for the account on the Windows device to be monitored or on the proxy server. This field is required.
  • Account Type. Type of authentication for the username and password in this credential. Choices are:
    • Active Directory. On the Windows device, Active Directory will authenticate the username and password in this credential.
    • Local. Local security on the Windows device will authenticate the username and password in this credential.
  • Use SSL (HTTPS) / Encrypted. Select whether SL1 will communicate with the device using an encrypted HTTP or HTTPS connection:
    • Toggle on (blue) if SL1 will communicate with the device using an encrypted connection over HTTPS. If toggled on, when communicating with the Windows server, SL1 will use a local user account with authentication of type "Basic Auth". You must then use HTTPS and can use a Microsoft Certificate or a self signed certificate.

      In SL1 versions prior to 12.3.7, this field is labeled Encrypted. In versions 12.3.7 and above, it is labeled Use SSL (HTTPS).

      In SL1 versions 11.3.0 and later, a newer Kerberos library is used that allows for message encryption over HTTP. This feature is on by default and may eliminate the need for you to configure an HTTPS certificate depending on your security requirements.

    • Toggle off (gray) . The credential is encrypted over HTTP rather than HTTPS.
  • Validate Certificate (when HTTPS is used). This field is visible when the Use SSL (HTTPS) toggle field is enabled for the connection and allows you to select whether a certificate is validated for the credential. Choices are:
    • Ignore. SL1 will not validate a certificate for the credential. This is the default setting.
    • Validate. SL1 will require a validated certificate for the credential. If you select Validate, then the target device must include a non-expired certificate issued from a certificate authority.
  • Active Directory Host/IP. If you selected Active Directory in the Account Type field, type the hostname or IP address of the Active Directory server that will authenticate the credential.
  • Active Directory Domain. If you selected Active Directory in the Account Type field, type the domain where the monitored Windows device resides.
  • Message Encryption Setting. If you selected Active Directory in the Account Type field, select whether Kerberos packages sent over PowerShell Remoting Protocol (PSRP) or Windows Remote Management (WinRM) are encrypted. Choices are:
    • Auto. Encryption is enabled if the package supports it; otherwise, encryption is disabled. This is the default setting.
    • Never. Messages are never encrypted. If selected, the target device must support this option.
    • Always. Messages are always encrypted. If selected, the target device must support this option.
  • PowerShell Proxy Hostname/IP. If you use a proxy server in front of the Windows devices you want to communicate with, type the fully-qualified domain name or the IP address of the proxy server in this field.
  1. Click Save & Close.

If you would like to test your credential using the Credential Tester panel, click Save & Test. For detailed instructions on using the Credential Tester panel, see the Using the Credential Tester Panel section.

Creating a Credential for Windows PowerShell in the Classic User Interface

To define a PowerShell credential in the classic SL1 user interface:

  1. Collect the information you need to create the credential:
  • The username and password for a user on the Windows device.
  • If the user is an Active Directory account, the hostname or IP address of the Active Directory server and the domain.
  • Determine if an encrypted connection should be used.
  • If you are using a Windows Management Proxy, the hostname or IP address of the proxy server.
  1. Go to the Credential Management page (System > Manage > Credentials).
  2. In the Credential Management page, click the Actions menu. Select Create PowerShell Credential.
  3. The Credential Editor page appears, where you can define the following fields:
  • Profile Name. Name of the credential. Can be any combination of alphanumeric characters. This field is required.
  • Hostname/IP. Hostname or IP address of the device from which you want to retrieve data. This field is required.
  • You can include the variable %D in this field. SL1 will replace the variable with the IP address of the device that is currently using the credential.
  • You can include the variable %N in this field. SL1 will replace the variable with the hostname of the device that is currently using the credential. If SL1 cannot determine the hostname, SL1 will replace the variable with the primary, management IP address for the current device.
  • You can include the prefix HOST or WSMAN before the variable %D in this field if the device you want to monitor uses a service principal name (for example, "HOST://%D" or "WSMAN://%D"). SL1 will use the WinRM service HOST or WSMan instead of HTTP and replace the variable with the IP address of the device that is currently using the credential.
  • Username. Type the username for an account on the Windows device to be monitored or on the proxy server. This field is required.

NOTE: The user should not include the domain name prefix in the username for Active Directory accounts. For example, use "em7admin" instead of "MSDOMAIN\em7admin".

  • Encrypted. Select whether SL1 will communicate with the device using an encrypted connection. Choices are:
  • yes. When communicating with the Windows server, SL1 will use a local user account with authentication of type "Basic Auth". You must then use HTTPS and can use a Microsoft Certificate or a self-signed certificate.
  • no. When communicating with the Windows server, SL1 will not encrypt the connection.
  • Port. Type the port number used by the WinRM service on the Windows device. This field is automatically populated with the default port based on the value you selected in the Encrypted field. This field is required.

  • Account Type. Type of authentication for the username and password in this credential. Choices are:
  • Active Directory. On the Windows device, Active Directory will authenticate the username and password in this credential.
  • Local. Local security on the Windows device will authenticate the username and password in this credential.

  • Timeout (ms). Type the time, in milliseconds, after which SL1 will stop trying to collect data from the authenticating server. For collection to be successful, SL1 must connect to the authenticating server, execute the PowerShell command, and receive a response within the amount of time specified in this field.
  • Password. Type the password for the account on the Windows device to be monitored or on the proxy server. This field is required.
  • PowerShell Proxy Hostname/IP. If you use a proxy server in front of the Windows devices you want to communicate with, type the fully-qualified domain name or the IP address of the proxy server in this field.
  • Active Directory Hostname/IP. If you selected Active Directory in the Account Type field, type the hostname or IP address of the Active Directory server that will authenticate the credential.
  • Domain. If you selected Active Directory in the Account Type field, type the domain where the monitored Windows device resides.
  1. To save the credential, click the Save button. To clear the values you set, click the Reset button.