Overview

You can use this app to execute PowerShell commands on an on-premise Windows server/host. This app communicates with the on-premise network using the orchestration server.


Recommended Powershell Version: 5.1

Description

Orchestration apps let you automate repeatable tasks and actions spanning various systems and applications using workflows.


All documentation related to this app can be accessed using the following URL

https://support.freshservice.com/en/support/solutions/folders/50000000621


Some of the critical actions supported by this app are listed below.

1. Execute Command

2. Execute Command Using Inline Connection


Working Principle

The app communicates with an on-premise Windows server with the help of the Orchestration server, which resides in the same private network as the Windows server and acts as an agent.

The Orchestration server establishes a secure outbound connection over port 443 from inside the private network and looks for any incoming app requests.

 

Once it receives the app request over the outbound connection, the Orchestration server will then communicate with the Windows server in the same private network using WinRM  - Windows Remote Management.


 

Prerequisites

  1. Orchestration Server Installation

Orchestration server should be installed using the installer on a windows server. You can find this installer in your Freshservice tenant in the Admin module, Helpdesk Productivity > Orchestration Centre > Orchestration Server > Download Windows Installer”.

To know more about the orchestration server installation, please refer to the Orchestration Server solution article.


It is recommended to install the Orchestration server on a separate windows server with access to the target Windows server over the WinRM listener port.


  1. WinRM quickconfig Command 

1.  Open up a Powershell terminal on the target Windows machine. 

2. Run the following command in the Powershell terminal: 

winrm quickconfig

    

    Note: The above command will configure the WinRM listener on port 5985.


    Configuring WinRM listener over HTTPS

winrm quickconfig -transport:https


Note: The above command will configure the WinRM listener on port 5986.


For detailed information on configuring the WinRM listener using SSL, please refer to the official Microsoft documentation.


Once you execute the winrm quickconfig command based on your connection type (SSL or otherwise), you can verify the WinRM listener port with the following command -

winrm enumerate winrm/config/listener


For WinRM listener over HTTPS, you’ll get a response in the following manner unless the port is specified explicitly -


 Listener

    Address = *

    Transport = HTTPS

    Port = 5986

    Hostname = heimdalls.internal.com

    Enabled = true

    URLPrefix = wsman

    CertificateThumbprint = <your-cert-thumbprint>

    ListeningOn = 10.0.3.15, 127.0.0.1, 169.254.195.74, ::1,  fe80::5efe:10.0.3.15%4, fe80::5efe:169.254.195.74%7,  fe80::153e:398e:1707:f6c6%3, fe80::cd13:eaaf:6931:c34a%2


For WinRM listener over HTTP, you’ll get a response in the following manner unless the port is specified explicitly -


Listener

    Address = *

    Transport = HTTP

    Port = 5985

    Hostname

    Enabled = true

    URLPrefix = wsman

    CertificateThumbprint

    ListeningOn = 10.0.3.15, 127.0.0.1, 169.254.195.74, ::1, fe80::5efe:10.0.3.15%4, fe80::5efe:169.254.195.74%7, fe80::153e:398e:1707:f6c6%3, fe80::cd13:eaaf:6931:c34a%2



What does the “winrm quickconfig” Command Do?

The "winrm quickconfig" command performs these operations:

  1. Starts the WinRM service and sets the service startup type to auto-start.

  2. Configures a listener for the ports that send and receive WS-Management protocol messages using either HTTP or HTTPS on any IP address.

  3. Defines ICF(Internet Connection Firewall) exceptions for the WinRM service and opens the ports for HTTP and HTTPS.



Note

The winrm quickconfig command creates a firewall exception only for the current user profile. Therefore, If the firewall profile is changed for any reason, you should run winrm quickconfig to enable the firewall exception for the new profile; otherwise, the exception might not be allowed. For more information, please refer to the documentation here.


Installation Parameters

The app requires the following parameters during installation. These parameters will be used to authenticate the calls from the app to the on-premise Windows server.


  1.  Windows Server IP:

The IP address of the Windows server. It can be a private IP or a public IP depending upon the server configurations. 

The private IP address can be retrieved using a PowerShell terminal with the following command: 

ipconfig /all

 

From the command result, copy the IPv4 address.



  1.  Windows Server Username: 

The username is used for logging in to the Windows server.


IMPORTANT

The user-specified in the app configuration should be either an Administrator or a user added to the built-in group Remote Management Users.


  1. Windows Server Password:

The password is used for authenticating the user on the target Windows server.


  1. WinRM Port:

The default WinRM port is 5985 for communication over HTTP, and 5986 for communication over HTTPS, unless the WinRM port is explicitly configured. If it is explicitly configured, the same port should be used in the app configuration and a WinRM listener should be configured on that port as mentioned in pre-requisite step 2.




  1. Use SSL Connection?

Specify whether the connection to the Windows server is over HTTPS (SSL certificate configured) or over HTTP (no SSL certificate configured).

If set to True, communication to the Windows server will be over HTTPS. If set to False, communication to the Windows server will be over HTTP.


  1. Disable SSL Certificate Verification? (Optional)

Specifies whether SSL certificate verification should take place or not.

    If set to True, SSL certificate verification will not take place.

    If set to False, SSL certificate verification will take place.

    The default value is ‘true’, and hence the default SSL certificate verification will not take place.

Networking Requirements

Please ensure that the following network communication is established before executing the app actions -


  1. Communication on the default WinRM port (or a custom port based on your configurations), from the Orchestration server to the target windows server should be enabled. You can use the telnet utility to verify the open WinRM port.



Verify Connection Using “Test App Action”

You can also use the “Test App Action” functionality inside the Workflow Automator’s App Node to verify the connection between the Orchestration server and Windows server.  You want to execute PowerShell commands remotely.


Disclaimer:

Using the “Test App Action” will execute the action on the target Windows machine. .