Remote Connections

Table of Contents
Purpose
Command Syntax
- Options
Field Descriptions
GreenArrow Proxy
Examples

Purpose

GreenArrow provides a command-line tool for viewing all open connections for delivering email via SMTP from the MTA. This tool can present a user-friendly command-line interface, or output its raw data as JSON.

Command Syntax

./greenarrow: Usage:
  greenarrow remote_connections [ARGUMENTS]

This tool is for viewing all open connections for delivering email via SMTP
from the MTA. It can present a user-friendly command-line interface, or output
its raw data as JSON.

Application Options:
      --verbose                     print the output in a more verbose format
      --json                        print the output as a json document
      --filter-remote-ip=           filter connections to those with this remote ip
      --filter-local-ip=            filter connections to those with this local ip
      --filter-connection-duration= filter connections to those that have been open at least this long
      --loop                        run continually every 500ms, clearing the terminal between executions

Help Options:
  -h, --help                        Show this help message

Options

--verbose	Instead of the default brief output on long lines, print a syntax that presents all of the same information on multiple lines.
--json	Print the data in the report as a JSON document. The JSON document is described below in the “Field Descriptions” section.
--filter-remote-ip=IP	Only include connections which are to the specified remote IP address. If the supplied value is only an IP address (e.g. `127.0.0.1`), connections using any port number will be matched. If the value includes a port number (e.g. `127.0.0.1:25`), only connections on exactly that port number will be matched.
--filter-local-ip	Only include connections which originate from the specified local IP address. If the supplied value is only an IP address (e.g. `127.0.0.1`), connections using any port number will be matched. If the value includes a port number (e.g. `127.0.0.1:25`), only connections on exactly that port number will be matched.
--filter-connection-duration=DURATION	Only include connections which have been connected for at least this long. Example usage: `greenarrow remote_connections --filter-connection-duration=4s`
--loop	Continuously loop and output the report, clearing the screen and refreshing the report every 500ms.

Field Descriptions

The table below describes the JSON format available when providing the --json argument to greenarrow remote_connections. The descriptions of these columns also apply to the user interface.

id
integer

An identifier associated with this connection. Each time the GreenArrow MTA is restarted, this value will be reset to 1 and increment thereafter with each connection.

state
string

The current state of this connection.

Possible values include:

connecting	The connection to the remote server is being attempted.
connecting_to_proxy	The Proxy Protocol is being used. This connection is currently connecting to the proxy server.
connecting_from_proxy	The Proxy Protocol is being used. This connection is currently waiting for the proxy server to connect to the remote SMTP server.
establishing_smtps	We are attempting to begin TLS over SMTPS (due to a remote server port number of 465).
sending	The connection has been established and the SMTP conversation is now proceeding.
saved_for_reuse	This connection is not currently in use and is eligible for reuse.
closing	We are in the process of closing this connection.

current_smtp_command
string

The SMTP command (if any) that is currently being executed. This value will be blank if no SMTP command is in progress.

Possible values include:

EHLO	The “EHLO” SMTP command is being transmitted or we are waiting for a response to it.
STARTTLS	The “STARTTLS” SMTP command is being transmitted or we are waiting for a response to it, including the negotiation of the TLS connection.
AUTH	The “AUTH” SMTP command is being transmitted or we are waiting for a response to it.
MAIL FROM	The “MAIL FROM” SMTP command is being transmitted or we are waiting for a response to it.
RCPT TO	The “RCPT TO” SMTP command is being transmitted or we are waiting for a response to it.
DATA	The “DATA” SMTP command is being transmitted or we are waiting for a response to it.
sending message (reading)	The message file is being read from disk.
sending message (sending)	The message is being transmitted to the remote server. This includes the final “dot” which signals the end of the message.
sending message (waiting)	The message has been transmitted to the remote server and we are waiting for the server to acknowledge it.
QUIT	The “QUIT” SMTP command is being transmitted or we are waiting for a response to it.

current_smtp_command_duration_ms
integer

