open-isp/docs/RADIUS_MIKROTIK_INTEGRATION.md

Dokumentasi Integrasi RADIUS & MikroTik

📋 Overview

Aplikasi billing ini mendukung dua mode autentikasi PPPoE:

1. Mode MikroTik - PPPoE Secret disimpan di MikroTik (RADIUS offline)
2. Mode RADIUS - PPPoE Secret dikelola oleh RADIUS Server internal (RADIUS aktif)
3. Mode Hybrid - RADIUS aktif tapi beberapa pelanggan tetap menggunakan MikroTik secret

---

🔄 Cara Kerja Saat Tambah/Edit Pelanggan

✅ PRINSIP PENTING:

PPPoE Secret TIDAK PERNAH dihapus dari MikroTik secara otomatis!

Sistem hanya melakukan:

• ✅ CREATE secret baru (jika belum ada)
• ✅ UPDATE profile secret (jika sudah ada)
• ❌ TIDAK menghapus/remove secret dari MikroTik

---

🎯 Logika Sinkronisasi ke MikroTik

1. SAAT RADIUS OFFLINE (radius_enabled = "0")

Semua pelanggan PPPoE WAJIB memiliki secret di MikroTik.

Saat Tambah Pelanggan:

1. Admin input: username, password, package
2. Data disimpan ke database billing
3. Secret OTOMATIS dibuat di MikroTik
4. Profile di-set sesuai package pelanggan

Saat Edit Pelanggan:

1. Admin edit data pelanggan (ganti package, status, dll)
2. Data diupdate di database billing
3. Sistem cek: apakah secret sudah ada di MikroTik?
   - Jika SUDAH ADA: Hanya update PROFILE (tidak hapus!)
   - Jika BELUM ADA: Create secret baru (jika ada password)

2. SAAT RADIUS AKTIF (radius_enabled = "1")

Ada dua kemungkinan per pelanggan:

Mode Full RADIUS (is_radius = 1)

• Pelanggan autentikasi via RADIUS Server
• Secret TIDAK perlu ada di MikroTik
• MikroTik hanya sebagai NAS Client yang forward request ke RADIUS
• Sinkronisasi ke MikroTik: SKIP

Mode Hybrid - Tetap ke MikroTik (is_radius = 0)

• Pelanggan autentikasi langsung dari MikroTik secret
• Secret HARUS ada di MikroTik
• Sinkronisasi ke MikroTik: AKTIF
• Berguna untuk pelanggan khusus yang tidak mau pakai RADIUS

---

🔧 Implementasi Teknis

File yang Dimodifikasi:

• routes/adminPortal.js (route handler tambah/edit pelanggan)

Logika Kode:

// Tentukan apakah harus sync ke MikroTik
const radiusEnabled = getSetting('radius_enabled', '0') === '1';
const isRadius = radiusEnabled ? (req.body.is_radius || 0) : 0;
const shouldSyncToMikrotik = !radiusEnabled || !isRadius;

// Jika shouldSyncToMikrotik = true, maka:
if (shouldSyncToMikrotik) {
  // TAMBAH: Create secret baru ke MikroTik
  // EDIT: Update profile atau create jika belum ada
}

Kondisi Sinkronisasi:

RADIUS Status	is_radius	Sync ke MikroTik?	Keterangan
OFFLINE (0)	-	✅ YA	Selalu ke MikroTik
AKTIF (1)	0	✅ YA	Hybrid mode
AKTIF (1)	1	❌ TIDAK	Full RADIUS

---

📝 Contoh Skenario

Skenario 1: RADIUS Offline (Mode Normal)

Settings: radius_enabled = "0"

TAMBAH PELANGGAN:
- Username: customer01
- Password: pass123
- Package: 10Mbps

HASIL:
✅ Data tersimpan di database billing
✅ Secret dibuat di MikroTik: customer01/pass123
✅ Profile di-set: 10Mbps

EDIT PELANGGAN (Ganti Package ke 20Mbps):
✅ Data diupdate di database
✅ Profile di MikroTik diupdate: 10Mbps → 20Mbps
✅ Secret TIDAK dihapus, tetap ada di MikroTik

Skenario 2: RADIUS Aktif - Full RADIUS Mode

Settings: radius_enabled = "1"
Form: is_radius = 1 (checkbox dicentang)

TAMBAH PELANGGAN:
- Username: customer02
- Password: pass456
- Package: 20Mbps

HASIL:
✅ Data tersimpan di database billing
❌ Secret TIDAK dibuat di MikroTik (RADIUS yang handle)
✅ Pelanggan login via RADIUS Server

EDIT PELANGGAN:
✅ Data diupdate di database
❌ Tidak sync ke MikroTik (RADIUS mode)

Skenario 3: RADIUS Aktif - Hybrid Mode

Settings: radius_enabled = "1"
Form: is_radius = 0 (checkbox TIDAK dicentang)

TAMBAH PELANGGAN:
- Username: customer03
- Password: pass789
- Package: 50Mbps

HASIL:
✅ Data tersimpan di database billing
✅ Secret dibuat di MikroTik (meskipun RADIUS aktif)
✅ Pelanggan login dari MikroTik secret, bukan RADIUS

Berguna untuk:
- Pelanggan VIP yang butuh koneksi stabil
- Testing sebelum migrasi penuh ke RADIUS

---

🛡️ Keamanan & Best Practices

1. Password Management:

• ✅ Password disimpan di database billing
• ✅ Password disimpan di MikroTik secret (saat mode MikroTik)
• ✅ Password di-hash di database RADIUS accounting (aman)

2. Saat Hapus Pelanggan:

// File: services/customerService.js
// Fungsi: deleteCustomer()

