External Tools

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:

- %NAME%
- %HOSTNAME%
- %PORT%
- %USERNAME%
- %PASSWORD%
- %DOMAIN%
- %DESCRIPTION%
- %MACADDRESS%
- %USERFIELD%

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:

- Each quotation mark will be escaped by a backslash.
- One or more backslashes (\) followed by a quotation mark ("):
  - Each backslash will be escaped by another backslash.
  - The quotation mark will be escaped by a backslash.
  If the connection's user field contains "This" is a \"test\".
  Then %USERFIELD% is replaced with \"This\" is a \\\"test\\\".
- A variable name followed by a quotation mark (for example, %USERFIELD%") with a value ending in one or more backslashes:
  - Each backslash will be escaped by another backslash.
  - Example:
  If the connection's user field contains c:\Example\
  Then "%USERFIELD%" is replaced with "c:\Example\\"

To disable argument splitting escaping for a variable, precede its name with a minus (-) sign. For example, %-USERFIELD%.

Shell metacharacter escaping:

- The shell metacharacters are ( ) % ! ^ " < > & |
- Each shell metacharacter will be escaped by a caret (^).

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.