Configure warnquota Notifications Without Surprises

The first time warnquota fires, it usually reaches a user as a terse, unsigned email that nobody can act on. Getting that message readable takes real configuration, not just a cron job. This guide sets up warnquota 4.06 to send a useful warning when a filesystem user or group crosses a soft limit, then proves the setup works without actually spamming every affected user to test it.

Allow about 20 minutes if quota accounting and a local mail transport are already working. You need root access, enabled quotas on the filesystem you will check, and a working local mail command. The examples use /srv/home as a placeholder. Replace it with a real quota-enabled mountpoint before running anything.

1. Confirm the installed tool

1. Check the version and available options as an ordinary user.

   warnquota --version
   warnquota --help

2. Write a readable notification message

1. Create a temporary configuration containing the sender, support contact and message text. This step changes a file only under /tmp.

   cat > /tmp/warnquota.conf.example <<'EOF'
   FROM = [email protected]
   SUPPORT = [email protected]
   PHONE = +44 20 0000 0000
   SUBJECT = Disk quota warning on %h
   MESSAGE = Hello %i,|your disk quota on %h has been exceeded.|Please remove files or contact %s.
   SIGNATURE = Storage support: %s|%d
   EOF

2. Inspect the file before using it as root.

   sed -n '1,20p' /tmp/warnquota.conf.example

Configuration syntax is an option name, an equals sign and a value. Blank lines and lines beginning with # or ; are ignored. Values may be quoted and may continue onto another line when the previous line ends with a backslash.

The format sequences here carry the meaning: %h is the host name, %i is the user or group name, %s is the support value, %d is the domain, and | inserts a newline. In SUBJECT, the host name gives an operator enough context to recognise which machine generated the message. A literal percent sign is written as %%.

For a real deployment, install the reviewed file as /etc/warnquota.conf. This is an elevated, persistent change, so preserve the old file first to keep undo straightforward.

sudo cp -p /etc/warnquota.conf /etc/warnquota.conf.before-warnquota 2>/dev/null || true
sudo install -o root -g root -m 0644 /tmp/warnquota.conf.example /etc/warnquota.conf

sudo test -f /etc/warnquota.conf.before-warnquota && \
  sudo cp -p /etc/warnquota.conf.before-warnquota /etc/warnquota.conf

3. Describe the filesystem in quota mail

1. Write a device description in a temporary quota table.

   cat > /tmp/quotatab.example <<'EOF'
   /dev/mapper/vg0-home: Home directories.|Quota warnings for this filesystem.
   EOF
   sed -n '1,5p' /tmp/quotatab.example

2. Install the reviewed table as root if the device path matches the mounted filesystem.

   findmnt -no SOURCE,TARGET /srv/home
   sudo cp -p /etc/quotatab /etc/quotatab.before-warnquota 2>/dev/null || true
   sudo install -o root -g root -m 0644 /tmp/quotatab.example /etc/quotatab

Each quotatab line has a device path, a colon and a description. Surrounding whitespace, apostrophes and double quotes are stripped, and a pipe in the description becomes a newline in the notification. The path must identify the device, not merely the directory you happen to use as a mountpoint, so check it with findmnt first.

4. Run a narrow test before enabling mail

1. Run the command against one filesystem with the reviewed files, human-readable values and no attached quota report.

   sudo warnquota --user --human-readable --no-details \
     --config=/etc/warnquota.conf \
     --quota-tab=/etc/quotatab \
     /srv/home

This checks the selected local filesystem and skips attaching the quota report to the message. It can still send mail to any user that meets the warning condition. The command normally prints nothing on success, so verify its exit status immediately if you are scripting it:

sudo warnquota --user --no-details /srv/home
status=$?
printf 'warnquota exit status: %s\n' "$status"
test "$status" -eq 0

5. Set up group warnings separately

Group mode is a different recipient workflow. It checks group quotas, then sends a warning to the user named for the group in /etc/quotagrpadmins. It does not infer a group administrator from the group database, so this file is not optional.

1. Review a group administrator mapping in a temporary file.

   cat > /tmp/quotagrpadmins.example <<'EOF'
   projects: [email protected]
   EOF

2. Install it only after checking the address and group name.

   getent group projects
   sudo cp -p /etc/quotagrpadmins /etc/quotagrpadmins.before-warnquota 2>/dev/null || true
   sudo install -o root -g root -m 0644 /tmp/quotagrpadmins.example /etc/quotagrpadmins

3. Run group mode against the same single filesystem.

   sudo warnquota --group --human-readable \
     --admins-file=/etc/quotagrpadmins \
     /srv/home

Whitespace around the group and recipient is allowed. Empty lines and lines beginning with # or ; are ignored. Restore /etc/quotagrpadmins.before-warnquota if this test used the wrong recipient.

Common traps

• Full mail storage: set MAILDEV to the device holding mailboxes, or to any when appropriate, so warnings do not bounce because the destination filesystem is full.

• Unexpected sender: MAIL_CMD defaults to /usr/lib/sendmail -t. The command receives the complete message, including headers, on standard input. Change it only after testing the replacement mail transport.

• Autofs noise: use --no-autofs when automounted filesystems should not be checked.

• Quota format guesswork: autodetection is the default. Use --format=vfsv0, vfsv1, vfsold or xfs only when you have verified the filesystem's format.

• LDAP mail lookup: disabled by default. If you enable LDAP_MAIL, treat the bind password and directory endpoint as security-sensitive configuration and restrict the file permissions.

Done means

• Version confirmed: warnquota --version reports the installed version you tested.
• Message reviewed: /etc/warnquota.conf has a reviewed sender, recipient behaviour and message.
• Device described: /etc/quotatab describes the actual quota device.
• User mode tested: it ran against one named filesystem and returned status 0.
• Group mode mapped: /etc/quotagrpadmins maps each group to an intentional recipient before use.
• Rollback ready: every saved .before-warnquota file can restore the previous configuration.