Quota Notification Utility

notifier is a command line utility for emailing users when their storage usage on a monitored file system crosses a configured threshold.

Requirements

The df command line utility must be installed on the host system.

Installation

Install the package with pip (or pipx):

pip install quota-notifier

Quick Start

Application settings are read from /etc/notifier/settings.json. If the file does not exist, the application runs using default settings. The example below is a minimal configuration that covers most deployments:

{
  "log_path": "/home/notifier.log",
  "log_level": "INFO",
  "db_url": "sqlite:///home/notifier_data.db",
  "uid_blacklist": [
    0
  ],
  "gid_blacklist": [
    0
  ],
  "file_systems": [
    {
      "name": "Example File System",
      "path": "/example",
      "type": "generic",
      "thresholds": [
        50,
        75
      ]
    }
  ],
  "email_from": "no-reply@domain.com",
  "email_domain": "@domain.com",
  "admin_emails": [
    "admin.user@domain.com"
  ]
}

Validate the settings file without sending any email:

notifier --validate

Send any pending notifications:

notifier

Notifications are normally automated with a cron job. Running at least once per day is recommended:

0 9 * * 0-6 notifier

Usage

Run notifier --help for the full argument list.

Configuration

Core Settings

File System Settings

Each entry in the file_systems list requires the following fields:

Adding a new file system type also requires updating QuotaType in quota_notifier.disk_utils.QuotaFactory.

Blacklisting Users and Groups

The uid_blacklist and gid_blacklist options accept individual ID values and inclusive ID ranges. To ignore the root user in addition to users 100 through 199:

{
  "uid_blacklist": [
    0,
    [
      100,
      199
    ]
  ]
}

The default value for both options is [0], which excludes the root user and group.

Email Template

The email sent to users is rendered from an HTML template at /etc/notifier/template.html, which is intended to be customized. Formatted fields are indicated with curly braces:

Supported File Systems

Most file systems are supported by default, with dedicated support for the types below.

Generic — Any file system where usage and available space can be determined with os.statvfs. Generic file systems must be organized so that each subdirectory is named after a user group. For a file system mounted at /mnt, the directory for group group1 must be /mnt/group1. Directories not named after a user group are ignored, and a directory does not have to exist for every group.

BeeGFS — Quota information is read directly from the beegfs-ctl utility, so there are no requirements on how the file system is organized.

ihome — Usage is determined with os.statvfs against the user's home directory. Since VAST reports the quota limit as the size of the underlying file system when no quota is configured, a user is skipped if their reported size is within 1% of the enclosing mount point's size.

vast — Usage is determined the same way as ihome, but against a group directory on VAST-hosted storage (organized the same way as generic file systems).