robott/mail-status
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update README.md

Browse Source
This commit is contained in:
robott
2026-03-27 22:10:29 +01:00
parent 8137161172
commit 85fb5bb45c
1 changed files with 94 additions and 111 deletions
Download Patch File Download Diff File Expand all files Collapse all files

201
README.md
View File

@@ -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) ![License](https://img.shields.io/badge/license-MIT-green)
![Bash](https://img.shields.io/badge/Bash-4.x+-blue)
Hardened, secure, and memory-safe Bash script for summarizing **Postfix** mail logs with filtering and detail views. ![Postfix](https://img.shields.io/badge/Postfix-Logs-lightgrey)
--- ---
## Table of Contents ## 📋 Table of Contents
* [Overview](#overview) 1. [Overview](#overview)
* [Features](#features) 2. [Features](#features)
* [Requirements](#requirements) 3. [Requirements](#requirements)
* [Installation](#installation) 4. [Installation](#installation)
* [Usage](#usage) 5. [Usage](#usage)
* [Options](#options) 6. [Options](#options)
* [Examples](#examples) 7. [Examples](#examples)
* [Preview](#preview) 8. [Security & Hardening](#security--hardening)
* [Security & Hardening](#security--hardening) 9. [Notes](#notes)
* [Notes](#notes) 10. [License](#license)
* [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 This tool is ideal for server administrators who need fast insights into sent, rejected, or deferred emails.
* Safe temporary file handling
* Single-instance locking ![Postfix Mail Summary](https://via.placeholder.com/900x200.png?text=Mail+Stats+Overview)
* Secure parsing and memory-safe processing
--- ---
## Features ## ✨ Features
* Summarizes Postfix logs with **color-coded output**. * **Color-coded output** for quick status recognition
* Filters by: * Filter by:
* Sender (`from`) * Sender (`from`)
* Recipient (`to`) * Recipient (`to`)
* Queue ID (`id`) * Queue ID (`id`)
* Date (`date`) * Date (`date`)
* **Use `-d ""` to search across all logs without date filtering** * Use `-d ""` to search across all logs
* Displays summary or detailed view per message. * Summary or detailed per-message view
* Handles compressed logs (`.gz`) automatically. * Handles `.gz` compressed logs automatically
* Safely deletes old temporary files. * Excludes local deliveries (`127.0.0.1`) unless filtered
* Avoids displaying internal local deliveries (`127.0.0.1`) unless explicitly filtered. * Limits CPU, memory, and file usage for safety
* Highlights **deferred**, **rejected**, and **greylisted** emails with color.
* Limits memory, CPU time, and file usage for safety.
--- ---
## Requirements ## 🖥 Requirements
* Linux or Unix-like system * Linux/Unix system
* Bash 4.x+ * 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 * `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 ```bash
sudo cp postfix_summary.sh /usr/local/bin/postfix_summary sudo cp mail-stats /usr/local/bin/mail-stats
sudo chmod +x /usr/local/bin/postfix_summary sudo chmod +x /usr/local/bin/mail-stats
``` ```
No additional dependencies are required. No additional dependencies required.
--- ---
## Usage ## 🛠 Usage
```bash ```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 | | Option | Description |
| ------------------------- | ------------------------------------------------ | | ------------------------- | ---------------------------------------- |
| `-h, --help` | Show this help message | | `-h, --help` | Show help message |
| `-l, --list NUMBER` | Show the last X records (default: 10, max: 1000) | | `-l, --list NUMBER` | Number of records (default 10, max 1000) |
| `-f, --from EMAIL/DOMAIN` | Filter by sender email or domain | | `-f, --from EMAIL/DOMAIN` | Filter by sender |
| `-t, --to EMAIL/DOMAIN` | Filter by recipient email or domain | | `-t, --to EMAIL/DOMAIN` | Filter by recipient |
| `-i, --id QUEUE_ID` | Show detail view for a specific queue ID | | `-i, --id QUEUE_ID` | Show detailed view of specific queue ID |
| `-d, --date "MMM DD"` | Filter by date (e.g., `"Mar 27"`) | | `-d, --date "MMM DD"` | Filter by date (e.g., `"Mar 27"`) |
* **Use `-d ""` to search across all logs without date filtering** |
--- ---
## Examples ## 📝 Examples
Show last 20 emails: Show last 20 emails:
```bash ```bash
postfix_summary.sh -l 20 mail-stats -l 20
``` ```
Filter emails from a specific sender: Filter by sender:
```bash ```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 ```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 ```bash
postfix_summary.sh -i 3F2A4B1C0 mail-stats -i 3F2A4B1C0
``` ```
Filter by a specific date: Filter by date:
```bash ```bash
postfix_summary.sh -d "Mar 27" mail-stats -d "Mar 27"
``` ```
Search across all logs without date filtering: Search all logs:
```bash ```bash
postfix_summary.sh -f "example@domain.com" -d "" mail-stats -d ""
``` ```
--- ---
## Preview ## 🛡 Security & Hardening
**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** 1. **Resource Limits**
Prevents excessive CPU or memory usage:
```bash ```bash
ulimit -t 15 # CPU time ulimit -t 15 # CPU time
ulimit -v 500000 # Virtual memory (kB) ulimit -v 500000 # Virtual memory (kB)
ulimit -f 102400 # Max file size ulimit -f 102400 # Max file size
``` ```
2. **Single Instance Locking** 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** 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** 4. **Safe Argument Handling**
Limits input length and validates required arguments.
* Limits input length and validates required arguments
5. **Memory-Safe Log Parsing** 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** 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. * Ignores local Postfix deliveries (`127.0.0.1`) by default
* Supports `.gz` compressed logs for backward compatibility. * Supports `.gz` compressed logs
* Detail view (`--id`) provides full information including: * Detailed view (`--id`) shows:
* Date/Time * Date/Time
* Client IP * Client IP
@@ -210,8 +185,16 @@ The script applies multiple security measures:
* Status * Status
* Reason * 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)