ip2nginx/README.md

ip2nginx

---

💡 Project Overview

ip2nginx is a lightweight and secure system for dynamically updating NGINX reverse proxy configurations based on public IP address changes, typically reported by edge devices like pfSense. It ensures that NGINX always routes traffic through the correct IP, even in dynamic environments.

---

📚 Table of Contents

• 💡 Project Overview
• ⚙️ Features
• 📁 Project Structure
• 🚀 Update Process: update.php
• 🚀 Update Process: updater.php
• 🛠 Environment Setup: check_env.php
• 📅 Cron Setup with run.sh
• 🔄 Usage Example from pfSense
• ✅ Example Entry in token.json
• ✅ Example Entry in meta.json
• 🛡 Security
• ✅ Requirements
• 📜 License
• 🤝 Author

---

⚙️ Features

• Accepts remote updates via update.php using token-authenticated requests.
• Supports both POST and GET, though POST is preferred to avoid token caching.
• Updates only the proxy_pass line in the relevant location block of nginx.conf.
• Automatically marks entries in meta.json as "changed": 1 when input changes.
• Logs all changes to log.json with timestamps.
• Automatically reloads NGINX: nginx -t && systemctl reload nginx (requires root).
• Built-in abuse protection: failed requests tracked and blocked.
• .htaccess ensures that only update.php is externally accessible.

---

📁 Project Structure

ip2nginx/
├── index.php             # Shared configuration and fallback error handler
├── update.php            # Receives incoming remote IP update requests
├── updater.php           # CLI-only: applies changes to nginx.conf if marked
├── run.sh                # Wrapper script for cron automation
├── check_env.php         # Environment validator and bootstrapper
├── .htaccess             # Blocks unauthorized access, routes traffic
├── data/
│   ├── meta.json         # Stores current configuration state per domain
│   ├── token.json        # Stores allowed tokens (auth)
│   ├── log.json          # Stores audit log of changes
│   ├── blocklist.json    # Temporarily blocked IPs (48h ban)
│   └── failures.json     # Tracks failed attempts per IP

---

🌐 Remote Update API: update.php

Supports POST (preferred) and GET methods.

Parameter	Required	Description
name	✅	Identifier (e.g. domain1.to.com)
token	✅	Secret token assigned for this name
ip	❌	New public IP (default: auto-detected from request)
domain	❌	Backend domain to proxy to (default: same as IP)
port	❌	Port number (default: 443 for https, 80 for http)
protocol	❌	One of http or https (default: http)
location	❌	NGINX location block path to update (default: /)

Any change in ip, domain, port, or protocol triggers "changed": 1 in meta.json.

If any parameter is received via GET, then ip and domain will be overridden with the client’s real IP for security.

---

🧩 Update Process: updater.php

To apply updates made via update.php:

1. Load all entries from meta.json
2. Check for entries marked "changed": 1
3. Find /var/www/vhosts/system/<domain>/conf/nginx.conf
4. Modify the appropriate location block’s proxy_pass directive only
5. Validate and reload NGINX
6. Reset "changed": 0

---

🛠 check_env.php: Environment Setup

This CLI script validates:

• Config files and permissions
• JSON structure of each config file
• Auto-creates missing files (with defaults)
• Token file includes example if missing

---

⏱ Cron Setup: run.sh

To automate updates, add run.sh to your crontab as root:

sudo crontab -e

Then add:

*/5 * * * * /path/to/ip2nginx/run.sh

This ensures automatic application of proxy changes to NGINX config and reloads.

---

🔄 pfSense Shell Example

Add the following script to pfSense via System > Advanced > Cron:

#!/bin/sh

SERVER="https://your-server.com/ip2nginx"
NAME="domain1.to.com"
DOMAIN="domain.from.com"
TOKEN="YOUR_SECRET_TOKEN"

curl -s -X POST "$SERVER/update.php"   -d "name=$NAME"   -d "domain=$DOMAIN"   -d "protocol=https"   -d "port=443"   -d "token=$TOKEN"

---

✅ Example: token.json

{
  "domain1.to.com": "SECRET_TOKEN_8v73jDKsdLzAq9DkeUz1",
  "domain2.to.com": "SECRET_TOKEN_3im83jUj28mjo2mI23un"
}

---

✅ Example: meta.json

{
  "domain1.to.com": {
    "domain": "domain.from.com",
    "ip": "192.0.2.4",
    "port": "443",
    "protocol": "https",
    "location": "/",
    "time": "2025-05-16T09:00:00+00:00",
    "changed": 1
  }
}

---

🔒 Security Highlights

• .htaccess denies access to all files except update.php.
• Only HTTPS connections should be used.
• All tokens are stored securely and verified per name.
• After 3 failed attempts, IP is banned for 48 hours.
• Generic error messages avoid leaking details to attackers.

---

✅ Requirements

• PHP 7.4 or newer
• NGINX with reload access (sudo systemctl reload nginx)
• curl on the client side
• Token definitions in token.json

---

📜 License

MIT (or similar): Open-source, free for use and modification.

---

🤝 Author

Maintained by SAFE-CAP / Alexander Schiemann