NFS Hostchange (nfs-hostchange) Plugin

Note

This plugin is intended for use only with NFS installations.

This plugin is intended to keep mailbox list indexes (dovecot.list.index* files) stored locally under /dev/shm.

If the user's backend has changed since previous access, the plugin automatically deletes any old dovecot.list.index* files from /dev/shm.

Backends should also delete local mailbox list indexes that haven't been accessed for a long time, to avoid wasting memory for them.

Configuration

# This stores mailbox list indexes in tmpfs rather than NFS. This makes moving
# the users between backends more expensive though. It also needs a way to
# delete the list indexes for users that have already moved to different
# backends (this is what NFS Hostchange plugin does).
mail_location = ...:LISTINDEX=/dev/shm/dovecot-listindex/%2.256Nu/%u/dovecot.list.index
mail_plugins = $mail_plugins nfs_hostchange

plugin {
  # Until all backends have been upgraded and most users accessed:
  nfs_hostchange_migration = yes
}

Settings

nfs_hostchange_migration

Default	no
Value	boolean

When enabled, assume user is being migrated.

Doveadm Commands

nfs usercache clean

Cleans user's cache under root path for given age.

CLI

• Usage: doveadm nfs usercache clean [--min-age min-age] <path>

Flag(s)	Type	Description
--min-age	string
path	string	Root path to clean.

HTTP API

Parameter	Type	Description
minAge	string
path	string	Root path to clean.

Migration

When first starting to use this plugin, dovecot.list.index* files don't exist locally anywhere yet.

To avoid large NFS disk I/O spikes, the existing dovecot.list.index* files should be copied from NFS to local /dev/shm if they don't exist yet.

nfs_hostchange_migration setting is used to do this.

If nfs_hostchange_migration=yes:

• stat(INDEX/dovecot.list.index.log) is done to see if a backend without nfs_hostchange plugin has accessed the user. If the stat() succeeds to find the file, the local LISTINDEX/.lasthost and LISTINDEX/dovecot.list.index* are deleted.
• If LISTINDEX/.lasthost doesn't now exist, INDEX/dovecot.list.index* are copied to local /dev/shm. INDEX/dovecot.list.index* files are then deleted.

Note that using the migration setting introduces the extra stat() call to NFS, so once most users have been accessed this setting should be disabled.

There should be also a cronjob that deletes old users from the local /dev/shm. It should be done with LISTINDEX/.lasthost locked.

This plugin provides a doveadm nfs usercache clean <age> <user dir> command, which can be used like:

doveadm nfs usercache clean 7days /dev/shm/dovecot/00/testuser

Note that this needs to be run separately for each user.

So first run a script that finds the old users based on the .lasthost file's access time.

Then for each such user run the doveadm nfs usercache clean command to safely delete it.

Technical Details

Backend Tracking

This plugin keeps track of the user's last hostname in INDEX/.lasthost file, which exists in NFS.

That file's inode and modification time is stored in LISTINDEX/.lasthost file, which exists locally under /dev/shm.

Whenever the user logs in, INDEX/.lasthost is compared to LISTINDEX/.lasthost to see if it has changed.

If yes, delete LISTINDEX/dovecot.list.index* files and rewrite the LISTINDEX/.lasthost file.