GreenArrow Email Software Documentation

GreenArrow Updates

We release updates to GreenArrow Engine and Studio periodically. You can see the currently available releases at any time by viewing the GreenArrow Engine Changelog and GreenArrow Studio Changelog.

Updates for Cloud Customers

We update the majority of our Cloud Customers about once a month. The updates typically occur in the first few business days of the month.

Updates For On-Premise Customers

On-Premise customers can either ask GreenArrow technical support to perform updates for them or perform updates on their end by following the instructions in this document.

How to Find Your Currently Installed Versions

Recent GreenArrow installations make their version numbers available in the web interface.

GreenArrow Engine’s version number is shown in the footer of each Engine web page, next to the copyright statement. For example, this system is running Engine 4.1.223:

Copyright © 2012–2019 GreenArrow Email | Version 4.1.223

To view GreenArrow Studio’s version number, navigate to “Admin” => “System” and view the “Version Number” field:

GreenArrow Studio Version

If you’re running an older GreenArrow installation which does not show versions in the web interface or just prefer to use the command line, then you can also SSH into your server and run the following command to view GreenArrow’s versions:

rpm -q greenarrow-engine greenarrow-studio 2> /dev/null || dpkg -l greenarrow-engine greenarrow-studio

The exact format of the above command’s output will vary, depending on what Linux distribution you’re using. As an example, here’s what the output will look like in CentOS:

greenarrow-engine-4.1.210-0.x86_64
greenarrow-studio-4.103.5-0.x86_64

The above indicates that GreenArrow Engine 4.1.210-0 and GreenArrow Studio 4.103.5-0 are installed.

Operating System Updates

We recommend keeping non-GreenArrow packages up-to-date. When updating both GreenArrow and non-GreenArrow packages, the safest approach is to perform non-GreenArrow package updates first.

Update Prerequisites

The GreenArrow update procedure has the following prerequisites:

  1. An experienced Linux systems administrator who can execute the update procedure.

  2. The /var/hvmail/bin/greenarrow_blockers file must exist, and when executed, it must output text telling you that it’s safe to proceed with the update. This is described in more detail in step 2 of the update procedure below.

Update Procedure

Prerequisites

Verify that you’ve met all of the prerequisites listed above before proceeding.

This section describes how to update both GreenArrow Engine and Studio.

GreenArrow Engine and Studio have some shared code, so don’t be alarmed if you’re a GreenArrow Engine only customer, and see references to GreenArrow Studio in the output of the commands you run during the update.

GreenArrow has a lot of moving parts, so we recommend reading through the entire update procedure before proceeding, and considering whether the update should be scheduled. Depending on how old your current GreenArrow version is, what hardware is in use, and how much data is present, you can expect anywhere from a few seconds to a few minutes of downtime during most updates.

  1. SSH into the GreenArrow server as the root user, or a user with equivalent permissions.

  2. Check if it’s safe to proceed with the update, and only proceed if the greenarrow_blockers command outputs text telling you that it’s safe to proceed:

    greenarrow_blockers
    

    Stop here if greenarrow_blockers returns anything other than this:

    It is safe to upgrade this system by following the instructions at:
    https://www.greenarrowemail.com/docs/greenarrow-engine/Server-Management-and-Backups/GreenArrow-Updates
    

  3. Check what version of GreenArrow Engine is installed:

    rpm -q greenarrow-engine 2> /dev/null || dpkg -l greenarrow-engine
    

  4. Read through the Version-Specific Steps section for any extra manual steps which are needed as part of the update process. Complete them at the time indicated.

  5. Update GreenArrow’s packages.

    On Red Hat-based Linux distributions, such as CentOS, run:

    yum --enablerepo=greenarrow update 'greenarrow-*'
    

    On Debian-based Linux distributions, such as Ubuntu:

    1. Enable GreenArrow’s package repository:

      sed -e '/greenarrow main/ s/^#*//' -i /etc/apt/sources.list.d/greenarrow.list
      

    2. Install the updated packages:

      apt-get update && apt-get --only-upgrade install 'greenarrow-*'
      

    3. Disable GreenArrow’s package repository to prevent accidental updates in the future:

      sed -e '/greenarrow main/ s/^#*/#/' -i /etc/apt/sources.list.d/greenarrow.list
      

  6. Run migrations. This step normally takes anywhere from a few seconds to a few minutes to complete:

    hvmail_migrate migrate
    

  7. Complete any post-update steps that you noted after reading through the the Version-Specific Steps section.

  8. Verify that some common misconfigurations are not present. Each test gets a simple pass/fail result:

    hvmail_check_config
    

  9. Verify that all services are running normally. Any services with an abnormal state are shown in red:

    hvmail_init status
    

  10. Send yourself a test email (replacing [email protected] with your actual email address):

    date | /var/hvmail/bin/mailsubj "GreenArrow Test Message" [email protected]
    

That’s it! You’re now running the latest GreenArrow releases.

Version-Specific Steps

The following table is in ascending chronological order. Please begin reading through it at the first release listed which comes after your currently installed version and work your down. Here are two examples:

  1. If you have GreenArrow Engine 4.1.233-0 or later installed, then there are no version-specific steps to complete.

  2. If you have GreenArrow Engine 4.1.217-0 installed, then you would begin with the upgrade instructions for 4.1.226-0.

