RSEE Credentials and Execution Process
The Remote Script Execution Engine™ (RSEE™) is an enterprise-level remote script execution environment. It consists of two components: The client, which is built into PowerShell Studio, and a remote service that must be deployed to each computer where you will remotely run scripts. RSEE is capable of deploying a script from within PowerShell Studio out to remote computers where the script is executed, and bringing the scripts' output and results back to PowerShell Studio for your review.
RSEE is a complex tool and it interacts closely with Windows' security subsystems. RSEE is recommended for use only by experienced Windows administrators who fully understand service deployment and management, cross-computer security and authentication and, in the case of domain environments, Group Policy objects and Active Directory administration. Apart from the guidelines in this manual, SAPIEN Technologies cannot assist you with security issues caused by improper configuration nor can we assist with Active Directory, Group Policy, or local computer configuration tasks.
RSEE is designed only for Windows Script Host (WSH) scripts in VBS (VBScript) or JS (JScript) files. It is not designed for other WSH scripts (including WSFs) nor is it designed for scripts written in other languages (such as batch, KiXtart, and so forth).
RSEE's service component is packaged in a Microsoft Windows Installer (MSI) file and is suitable for deployment via Group Policy. You can also manually install it on individual machines. Keep in mind that, once installed, the service needs to be started in order to be useful. This will occur automatically after restarting the computer on which the service is installed (the service is set to start automatically by default).
After deploying the service, there are a number of configuration steps that you must take in order to properly configure RSEE in your environment.
RSEE installs, by default, to log in under the privileged LocalSystem account. This may be sufficient for your purposes. However, when deploying scripts in PowerShell Studio, be sure not to specify any credentials in the Launch dialog box. Also be advised that the LocalSystem account may not be able to execute some scripts, depending on their security requirements.
We recommend that you configure the RSEE service to run under a user account that has administrative privileges on the local computer. In a workgroup environment this would be a local account, and we recommend creating the same local account (with the same password) on all of your computers, for consistency. In a domain environment, we recommend creating a single domain account which has local administrative rights on all computers in the domain, and using this account to run the RSEE service. Whenever the RSEE service is running under a user account, you must specify that account (and its password) when deploying scripts in PrimalScript.
When using RSEE, you have the option to specify the credentials under which the script should execute. Generally speaking, you need to provide the same credentials that the RSEE service is using to log on.
The RSEE service defaults to using TCP port 9987 for incoming connections, and TCP port 9988 for outgoing connections. It is your responsibility to ensure that any local firewalls will permit incoming traffic on this port. Keep in mind that the Windows Firewall (Windows XP SP 2 and later, and Windows Server 2003 SP 1 and later) can be centrally configured via a domain Group Policy object.
You can specify a different port:
Both PowerShell Studio (as the RSEE client) and the RSEE service utilize InPort and OutPort. The service listens to InPort for incoming connections and uses OutPort to send script output back to the client. The client reverses this: scripts are sent via InPort and results are received on OutPort. The registry key above configures these ports for both clients and the service.
While manually configuring a few computers in a workgroup is not a hardship, manually configuring an entire domain of computers can be burdensome. An Active Directory domain environment provides a number of capabilities for centralizing and automating this configuration, however. While this section is not intended as a comprehensive tutorial in Active Directory (we recommend that you consult an experienced Active Directory administrator or the appropriate documentation if you need more assistance), the following tips should help you configure RSEE more easily:
RSEE now supports Powershell. To deploy the current script (only VBS and JS files are currently supported) to one or more remote computers that have the RSEE service installed, click the RSEE button on the Script toolbar, or select Run Script on Remote Computer from the Script menu.
RSEE performs a quick scan of your script to look for commands that might create a graphical user element such as the VBScript MsgBox() function. If it finds any of these functions, it displays a warning message. Keep in mind that scripts will not normally be able to interact with the desktop environment on remote computers, meaning there would be no way for someone to respond to graphical elements such as MsgBox() or InputBox(). As a result, these elements can cause the script to "hang" and stop responding. RSEE does not perform an exhaustive check for graphical elements; it is your responsibility to ensure they're not used in your scripts. RSEE will allow you to continue with graphical elements because you may have configured the RSEE service to interact with the desktop of the remote computer. It's your decision.
Next is the RSEE Launch dialog. The Launch dialog lists the computers where your script will be deployed. Note that the Launch dialog always preloads a default list of computer names at startup. Here's what you can do:
When you click Launch, RSEE will execute the script on the remote computer(s). Any output produced by the script will be displayed in the Output tab within the PowerShell Studio window. Note that the message "Socket connection failed" indicates that RSEE was unable to connect to the RSEE service on a specified computer (either because the computer is not connected to the network, has a firewall blocking the RSEE service ports, or the RSEE service is not installed).
RSEE deploys scripts asynchronously. That is, RSEE sends the scripts out to the remote computers you've selected and then displays whatever results come back. If your scripts produce no output then you won't see any results in PowerShell Studio.
It's possible for the RSEE service on a remote computer to run into a problem (particularly security-related ones) that it can't report back; in these instances, it will seem to you (looking at PowerShell Studio) as if nothing has happened. Whenever possible, your scripts should incorporate error-checking and -trapping, and should produce appropriate output so that you get some results back if the script executes correctly.
Note that RSEE cannot be used to deploy a script for later execution. If you need to schedule a script to execute on a remote computer at a particular time, use Windows' built-in Task Scheduler instead of RSEE. You can even write a script utilizing the SCHTASKS.EXE command line tool that creates remote scheduled tasks on multiple computers.
Also note that, if an Output tab is already open in PowerShell Studio, RSEE will utilize it rather than creating a new one. You will need to manually select the tab to view any RSEE results or error messages.
In order to bring the output of remote scripts back to your computer, the remote RSEE service captures the standard command-line output of your scripts. That means any script output must be created using the WScript.Echo method. Do not use graphical user interface functions such as MsgBox() or InputBox(). Because the RSEE service doesn't interact with the desktop, nobody will ever see these functions' dialog boxes and the script will hang.
It is possible, if the RSEE service is running under the LocalSystem account, to configure Windows to allow the service to interact with the desktop. You may wish to experiment with this configuration, but it is not a recommended configuration because of the usual security restrictions on the LocalSystem account.
Also avoid any object methods-such as WScript.Popup-that create graphical elements.
Any objects referenced by a script must be installed, registered, and available on the remote machine where RSEE executes the script.
At this time, RSEE can only be used to execute Windows Script Host scripts. RSEE explicitly launches scripts under CScript.exe which must be available on the remote computers.
Most other restrictions in RSEE are actually Windows security restrictions. When the RSEE service launches, it does so using the credentials you configure in Windows' service manager. When the RSEE service receives a script, it creates a brand-new process using whatever credentials you enter into the RSEE Launch dialog. The following figure illustrates this process and the three sets of credentials involved:
RSEE Credentials and Execution Process
Always bear in mind that your scripts execute under the security credentials you provide (Credentials #2 in the diagram). This process does require your attention, as several things can go wrong if you're not careful:
Practically speaking, the credentials you provide in the Launch dialog (#2 in the diagram) need to be the same as the credentials the RSEE service uses to log in (#3 in the diagram).
These and other similar situations are not problems with RSEE; they are inherent conditions of the Windows operating system and its security subsystems. Whenever you encounter an error with RSEE, bear these conditions in mind and think about the possible security ramifications of what your script is trying to do.
RSEE encrypts scripts during transmission to help keep them secure.
RSEE does not implement any sort of IP filtering capability (which might, for example, allow you to ensure that only your computer can utilize RSEE on remote servers). Instead, we recommend using Windows' own built-in IP filtering (available as part of Windows' IPSec features). Using this filtering, you can ensure that only specified IP addresses are allowed to communicate on the TCP ports used by the RSEE service, thus restricting who can contact that service and utilize RSEE.