Persistence Path Mode

Table of Contents
Introduction
Persistence Path Requirements
Installation Differences
Application guide

Introduction

Ordinarily, GreenArrow stores its persistent data in a variety of paths under the /var/hvmail directory tree. In Persistence Path Mode, GreenArrow will create the necessary symlinks within /var/hvmail such that all persistent data is in a directory path of your choosing.

One reason for using Persistence Path Mode is if you want to treat individual virtual machines / installations of GreenArrow as less “precious” or more “disposable”. In this case, you’ll have a path on durable storage that contains GreenArrow’s persistent data. The /var/hvmail hierarchy into which GreenArrow is installed is hence “disposable” and may be destroyed and recreated at-will.

Persistence Path Requirements

GreenArrow utilizes some UNIX domain sockets for internal communication. These sockets are stored in one of our persistent data paths (/var/hvmail/var). Due to this, some filesystems which aren’t capable of hosting UNIX domain sockets cannot be used as a persistence path.

Using NFS for a persistence path is not supported.

Installation Differences

The Installation Guide covers how to set up a new installation using Persistence Path Mode. The primary difference is when calling greenarrow init, you must specify the --persistence-path parameter to instruct GreenArrow to store its persistent data at the specified path.

You must decide if you want to use Persistence Path Mode at the time of installation. An installation of GreenArrow cannot be converted to Persistence Path Mode after it has been initialized.

Application guide

How to create a new persistence path

During installation, you should have your persistence path mounted or otherwise available for GreenArrow to use. You may follow the standard installation guide, adding the --persistence-path parameter to greenarrow init as described therein.

How to attach a new installation to an existing persistence path

To start a new installation of GreenArrow which reuses a persistence path that has already been initialized:

Install GreenArrow from packages.
Run greenarrow init --persistence-path=/Volumes/Your-Saved-Data --attach to attach the new installation to your persistence path.
Start GreenArrow.

Ordinarily, greenarrow init requires additional arguments such as --admin-email. However, these arguments are not accepted when the persistence path is already initialized, which is indicated by the presence of the --attach parameter. When --attach is specified, the targeted persistence path will not be re-initialized.

How to attach a new installation to an existing persistence path (when the versions mismatch)

By default, greenarrow init will refuse to attach if there’s a version mismatch between the persistence path and the installed version of GreenArrow.

If you want to attach a previously initialized persistence path to a different version of GreenArrow (for example, to upgrade GreenArrow), you can provide greenarrow init the --attach-with-version-mismatch argument to allow this.

After attaching to an existing persistence path of a different version, you’ll need to run greenarrow update after starting GreenArrow. The greenarrow init command will warn you if this is the case. If you’re automating this procedure, you may want to always run greenarrow update after starting GreenArrow to ensure it’s ready-to-run (greenarrow update is safe to run when no migrations are pending).

How to relocate the persistence path

If you’ve got a Persistence Path Mode system up and running, and need to relocate the persistence path, you can accomplish this.

Stop GreenArrow.
Move the persistence path directory to its new location.
Run greenarrow init with the --attach parameter using the new persistence path (greenarrow init --persistence-path=/new/path --attach).
Start GreenArrow.

How to verify that Persistence Path Mode symbolic links are correct

GreenArrow verifies that symbolic links are correct when running the greenarrow_config validate or greenarrow_config reload commands.

How to determine the current persistence path

The following command will print information about your current installation of GreenArrow, including the persistence path.

greenarrow info

Upgrade GreenArrow to the latest release

Installations of GreenArrow running in Persistence Path Mode may be upgraded just as any other installation. See GreenArrow Updates for instructions on how to upgrade GreenArrow.

Downgrade GreenArrow to a previous release

When you attach a new installation of GreenArrow to an initialized persistence path, the version of GreenArrow must be greater than or equal to the version most recently used by that persistence path.

You may follow the GreenArrow Downgrades procedure to downgrade the version of GreenArrow used by that persistence path after it has been attached.