2.8 KiB
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
- Clone the repository:
git clone [https://github.com/your-username/s4k-ip-manager.git](https://github.com/your-username/s4k-ip-manager.git) cd s4k-ip-manager - Configure the environment:
Create your local configuration file from the provided example:
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 file for details.