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
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, Service Desk 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.
WinRM quickconfig Command
1. Open up a Powershell terminal on the target Windows machine.
2. Run the following command in the Powershell terminal:
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:
Starts the WinRM service and sets the service startup type to auto-start.
Configures a listener for the ports that send and receive WS-Management protocol messages using either HTTP or HTTPS on any IP address.
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.
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:
From the command result, copy the IPv4 address.
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.
Windows Server Password:
The password is used for authenticating the user on the target Windows server.
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.
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.
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.
Note: Currently self signed certificate and certificate acquired from private ca is not supported, in case of self signed certificate, verification(Disable SSL Certificate Verification) should be disabled.
Networking Requirements
Please ensure that the following network communication is established before executing the app actions -
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. .
Check out the FAQ article for troubleshooting. More info here