All steps in this table should be completed before updating GreenArrow’s packages unless otherwise indicated:

4.1.216

April 18, 2018

This update introduces the greenarrow.conf configuration file. If GreenArrow’s Apache or PostgreSQL installation has a customized configuration, then one or more configuration directives may need to be moved into greenarrow.conf.

For this update, please:

  1. Complete all other upgrade steps.

  2. Run the following command, and examine the output:

    greenarrow_config validate
    
    If any conflicts are found, then a warning describing the conflict and how to resolve it are displayed as part of the output.

4.1.226

August 16, 2018

Starting with this update, the contents of the /var/hvmail/control/httpd.ssl.custom.conf file get included in alll HTTPS VirtualHost definitions. Previously, it was only included in the default HTTPS VirtualHost’s definition.

Before performing this update, please review the contents of your /var/hvmail/control/httpd.ssl.custom.conf file (which is blank by default) and verify that you’re okay with it being included in all HTTPS VirtualHost definitions.

If the new behavior presents a problem, then instead of defining VirtualHosts in /var/hvmail/control/httpd.ssl.listen, define them in /var/hvmail/control/httpd.custom.conf. See our HTTP Server documentation for more details on those two files.

4.1.227

August 31, 2018

This release lowers the dynamic defaults for apache_max_clients and passenger_max_requests_in_queue, reducing overall memory utilization to be closer to what it was before the April 2018 release of Engine 4.1.216.

If you’re running Engine 4.1.215 or earlier, then your release predates dynamic defaults, so no extra steps are required.

If you’re running Engine 4.1.216 or later, then we recommend the following:

  • Before upgrading, compare your existing configured or default limits (which you can get from the show_dynamic_defaults command) to the new defaults for these limits, which are described below. Most installations can use the new defaults for optimum performance.

  • After upgrading, you may want to monitor your utilization of these limits.

The new dynamic defaults are calculated as follows:

All systems start with the following:

apache_max_clients = 150
passenger_max_requests_in_queue = 100

If the system has more than 4GB of RAM and at least 4 CPU cores, those numbers are increased:

modifier = ( memory_in_gb - 4.0 ) * 32
apache_max_clients += modifier
passenger_max_requests_in_queue += 3 * modifier / 4

4.1.230

September 18, 2018

Before installing this update, please check if the /var/hvmail/control/domainkeys.legacy directory exists.

If the directory does exist, then you’re using the old command line DKIM configuration system that was replaced in this release. You’ll need to convert any DKIM keys in that directory to a Web or API based DKIM configurations before the upgrade or the new command line system after the upgrade.

If the directory does not exist, then no additional steps are required.

4.1.233

October 17, 2018

  1. The X-GreenArrow-Signing-Key-Filename and X-Greenarrow-DomainKeys-Enable headers are no longer supported, starting with this release. If you’re currently using them, then transition away from them before proceeding with this upgrade:

    1. The recommended replacement for X-GreenArrow-Signing-Key-Filename is the X-GreenArrow-DKIM header.
    2. There is no replacement for the X-Greenarrow-DomainKeys-Enable header. DomainKeys is obsolete. DKIM should be used instead.
  2. For new installations, SimpleMH now defaults to using URL suffixes of /click and /open for clicks and opens. Previously, both clicks and opens used /click.php

    If you wish to use the new defaults, perform the update as normal, then come back and do the following:

    1. Edit /var/hvmail/control/simplemh-config.
    2. Find the definition of $CLICKTHROUGH_URL.
    3. On that line, replace /click.php with simply /click.
    4. Restart SimpleMH by running svc -t /service/hvmail-simplemh*.
4.1.274

October 3, 2019

Search for non-standard SMTP and QMQP services by running the following command:

find /service/ -name "hvmail-qmail-smtpd*" -o -name "hvmail-qmail-qmqp*" | 
grep -v "/service/hvmail-qmail-smtpd[23]*$"

If the above command produces no output, then only default services are present, so you can ignore the rest of this version’s update instructions.

If the above command does produce output, use the following update sequence:

  1. Open the run file for each non-standard SMTP and QMQP service identified above in a text editor. The path to the run file is the filesystem path that was output by the find command, plus /run. For example, /service/hvmail-qmail-smtpd4/run.

  2. Insert the following line after the existing exec 2>&1 line, and save your changes:
    export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/var/hvmail/openssl/lib/
    
  3. Perform the rest of the GreenArrow update steps.

  4. Restart all of the SMTP and QMQP services, and verify that they come back up, and stay up for at least 5 seconds:
    svc -t /service/hvmail-qmail-{smtpd,qmqp}*
    sleep 10
    svstat /service/hvmail-qmail-{smtpd,qmqp}* |
    grep -v "/service/hvmail-qmail-smtpd3:"
    

Most GreenArrow installations do not have a QMQP service, so if you receive an error indicating that the /service/hvmail-qmail-qmqp* file does not exist, that’s normal.


Copyright © 2012–2019 GreenArrow Email