HTTP Server

GreenArrow Engine comes with an HTTP server to provide a web interface, and click and open tracking.

• Table of Contents
• Enabling and Starting the HTTP Server
• IP Addresses and Ports to Provide HTTP
• IP Addresses and Ports to Provide HTTPS
• Default TLS Configuration
• Automatic TLS Configuration
• Multiple TLS Certificates with Dedicated IPs
• Multiple TLS Certificates with Shared IPs
• Graceful Restarts
• URI Filtering
• Performance Tuning
• Advanced Configuration Changes
• Apache Server Status
• Passenger Status
• Processing clicks and opens behind a proxy server
• Troubleshooting

Enabling and Starting the HTTP Server

• To enable the HTTP server, set the /var/hvmail/control/httpd.enabled file to 1 or true:

  echo 1 > /var/hvmail/control/httpd.enabled
  

• After enabling the HTTP server, you can start it with:

  svc -u /service/hvmail-httpd
  

• To disable the HTTP server, set the /var/hvmail/control/httpd.enabled file to 0 or false:

  echo 0 > /var/hvmail/control/httpd.enabled
  

• After disabling the HTTP server, you can shut it down with:

  svc -d /service/hvmail-httpd
  

IP Addresses and Ports to Provide HTTP

If you’re using GreenArrow’s click and open tracking, then we recommend running GreenArrow’s HTTP server on the default port (port 80). This is because some spam filters and firewalls are more likely to score a message as spam, or block access to a URL if a non-default port is used.

• List the IP address and port combinations for the HTTP service to listen on, one per line, in the /var/hvmail/control/httpd.listen file. For example, a line can contain just a port number, such as 80 to configure GreenArrow Engine’s HTTP server to listen on that port for all IP addresses assigned to the server:

  echo 80 > /var/hvmail/control/httpd.listen
  

• A line can also contain an IP address and a port combination, such as 1.2.3.4:80:

  echo 1.2.3.4:80 > /var/hvmail/control/httpd.listen
  

• To apply these changes, run:

  svc -t /service/hvmail-httpd
  

IP Addresses and Ports to Provide HTTPS

• List the IP address and port combinations for the HTTPS service to listen on, one per line, in the /var/hvmail/control/httpd.ssl.listen file. This file is in the same format as the /var/hvmail/control/httpd.listen file, unless you’re using multiple TLS Virtual Hosts.

• To apply changes, run:

  svc -t /service/hvmail-httpd
  

Default TLS Configuration

The TLS Certificate Configuration doc describes how to configure the default TLS certificate and key.

Automatic TLS Configuration

See the TLS Certificate Configuration doc.

Multiple TLS Certificates with Dedicated IPs

You can configure different IP addresses to use different TLS certificates.

You can specify what ports or IP/port pairs the HTTPS server should listen on and optionally overwrite the default TLS certificate in /var/hvmail/control/httpd.ssl.listen. Here’s an example that uses the default TLS certificate on port 443, with the exception of three IP addresses, which each use a custom key, certificate and certificate chain:

443
10.0.0.1:443 key=/var/hvmail/control/custom_certificates/1.key crt=/var/hvmail/control/custom_certificates/1.crt crt_chain=/var/hvmail/control/custom_certificates/ca1.crt
10.0.0.2:443 key=/var/hvmail/control/custom_certificates/2.key crt=/var/hvmail/control/custom_certificates/2.crt crt_chain=/var/hvmail/control/custom_certificates/ca2.crt
10.0.0.3:443 key=/var/hvmail/control/custom_certificates/3.key crt=/var/hvmail/control/custom_certificates/3.crt crt_chain=/var/hvmail/control/custom_certificates/ca3.crt

To apply these changes, run:

svc -t /service/hvmail-httpd

Multiple TLS Certificates with Shared IPs

You can configure the same IP address to use multiple TLS certificates.

You can specify what ports or IP/port pairs the HTTPS server should listen on and optionally overwrite the default TLS certificate in /var/hvmail/control/httpd.ssl.listen. Here’s an example that uses the default TLS certificate on port 443, with the exception of an IP address which uses two custom certificates:

443
10.0.0.1:443 key=/var/hvmail/control/custom_certificates/1.key crt=/var/hvmail/control/custom_certificates/1.crt server_name=tls1.example.com
10.0.0.1:443 key=/var/hvmail/control/custom_certificates/2.key crt=/var/hvmail/control/custom_certificates/2.crt server_name=tls2.example.com

To apply these changes, run:

svc -t /service/hvmail-httpd

Graceful Restarts

To gracefully restart the web server, rather sending it a TERM signal with svc, run the following command:

/var/hvmail/bin/hvmail_update_httpd_config --graceful

URI Filtering

The following URI prefix needs to be publicly accessible in order for Engine to properly function:

• /click/
• /open/

