MIMIC Server Proxy Protocol Module Guide

Overview

The MIMIC Server Proxy (PROXY) Protocol Module is an optional facility that enables simulating any number of existing UDP- or TCP-based servers. The module acts as a reverse proxy for any number of existing services for a specific MIMIC agent. Thus, a MIMIC agent can simulate any existing UDP- or TCP-based service. The PROXY module in effect multiplies an existing service by the number of agents that run it.

Installation

Server Proxy (PROXY) support is made available in MIMIC as an optional dynamically loadable module. Starting with MIMIC 10.00, you can use the Protocol Wizard to install the PROXY module (select Server Simulator). If you prefer to enable PROXY by hand, you need to do the following:

Use File->Terminate to stop the any running MIMIC daemon.
Copy the PROXY library (proxy.dll on Windows, proxy.so on Unix) from "bin/dynamic/optional" to "bin/dynamic" in the install directory.
Install the license keys as detailed in the instructions e-mailed to you.
Restart MIMIC. You should see the following type of message in the MIMICLog that confirms that the PROXY module was properly loaded :
```
INFO  - PROXY : Loaded protocol from < path-to-DLL >
INFO  - PROXY v10.00 : Individual license #2345
```

Once PROXY is loaded, any agent instance configured to support the PROXY protocol will be able to act as a reverse proxy to an existing server.

Using PROXY from MIMICView

If the PROXY module is enabled, then Agent->Add, Agent->Configure and Agent->Paste dialogs will display PROXY as an additional checkbox in the Advanced pane along with the SNMP protocols. On selecting the checkbox a new PROXY pane will appear.

This PROXY configuration pane lets the user configure the parameters for a PROXY retrieval:

Port
This mandatory parameter specifies the port number at which the service can be accessed for this agent. All other configurables on the PROXY pane apply to this port only. MIMICShell commands can be used to add and configure additional PROXY ports on an agent.
Target
This mandatory parameter specifies the comma-separated target server IP address and port. The IP address can be input either as "dot-value" notation (e.g., 192.9.200.1), or as a hostname (e.g., gambit), or fully qualified domainname (e.g., gambit.gambitcomm.com) provided that it can be resolved to an address (via /etc/hosts, Yellow Pages or DNS). The port is the numeric target server port. For example:
- a standard Telnet server at address 192.9.200.1 would be specified as 192.9.200.1,23
- a standard SSH server at address 192.9.200.2 would be specified as 192.9.200.2,22
- a standard TFTP server at address 192.9.200.3 would be specified as 192.9.200.3,69
- a standard HTTP server at address 192.9.200.4 would be specified as 192.9.200.4,80
Transport
This optional parameter specifies the transport protocol for PROXY ports on the agent. The transport protocol must be either "TCP" or "UDP". If left blank, TCP is assumed.
Configure the Transport parameter to TCP if you intend to proxy TCP-based protocols such as TELNET, SSH or DNS. Configure the Transport parameter to UDP if you intend to proxy UDP-based procotols such as DNS.
The configured transport protocol applies to all PROXY ports on the agent: the PROXY ports on the agent must be all TCP ports or all UDP ports, a mix of TCP and UDP PROXY ports cannot be configured on a single agent.
Maximum Connections
For TCP PROXY ports, this optional integer parameter specifies the maximum number of simultaneous client connections that may be opened on the port. Additional connections beyond this limit will be refused.
For UDP PROXY ports, this parameter specifies the maximum number of UDP client requests that can be served simultaneously by a single port on the agent. Additional simultaneous client requests beyond this limit can cause responses to be dropped to the requesting client or to other clients using the port.
This parameter must be configured to a positive integer value. If left blank, it defaults to 10.
TCP_NODELAY
This optional integer parameter specifies whether TCP_NODELAY (Nagel buffering) is applied to TCP connections to the target server. Legal values are 0 for no and 1 for yes.
Disconnect Delay (msec)
Delay in milliseconds between client or target server disconnect and PROXY connection close. This configuration is used to address issues with certain TCP protocols, and can affect PROXY connection performance. Do not specify unless instructed to do so by Gambit Support.
Pre-Connect Script
File name of PROXY pre-connect action script for port. If set, the specified action script is called after each client connection to the proxy port, before the target server connection is established. The action script is called with the following global variables as input:
- gCurrentAgent - Agent number
- gProxyPort - PROXY port number
- gFromAddres - Client IP address
- gFromPort - Client port number
The pre-connect action script may be used to reconfigure PROXY connection configurations, for example, to reset the target server address or the TCP_NODELAY setting on the target server connection.
If the pre-connect action script is not specified, the PROXY port configurations are used to configure the connection.
Client-to-Server Script
File name of an optional PROXY client-to-server data action script. Do not specify unless instructed to do so by Gambit support.
Server-to-Client Script
File name of an optional PROXY server-to-client data action script. Do not specify unless instructed to do so by Gambit support.

