218 lines
5.2 KiB
Markdown
218 lines
5.2 KiB
Markdown
# 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](#overview)
|
||
* [Features](#features)
|
||
* [Requirements](#requirements)
|
||
* [Installation](#installation)
|
||
* [Usage](#usage)
|
||
* [Options](#options)
|
||
* [Examples](#examples)
|
||
* [Preview](#preview)
|
||
* [Security & Hardening](#security--hardening)
|
||
* [Notes](#notes)
|
||
* [License](#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.:
|
||
|
||
```bash
|
||
sudo cp postfix_summary.sh /usr/local/bin/postfix_summary
|
||
sudo chmod +x /usr/local/bin/postfix_summary
|
||
```
|
||
|
||
No additional dependencies are required.
|
||
|
||
---
|
||
|
||
## Usage
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
postfix_summary.sh -l 20
|
||
```
|
||
|
||
Filter emails from a specific sender:
|
||
|
||
```bash
|
||
postfix_summary.sh -f "example@domain.com"
|
||
```
|
||
|
||
Filter emails sent to a specific recipient:
|
||
|
||
```bash
|
||
postfix_summary.sh -t "recipient@domain.com"
|
||
```
|
||
|
||
Show detailed view of a specific queue ID:
|
||
|
||
```bash
|
||
postfix_summary.sh -i 3F2A4B1C0
|
||
```
|
||
|
||
Filter by a specific date:
|
||
|
||
```bash
|
||
postfix_summary.sh -d "Mar 27"
|
||
```
|
||
|
||
Search across all logs without date filtering:
|
||
|
||
```bash
|
||
postfix_summary.sh -f "example@domain.com" -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:
|
||
|
||
```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`.
|
||
|
||
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.
|