// Secret AKAN dihapus dari MikroTik jika:
✅ Pelanggan dihapus dari database
✅ Connection type = pppoe
✅ Ada pppoe_username
✅ Ada router_id

// Ini adalah satu-satunya kondisi secret dihapus otomatis!

3. Saat Ganti Connection Type:

PPPoE → Static IP:
✅ pppoe_username dikosongkan di database
⚠️ Secret TETAP ada di MikroTik (tidak auto-hapus)
💡 Admin perlu hapus manual jika diperlukan

Static IP → PPPoE:
✅ pppoe_username diisi
✅ Secret dibuat baru di MikroTik (jika ada password)

---

🚀 Migrasi dari MikroTik ke RADIUS

Langkah Migrasi Bertahap:

Step 1: Persiapan

1. Pastikan database billing sudah lengkap (username & password)
2. Test RADIUS Server: aktifkan di Admin → RADIUS Settings
3. Setup MikroTik: jalankan script auto-setup dari admin panel
4. Test koneksi 1-2 pelanggan pilot

Step 2: Migrasi Bertahap

1. RADIUS aktif, tapi semua pelanggan is_radius = 0 (hybrid)
2. Pelanggan masih login dari MikroTik secret
3. Test RADIUS dengan mengubah 5-10 pelanggan ke is_radius = 1
4. Monitor stability & performance

Step 3: Full RADIUS

1. Bulk update semua pelanggan: is_radius = 1
2. Semua autentikasi via RADIUS Server
3. Secret di MikroTik bisa dihapus (opsional, untuk cleanup)

Rollback Plan:

Jika ada masalah dengan RADIUS:
1. Set radius_enabled = "0" di settings.json
2. Restart aplikasi
3. Semua pelanggan otomatis kembali ke MikroTik mode
4. Secret masih ada di MikroTik (tidak pernah dihapus)

---

🐛 Troubleshooting

Problem: "Secret tidak dibuat di MikroTik saat tambah pelanggan"

Cek:

1. ✅ RADIUS Status: Apakah RADIUS sedang aktif?

   • Jika YA: Cek checkbox "Mode RADIUS" di form (harus TIDAK dicentang)
   • Jika TIDAK: Seharusnya auto-create

2. ✅ Password: Apakah field password diisi?

   • Jika TIDAK: Secret tidak bisa dibuat
   • Jika YA: Cek error log di logs/error.log

3. ✅ Router: Apakah router MikroTik dipilih dan online?

   • Test koneksi: Admin → MikroTik → Test Connection

4. ✅ Profile: Apakah profile/package ada di MikroTik?

   • Cek: Admin → MikroTik → PPPoE Profiles

Solusi:

# Cek log error
tail -f logs/error.log

# Restart aplikasi
pm2 restart billing-rtrw

Problem: "Secret tidak terupdate saat edit pelanggan"

Cek:

1. ✅ Mode RADIUS: Apakah is_radius = 0? (harus 0 untuk sync ke MikroTik)
2. ✅ Username: Apakah pppoe_username terisi?
3. ✅ Connection Type: Apakah masih PPPoE?

Catatan:

• Update hanya mengubah profile, bukan password
• Jika ingin ganti password, edit langsung di MikroTik

Problem: "Pelanggan tidak bisa login setelah edit"

Kemungkinan:

1. Profile tidak ada di MikroTik
2. Secret terhapus manual dari MikroTik
3. Password berubah di database tapi tidak di MikroTik

Solusi:

1. Cek secret di MikroTik:
   Admin → MikroTik → PPPoE Secrets
   
2. Jika secret hilang:
   - Edit pelanggan
   - Isi password
   - Save (akan create secret baru)
   
3. Jika profile salah:
   - Edit pelanggan
   - Ganti package
   - Save (akan update profile)

---

📊 Monitoring & Logging

Log yang Tercatat:

Saat Tambah Pelanggan:

[Add Customer] Created PPPoE secret "customer01" in MikroTik (RADIUS OFF)
[Add Customer] Updated PPPoE profile for "customer01" to "10Mbps"

Saat Edit Pelanggan:

[Edit Customer] Updated PPPoE profile for "customer01" to "20Mbps"
[Edit Customer] Created NEW PPPoE secret for "customer02" in MikroTik

Saat Hapus Pelanggan:

[DELETE] Attempting to remove PPPoE secret: customer01 from router 1
[DELETE] Successfully removed PPPoE secret for customer01 from MikroTik

Lokasi File Log:

logs/combined.log  - Semua log aplikasi
logs/error.log     - Error saja

---

🎓 Kesimpulan

Yang Perlu Diingat:

1. ✅ PPPoE Secret TIDAK PERNAH dihapus otomatis saat edit pelanggan
2. ✅ RADIUS offline = semua ke MikroTik (auto-create/update)
3. ✅ RADIUS aktif = bisa hybrid (sebagian RADIUS, sebagian MikroTik)
4. ✅ Edit hanya update profile, bukan hapus secret
5. ✅ Hapus pelanggan = secret dihapus (satu-satunya kondisi auto-delete)

Keuntungan Desain Ini:

• 🔒 Aman: Secret tidak hilang karena salah edit
• 🔄 Fleksibel: Bisa RADIUS, MikroTik, atau hybrid
• 📈 Scalable: Mudah migrasi bertahap ke RADIUS
• 🛡️ Rollback: Bisa kembali ke MikroTik mode kapan saja

---

📞 Support

Jika ada pertanyaan atau masalah, hubungi developer atau cek dokumentasi lengkap di:

• README.md
• FITUR_APLIKASI_LENGKAP.md
• AUDIT_SECURITY_2026.md

---

Dibuat: 18 Agustus 2026
Versi: 1.0
Last Update: 18 Agustus 2026