If the mandatory parameters are supplied, the agent will automatically serve as a reverse proxy to the target server upon starting.

Using PROXY from MIMICShell

A few new commands and some enhanced old commands can be used from the MIMICShell to use the PROXY functionality. Here is a synopsis:

mimic protocol msg PROXY get args

This command lets the user gather the self-defining list of arguments required and their particulars. The parameters are detailed above. A sample exchange for this command would be:

  mimicsh> mimic protocol msg PROXY get args
  {{portno} {Port} {integer} {} {mandatory} {}}
  {{target} {Target} {string} {} {mandatory} {}}
  {{transport} {Transport (TCP or UDP)} {string} {} {optional} {TCP}}
  {{max_connects} {Maximum Connections} {integer} {} {optional} {100}}
  {{TCP_NODELAY} {TCP_NODELAY} {integer} {} {optional} {1}}
  {{disconnect_delay} {Disconnect Delay (msec)} {integer} {} {optional} {0}}
  {{pre_connect} {Pre-connect Script} {string} {} {optional} {}}
  {{client_to_server} {Client-to-Server Script} {string} {} {optional} {}}
  {{server_to_client} {Server-to-Client Script} {string} {} {optional} {}}

mimic agent get protocol
This command lets the user look at the protocols currently configured on the agent. A sample exchange for this command would be:
```
  mimicsh> mimic agent get protocol
  snmpv1,snmpv2c
```
mimic agent set protocol
This command lets the user change the protocol setting for an agent. A sample exchange for this command would be:
```
  mimicsh> mimic agent set protocol snmpv1,PROXY
  mimicsh> mimic agent get protocol
  snmpv1,snmpv2c,PROXY
```
mimic agent protocol msg PROXY state
This command lets the user query the state of the PROXY module. This is particularly useful at agent startup time to wait for PROXY startup. A sample usage for this command would be:
```
	if { [mimic agent protocol msg PROXY state] != "up" } {
		# do necessary to wait until PROXY server is up
	}
```

mimic agent protocol msg PROXY get config

This command lets the user get the current argument settings. A sample exchange for this command would be:

  mimicsh> mimic agent protocol msg PROXY get config
  {portno=9922} {target=127.0.0.1,9923} {transport=TCP} {max_connects=100} {TCP_NODELAY=1}
  {disconnect_delay=0} {pre_connect=} {client_to_server=} {server_to_client=}

mimic agent protocol msg PROXY set config config
This command lets the user change the current argument settings of all PROXY sessions for an agent. A sample exchange for this command would be:
```
  mimicsh> mimic agent protocol msg PROXY set config TCP_NODELAY=1
```

mimic agent protocol msg PROXY get trace
mimic agent protocol msg PROXY set trace [0 or 1]

This command lets the user change the PROXY tracing configuration for an agent. A sample exchange would be:

  mimicsh> mimic agent assign 9

  mimicsh> mimic agent protocol msg PROXY get trace
  0
  mimicsh>  mimic agent protocol msg PROXY set trace 1

  mimicsh> mimic agent protocol msg PROXY get trace
  1

and the log would show:

