The Remote Script Execution Engine™ (RSEE™) is an enterprise-level remote script execution environment.
RSEE Overview
RSEE consists of two components: The client, which is built into PrimalScript and 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 PrimalScript and PowerShell Studio, out to remote computers where the script is executed, and bringing the scripts' output and results back to PrimalScript or 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 Deployment
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.
Identity
RSEE installs, by default, to log in under the privileged LocalSystem account. This may be sufficient for your purposes. However, when deploying scripts in PrimalScript and 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.
TCP Port
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.
To specify a different port
•You can specify a different port via the registry key HKEY_LOCAL_MACHINE\Software\Policies\SAPIEN. The Value name is InPort (for the incoming port) and OutPort (for the outgoing port). Note that these values are most easily configured by means of a Group Policy object (GPO), and we provide a template (ADM file) that can be imported into a GPO to configure RSEE.
The RSEE service and both PrimalScript and PowerShell Studio (as the RSEE client) 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.
Domain Tips
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:
•Create a domain account
Name this account something like "RSEEUser" and provide it with a strong password per your organization's password policies.
•Deploy the RSEE service
This can be done by means of a Group Policy object (GPO) linked to the appropriate levels in the domain. The RSEE service defaults to running under the LocalSystem account and it defaults to port 9987. The service's MSI is located in the RSEE folder under your PrimalScript Enterprise installation folder.
•Make the RSEE service account a local Administrator
You can do this in a Group Policy object (GPO). Browse to Computer Configuration > Security Settings > Restricted Groups. Add a group ("Administrators") and then add your RSEE domain account (and any other appropriate accounts) to the group.
•Configure the RSEE service
You need to configure the RSEE service to log on with the user account (and password) you created. This can either be done manually or using a script. The book Windows Administrator's Automation Toolkit, for example, contains a script that can set the logon account and password used by services running on multiple computers. Utilities like Service Explorer (www.scriptlogic.com) can perform the same task.
•Select the TCP port
We provide a Group Policy object (GPO) administrative template (ADM file) that you can import into a GPO and use to centrally configure the TCP port used by the RSEE service. This ADM file is located in the RSEE folder under your PrimalScript Enterprise installation folder.
Using RSEE
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.
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:
•Click Launch to run the script on the computers which have a checkmark next to their name.
•Set or clear the checkbox next to one or more computer names. You can leave names in the list but clearing their checkbox will prevent RSEE from attempting to run the script on them.
•Click Close to close the Launch dialog. If you've changed the list of computer names, you'll be prompted to save your changes.
•Use Load List and Save List to load an alternate list of computer names (from a text file) or save the current list to a text file. By default, PrimalScript will look for a text file called Default.clt in the \SAPIEN\RSEE Lists folder under your Documents folder. You will need to create the file yourself if you want a pre-loaded list when you launch RSEE.
•Use Select All and Unselect All to set or clear the checkbox next to all computer names currently in the list.
•Select a computer name and click Remove to remove it from the list.
•Type a computer name (must be resolvable to an IP address by your computer) or IP address and click + to add that computer to the list.
•Specify a username (user ID) and password. These will be used to run the script on the remote computer, and should generally match the username that the remote RSEE service is using to log in. Note: if the username you specify is a local account on the remote computer(s), then just type the username. If the username is a domain account, specify the name in the format user@domain. The older domain\user format is not supported.
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 pane within PrimalScript or PowerShell Studio. 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 PrimalScript or 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 PrimalScript or 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 pane is already open in PrimalScript or 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.
RSEE Restrictions
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:
•If you specify credentials in the Launch dialog (#2 in the diagram) that the RSEE service account (#3 in the diagram) doesn't have permission to use in a new process launch, then script execution will fail.
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).
•If the RSEE service account (#3 in the diagram) doesn't have appropriate rights (including "Log on as a service"), then the RSEE service will not be able to start.
•If your script tries to do something that the Launch credentials (#2 in the diagram) don't have permission to do—such as log into a database or access a file share—then you'll receive an error. Depending on the exact situation, this may or may not be communicated back to you in PrimalScript or PowerShell Studio.
•If your script tries to perform an illegal operation—such as specifying alternate credentials in a WMI connection (which is illegal because the script is executing locally on the remote machine, and local connections to WMI aren't allowed to use alternate credentials)—you'll receive an error. Again, depending on the exact circumstances, this error may or may not be fed back to you in PrimalScript or PowerShell Studio.
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 Notes
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.
See also:
