GreenArrow Email Software Documentation

Remote Connections

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.

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

local_ip

string

The outgoing IP address from which this connection originated.

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.

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.

Examples

Regular Output

                                                     current smtp                                                 connected      messages                                       throttle group
    id                 state                     command /   time  tls        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.43: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
Local IP:               64.21.76.43
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
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",
            "local_ip": "64.21.76.43",
            "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",
            "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
}


Copyright © 2012–2021 GreenArrow Email