If $CLICKTHROUGH_URL in /var/hvmail/control/simplemh-config ends with /click.php, then /click.php/ should also be included in this list. This was the default prior to GreenArrow Engine v4.1.232.

If you want to use the embeddable HTML campaign stats API then you should allow the access to the following URI prefixes:

• /greenarrowembed/assets/
• /greenarrowembed/stats_sends_view_drilldown.php
• /greenarrowembed/stats_sends_view_logs.php
• /gaeembed/assets/
• /gaeembed/stats_sends_view_drilldown.php
• /gaeembed/stats_sends_view_logs.php

The following URI prefixes need to be publicly accessible in order for Studio to properly function:

• /ga/open/
• /ga/click/
• /ga/unsubscribe/
• /ga/webviews/
• /ga/campaign_images/
• /ga/front/

Performance Tuning

The greenarrow.conf configuration file can be used to tune performance-related settings.

Advanced Configuration Changes

GreenArrow Engine uses the Apache HTTP Server. To customize this Apache installation’s configuration beyond the settings described above, place the configuration in one of the following files:

• Update the /var/hvmail/control/httpd.custom.conf file to make changes to the main Apache configuration.
• Update the /var/hvmail/control/httpd.ssl.custom.conf file to make change to the configuration of both GreenArrow’s default HTTPS Virtual Host, and any Virtual Hosts defined in /var/hvmail/control/httpd.ssl.listen.

To avoid creating conflicting configurations, please verify that your desired customizations are not configurable via some other mechanism, such as the configuration file before editing either of these advanced configuration files.

Apache Server Status

To view the status of Apache, navigate to the /greenarrowadmin/server-status path. This will require the credentials for GreenArrow Engine.

This screen can also be reached locally on the server at http://127.0.0.1/server-status-localhost.

Passenger Status

The web application server includes a command to check its status.

# passenger-status
Version : 6.0.4
Date    : 2020-03-04 06:11:30 -0600
Instance: YwAMfniA (Phusion_Passenger/6.0.4)

----------- General information -----------
Max pool size : 4
App groups    : 1
Processes     : 2
Requests in top-level queue : 0

----------- Application groups -----------
/var/hvmail/studio (production):
  App root: /var/hvmail/studio
  Requests in queue: 0
  * PID: 6763    Sessions: 0       Processed: 193     Uptime: 17h 38m 31s
    CPU: 0%      Memory  : 153M    Last used: 1h 36m
  * PID: 6784    Sessions: 0       Processed: 2       Uptime: 17h 38m 30s
    CPU: 0%      Memory  : 106M    Last used: 1h 32m

In this screen, we can see Processes that indicates how many application processes are available for serving web requests. If pass__min_instances is lower than pass__max_pool_size, this number will vary based upon the volume of traffic. If they are equal, they will stay steady at that value.

Processing clicks and opens behind a proxy server

When a click or open is recorded, it includes the IP address of the client. When GreenArrow is placed behind a proxy server, without further configuration, the recorded IP address would always be that of the proxy server.

To this end, we provide an option for specifying one or more trusted IP addresses. When a client is recognized to be from a trusted IP address, GreenArrow will attempt to use the X-Forwarded-For or X-Client-IP HTTP headers. If one of these headers are present, the click or open will be recorded using that IP and not that of the proxy server.

To configure this, append the trusted proxy IP addresses to the following files.

For Studio:

echo 1.2.3.4 >> /var/hvmail/control/studio.trusted_proxy_ips

For SimpleMH:

echo 1.2.3.4 >> /var/hvmail/control/opt.engine.trusted_proxy_ips

Troubleshooting

If the HTTP server fails to start, or otherwise acts incorrectly, then the first place to look at is the /var/hvmail/log/httpd/current log. Here’s an example command to monitor that log file’s output, and convert the timestamps into a readable format:

tail -F /var/hvmail/log/httpd/current | tai64nlocal

Press Ctrl-c when you’re finished viewing the file.

Apache’s log files, located in /var/hvmail/apache/logs/ can also be useful for debugging if you’re in a situation where the webserver starts but doesn’t behave as desired. That directory’s error_log file is the most likely to contain useful info. Additional information is logged to access_log for HTTP requests, and ssl_request_log for HTTPS requests.

Compare any recent changes to the above log file’s output. Hopefully that’s enough to identify a fix for the problem, but if not, review the following configuration files for issues related to the errors that are logged:

• /var/hvmail/control/httpd.custom.conf
• /var/hvmail/control/httpd.ssl.custom.conf
• /var/hvmail/control/httpd.listen
• /var/hvmail/control/httpd.ssl.listen

For example, if an error message is logged about a missing file, check if any of the above configuration files contain a reference to that missing file.

The HTTP server automatically recovers from some types of configuration errors once the configuration file is fixed. If it doesn’t automatically cover, then you can force it to restart, and re-read all configuration files by running:

svc -tu /service/hvmail-httpd