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.

VAST API Credentials

Quotas for ihome file systems are read directly from the VAST management API using vastpy, so the vast_host setting and exactly one of vast_token or vast_user/vast_password are required whenever an ihome file system is configured. The credentials only need read-only access to quota information:

{
  "vast_host": "vms.domain.com",
  "vast_user": "readonly-user",
  "vast_password": "********"
}

Since the settings file now contains credentials, restrict its permissions so only the account running the notifier can read it (e.g., chmod 600 /etc/notifier/settings.json).

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 and limits are read from the VAST management API by matching each user's home directory (as reported by the system password database) against the path of quotas configured in VAST. The notifier does not need read access to user home directories. Users without a quota, or whose quota has no hard or soft limit, are skipped. See VAST API Credentials.

vast — Usage is determined with os.statvfs against a group directory on VAST-hosted storage (organized the same way as generic file systems). Since VAST reports the quota limit as the size of the underlying file system when no quota is configured, a group is skipped if its reported size is within 1% of the enclosing mount point's size.