NFS Hostchange Plugin (nfs-hostchange)

WARNING

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).
mailbox_list_index_prefix = /dev/shm/dovecot-listindex/%{user | sha1 % 256 | hex(2)}/%{user}/dovecot.list.index
mail_plugins {
  nfs_hostchange = yes
}

# 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

HTTP API

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(mail_index_path/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 mailbox_list_index_prefix/.lasthost and mailbox_list_index_prefix/dovecot.list.index* are deleted.
• If mailbox_list_index_prefix/.lasthost doesn't now exist, mail_index_path/dovecot.list.index* are copied to local /dev/shm. mailbox_list_index_prefix/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 mailbox_list_index_prefix/.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 mail_index_path/.lasthost file, which exists in NFS.

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

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

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