mirror of
https://github.com/MrUnknownDE/internetx-ddns-updater.git
synced 2026-04-23 08:43:45 +02:00
383 lines
9.0 KiB
Markdown
383 lines
9.0 KiB
Markdown
# 🌐 InterNetX DDNS Updater
|
|
|
|
Ein moderner DDNS-Service für InterNetX AutoDNS, der es Routern ermöglicht, DNS-Records automatisch zu aktualisieren.
|
|
|
|
[](https://nodejs.org/)
|
|
[](LICENSE)
|
|
|
|
---
|
|
|
|
## ✨ Features
|
|
|
|
- 🔒 **Sicherheit**: Token-Authentifizierung, Rate Limiting, Helmet.js Security Headers
|
|
- 🌍 **IPv4 & IPv6**: Unterstützung für beide IP-Protokolle
|
|
- 🚀 **InterNetX Integration**: Nutzt das offizielle `js-domainrobot-sdk`
|
|
- 📊 **Logging**: Winston Logger mit täglicher Log-Rotation
|
|
- 🐳 **Docker**: Production-ready Container mit Multi-Stage Build
|
|
- 🎯 **Router-Kompatibel**: Getestet mit DrayTek Vigor-Serie
|
|
|
|
---
|
|
|
|
## 📋 Voraussetzungen
|
|
|
|
- Node.js >= 24.0.0
|
|
- npm >= 10.0.0
|
|
- InterNetX AutoDNS Account mit API-Zugang
|
|
- Domain/Zone in InterNetX AutoDNS
|
|
|
|
---
|
|
|
|
## 🚀 Installation
|
|
|
|
### Option 1: Node.js (Lokal)
|
|
|
|
```bash
|
|
# Repository klonen
|
|
git clone https://github.com/MrUnknownDE/internetx-ddns-updater.git
|
|
cd internetx-ddns-updater
|
|
|
|
# Dependencies installieren
|
|
npm install
|
|
|
|
# .env Datei erstellen
|
|
cp .env.example .env
|
|
|
|
# .env mit deinen Credentials bearbeiten
|
|
# Siehe Konfiguration weiter unten
|
|
|
|
# Server starten
|
|
npm start
|
|
```
|
|
|
|
### Option 2: Docker
|
|
|
|
```bash
|
|
# .env Datei erstellen
|
|
cp .env.example .env
|
|
|
|
# docker-compose starten
|
|
docker-compose up -d
|
|
|
|
# Logs anzeigen
|
|
docker-compose logs -f
|
|
```
|
|
|
|
---
|
|
|
|
## ⚙️ Konfiguration
|
|
|
|
Bearbeite die `.env` Datei mit deinen Einstellungen:
|
|
|
|
### Erforderliche Einstellungen
|
|
|
|
```env
|
|
# InterNetX API Credentials
|
|
INTERNETX_USER=dein-username
|
|
INTERNETX_PASSWORD=dein-passwort
|
|
INTERNETX_CONTEXT=4
|
|
|
|
# DDNS Zone
|
|
DEFAULT_ZONE=ddns.netstack.berlin
|
|
|
|
# Authentifizierungs-Tokens (mind. 1 Token erforderlich)
|
|
# Token generieren: node -e "console.log(require('crypto').randomBytes(64).toString('hex'))"
|
|
AUTH_TOKENS=dein-token-hier,noch-ein-token
|
|
```
|
|
|
|
### Optionale Einstellungen
|
|
|
|
```env
|
|
# Server
|
|
PORT=3000
|
|
NODE_ENV=production
|
|
|
|
# InterNetX API URL (Standard ist OK)
|
|
INTERNETX_API_URL=https://api.autodns.com/v1
|
|
|
|
# DNS TTL (in Sekunden)
|
|
DEFAULT_TTL=300
|
|
|
|
# IP Whitelist (optional, leer = alle IPs erlaubt)
|
|
IP_WHITELIST=
|
|
|
|
# Rate Limiting
|
|
RATE_LIMIT_WINDOW_MS=300000 # 5 Minuten
|
|
RATE_LIMIT_MAX_REQUESTS=20 # Max 20 Anfragen pro IP
|
|
|
|
# Logging
|
|
LOG_LEVEL=info
|
|
LOG_FILE_MAX_SIZE=10m
|
|
LOG_FILE_MAX_AGE=30d
|
|
```
|
|
|
|
---
|
|
|
|
## 🔑 Token Generierung
|
|
|
|
Generiere sichere Tokens mit Node.js:
|
|
|
|
```bash
|
|
node -e "console.log(require('crypto').randomBytes(64).toString('hex'))"
|
|
```
|
|
|
|
Kopiere das generierte Token in deine `.env` Datei unter `AUTH_TOKENS`.
|
|
|
|
---
|
|
|
|
## 📡 Router-Konfiguration
|
|
|
|
### DrayTek Vigor-Serie (2927, 3910, etc.)
|
|
|
|
1. **Router-Admin öffnen**: Login in die Web-Oberfläche
|
|
2. **DDNS konfigurieren**: `Applications` → `Dynamic DNS`
|
|
3. **Einstellungen**:
|
|
- **Provider**: Custom DDNS
|
|
- **Server/Provider**: `ddns.netstack.berlin` (oder deine Domain)
|
|
- **Hostname**: `@HOSTNAME@` (z.B. `home.ddns.netstack.berlin`)
|
|
- **URL**: `/update?hostname=@HOSTNAME@&myip=@IP@&token=DEIN_TOKEN_HIER`
|
|
- **Port**: `443` (HTTPS)
|
|
|
|
4. **Test**: Klicke auf den Test-Button
|
|
|
|
### Andere Router
|
|
|
|
Die meisten Router unterstützen "Custom DDNS" mit diesen Parametern:
|
|
|
|
- **URL-Format**: `https://ddns.netstack.berlin/update?hostname=<hostname>&myip=<ip>&token=<token>`
|
|
- **Parameter**:
|
|
- `hostname`: Voller Hostname (z.B. `home.ddns.netstack.berlin`)
|
|
- `myip`: IPv4-Adresse (optional, wird automatisch erkannt)
|
|
- `myipv6`: IPv6-Adresse (optional)
|
|
- `token`: Dein Authentifizierungs-Token
|
|
|
|
---
|
|
|
|
## 🔒 Sicherheit
|
|
|
|
### HTTPS ist PFLICHT!
|
|
|
|
⚠️ **WICHTIG**: Der Service MUSS hinter HTTPS laufen!
|
|
|
|
#### Nginx Reverse Proxy Beispiel
|
|
|
|
```nginx
|
|
server {
|
|
listen 443 ssl http2;
|
|
server_name ddns.netstack.berlin;
|
|
|
|
ssl_certificate /etc/letsencrypt/live/ddns.netstack.berlin/fullchain.pem;
|
|
ssl_certificate_key /etc/letsencrypt/live/ddns.netstack.berlin/privkey.pem;
|
|
ssl_protocols TLSv1.2 TLSv1.3;
|
|
|
|
location / {
|
|
proxy_pass http://localhost:3000;
|
|
proxy_set_header X-Real-IP $remote_addr;
|
|
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
|
proxy_set_header X-Forwarded-Proto $scheme;
|
|
}
|
|
}
|
|
```
|
|
|
|
#### Caddy Reverse Proxy (einfacher)
|
|
|
|
```caddy
|
|
ddns.netstack.berlin {
|
|
reverse_proxy localhost:3000
|
|
}
|
|
```
|
|
|
|
Caddy holt automatisch Let's Encrypt Zertifikate! 🎉
|
|
|
|
### Sicherheitsmaßnahmen
|
|
|
|
- ✅ Token-basierte Authentifizierung (256-Bit Entropie)
|
|
- ✅ Rate Limiting (20 Anfragen / 5 Minuten pro IP)
|
|
- ✅ Input Validation (Joi-Schemas)
|
|
- ✅ Helmet.js Security Headers
|
|
- ✅ IP-Whitelisting (optional)
|
|
- ✅ Audit-Logging aller Anfragen
|
|
|
|
---
|
|
|
|
## 📚 API-Dokumentation
|
|
|
|
### `GET/POST /update`
|
|
|
|
Update DNS-Record für DDNS.
|
|
|
|
#### Parameter
|
|
|
|
| Parameter | Typ | Erforderlich | Beschreibung |
|
|
|-----------|-----|--------------|--------------|
|
|
| `hostname` | string | ✅ | Voller Hostname (z.B. `home.ddns.netstack.berlin`) |
|
|
| `myip` | string | ⚠️ | IPv4-Adresse (optional, auto-detect wenn leer) |
|
|
| `myipv6` | string | ⚠️ | IPv6-Adresse (optional) |
|
|
| `token` | string | ✅ | Authentifizierungs-Token |
|
|
|
|
⚠️ Mindestens eine IP (`myip` oder `myipv6`) erforderlich, oder keine (dann Client-IP)
|
|
|
|
#### Beispiel-Anfragen
|
|
|
|
```bash
|
|
# IPv4 Update
|
|
curl "https://ddns.netstack.berlin/update?hostname=home.ddns.netstack.berlin&myip=1.2.3.4&token=YOUR_TOKEN"
|
|
|
|
# IPv6 Update
|
|
curl "https://ddns.netstack.berlin/update?hostname=home.ddns.netstack.berlin&myipv6=2001:db8::1&token=YOUR_TOKEN"
|
|
|
|
# Beide gleichzeitig
|
|
curl "https://ddns.netstack.berlin/update?hostname=home.ddns.netstack.berlin&myip=1.2.3.4&myipv6=2001:db8::1&token=YOUR_TOKEN"
|
|
|
|
# Auto-Detect (Client-IP)
|
|
curl "https://ddns.netstack.berlin/update?hostname=home.ddns.netstack.berlin&token=YOUR_TOKEN"
|
|
```
|
|
|
|
#### Success Response
|
|
|
|
```json
|
|
{
|
|
"status": "success",
|
|
"message": "DNS record updated successfully",
|
|
"hostname": "home.ddns.netstack.berlin",
|
|
"updates": [
|
|
{
|
|
"type": "A",
|
|
"action": "updated",
|
|
"value": "1.2.3.4"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
#### Error Response
|
|
|
|
```json
|
|
{
|
|
"status": "error",
|
|
"message": "Authentication failed"
|
|
}
|
|
```
|
|
|
|
### `GET /health`
|
|
|
|
Health Check Endpoint für Monitoring.
|
|
|
|
```bash
|
|
curl http://localhost:3000/health
|
|
```
|
|
|
|
```json
|
|
{
|
|
"status": "healthy",
|
|
"service": "ddns-updater",
|
|
"version": "1.0.0",
|
|
"uptime": 12345.67
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 🐛 Troubleshooting
|
|
|
|
### Router sendet keine Updates
|
|
|
|
1. **HTTPS Zertifikat prüfen**: Self-Signed Certs funktionieren oft nicht!
|
|
2. **Token überprüfen**: In `.env` und Router-Konfiguration identisch?
|
|
3. **Logs checken**: `docker-compose logs -f` oder `logs/combined-*.log`
|
|
4. **Router-Test**: Nutze die Test-Funktion des Routers
|
|
|
|
### DNS-Record wird nicht aktualisiert
|
|
|
|
1. **InterNetX Credentials**: Login in AutoDNS Control Panel testen
|
|
2. **Zone existiert**: Ist die Zone in InterNetX vorhanden?
|
|
3. **Berechtigungen**: Hat der API-User DNS-Rechte?
|
|
4. **Logs prüfen**: Fehler in `logs/error-*.log`?
|
|
|
|
### Rate Limit Errors
|
|
|
|
- **Standard**: 20 Anfragen / 5 Minuten
|
|
- **Lösung**: `RATE_LIMIT_MAX_REQUESTS` in `.env` erhöhen
|
|
- **Hinweis**: Router machen oft mehrere Retries bei Fehlern
|
|
|
|
### "Zone not found" Fehler
|
|
|
|
- `DEFAULT_ZONE` in `.env` muss exakt mit InterNetX Zone übereinstimmen
|
|
- Zone muss in AutoDNS existieren und aktiv sein
|
|
|
|
---
|
|
|
|
## 📁 Projektstruktur
|
|
|
|
```
|
|
internetx-ddns-updater/
|
|
├── src/
|
|
│ ├── config/
|
|
│ │ └── config.js # Konfiguration & Validierung
|
|
│ ├── middleware/
|
|
│ │ ├── auth.middleware.js
|
|
│ │ ├── validation.middleware.js
|
|
│ │ └── rateLimiter.middleware.js
|
|
│ ├── routes/
|
|
│ │ └── update.route.js # DDNS Update Endpoint
|
|
│ ├── services/
|
|
│ │ ├── internetx.service.js # InterNetX API Integration
|
|
│ │ └── ddns.service.js # DDNS Business Logic
|
|
│ ├── utils/
|
|
│ │ ├── logger.js # Winston Logger
|
|
│ │ └── ipHelper.js # IP-Validierung
|
|
│ └── index.js # Express App Entry
|
|
├── public/
|
|
│ ├── index.html # Easter Egg Homepage
|
|
│ └── logo.png # Dein Logo hier
|
|
├── logs/ # Log-Dateien (auto-generiert)
|
|
├── .env.example # Konfiguration Example
|
|
├── package.json
|
|
├── Dockerfile
|
|
└── docker-compose.yml
|
|
```
|
|
|
|
---
|
|
|
|
## 🏗️ Development
|
|
|
|
```bash
|
|
# Development Mode (mit Nodemon)
|
|
npm run dev
|
|
|
|
# Tests ausführen (wenn implementiert)
|
|
npm test
|
|
|
|
# Linting
|
|
npm run lint
|
|
```
|
|
|
|
---
|
|
|
|
## 🌟 Easter Egg
|
|
|
|
Besuche die Homepage des Services im Browser: `https://ddns.netstack.berlin/`
|
|
|
|
Du findest eine nette Überraschung! 🎉
|
|
|
|
---
|
|
|
|
## 📄 Lizenz
|
|
|
|
MIT License - siehe [LICENSE](LICENSE) Datei
|
|
|
|
---
|
|
|
|
## 🤝 Support
|
|
|
|
Bei Fragen oder Problemen:
|
|
|
|
- **Issues**: [GitHub Issues](https://github.com/netstack/internetx-ddns-updater/issues)
|
|
- **Email**: support@netstack.berlin
|
|
- **Website**: [netstack.berlin](https://www.netstack.berlin)
|
|
|
|
---
|
|
|
|
## 👨💻 Made with ❤️ by [Netstack GmbH](https://www.netstack.berlin)
|
|
|
|
**Interesse an coolen Projekten?** [Wir stellen ein!](https://www.netstack.berlin/karriere)
|