Initial release: Billing infrastructure automation (IP manager).

README.md

@@ -0,0 +1,53 @@
+# 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!