Introduction to External Tools
External Tools can help you get things done that can't be done in
mRemoteNG.
You can for example start a command prompt or launch your favorite FTP tool from
within mRemoteNG.
This wouldn't make much sense by itself because you can already launch your
applications by using the Windows Start Menu, Quick Launch or whatever you
prefer to use
to start your apps.
But there's more!
In mRemoteNG, you can launch applications and tell them what to do with the use of arguments (parameters) and variables of the currently selected Connection. You can, for example, select your home router's SSH Connection entry and do a traceroute (tracert) on that host. This is much quicker and more powerful than opening the console and typing "tracert yourhost".
The external tools configuration is stored in %APPDATA%\mRemoteNG\extApps.xml
Variables
Variables and arguments can be used to tell the external tool what to do.
This is the list of variables supported by mRemoteNG:
Variables always refer to the currently selected connection. Variable names are case-insensitive. Variables can be used in both the Filename and Arguments fields.
mRemoteNG will also expand environment variables such as %PATH% and %USERPROFILE%. If you need to use an environment variable with the same name as an mRemoteNG variable, use \% instead of %. The most common use of this is for the USERNAME environment variable. %USERNAME% will be expanded to the username set in the currently selected connection. \%USERNAME\% will be expanded to the value set in the USERNAME environment variable.
If you need to send a variable name to a program without mRemoteNG expanding it, use ^% instead of %. mRemoteNG will remove the caret (^) and leave the rest unchanged. For example, ^%USERNAME^% will be sent to the program as %USERNAME% and will not be expanded.
Special Character Escaping
Expanded variables will be escaped using the rules below. There are two levels of escaping that are done. The first is escaping for standard argument splitting (C/C++ argv, CommandLineToArgvW, etc). The second is escaping shell metacharacters for ShellExecute.
Argument splitting escaping:
To disable argument splitting escaping for a variable, precede its name with a minus (-) sign. For example, %-USERFIELD%.
Shell metacharacter escaping:
To disable both argument splitting and shell metacharacter escaping for a variable, precede its name with an exclamation point (!). For example, %!USERFIELD%. This is not recommended and may cause unexpected results.
Only variables that have been expanded will be escaped. It is up to you to escape the rest of the arguments.
Variable Examples
Arguments | User Field | Result |
---|---|---|
%USERFIELD% | "Example" Text | \^"Example\^" Text |
%-USERFIELD% | "Example" Text | ^"Example^" Text |
%!USERFIELD% | "Example" Text | "Example" Text |
^%USERFIELD^% | "Example" Text | %USERFIELD% |
^^%USERFIELD^^% | "Example" Text | ^%USERFIELD^% |
-d "%USERFIELD%" | c:\Example\ | -d "c:\Example\\" |
-d "%-USERFIELD%" | c:\Example\ | -d "c:\Example\" |
-d "%USERFIELD%" | Left & Right | -d "Left ^& Right" |
-d "%!USERFIELD%" | Left & Right | -d "Left & Right" |
%WINDIR% | N/A | c:\Windows\ |
\%WINDIR\% | N/A | c:\Windows\ |
\^%WINDIR\^% | N/A | \%WINDIR\% |
\\%WINDIR\\% | N/A | \\%WINDIR\\% |
Example
First of all, start the external tools editor. To do this, click Tools in the main menu and
select External Tools.
You will see a screen like on the following screenshot.
The fields below the list are greyed out because you haven't created an external tool
entry yet.
To create one, right click the blank area in the list and select Add, as in the
screenshot below.
This is what you'll get:
So the three fields are now available and need to be filled.
The Display Name is simply the name you will see when you want to launch that
tool, so give it a descriptive name.
I named mine Traceroute as I will create a external tool that will start the
tracert command in the console.
Ok, the next thing we'll need is a filename. This is the program that we
want to be executed.
I simply type in cmd for a Windows cmd console.
Now the fun part comes in—the arguments.
The Windows cmd has a command line argument that tells the console to launch the
command followed by that argument and stay open.
It's /K. (There's also /C, this is useful when you want the console to close
after the command was executed)
In this case, I'll use /K as I want to look through the result when the command
completes.
After that, I just type tracert %HostName%. This tells the console to do a
traceroute on the hostname of the currently selected Connection.
Alright! That's all we'll need.
Now right click one of you connections, click Tools, External Tools
and select Traceroute.
Voilą! A console window will popup and execute your tracert command.