GreenArrow Proxy

• Table of Contents
• Overview
• Configuration
  • Example Configuration
  • Updating GreenArrow Proxy Configuration at Runtime
• Running GreenArrow Proxy
  • Install the greenarrow_proxy executable
  • Write a greenarrow_proxy configuration file
  • Run greenarrow_proxy
  • Review Systemd status and logging
  • Reload configuration
• License Key
• GreenArrow Proxy Data Storage
• Logging

Overview

GreenArrow Proxy is the name of a service that provides:

• Cooperative throttling between multiple instances of GreenArrow.
• SMTP connection proxying that allows MTAs to make outgoing connections from IP Addresses on the GreenArrow Proxy server (similar to using our support for HAProxy).
• Sharing (between multiple GreenArrow instances) connections that are held open using reuse_connections.

The GreenArrow Proxy executable runs external to your GreenArrow instances (for example, on a separate container or VM).

Configuration

GreenArrow Proxy is configured by its own configuration file. The path to this configuration file is specified using the --config-filename command line directive when you launch greenarrow_proxy. This configuration file accepts the following directives:

$ cat /dev/urandom | base64 --wrap=32 | head -1
egPuosFs4crMEfHESlS7tNW4Ebxnj1Dx

Example Configuration

Here’s what greenarrow_proxy.conf might look like:

listen "0.0.0.0:807"
allow_from 127.0.0.0/24, 10.0.0.0/8
auth_shared_secret "00000000000000000000000000000000"
log_verbose no

Updating GreenArrow Proxy Configuration at Runtime

If you have GreenArrow Proxy running, and need to change its configuration, you can do this without restarting the greenarrow_proxy process:

1. Update the greenarrow_proxy.conf configuration file.
2. Send the greenarrow_proxy process SIGHUP.

If you use Systemd as described below, the SIGHUP can be sent to the greenarrow_proxy in this way:

systemctl reload greenarrow_proxy.service

Running GreenArrow Proxy

GreenArrow Proxy is flexible on how it fits into your architecture.

The greenarrow_proxy executable accepts a path to its configuration file with the --config-filename parameter. It does not write any local files, and all of its logging is to STDOUT and STDERR.

Below, we’ll demonstrate an example installation, using Systemd to run the service.

Install the greenarrow_proxy executable

The only file you need from GreenArrow to get started is /var/hvmail/bin/greenarrow_proxy. To obtain this, you can either copy it from an existing GreenArrow installation, or install GreenArrow from packages (see the Installation Guide for information on how to do this).

It’s critical that the greenarrow_proxy executable be from a GreenArrow version greater-than-or-equal-to the GreenArrow version of the instances that will be connecting to it.

The greenarrow_proxy executable does not need to be at any particular path.

For this example, install it as:

/opt/greenarrow/greenarrow_proxy

Write a greenarrow_proxy configuration file

Create a greenarrow_proxy.conf configuration file (as described above) to which you can point greenarrow_proxy using the --config-filename parameter.

For this example, write the configuration as:

/opt/greenarrow/greenarrow_proxy.conf

Run greenarrow_proxy

The greenarrow_proxy executable accepts a path to its configuration file with the --config-filename parameter. It does not write any local files, and all of its logging is to STDOUT and STDERR.

Given this, it’s up to you how to arrange it to be run. In the example below, we’ve chosen to run it as a Systemd service.

Here’s an example Systemd service file that will run greenarrow_proxy:

[Unit]
Description=GreenArrow Proxy
Documentation=https://www.greenarrowemail.com/docs/
After=network.target iptables.service firewalld.service firewalld.service

[Service]
Type=simple
RemainAfterExit=no
WorkingDirectory=/opt/greenarrow
ExecStart=/opt/greenarrow/greenarrow_proxy --config-filename=/opt/greenarrow/greenarrow_proxy.conf
KillMode=control-group
ExecReload=kill -HUP $MAINPID
Restart=always
OOMPolicy=continue
StandardInput=null
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

Write the above Systemd unit file as:

/opt/greenarrow/greenarrow_proxy.service

Then symlink the unit file to make it available to Systemd:

ln -s /opt/greenarrow/greenarrow_proxy.service /etc/systemd/system/greenarrow_proxy.service

Now reload Systemd, enable the service at boot-up, and start it now.

systemctl daemon-reload
systemctl enable greenarrow_proxy.service
systemctl start greenarrow_proxy.service

Review Systemd status and logging

With this Systemd configuration, greenarrow_proxy is logging to the Systemd journal. You can now review those logs to see that greenarrow_proxy is up and running.

See the status of the greenarrow_proxy.service Systemd service:

systemctl status greenarrow_proxy

See the last 5 minutes of logs:

journalctl -u greenarrow_proxy.service --since '5min ago'

“Tail” the logs to see its current output:

journalctl -u greenarrow_proxy.service --follow

Reload configuration

Systemd integration provides a simple command for telling greenarrow_proxy to reload its config file:

systemctl reload greenarrow_proxy.service

After reloading configuration, you can check the recent logs to check for any problem loading the configuration:

journalctl -u greenarrow_proxy --since '15sec ago'

If there is a problem loading the new configuration, greenarrow_proxy will continue to run the previous configuration until it is restarted (or until it is told to reload a new, valid configuration).

License Key

At this time, no license key is required to run GreenArrow Proxy – however this may change in the future for future versions of GreenArrow.

GreenArrow Proxy Data Storage

GreenArrow Proxy does not persist any data. The only storage requirements are for the software itself and any logging of its output you might wish to capture.

Logging

GreenArrow Proxy, among other “chatter” that might appear in its log, will log the following messages:

listener(0.0.0.0:807): open_connections=965
throttle: manager(0543b19c): throttles=1758 sessions=3 backlog(ram=532 bounce=0 disk=1093) forward(in=0/16 out=0/16 buf=0) back(in=0/16 out=0/16 buf=0)
throttle: session(server-a): timeconnected=1h5m19s ping=0.250ms(0s ago) backlog(ram=0 bounce=0 disk=0) forward(in=0/16 out=0/16 buf=0) back(in=0/16 out=0/16 buf=0)
throttle: session(server-b): timeconnected=1h5m19s ping=0.379ms(0s ago) backlog(ram=0 bounce=0 disk=0) forward(in=0/16 out=0/16 buf=0) back(in=0/16 out=0/16 buf=0)
throttle: session(server-c): timeconnected=1h5m19s ping=5.430ms(0s ago) backlog(ram=532 bounce=0 disk=1093) forward(in=0/16 out=0/16 buf=0) back(in=0/16 out=0/16 buf=0)
direct_remote_smtp: connections=613(active=610 cached=3)

Here’s a description of what’s included above (wrapped below for easier reading):

listener(0.0.0.0:807): open_connections=965

throttle: manager(0543b19c): throttles=1758 sessions=3
  backlog(ram=532 bounce=0 disk=1093)
  forward(in=0/16 out=0/16 buf=0) back(in=0/16 out=0/16 buf=0)

throttle: session(server-a): timeconnected=1h5m19s ping=0.250ms(0s ago)
  backlog(ram=0 bounce=0 disk=0)
  forward(in=0/16 out=0/16 buf=0) back(in=0/16 out=0/16 buf=0)

direct_remote_smtp: connections=613(active=610 cached=3)