mirror of
https://github.com/mRemoteNG/mRemoteNG.git
synced 2026-02-25 19:38:37 +08:00
245 lines
11 KiB
HTML
245 lines
11 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
|
||
<html xmlns="http://www.w3.org/1999/xhtml" >
|
||
<head>
|
||
<title>External Tools</title>
|
||
<link href="Main.css" rel="stylesheet" type="text/css" />
|
||
<style type="text/css">
|
||
.style1
|
||
{
|
||
white-space: nowrap;
|
||
font-family: 'Courier New', monospace;
|
||
height: 25px;
|
||
}
|
||
</style>
|
||
</head>
|
||
<body>
|
||
|
||
<p>
|
||
<span class="heading1">Introduction to External Tools</span></p>
|
||
<p>
|
||
External Tools can help you get things done that can't be done in
|
||
mRemoteNG.<br />
|
||
You can for example start a command prompt or launch your favorite FTP tool from
|
||
within mRemoteNG.<br />
|
||
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.</p>
|
||
<p>
|
||
But there's more!</p>
|
||
<p>
|
||
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".</p>
|
||
<p>
|
||
The external tools configuration is stored in %APPDATA%\mRemoteNG\extApps.xml</p>
|
||
|
||
<p>
|
||
<span class="heading1">Variables</span>
|
||
</p>
|
||
|
||
<p>
|
||
Variables and arguments can be used to tell the external tool what to do.</p>
|
||
<p>
|
||
This is the list of variables supported by mRemoteNG:
|
||
</p>
|
||
|
||
<ul>
|
||
<li>%NAME%</li>
|
||
<li>%HOSTNAME%</li>
|
||
<li>%PORT%</li>
|
||
<li>%USERNAME%</li>
|
||
<li>%PASSWORD%</li>
|
||
<li>%DOMAIN%</li>
|
||
<li>%DESCRIPTION%</li>
|
||
<li>%MACADDRESS%</li>
|
||
<li>%USERFIELD%</li>
|
||
</ul>
|
||
|
||
<p>
|
||
Variables always refer to the currently selected connection. Variable names are case-insensitive.
|
||
Variables can be used in both the Filename and Arguments fields.</p>
|
||
|
||
<p>
|
||
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.</p>
|
||
|
||
<p>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.</p>
|
||
|
||
<p>
|
||
<span class="heading1">Special Character Escaping</span>
|
||
</p>
|
||
|
||
<p>
|
||
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.</p>
|
||
<p>
|
||
<span class="heading2">Argument splitting escaping:</span></p>
|
||
|
||
<ul>
|
||
<li>Each quotation mark will be escaped by a backslash.</li>
|
||
<li>One or more backslashes (\) followed by a quotation mark ("):
|
||
<ul>
|
||
<li>Each backslash will be escaped by another backslash.</li>
|
||
<li>The quotation mark will be escaped by a backslash.</li>
|
||
If the connection's user field contains
|
||
"This" is a \"test\".<br/>
|
||
Then %USERFIELD% is replaced with
|
||
\"This\" is a \\\"test\\\".
|
||
</ul>
|
||
</li>
|
||
<li>A variable name followed by a quotation mark (for example, %USERFIELD%") with
|
||
a value ending in one or more backslashes:
|
||
<ul>
|
||
<li>Each backslash will be escaped by another backslash.</li>
|
||
<li>Example:</li>
|
||
If the connection's user field contains c:\Example\<br/>
|
||
Then "%USERFIELD%" is replaced with "c:\Example\\"
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
<p>
|
||
To disable
|
||
argument splitting escaping for a variable, precede its name with a minus (-)
|
||
sign. For example, %-USERFIELD%.</p>
|
||
<p>
|
||
<span class="heading2">Shell metacharacter escaping:</span></p>
|
||
|
||
<ul>
|
||
<li>The shell metacharacters are ( ) % ! ^ " < > & |</li>
|
||
<li>Each shell metacharacter will be escaped by a caret (^).</li>
|
||
</ul>
|
||
<p>
|
||
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.</p>
|
||
<p>
|
||
Only variables that have been expanded will be escaped. It is up to you to
|
||
escape the rest of the arguments.</p>
|
||
|
||
<p>
|
||
<span class="heading1">Variable Examples</span></p>
|
||
|
||
<table>
|
||
<tr><th>Arguments</th><th>User Field</th><th>Result</th></tr>
|
||
<tr>
|
||
<td class='monospace'>%USERFIELD%</td><td class='monospace'>"Example" Text</td><td class='monospace'>
|
||
\^"Example\^" Text</td>
|
||
</tr>
|
||
<tr>
|
||
<td class='monospace'>%-USERFIELD%</td><td class='monospace'>"Example" Text</td><td class='monospace'>
|
||
^"Example^" Text</td>
|
||
</tr>
|
||
<tr>
|
||
<td class='monospace'>%!USERFIELD%</td><td class='monospace'>"Example" Text</td><td class='monospace'>
|
||
"Example" Text</td>
|
||
</tr>
|
||
<tr>
|
||
<td class='style1'>^%USERFIELD^%</td><td class='style1'>"Example" Text</td>
|
||
<td class='style1'>%USERFIELD%</td>
|
||
</tr>
|
||
<tr>
|
||
<td class='monospace'>^^%USERFIELD^^%</td><td class='monospace'>"Example" Text</td><td class='monospace'>
|
||
^%USERFIELD^%</td>
|
||
</tr>
|
||
<tr>
|
||
<td class='monospace'>-d "%USERFIELD%"</td><td class='monospace'>c:\Example\</td><td class='monospace'>-d "c:\Example\\"</td>
|
||
</tr>
|
||
<tr>
|
||
<td class='monospace'>-d "%-USERFIELD%"</td><td class='monospace'>c:\Example\</td><td class='monospace'>-d "c:\Example\"</td>
|
||
</tr>
|
||
<tr>
|
||
<td class='monospace'>-d "%USERFIELD%"</td><td class='monospace'>Left
|
||
& Right</td><td class='monospace'>-d "Left ^& Right"</td>
|
||
</tr>
|
||
<tr>
|
||
<td class='monospace'>-d "%!USERFIELD%"</td><td class='monospace'>Left
|
||
& Right</td><td class='monospace'>-d "Left & Right"</td>
|
||
</tr>
|
||
<tr>
|
||
<td class='monospace'>%WINDIR%</td><td>N/A</td><td class='monospace'>c:\Windows\</td>
|
||
</tr>
|
||
<tr>
|
||
<td class='monospace'>\%WINDIR\%</td><td>N/A</td><td class='monospace'>c:\Windows\</td>
|
||
</tr>
|
||
<tr>
|
||
<td class='monospace'>\^%WINDIR\^%</td><td>N/A</td><td class='monospace'>
|
||
\%WINDIR\%</td>
|
||
</tr>
|
||
<tr>
|
||
<td class='monospace'>\\%WINDIR\\%</td><td>N/A</td><td class='monospace'>\\%WINDIR\\%</td>
|
||
</tr>
|
||
</table>
|
||
|
||
<p>
|
||
<span class="heading1">Example</span></p>
|
||
<p>
|
||
First of all, start the external tools editor. To do this, click Tools in the main menu and
|
||
select External Tools.<br />
|
||
You will see a screen like on the following screenshot.</p>
|
||
<p>
|
||
<img alt="" src="Screenshots/External Tools/01.png" /></p>
|
||
<p>
|
||
The fields below the list are greyed out because you haven't created an external tool
|
||
entry yet.<br />
|
||
To create one, right click the blank area in the list and select Add, as in the
|
||
screenshot below.</p>
|
||
<p>
|
||
<img alt="" src="Screenshots/External Tools/02.png" /></p>
|
||
<p>
|
||
This is what you'll get:</p>
|
||
<p>
|
||
<img alt="" src="Screenshots/External Tools/03.png" /></p>
|
||
<p>
|
||
So the three fields are now available and need to be filled.<br />
|
||
The Display Name is simply the name you will see when you want to launch that
|
||
tool, so give it a descriptive name.<br />
|
||
I named mine Traceroute as I will create a external tool that will start the
|
||
tracert command in the console.</p>
|
||
<p>
|
||
<img alt="" src="Screenshots/External Tools/04.png" /></p>
|
||
<p>
|
||
Ok, the next thing we'll need is a filename. This is the program that we
|
||
want to be executed.<br />
|
||
I simply type in cmd for a Windows cmd console.</p>
|
||
<p>
|
||
<img alt="" src="Screenshots/External Tools/05.png" /></p>
|
||
<p>
|
||
Now the fun part comes in—the arguments.<br />
|
||
The Windows cmd has a command line argument that tells the console to launch the
|
||
command followed by that argument and stay open.<br />
|
||
It's /K. (There's also /C, this is useful when you want the console to close
|
||
after the command was executed)<br />
|
||
In this case, I'll use /K as I want to look through the result when the command
|
||
completes.<br />
|
||
After that, I just type tracert %HostName%. This tells the console to do a
|
||
traceroute on the hostname of the currently selected Connection.</p>
|
||
<p>
|
||
<img alt="" src="Screenshots/External Tools/06.png" /></p>
|
||
<p>
|
||
Alright! That's all we'll need.<br />
|
||
Now right click one of you connections, click Tools, External Tools
|
||
and select Traceroute.</p>
|
||
<p>
|
||
<img alt="" src="Screenshots/External Tools/07.png" /></p>
|
||
<p>
|
||
Voil<69>! A console window will popup and execute your tracert command.</p>
|
||
<p>
|
||
<img alt="" src="Screenshots/External Tools/08.png" /></p>
|
||
|
||
</body>
|
||
</html> |