The query exchange debugger protocol allows you to create monitoring programs that communicate in real time to operating lanes and servers to extract support and status information. This means you can
- Remotely poll a single lane for support information
- Write a web page to scan numerous machines for support information, creating site support dashboards
- Invoke remote automated support tools. These tools use exactly the same QeDebug API but in a automated manner. For example, if you start the support tools for "performance issues" on a computer, it will use the QeDebug API to try and isolate where and what is causing the performance slowdown.
Various Fieldpine programs contain support for the QeDebug protocol. Each program elects which command packets it will respond too. In order to use the protocol, you only need to direct a command packet to the program you wish to respond.
Essentially, each program will respond to HTTP request to execute commands packets and return a standard response. The request/response is an API level call, and you simply provide wrappers around the calls in order format the response as you require.
If you are having trouble getting these commands to work, be sure to checkout Security Implications below
Manual, Single Command
One very easy way to use QeDebug protocol is simply to open a web browser and enter a URL containing your request. The remote machine will respond with the information requested.
Remote programs (called agents in QeDebug lingo) can usually return the information in different formats depending on your need. For manual use such as this, the "M" format (named XML) is usually the easiest to read. However, you can also have numeric XML, named JSON or numeric JSON.
The QeDebug command 140,202 will return a list of modules in an address space. Essentially a list of DLLs being used by a program. Open a browser and try the following URLs. Each request is returning the same information, just in different formats. Experiment with different command numbers to see the various responses
http://127.0.0.1:8095/gnap/M/buck?3=fieldpineinternal.fdl911.fetch&100=140202
<DATS>
<f100>140202</f100>
<f110>3620</f110>
<MODU>
<f110>1</f110>
<GlobalUsage>65535</GlobalUsage>
<ProcessUseage>65535</ProcessUseage>
<BaseAddress>4194304</BaseAddress>
<BaseSize>2158592</BaseSize>
<Name>fposwin.exe</Name>
<Path>C:\LiveDev\fposstart\fposwin\Debug\fposwin.exe</Path>
<Version>1.7-5.25 (10007:50019)</Version>
<MemXor>161279847</MemXor>
<MemXorY>128</MemXorY>
</MODU>
<MODU>
<f110>1</f110>
<GlobalUsage>65535</GlobalUsage>
<ProcessUseage>65535</ProcessUseage>
<BaseAddress>2089811968</BaseAddress>
<BaseSize>716800</BaseSize>
<Name>ntdll.dll</Name>
<Path>C:\WINDOWS\system32\ntdll.dll</Path>
<Version>5.1-2600.5512 (50001:a281588)</Version>
<MemXor>-1243016746</MemXor>
<MemXorY>128</MemXorY>
</MODU>
...
http://127.0.0.1:8095/gnap/buck?3=fieldpineinternal.fdl911.fetch&100=140202
<DATS>
<f100>140202</f100>
<f110>3620</f110>
<MODU>
<f110>1</f110>
<f111>65535</f111>
<f112>65535</f112>
<f113>4194304</f113>
<f114>2158592</f114>
<f115>fposwin.exe</f115>
<f116>C:\LiveDev\fposstart\fposwin\Debug\fposwin.exe</f116>
<f117>1.7-5.25 (10007:50019)</f117>
<f120>161279847</f120>
<f121>128</f121>
</MODU>
<MODU>
<f110>1</f110>
<f111>65535</f111>
<f112>65535</f112>
<f113>2089811968</f113>
<f114>716800</f114>
<f115>ntdll.dll</f115>
<f116>C:\WINDOWS\system32\ntdll.dll</f116>
<f117>5.1-2600.5512 (50001:a281588)</f117>
<f120>-1129262518</f120>
<f121>128</f121>
</MODU>
...
http://127.0.0.1:8095/gnap/J/buck?3=fieldpineinternal.fdl911.fetch&100=140202
{ "RootType":"DATS",
"f100":140202,
"f110":3620,
"MODU":[
{
"f110":1,
"GlobalUsage":65535,
"ProcessUseage":65535,
"BaseAddress":4194304,
"BaseSize":2158592,
"Name":"fposwin.exe",
"Path":"C:\\LiveDev\\fposstart\\fposwin\\Debug\\fposwin.exe",
"Version":"1.7-5.25 (10007:50019)",
"MemXor":161279847,
"MemXorY":128
},{
"f110":1,
"GlobalUsage":65535,
"ProcessUseage":65535,
"BaseAddress":2089811968,
"BaseSize":716800,
"Name":"ntdll.dll",
"Path":"C:\\WINDOWS\\system32\\ntdll.dll",
"Version":"5.1-2600.5512 (50001:a281588)",
"MemXor":840570975,
"MemXorY":128}
...
http://127.0.0.1:8095/gnap/j/buck?3=fieldpineinternal.fdl911.fetch&100=140202
{ "RootType":"DATS",
"f100":140202,
"f110":3620,
"MODU":[
{
"f110":1,
"f111":65535,
"f112":65535,
"f113":4194304,
"f114":2158592,
"f115":"fposwin.exe",
"f116":"C:\\LiveDev\\fposstart\\fposwin\\Debug\\fposwin.exe",
"f117":"1.7-5.25 (10007:50019)",
"f120":161279847,
"f121":128
},{
"f110":1,
"f111":65535,
"f112":65535,
"f113":2089811968,
"f114":716800,
"f115":"ntdll.dll",
"f116":"C:\\WINDOWS\\system32\\ntdll.dll",
"f117":"5.1-2600.5512 (50001:a281588)",
"f120":956812896,
"f121":128
}
...
Retrieving Performance Counters
Several Agent programs will respond with performance counters detailing internal state such as number in calls and time to respond. To request all the performance counters issue the following command to your Gds Server.
http://127.0.0.1:7788/GNAP/M/buck?3=fieldpineinternal.fdl911.fetch&100=140203&120=15000 (for XML reply) http://127.0.0.1:7788/GNAP/J/buck?3=fieldpineinternal.fdl911.fetch&100=140203&120=15000 (for JSON reply)The response will be an ARAY of responses from different agents.
{
"DATS":[
{ // First response (empty) from WordsPb agent
"f100":140203,
"f110":3152, // Responding ProcessId
"f111":"WordsPb",
"f112":3792 // Responding ThreadId
},
{ // Second response from Files agent
"f100":140203,
"f110":3152,
"f111":"Files",
"f112":2704,
"GSTA":[ // A counter block
{
"Name":"FilesWebFetch",
"Count":74,
"Ticks":72590,
"MaxActive":6,
"CurActive":0,
"SlowestTicks":24312,
"SlowestTime":"2017|2|1|9|45|49||",
"ReturnState0":54,
"ReturnState1":20,
"ReturnState2":0,
"ReturnState3":0,
"ReturnState4":0,
"ReturnState5":0,
...
}
]}
]}
Scanning several machines with Wget, Curl
Wget is a command line tool to read web pages and store the output. Wget can be used to automatically poll serveral machines in a batch file and create outputs from each.
WGET -O StoreA_Status.xml http://192.168.23.47:8555/GNAP/M/buck?3=fieldpineinternal.fdl911.fetch&100=25000 WGET -O StoreB_Status.xml http://192.164.1.2:8555/GNAP/M/buck?3=fieldpineinternal.fdl911.fetch&100=25000 WGET -O StoreC_Status.xml http://192.172.128.202:8555/GNAP/M/buck?3=fieldpineinternal.fdl911.fetch&100=25000
Wget is a very powerful tool and has many options to read and process web pages. If you are going to use command files to read multiple machines we recommend reading the Wget documentation
Security Implications and QeDebug
Some QeDebug packets can return possibly senstive information, such as serial numbers or IP address and file names. While the QeDebug protocol is primarily (but not solely) a read only protocol the information is still should not be widely disclosed. Most agents will follow the following rules when accepting commands:
- If the command arrives via Shared memory (not discussed above, not an option for most) the agent will respond. Commands will only arrive via shared memory if another program on the same computer has already accepted the command.
- If the source IP address of a request is localhost, the command will typically be executed. This occurs where the requestor is on the same machine already.
- If the request arrives by TCP/UDP, the source address needs to be of the same internet class as the responding machine. This means that requests need to come from machines inside your network and random internet addresses will not be responded too. Refer to your network support for more exact details as some routers may convert external IP addresses to local addresses, rendering this ineffective.
- Agents will typically enable CORs support, although this can be disabled. Using CORs alone is not a reliable security control.
- Agents can typically have the security on QeDebug tightened to restrict access if needed. Refer to each agent documentation
- If the agent program initiated the QeDebug link, ie the Agent called a remote server, then all commands will be executed.