Debian Updates

Table of Contents
Intro
Minor and Point Releases
Major Releases

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 12.1 to 12.2.

Major Releases

Debian-family Linux distributions allow for online updates between major releases. For example, it’s possible to update Debian 11 to Debian 12 or Ubuntu 22.04 to 24.04 through an SSH session.

Major Release Update Prerequisites

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

An experienced Linux systems administrator to execute the update procedure.
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.
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.
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
```
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:

Upgrade to the latest GreenArrow release available for your Linux distribution.
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.
Stop GreenArrow:
```
systemctl stop greenarrow.service
```
Remove GreenArrow packages:
```
apt-get remove greenarrow-support
```
Delete the /etc/apt/sources.list.d/greenarrow.list file:
```
rm -f /etc/apt/sources.list.d/greenarrow.list
```
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.
View the contents of the greenarrow-repository-access-key.txt file created in step 2. This key is needed for the next step.
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.

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

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

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
```

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/

Start GreenArrow:
```
systemctl start greenarrow.service
```
Run GreenArrow migrations:
```
greenarrow update
```
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

Verify that some common misconfigurations are not present. Each test gets a simple pass/fail result:
```
hvmail_check_config
```
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.
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:

Migrate to a new server
Backup GreenArrow, then restore to a server running the desired Linux distribution.