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

205
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)
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)