The time (in milliseconds) that the current SMTP command has been in progress. This will always be 0 if current_smtp_command is blank.

start_time
datetime string

The time this connection was first opened.

Example: 2021-01-18T07:56:50.633453562-06:00

proxy_ip
string

The IP address of the proxy server, if the session is being proxied.

In the Regular Output and Verbose Output reports, the proxy_ip, proxy_port, and proxy_outgoing_ip values are presented as proxy_ip:proxy_port as proxy_outgoing_ip (e.g. 10.0.0.10:3030 as 123.234.123.5).

proxy_port
integer

The port number of the proxy server, if the session is being proxied.

proxy_outgoing_ip
string

The IP address on the proxy server being used to connect to the remote SMTP server, if the session is being proxied.

greenarrow_proxy_id
string

The name of the greenarrow_proxy used for this connection.

greenarrow_proxy_hostpair
string

The hostname:port pair of the greenarrow_proxy used for this connection.

local_ip
string

The local IP address from which this connection originated.

If this connection is being proxied then this will be the local IP address which was used to connect to the proxy.

local_port
integer

The outgoing port number from which this connection originated.

remote_ip
string

The destination IP address to which this connection is connected.

If this connection is being proxied then this will be the IP address of the remote SMTP server.

remote_port
integer

The destination port number to which this connection is connected.

deliveries_done
integer

The number of deliveries that have been completed using this connection.

deliveries_max
integer

The maximum number of deliveries that will be attempted using this connection. See the reuse_connections_max_messages configuration directive to increase this value.

conn_expires_remaining
integer

The number of seconds until this connection will expire. To determine if this value is meaningful, first check to see if state is equal to saved_for_reuse.

If this value is meaningful, the connection is not being used and may expire due to reuse_connections_timeout.

initial_domain
string

The first recipient domain that caused this connection to be opened.

most_recent_domain
string

The most recent recipient domain to have a delivery attempt using this connection.

mx_hostname
string

The MX hostname that was used to resolve remote_ip for this connection.

throttle_group_key
string

The key by which connections are grouped for purposes of throttling. See our documentation on Throttling for more information.

The forms ip1234pd456, ip1234tt456, and t1234 (described below) may be used as identifiers in the GreenArrow Engine user interface. This is done by appending them to the throttle path like so:

https://YOURHOSTNAME/ga/eui/virtual_mta/eng_throttles/ip1234pd456

The value will be in one of the forms listed below.

relay1234	The destination is a relay server with ID 1234.
ip1234pd456	Email is being deliveried through an IP address with ID 1234. The throttling rule being used has ID 456 and is defined on the IP address.
ip1234tt456	Email is being deliveried through an IP address with ID 1234. The throttling rule being used has ID 456 and is defined on the throttling template.
t1234	The internal throttle ID used for this group is 1234.
1234,greenarrowemail.com	Email is being deliveried through an IP address with ID 1234. The recipient domain `greenarrowemail.com` is not in any rule and the “Default Throttling Rule” has been applied.

throttle_group_maxconn
integer

The maximum number of connections that can be opened for this throttle_group_key. This value is affected by the result of any dynamic delivery rules.

outmtaid
string

The outgoing VirtualMTA ID used to establish this connection. This will match the ID within the throttle_group_key.

GreenArrow Proxy

Connections being held open in GreenArrow Proxy due to reuse_connections (but not currently being used by any GreenArrow instance) will not show up in the Remote Connections on any GreenArrow instance.

Examples

Regular Output

                                                     current smtp                                                                                    connected      messages                                       throttle group
    id                 state                     command /   time  tls                              proxy        local ip:port ->    remote ip:port       time    sent / max  timeout   mtaid                       key / maxconn  mx hostname             initial domain          most recent domain
