Description:
Execute an application on a remote host
App name: rctrlx
Version: 1.9
Created by: Leon Sodhi


Updates:
(15/11/08):
-Added support for I/O redirection when using the /cm switch (see the compatibility mode section for more details)
-Changed the output text to make it more consistent between using normal stdout redirection and the /cm switch
-Removed displaying the remote applications process ID

(10/11/08):
-Fixed a bug which caused a crash on Windows Vista based operating systems
Known issues:
	-Displaying an application on the remote machines interactive desktop (/i) is not supported under Vista

(5/11/08):
-Added support for the /cm switch which provides a more reliable stdin and stdout for interactive applications e.g. powershell, ftp etc
Known issues:
	-When using the compatibility mode, specifying an invalid command will return immediately with an exit code of 1 rather than state the error
	-When using the compatibility mode, the process ID is not visible before the remote application launches

(20/10/08):
-Increased the maximum length allowed for the hostname (this is only useful for specifying fully qualified domain names)

(25/08/08):
-Added options /ru and /rp to specify the username and password that the remote service should log on as
-The remote service now gets deleted when it fails to start

(9/08/08):
-Increased the maximum length allowed for command line parameters

(31/12/07):
-Renamed to rctrlx
-Fixed a command line processing bug
-Slightly improved performance
-Reduced the number of situations where the remote service must be manually removed

(27/10/07):
-Fixed a bug where a long application+parameters would cause an error to be returned

(23/09/07):
-Fixed a bug where an error message would be shown with a return code of zero

(15/12/06):
-Added the rrc switch to return the remote applications return code when the client exits

(21/11/06):
-Added retry code incase the remote service takes a while to de-initialise


Usage
rctrlx [hostname] [OPTIONS] /app [Application executable parameters]
/app            Specifies the application to run.

Options list:

/c file1,file2  Copies a list of files to the remote working directory.
                These files will be removed on the server exiting successfully
                unless the /d switch is used.
                Note1: The windows directory is the default working directory
                Note2: This first copies to the system32 directory and
                then gets moved to the working directory if specified
                Note4: This will overwrite existing files

/d              Doesn't wait for the application to exit

/i              Displays on the interactive desktop

/s              Run as local system

/u              Username to access the remote host and execute the
                application in the format Domain\Username or just Username

/p              Password for the above username, you will be
                prompted if a username is specified without a password

/w              Working directory on the remote machine

/rrc            Returns the remote applications status on exit

/ru             Remote username that the remote service will run under

/rp             Password for the above remote username, you will be
                prompted if a remote username is specified without a password

/cm XxY 	Compatibility mode for applications that create sub shells
                e.g. telnet, ftp, powershell etc. The XxY value specifies the
                buffer size of the remote command prompt only when output is
		redirected e.g 80x300. If output is sent to the screen this 
		value can be 0x0. See the readme for more information

Usernames and passwords are transferred in cleartext.


Example usage: working directory
rctrlx hostname /w c:\temp /c c:\somefile.txt /i /app notepad.exe somefile.txt - copies the local file c:\somefile.txt to the remote hosts directory c:\temp and then opens the file with notepad.


Example usage: copying files
rctrlx hostname /c c:\somefile.txt /app notepad.exe
rctrlx hostname /c somefile.txt /app notepad.exe - somefile.txt must be in the same directory as the rctrlx executable

A typical event log message on the remote host:
The description for Event ID ( 1 ) in Source ( Application ) cannot be found. The local computer may not have the necessary registry information or message DLL files to display messages from a remote computer. You may be able to use the /AUXSOURCE= flag to retrieve this description; see Help and Support for details. The following information is part of the event: Error transferring file FilterLog.log: The system cannot find the path specified.

The only important parts of this message are the details after "The following information is part of the event".


Compatibility mode:
When using compatibility mode the XxY value must always be specified but is only actually used when I/O is redirected. If the output is being sent directly to the screen, 0x0 can be used. When I/O is being redirected, the XxY value must be between 1x1 - 9999x9999. Please note that setting it to the maximum value will cause significant delay, even a value such as 80x9999 will take roughly 30 seconds to complete. Because of the way compatibility mode works, it is only possible to redirect output that fits within the remote consoles buffer i.e. if you set the buffer to 80x9999 you will only get 9999 rows of data which are each 80 columns wide.


Troubleshooting
Q: How do I access the remote hosts event logs?
A: Either get a terminal up on the remote host and run eventvwr or run "mmc" (Microsoft Management Console) and do file -> add\remove snap in -> add -> event viewer and specify the remote host in the "another computer" text box. Be sure to close the mm console before using the /u option otherwise you may get other errors.

Q: I get the error:
Unable to connect to the remote host: Multiple connections to a server or shared resource by the same user, using more than one user name, are not allowed. Disconnect all previous connections to the server or shared resource and try again..
A: This can be solved by closing any open connections to the remote host including window shares etc

Q: In the remote hosts event logs I get the error:
Error transferring file somefile.txt: The system cannot find the path specified.
A: The working directory probably doesnt exist or is invalid e.g. you dont have access etc

Q: How can I manually remove the servers service on the remote host?
A: On the remote host, stop the service "rctrlx" and then run "sc delete rctrlx".

Q: How can I force the service on the remote host to stop?
A: Kill the rctrlxsrv.exe executable. You can then run "sc delete rctrlx" to remove the service.

Q: Why is the return code always 0 even when an error occurs?
A: Make sure that the environment variable "ERRORCODE" has not been explicitly set (use the set command to show all env vars)

Q: I am trying to use powershell, ftp, telnet or other programs like these and they aren't working as expected.
A: Applications that use sub shells are currently incompatible with rctrlx. This is a known issue and will be solved in an upcoming update.

Q: I've run a sub shell program (like telnet, powershell etc) and I can now no longer run anymore rctrlx sessions on the remote machine what do I do?
A: You need to kill the remote sub shell process manually i.e. telnet.exe etc.

Q: I am running a Windows Vista based operating system (Windows Vista, Windows Server 2008 etc) and I keep getting an access permissions error
A: Rctrlx must be able to access the admin$ share which is disabled by default even if you are an administrator. To enable it you must do the following: Edit the registry and navigate to "HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion \Policies\system\" then add a DWORD value of "LocalAccountTokenFilterPolicy", set its value to 1 and then restart.


TODO:
-On error copying files, delete any files that have already been copied
-Implement more features from psexec e.g. choosing which CPU an application can use, priority of an application etc
-Allow multiple computers to be specified instead of one hostname
-Allow multiple concurrent connections to the remote host
-Allow options to be read from a file (probably XML config file)
-Implement a simple scripting system to manipulate remote GUI applications


Other:
Any bugs, questions, new feature suggestions etc please email me at gtaLon51@ntlworldNOSPAMTHXS.com. Please remove the NOSPAMTHXS. This information is also included here: http://www.geocities.com/gtalon51.


Legal blah:
I am not responsible for any damage that may come to you, your computer, your dog etc through the use of this program.