INFO  - PROXY [AGT=9]: PROXY server started
INFO  - agent 9 trace enabled for PROXY
INFO  - PROXY [AGT=9]: socket 4: connect at 10.0.0.9,2323 from 10.0.0.9,43292
INFO  - PROXY [AGT=9]: port 2323: socket 5: receiving 3 data bytes from server at 10.0.0.9,60752 in pkt #1
INFO  -    FF FD 25                                ..%
INFO  - PROXY [AGT=9]: port 2323: socket 4: sending 3 data bytes to client at 10.0.0.9,2323 in pkt #2
INFO  -    FF FD 25                                ..%
...

mimic protocol msg PROXY get stats_hdr
mimic agent protocol msg PROXY get statistics
Returns PROXY statistics information:
- a list of statistic headers, and
- current statistics values for the specified proxy.
In order, the statistic values are:
- Number of connections established
- Number of connect errors
- Number of disconnects
- Number of packets from client to server
- Number of bytes from client to server
- Number of packets from server to client
- Number of bytes from server to client
A sample exchange for these commands would be:
```
  mimicsh> mimic protocol msg PROXY get stats_hdr
  {{connect} {connect}} {{connectError} {connectError}} {{disconnect} {disconnect}}
  {{pktsTo} {pktsTo}} {{bytesTo} {bytesTo}} {{pktsFrom} {pktsFrom}} {{bytesFrom} {bytesFrom}}

  mimicsh> mimic agent protocol msg PROXY get statistics
  1 0 0 24 202 26 1009
```
mimic agent protocol msg PROXY port add portno,target
This command adds a proxy port with port number portno to the proxy server. This proxy port serves as a proxy to a target server at address target. target should be of the form IP adress,port number. A sample exchange for this command would be:
```
  mimicsh> mimic agent protocol msg proxy port add 16001,192.9.200.71,23
```
mimic agent protocol msg PROXY port remove portno
This command removes a proxy port with port number portno. A sample exchange for this command would be:
```
  mimicsh> mimic agent protocol msg proxy port remove 16001
```

mimic agent protocol msg PROXY port list

This command returns a list of port numbers for configured proxy ports. A sample exchange for this command would be:

  mimicsh> mimic agent protocol msg proxy port list
  {9923}
  mimicsh> mimic agent protocol msg proxy port add 16001,192.9.200.71,23
  mimicsh> mimic agent protocol msg proxy port add 16002,192.9.200.71,23
  mimicsh> mimic agent protocol msg proxy port list
  {9923 16001 16002}

mimic agent protocol msg PROXY port start portno
mimic agent protocol msg PROXY port stop portno
mimic agent protocol msg PROXY port is_started portno

These commands start/stop and check started status of a proxy port with port number portno. A sample exchange for this command would be:

  mimicsh> mimic agent protocol msg proxy port is_started 16001
  0
  mimicsh> mimic agent protocol msg proxy port start 16001
  mimicsh> mimic agent protocol msg proxy port is_started 16001
  1
  mimicsh> mimic agent protocol msg proxy port stop 16001
  mimicsh> mimic agent protocol msg proxy port is_started 16001
  0

mimic agent protocol msg PROXY port set config portno config=value
mimic agent protocol msg PROXY port get config portno config
These commands set/get the configurable config for the port with port number portno. config can be one of
- target
  target server address - IP address, portno
- max_connects
  maximum number of proxy connections on port - number > 0. For UDP servers, this is the maximum number of simultaneous requests it will handle before some are possibly discarded.
- TCP_NODELAY
  set TCP_NODELAY on proxy connections - 0 (false) or 1 (true)
- disconnect_delay
  PROXY connection disconnect delay in milliseconds
- pre_connect
  
  file name of PROXY pre-connect action script
- client_to_server
  
  file name of PROXY client-to-server action script
- server_to_client
  
  file name of PROXY server-to-client action script
A sample exchange for this command would be:
```
  mimicsh> mimic agent protocol msg proxy port get config 16000 target
  192.9.200.71,23
  mimicsh> mimic agent protocol msg proxy port set config 16000 target=192.9.200.27,23
  mimicsh> mimic agent protocol msg proxy port get config 16000 target
  192.9.200.27,23
```

Compatibility

Click here for the compatibility document. If you get an error, you need to download the optional update package with the Update Wizard.

MIMIC^® Online Documentation