# 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!