Skip to content

Commit 19d63aa

Browse files
Anton-BabaskinAnton-Babaskin
authored
README.md
1 parent 9ddd371 commit 19d63aa

File tree

1 file changed

+126
-76
lines changed

1 file changed

+126
-76
lines changed

‎README.md‎

Lines changed: 126 additions & 76 deletions
Original file line numberDiff line numberDiff line change
@@ -1,118 +1,168 @@
1-
MIAB Whitelists
1+
# MIAB Whitelists
2+
3+
![ShellCheck](https://github.com/Anton-Babaskin/miab-whitelists/actions/workflows/shellcheck.yml/badge.svg)
4+
5+
6+
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
27

38
Automate adding domains and IP addresses to Postfix and Postgrey whitelists on Mail-in-a-Box servers with a single, universal Bash script.
4-
📝 Overview
5-
The add_whitelists.sh script simplifies whitelisting domains and IP addresses for Postfix and Postgrey on Mail-in-a-Box servers. It supports:
69

7-
Reading a text file (whitelist.txt) with one domain or IP per line.
8-
Adding a single domain or IP directly via command-line argument.
9-
Dry-run mode to preview changes without modifying files.
10-
Creating timestamped backups of existing whitelist files.
11-
Adding entries to Postfix (/etc/postfix/client_whitelist) with OK suffix.
12-
Adding domain entries to Postgrey (/etc/postgrey/whitelist_clients.local).
13-
Rebuilding the Postfix hash database and restarting services as needed.
10+
---
11+
12+
## 📖 Table of Contents
13+
14+
* [Overview](#overview)
15+
* [Prerequisites](#prerequisites)
16+
* [Installation](#installation)
17+
* [Configuration](#configuration)
18+
* [Usage](#usage)
19+
* [Backup & Safety](#backup--safety)
20+
* [Examples](#examples)
21+
* [Contributing](#contributing)
22+
* [License](#license)
23+
24+
---
25+
26+
## 📝 Overview
27+
28+
`add_whitelists.sh` reads a simple text file (`whitelist.txt`) with one domain or IP (CIDR supported) per line, then:
29+
30+
1. Creates timestamped backups of your existing whitelist files.
31+
2. Adds entries to Postfix (`/etc/postfix/client_whitelist`) suffixed with `OK`.
32+
3. Adds domain entries to Postgrey (`/etc/postgrey/whitelist_clients.local`).
33+
4. Rebuilds the Postfix hash database and restarts both services.
34+
35+
Keeping your whitelist entries in a separate file lets you safely publish this script on GitHub without exposing private data.
1436

15-
The whitelist entries are stored in a separate file or provided as arguments, ensuring sensitive data is not hardcoded in the script.
16-
⚙️ Prerequisites
37+
---
1738

18-
OS: Debian / Ubuntu
19-
Services: Postfix and Postgrey installed
20-
Permissions: Root or sudo access to modify /etc/postfix and /etc/postgrey
21-
Input Format: Domains (e.g., example.com, mail.partner-domain.org) or IPv4 addresses (e.g., 198.51.100.1). CIDR notation (e.g., 198.51.100.0/24) is not supported in Postfix hash maps and will be skipped with a warning.
39+
## ⚙️ Prerequisites
2240

23-
🚀 Installation
41+
* **OS:** Debian / Ubuntu
42+
* **Services:** Postfix & Postgrey installed
43+
* **Permissions:** Root or `sudo` to modify `/etc/postfix` and `/etc/postgrey`
2444

25-
Clone the repository:
26-
git clone https://github.com/Anton-Babaskin/miab-whitelists.git
27-
cd miab-whitelists
45+
---
2846

47+
## 🚀 Installation
2948

30-
Create a whitelist.txt file (optional, for bulk entries):
31-
# whitelist.txt
32-
example.com
33-
198.51.100.1
34-
mail.partner-domain.org
49+
1. **Clone the repo**
3550

51+
```bash
52+
git clone https://github.com/Anton-Babaskin/miab-whitelists.git
53+
cd miab-whitelists
54+
```
55+
2. **Create your whitelist file**
3656

37-
Make the script executable:
38-
chmod +x add_whitelists.sh
57+
```text
58+
# whitelist.txt
59+
example.com
60+
198.51.100.0/24
61+
mail.partner-domain.org
62+
```
63+
3. **Make the script executable**
3964

65+
```bash
66+
chmod +x add_whitelists.sh
67+
```
4068

69+
---
4170

42-
🛠️ Configuration
43-
Customize file paths in the script header if needed:
71+
## 🛠️ Configuration
72+
73+
Customize paths in the script header if needed:
74+
75+
```bash
4476
# add_whitelists.sh
4577
POSTFIX_FILE="/etc/postfix/client_whitelist"
4678
POSTGREY_FILE="/etc/postgrey/whitelist_clients.local"
79+
```
80+
81+
---
4782

48-
Ensure /etc/postfix/main.cf includes the Postfix whitelist in smtpd_client_restrictions, e.g.:
49-
smtpd_client_restrictions = ..., check_client_access hash:/etc/postfix/client_whitelist, ...
83+
## ▶️ Usage
5084

51-
▶️ Usage
52-
Add entries from a file
53-
Run the script with a whitelist file:
54-
sudo ./add_whitelists.sh -f whitelist.txt
85+
Run the script with your whitelist file:
5586

56-
Add a single entry
57-
Add a single domain or IP directly:
58-
sudo ./add_whitelists.sh example.com
59-
sudo ./add_whitelists.sh 198.51.100.1
87+
```bash
88+
sudo ./add_whitelists.sh whitelist.txt
89+
```
90+
Quick add: add any single domain or IP with one command, no file needed:
91+
```bash
92+
sudo ./add_whitelists.sh YOURDOMAIN.com
93+
```
94+
**What happens under the hood:**
6095

61-
Dry-run mode
62-
Preview changes without applying them:
63-
sudo ./add_whitelists.sh -n -f whitelist.txt
64-
sudo ./add_whitelists.sh -n example.com
96+
1. Backups:
6597

66-
What happens
98+
```bash
99+
/etc/postfix/client_whitelist.bak_YYYY-MM-DD_HH:MM:SS
100+
/etc/postgrey/whitelist_clients.local.bak_YYYY-MM-DD_HH:MM:SS
101+
```
102+
2. Reads each line:
67103

68-
Backups: Creates timestamped backups of whitelist files (e.g., client_whitelist.bak_YYYY-MM-DD_HHMMSS).
69-
Processing:
70-
Skips empty lines, comments (#), or invalid entries.
71-
Warns about unsupported CIDR entries and skips them.
72-
Adds valid IPs or domains to Postfix (ENTRY OK).
73-
Adds valid domains (not IPs) to Postgrey (ENTRY).
104+
* If missing in Postfix: appends `ENTRY OK`.
105+
* If a domain (not IP/CIDR) and missing in Postgrey: appends `ENTRY`.
106+
3. Applies changes:
74107

108+
```bash
109+
postmap "$POSTFIX_FILE"
110+
systemctl restart postfix
111+
systemctl restart postgrey
112+
```
75113

76-
Application:
77-
Runs postmap on the Postfix whitelist if modified.
78-
Restarts postfix and postgrey services if changes are made.
114+
---
79115

116+
## 🛡️ Backup & Safety
80117

118+
Before making changes, the script creates timestamped backups. To restore from backup:
81119

82-
🛡️ Backup & Safety
83-
The script creates timestamped backups before modifying files. To restore:
84-
sudo cp /etc/postfix/client_whitelist.bak_YYYY-MM-DD_HHMMSS /etc/postfix/client_whitelist
85-
sudo cp /etc/postgrey/whitelist_clients.local.bak_YYYY-MM-DD_HHMMSS /etc/postgrey/whitelist_clients.local
120+
```bash
121+
sudo cp /etc/postfix/client_whitelist.bak_YYYY-MM-DD_HH:MM:SS /etc/postfix/client_whitelist
122+
sudo cp /etc/postgrey/whitelist_clients.local.bak_YYYY-MM-DD_HH:MM:SS /etc/postgrey/whitelist_clients.local
86123
sudo postmap /etc/postfix/client_whitelist
87124
sudo systemctl restart postfix postgrey
125+
```
88126

89-
To automatically delete backups older than 30 days, add to the script or run separately:
127+
**Backup rotation:**
128+
To automatically delete backups older than 30 days, add this line at the end of your script or run it separately:
129+
130+
```bash
90131
find /etc/postfix -name "client_whitelist.bak_*" -mtime +30 -delete
91-
find /etc/postgrey -name "whitelist_clients.local.bak_*" -mtime +30 -delete
132+
```
133+
134+
---
92135

93-
💡 Examples
94-
Bulk add via file
95-
echo -e "partner.com\n198.51.100.1" > whitelist.txt
96-
sudo ./add_whitelists.sh -f whitelist.txt
136+
## 💡 Examples
97137

98-
Single entry
99-
sudo ./add_whitelists.sh mail.example.org
138+
**One-liner:**
100139

101-
Automate via cron
140+
```bash
141+
echo -e "partner.com
142+
198.51.100.0/24" > whitelist.txt
143+
sudo ./add_whitelists.sh whitelist.txt
144+
```
145+
146+
**Automate via cron:**
147+
148+
```cron
102149
# /etc/cron.daily/miab-whitelist
103150
#!/bin/bash
104151
cd /opt/miab-whitelists
105152
git pull --ff-only
106-
/opt/miab-whitelists/add_whitelists.sh -f /opt/miab-whitelists/whitelist.txt
153+
/opt/miab-whitelists/add_whitelists.sh /opt/miab-whitelists/whitelist.txt
154+
```
155+
156+
---
157+
158+
## 🤝 Contributing
159+
160+
Pull requests and issues welcome!
161+
Please follow the standard fork → branch → PR workflow.
107162

108-
⚠️ Notes
163+
---
109164

110-
CIDR Limitation: CIDR notation (e.g., 198.51.100.0/24) is not supported in Postfix hash maps. Use a separate CIDR table in /etc/postfix/main.cf (e.g., check_client_access cidr:/etc/postfix/client_whitelist.cidr).
111-
Validation: The script validates domains and IPv4 addresses, skipping invalid entries with warnings.
112-
Case Handling: Entries are converted to lowercase to ensure consistency.
113-
Main.cf Check: The script checks if client_whitelist is referenced in /etc/postfix/main.cf and warns if missing.
165+
## 📜 License
114166

115-
🤝 Contributing
116-
Contributions are welcome! Please follow the standard fork → branch → pull request workflow. Report issues or suggest improvements via GitHub Issues.
117-
📜 License
118-
MIT © Anton Babaskin. See LICENSE for details.
167+
MIT © Anton Babaskin. See [LICENSE](LICENSE) for details.
168+
![ShellCheck](https://github.com/Anton-Babaskin/miab-whitelists/actions/workflows/shellcheck.yml/badge.svg)

0 commit comments

Comments
 (0)