201 lines
3.9 KiB
Markdown
201 lines
3.9 KiB
Markdown
# Mail Stats - Postfix Summary Tool (v2026.1.1)
|
||
|
||
|
||
|
||
|
||
|
||
---
|
||
|
||
## 📋 Table of Contents
|
||
|
||
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
|
||
|
||
**Mail Stats** is a secure, hardened, memory-safe Bash tool for summarizing **Postfix** mail logs. It provides:
|
||
|
||
* 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
|
||
|
||
This tool is ideal for server administrators who need fast insights into sent, rejected, or deferred emails.
|
||
|
||
|
||
|
||
---
|
||
|
||
## ✨ Features
|
||
|
||
* **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
|
||
* 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
|
||
|
||
* Linux/Unix system
|
||
* Bash 4.x+
|
||
* Postfix logs in `/var/log/` (e.g., `maillog*`, `mail.log*`)
|
||
* `awk`, `zcat`, `grep`, `find`, `sed` installed
|
||
|
||
---
|
||
|
||
## ⚡ Installation
|
||
|
||
Copy or clone the script:
|
||
|
||
```bash
|
||
sudo cp mail-stats /usr/local/bin/mail-stats
|
||
sudo chmod +x /usr/local/bin/mail-stats
|
||
```
|
||
|
||
No additional dependencies required.
|
||
|
||
---
|
||
|
||
## 🛠 Usage
|
||
|
||
```bash
|
||
mail-stats [OPTIONS]
|
||
```
|
||
|
||
By default, it displays the **last 10 mail log entries** for today.
|
||
|
||
---
|
||
|
||
## 🔧 Options
|
||
|
||
| 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
|
||
|
||
Show last 20 emails:
|
||
|
||
```bash
|
||
mail-stats -l 20
|
||
```
|
||
|
||
Filter by sender:
|
||
|
||
```bash
|
||
mail-stats -f "example@domain.com"
|
||
```
|
||
|
||
Filter by recipient:
|
||
|
||
```bash
|
||
mail-stats -t "recipient@domain.com"
|
||
```
|
||
|
||
Detailed view for Queue ID:
|
||
|
||
```bash
|
||
mail-stats -i 3F2A4B1C0
|
||
```
|
||
|
||
Filter by date:
|
||
|
||
```bash
|
||
mail-stats -d "Mar 27"
|
||
```
|
||
|
||
Search all logs:
|
||
|
||
```bash
|
||
mail-stats -d ""
|
||
```
|
||
|
||
---
|
||
|
||
## 🛡 Security & Hardening
|
||
|
||
1. **Resource Limits**
|
||
|
||
```bash
|
||
ulimit -t 15 # CPU time
|
||
ulimit -v 500000 # Virtual memory (kB)
|
||
ulimit -f 102400 # Max file size
|
||
```
|
||
|
||
2. **Single Instance Locking**
|
||
|
||
* Prevents simultaneous executions via `/tmp/mail-stats.lock`
|
||
|
||
3. **Temporary File Safety**
|
||
|
||
* Uses `mktemp` and cleans files on exit
|
||
|
||
4. **Safe Argument Handling**
|
||
|
||
* Limits input length and validates required arguments
|
||
|
||
5. **Memory-Safe Log Parsing**
|
||
|
||
* Skips overly long/short lines
|
||
|
||
6. **Old Temp File Cleanup**
|
||
|
||
* Deletes stale files older than 10 minutes
|
||
|
||
---
|
||
|
||
## ⚠ Notes
|
||
|
||
* Ignores local Postfix deliveries (`127.0.0.1`) by default
|
||
* Supports `.gz` compressed logs
|
||
* Detailed view (`--id`) shows:
|
||
|
||
* Date/Time
|
||
* Client IP
|
||
* Sender
|
||
* Recipient
|
||
* Status
|
||
* Reason
|
||
|
||
|
||
|
||
---
|
||
|
||
## 📜 License
|
||
|
||
MIT License – free to use, modify, and distribute
|
||
|
||
---
|
||
|
||
## 👤 Author
|
||
|
||
**robott** – [GitHub](https://git.robott.sk/robott)
|