Persistence Path Mode
- Table of Contents
- Persistence Path Requirements
- Installation Differences
- How to create a new persistence path
- How to attach a new installation to an existing persistence path
- How to attach a new installation to an existing persistence path (when the versions mismatch)
- How to relocate the persistence path
- How to verify that Persistence Path Mode symbolic links are correct
- How to determine the current persistence path
- Upgrade GreenArrow to the latest release
- Downgrade GreenArrow to a previous release
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.
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.
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,
--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.
greenarrow init --persistence-path=/Volumes/Your-Saved-Data --attachto attach the new installation to your persistence path.
- Start GreenArrow.
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 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)
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
--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
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
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.
greenarrow initwith the
--attachparameter 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.
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.