------  --------------------  -----------------------------------  ---  ---------------------------------  ----------------------------------------  ---------  ------------  -------  ------  ----------------------------------  ----------------------  ----------------------  ----------------------
    21       saved_for_reuse                           - /          no  64.21.76.250:3030 as 64.21.76.251       10.0.0.1:39729 ->    64.21.76.32:26         2s       1 /   5      30s       2  2,discardallmail.drh.net /     100  discardallmail.drh.net  discardallmail.drh.net  discardallmail.drh.net
    22               sending      sending data (waiting) / 0.214s  yes                                  -    64.21.76.43:47841 -> 173.194.206.27:25         2s       0 /   5   active       2                       t24 /       1  aspmx.l.google.com.     greenarrowemail.com     greenarrowemail.com

open connections: 2
- delivery in progress: 1
- waiting for possible reuse: 1

Verbose Output (--verbose)

CONNECTION #17
Connection State:       saved_for_reuse
Connection Time:        2021-02-08 14:01:37.317711593 -0600 CST
Current SMTP Command:   -
TLS Active:             no
Proxy IP:               64.21.76.43:3030 as 64.21.76.44
Local IP:               10.0.0.1
Remote IP:              64.21.76.32
Deliveries Completed:   1 / 5 (28 secs until close)
VirtualMTA ID:          2
Throttle Group Key:     2,discardallmail.drh.net
Throttle Group Maxconn: 100
MX Hostname:            discardallmail.drh.net
Initial Domain:         discardallmail.drh.net
Most Recent Domain:     discardallmail.drh.net

CONNECTION #18
Connection State:       sending
Connection Time:        2021-02-08 14:01:42.402560469 -0600 CST
Current SMTP Command:   sending message (sending) (0.140s)
TLS Active:             yes
Proxy IP:               -
Local IP:               64.21.76.43
Remote IP:              173.194.206.27
Deliveries Completed:   0 / 5 (active)
VirtualMTA ID:          2
Throttle Group Key:     t24
Throttle Group Maxconn: 1
MX Hostname:            aspmx.l.google.com.
Initial Domain:         greenarrowemail.com
Most Recent Domain:     greenarrowemail.com

open connections: 2
- delivery in progress: 1
- waiting for possible reuse: 1

JSON Output (--json)

{
    "remote_connections": [
        {
            "id": 17,
            "state": "sending",
            "start_time": "2021-02-08T14:01:37.317711593-06:00",
            "proxy_ip": "64.21.76.43",
            "proxy_port": 3030,
            "proxy_outgoing_ip": "64.21.76.44",
            "local_ip": "10.0.0.1",
            "local_port": 40786,
            "remote_ip": "64.21.76.32",
            "remote_port": 26,
            "deliveries_done": 1,
            "deliveries_max": 5,
            "conn_expires_remaining": 0,
            "initial_domain": "discardallmail.drh.net",
            "most_recent_domain": "discardallmail.drh.net",
            "mx_hostname": "discardallmail.drh.net",
            "throttle_group_key": "2,discardallmail.drh.net",
            "throttle_group_maxconn": 100,
            "outmtaid": "2",
            "tls_active": false,
            "current_smtp_command_duration_ms": 1566,
            "current_smtp_command": "sending message (sending)"
        },
        {
            "id": 18,
            "state": "sending",
            "start_time": "2021-02-08T14:01:42.402560469-06:00",
            "proxy_ip": "",
            "proxy_port": 0,
            "proxy_outgoing_ip": "",
            "local_ip": "64.21.76.43",
            "local_port": 58829,
            "remote_ip": "173.194.206.27",
            "remote_port": 25,
            "deliveries_done": 1,
            "deliveries_max": 5,
            "conn_expires_remaining": 0,
            "initial_domain": "greenarrowemail.com",
            "most_recent_domain": "greenarrowemail.com",
            "mx_hostname": "aspmx.l.google.com.",
            "throttle_group_key": "t24",
            "throttle_group_maxconn": 1,
            "outmtaid": "2",
            "tls_active": true,
            "current_smtp_command_duration_ms": 1650,
            "current_smtp_command": "sending message (sending)"
        }
    ],
    "connections_saved_for_reuse": 0,
    "connections_delivery_in_progress": 2
}