mail-status/README.md

Postfix Mail Summary Script

Hardened, secure, and memory-safe Bash script for summarizing Postfix mail logs with filtering and detail views.

---

Table of Contents

• Overview
• Features
• Requirements
• Installation
• Usage
• Options
• Examples
• Preview
• Security & Hardening
• Notes
• License

---

Overview

This script parses and summarizes Postfix log files located in /var/log/. It supports filtering by sender, recipient, queue ID, and date. The output can be a concise summary table or a detailed per-message view.

The script is hardened with:

• Resource limits
• Safe temporary file handling
• Single-instance locking
• Secure parsing and memory-safe processing

---

Features

• Summarizes Postfix logs with color-coded output.

• Filters by:

  • Sender (from)

  • Recipient (to)

  • Queue ID (id)

  • Date (date)

    • Use -d "" to search across all logs without date filtering

• Displays summary or detailed view per message.

• Handles compressed logs (.gz) automatically.

• Safely deletes old temporary files.

• Avoids displaying internal local deliveries (127.0.0.1) unless explicitly filtered.

• Highlights deferred, rejected, and greylisted emails with color.

• Limits memory, CPU time, and file usage for safety.

---

Requirements

• Linux or Unix-like system
• Bash 4.x+
• Postfix logs under /var/log/ (e.g., maillog*, mail.log*)
• awk, zcat, grep, find, sed installed

---

Installation

Clone or copy the script to your preferred location, e.g.:

sudo cp postfix_summary.sh /usr/local/bin/postfix_summary
sudo chmod +x /usr/local/bin/postfix_summary

No additional dependencies are required.

---

Usage

postfix_summary.sh [OPTIONS]

By default, it shows the last 10 mail log records from today.

---

Options

Option	Description
-h, --help	Show this help message
-l, --list NUMBER	Show the last X records (default: 10, max: 1000)
-f, --from EMAIL/DOMAIN	Filter by sender email or domain
-t, --to EMAIL/DOMAIN	Filter by recipient email or domain
-i, --id QUEUE_ID	Show detail view for a specific queue ID
-d, --date "MMM DD"	Filter by date (e.g., "Mar 27")

• Use -d "" to search across all logs without date filtering |

---

Examples

Show last 20 emails:

postfix_summary.sh -l 20

Filter emails from a specific sender:

postfix_summary.sh -f "example@domain.com"

Filter emails sent to a specific recipient:

postfix_summary.sh -t "recipient@domain.com"

Show detailed view of a specific queue ID:

postfix_summary.sh -i 3F2A4B1C0

Filter by a specific date:

postfix_summary.sh -d "Mar 27"

Search across all logs without date filtering:

postfix_summary.sh -d ""

---

Preview

Running postfix_summary.sh (default summary view):

DATE-TIME        ID           CLIENT_IP        SENDER                               RECIPIENT                         STATUS       REASON
Mar 27 12:34:56  3F2A4B1C0   192.168.1.10     sender@example.com                    recipient@domain.com              sent         [OK]
Mar 27 12:35:10  4A1B2C3D4   203.0.113.5      admin@domain.org                       user@example.com                  deferred     [Temporary failure]

Running postfix_summary.sh -i 3F2A4B1C0 (detail view):

--- Detail for ID: 3F2A4B1C0 ---
Date        : Mar 27 12:34:56
Client IP   : 192.168.1.10
Sender      : sender@example.com
Recipient   : recipient@domain.com
Status      : sent
Reason      : OK
--------------------------------

---

Security & Hardening

The script applies multiple security measures:

1. Resource Limits Prevents excessive CPU or memory usage:

   ulimit -t 15        # CPU time
   ulimit -v 500000    # Virtual memory (kB)
   ulimit -f 102400    # Max file size
   

2. Single Instance Locking Prevents multiple simultaneous executions using /tmp/postfix_summary.lock.

3. Temporary File Safety Uses mktemp to create secure temporary files and cleans them on exit.

4. Safe Argument Handling Limits input length and validates required arguments.

5. Memory-Safe Log Parsing Skips overly long or short lines to prevent potential buffer abuse.

6. Old Temp File Cleanup Deletes stale files older than 10 minutes to prevent clutter or accidental data leak.

---

Notes

• The script ignores local Postfix deliveries (127.0.0.1) in summary mode.

• Supports .gz compressed logs for backward compatibility.

• Detail view (--id) provides full information including:

  • Date/Time
  • Client IP
  • Sender
  • Recipient
  • Status
  • Reason

---

License

MIT License – feel free to use, modify, and distribute.