GreenArrow Email Software Documentation

Debian Updates

Intro

This document describes how to update your GreenArrow server’s Debian or Ubuntu Linux distribution. See Supported Debian-based Linux Distributions for a list of GreenArrow-compatible distributions.

Minor and Point Releases

You can update your Linux distribution to a new point or minor release without having to take any special precautions for GreenArrow as long as you don’t cross into a new major version. Here are some examples of updates between minor releases:

  • Updating from Ubuntu 18.04.4 to 18.04.5.
  • Updating from Debian 10.8 to 10.9.

Major Releases

Debian-family Linux distributions allow for online updates between major releases. For example, it’s possible to update Debian 9 to Debian 10 or Ubuntu 16.04 to 18.04 through an SSH session.

Major Release Update Prerequisites

The procedure for updating between major Linux distribution releases has some prerequisites:

  1. An experienced Linux systems administrator to execute the update procedure.

  2. The server must run PostgreSQL 9.5 or later. You can check what version it’s running by reading the PG_VERSION file:

    cat /var/hvmail/postgres/default/data/PG_VERSION
    

    If you’re running an older version of PostgreSQL, such as version 8.3, contact GreenArrow technical support to schedule a PostgreSQL update.

  3. The server that’s to be updated must run GreenArrow 4.200.0 or later:

    dpkg -l greenarrow || echo "GreenArrow is either not installed, or is older than version 4.200.0."
    

    If an earlier GreenArrow release is installed, then you’ll need to update GreenArrow to version 4.200.0 or later before proceeding.

  4. The server must not have been flagged by GreenArrow technical support as blocked for upgrades. Run the greenarrow_blockers command and only proceed if it outputs the following text:

    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
    

  5. As part of the upgrade process, you’ll upgrade to the latest GreenArrow release. Review GreenArrow’s changelog and the GreenArrow Updates document to verify that you’re comfortable with making that version jump.

Major Release Upgrade Procedure

Once all of the prerequisites in the previous section are satisfied, you can perform the Linux distribution upgrade using the following procedure:

  1. Upgrade to the latest GreenArrow release available for your Linux distribution.

  2. Back up GreenArrow using the unmanaged backup script. The backup is used during the update process, so a copy of it should be available to the server you’re updating. We also strongly recommend storing a copy at a location external to the server so that you can use it to recover if something goes wrong during the update process.

  3. Stop GreenArrow:

    systemctl stop greenarrow.service
    

  4. Remove GreenArrow packages:

    apt-get remove greenarrow-support
    

  5. Delete the /etc/apt/sources.list.d/greenarrow.list file:

    rm -f /etc/apt/sources.list.d/greenarrow.list
    

  6. Perform the Linux distribution update using the procedure documented by Debian or Ubuntu. Note that in some server configurations, DNS resolution may stop working after GreenArrow is stopped. If that happens, you may need to temporarily update /etc/resolv.conf to query an external DNS server instead of GreenArrow’s 127.0.0.1 DNS server.

  7. View the contents of the greenarrow-repository-access-key.txt file created in step 2. This key is needed for the next step.

  8. Complete the Prerequisites section of our Installation Guide. If you get to the “Install GreenArrow” step in the Installation Guide, you’ve gone too far.

  9. Make a copy of configuration files that may be overwritten when GreenArrow is reinstalled:

    mkdir -p /var/hvmail/control.pre-update /var/hvmail/var/control.pre-update
    cp -a /var/hvmail/control/* /var/hvmail/control.pre-update/
    cp -a /var/hvmail/var/control/* /var/hvmail/var/control.pre-update/
    rm -f /var/hvmail/var/control.pre-update/httpd.studio.conf
    

  10. Install GreenArrow’s packages:

    apt-get update && \
    apt-get -y install greenarrow && \
    systemctl enable greenarrow.service && \
    sed -i 's/^deb /#deb /' /etc/apt/sources.list.d/greenarrow.list
    

  11. GreenArrow packages make some changes to environment settings. To activate the changes, either log out, then back into the server or run the following commands. If you’re logged into the server in multiple windows, then you’ll need to complete this step in each window:

    . /etc/profile.d/greenarrow-engine.sh
    . /etc/profile.d/greenarrow-ruby.sh
    . /etc/profile.d/greenarrow-studio.sh
    . /etc/profile.d/greenarrow-passenger.sh
    

  12. Move GreenArrow’s configuration files from before the package installation back into place:

    mv /var/hvmail/control.pre-update/dkim/* /var/hvmail/control/dkim
    rm -rf /var/hvmail/control.pre-update/{dkim,logrotate.d,dnscache}/
    mv /var/hvmail/control.pre-update/* /var/hvmail/control/
    mv /var/hvmail/var/control.pre-update/* /var/hvmail/var/control/
    rmdir /var/hvmail/control.pre-update/ /var/hvmail/var/control.pre-update/
    

  13. Start GreenArrow:

    systemctl start greenarrow.service
    

  14. Run GreenArrow migrations:

    greenarrow update
    

  15. Review the GreenArrow Updates document for upgrade steps (other than updating packages and then running greenarrow update) required for the jump from the version of GreenArrow that your old Linux distribution ran to the version that’s currently running. If you’re uncertain what version of GreenArrow your old Linux distribution ran, it’s recorded in the greenarrow-packages.txt file created when a backup was taken in step 2.

Post-Upgrade Testing

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

    hvmail_check_config
    

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

    hvmail_init status
    

    The hvmail-qmail-smtpd3 and hvmail-dnscache services are down by default. All other services should be up unless you shut them down intentionally.

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

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

Alternatives

If you cannot, or prefer not to perform the procedure on this page to upgrade to a new Linux distribution, then the following alternatives are available:


Copyright © 2012–2024 GreenArrow Email