mirror of
https://github.com/andsyrovatko/s4k-ip-manager.git
synced 2026-04-21 14:08:53 +02:00
54 lines
2.8 KiB
Markdown
54 lines
2.8 KiB
Markdown
# IP Manager for ISPs (Billing ↔ IPSET)
|
|
|
|
### 📋 Overview
|
|
This script acts as a robust bridge between the **BOSS (Billing System)** (or any other billing/CRM) and the **Linux Netfilter (ipset)**. It automates customer access control by dynamically moving IP addresses between different firewall sets based on their current account status.
|
|
|
|
### ⚙️ How It Works
|
|
The system logic relies on two primary IPSET groups:
|
|
* **Allowed (`allowed_customers_nets`)**: IPs in this set are granted full Internet access.
|
|
* **Restricted (`restricted_customers_nets`)**: IPs in this set are redirected to a captive portal (e.g., for billing reminders or payment pages).
|
|
|
|
### 🚀 Commands & Logic Flow
|
|
The billing system invokes this script with specific commands to reflect customer state changes:
|
|
|
|
| Command | Action | Customer Status / Use Case |
|
|
| :--- | :--- | :--- |
|
|
| **`NEW`** | Add IP to *Allowed* | New connection or service activation. |
|
|
| **`RESTRICT`** | Add to *Allowed* + *Restricted* | Balance is zero; redirecting to portal. |
|
|
| **`RESUME`** | Remove from *Restricted* | Payment received; restoring access. |
|
|
| **`SUSPEND`** | Remove from both sets | Manual temporary service suspension. |
|
|
| **`DELETE`** | Remove from both sets | Contract terminated or account closed. |
|
|
| **`UPDATE`** | Swap `OLD_IP` with `NEW_IP` | Change of equipment or static IP address. |
|
|
|
|
### 🛠 Installation & Setup
|
|
1. **Clone the repository:**
|
|
```bash
|
|
git clone [https://github.com/your-username/s4k-ip-manager.git](https://github.com/your-username/s4k-ip-manager.git)
|
|
cd s4k-ip-manager
|
|
```
|
|
2. **Configure the environment:**
|
|
Create your local configuration file from the provided example:
|
|
```bash
|
|
cp ip_manager.conf.example ip_manager.conf
|
|
```
|
|
Edit `ip_manager.conf` to set your specific IPSET names, log paths, and email for alerts.
|
|
3. **Prepare log directories:**
|
|
```bash
|
|
sudo mkdir -p /var/log/ip-manager
|
|
sudo chown $USER:$USER /var/log/ip-manager
|
|
```
|
|
4. **Testing:**
|
|
Before running in production, ensure `DRY_RUN=1` is set in your .conf file to simulate actions without modifying live firewall rules.
|
|
|
|
### 🛡 Reliability & Safety Features
|
|
* **Atomic-like Locking:** Utilizes flock to manage a wait queue, preventing race conditions when the billing system sends hundreds of concurrent updates.
|
|
* **Strict Validation:** Uses regex to validate IPv4 formats and automatically cleans input (e.g., stripping trailing /32 masks).
|
|
* **State Persistence:** Automatically executes ipset save to ensure changes survive a system reboot.
|
|
* **Linter-Friendly:** Fully compliant with ShellCheck (SC1090 handled) for high-quality, predictable execution.
|
|
|
|
### ⚖️ License
|
|
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
|
|
|
|
|
|
### Use at your own risk! The author is not responsible for any data loss!
|