From 85fb5bb45c6a06714cfd9146d51b36b3a92f10ef Mon Sep 17 00:00:00 2001 From: robott Date: Fri, 27 Mar 2026 22:10:29 +0100 Subject: [PATCH] Update README.md --- README.md | 205 +++++++++++++++++++++++++----------------------------- 1 file changed, 94 insertions(+), 111 deletions(-) diff --git a/README.md b/README.md index 3f7cc1c..2847016 100644 --- a/README.md +++ b/README.md @@ -1,207 +1,182 @@ -# Postfix Mail Summary Script +# Mail Stats - Postfix Summary Tool (v2026.1.1) ![License](https://img.shields.io/badge/license-MIT-green) - -Hardened, secure, and memory-safe Bash script for summarizing **Postfix** mail logs with filtering and detail views. +![Bash](https://img.shields.io/badge/Bash-4.x+-blue) +![Postfix](https://img.shields.io/badge/Postfix-Logs-lightgrey) --- -## Table of Contents +## 📋 Table of Contents -* [Overview](#overview) -* [Features](#features) -* [Requirements](#requirements) -* [Installation](#installation) -* [Usage](#usage) -* [Options](#options) -* [Examples](#examples) -* [Preview](#preview) -* [Security & Hardening](#security--hardening) -* [Notes](#notes) -* [License](#license) +1. [Overview](#overview) +2. [Features](#features) +3. [Requirements](#requirements) +4. [Installation](#installation) +5. [Usage](#usage) +6. [Options](#options) +7. [Examples](#examples) +8. [Security & Hardening](#security--hardening) +9. [Notes](#notes) +10. [License](#license) +11. [Author](#author) --- -## Overview +## 🌟 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. +**Mail Stats** is a secure, hardened, memory-safe Bash tool for summarizing **Postfix** mail logs. It provides: -The script is hardened with: +* Filtering by sender, recipient, queue ID, and date +* Concise summary tables or detailed per-message views +* Automatic processing of compressed logs (`.gz`) +* Color-coded terminal output for easier readability -* Resource limits -* Safe temporary file handling -* Single-instance locking -* Secure parsing and memory-safe processing +This tool is ideal for server administrators who need fast insights into sent, rejected, or deferred emails. + +![Postfix Mail Summary](https://via.placeholder.com/900x200.png?text=Mail+Stats+Overview) --- -## Features +## ✨ Features -* Summarizes Postfix logs with **color-coded output**. -* Filters by: +* **Color-coded output** for quick status recognition +* Filter 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. + * Use `-d ""` to search across all logs +* Summary or detailed per-message view +* Handles `.gz` compressed logs automatically +* Excludes local deliveries (`127.0.0.1`) unless filtered +* Limits CPU, memory, and file usage for safety --- -## Requirements +## 🖥 Requirements -* Linux or Unix-like system +* Linux/Unix system * Bash 4.x+ -* Postfix logs under `/var/log/` (e.g., `maillog*`, `mail.log*`) +* Postfix logs in `/var/log/` (e.g., `maillog*`, `mail.log*`) * `awk`, `zcat`, `grep`, `find`, `sed` installed --- -## Installation +## ⚡ Installation -Clone or copy the script to your preferred location, e.g.: +Copy or clone the script: ```bash -sudo cp postfix_summary.sh /usr/local/bin/postfix_summary -sudo chmod +x /usr/local/bin/postfix_summary +sudo cp mail-stats /usr/local/bin/mail-stats +sudo chmod +x /usr/local/bin/mail-stats ``` -No additional dependencies are required. +No additional dependencies required. --- -## Usage +## 🛠 Usage ```bash -postfix_summary.sh [OPTIONS] +mail-stats [OPTIONS] ``` -By default, it shows the **last 10 mail log records** from today. +By default, it displays the **last 10 mail log entries** for today. --- -## Options +## 🔧 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** | +| Option | Description | +| ------------------------- | ---------------------------------------- | +| `-h, --help` | Show help message | +| `-l, --list NUMBER` | Number of records (default 10, max 1000) | +| `-f, --from EMAIL/DOMAIN` | Filter by sender | +| `-t, --to EMAIL/DOMAIN` | Filter by recipient | +| `-i, --id QUEUE_ID` | Show detailed view of specific queue ID | +| `-d, --date "MMM DD"` | Filter by date (e.g., `"Mar 27"`) | --- -## Examples +## 📝 Examples Show last 20 emails: ```bash -postfix_summary.sh -l 20 +mail-stats -l 20 ``` -Filter emails from a specific sender: +Filter by sender: ```bash -postfix_summary.sh -f "example@domain.com" +mail-stats -f "example@domain.com" ``` -Filter emails sent to a specific recipient: +Filter by recipient: ```bash -postfix_summary.sh -t "recipient@domain.com" +mail-stats -t "recipient@domain.com" ``` -Show detailed view of a specific queue ID: +Detailed view for Queue ID: ```bash -postfix_summary.sh -i 3F2A4B1C0 +mail-stats -i 3F2A4B1C0 ``` -Filter by a specific date: +Filter by date: ```bash -postfix_summary.sh -d "Mar 27" +mail-stats -d "Mar 27" ``` -Search across all logs without date filtering: +Search all logs: ```bash -postfix_summary.sh -f "example@domain.com" -d "" +mail-stats -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: +## 🛡 Security & Hardening 1. **Resource Limits** - Prevents excessive CPU or memory usage: - ```bash - ulimit -t 15 # CPU time - ulimit -v 500000 # Virtual memory (kB) - ulimit -f 102400 # Max file size - ``` +```bash +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`. + +* Prevents simultaneous executions via `/tmp/mail-stats.lock` 3. **Temporary File Safety** - Uses `mktemp` to create secure temporary files and cleans them on exit. + +* Uses `mktemp` and cleans files on exit 4. **Safe Argument Handling** - Limits input length and validates required arguments. + +* Limits input length and validates required arguments 5. **Memory-Safe Log Parsing** - Skips overly long or short lines to prevent potential buffer abuse. + +* Skips overly long/short lines 6. **Old Temp File Cleanup** - Deletes stale files older than 10 minutes to prevent clutter or accidental data leak. + +* Deletes stale files older than 10 minutes --- -## Notes +## ⚠ 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: +* Ignores local Postfix deliveries (`127.0.0.1`) by default +* Supports `.gz` compressed logs +* Detailed view (`--id`) shows: * Date/Time * Client IP @@ -210,8 +185,16 @@ The script applies multiple security measures: * Status * Reason +![Detail View](https://via.placeholder.com/900x200.png?text=Detailed+Mail+View) + --- -## License +## 📜 License -MIT License – feel free to use, modify, and distribute. +MIT License – free to use, modify, and distribute + +--- + +## 👤 Author + +**robott** – [GitHub](https://git.robott.sk/robott)