DANYDHSV/siip-available-ips
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
0be508e749
siip-available-ips/README.md

14 KiB
Raw Blame History

SIIP - Buscador de IP's Disponibles UISP

Version UCRM UNMS

Plugin para UISP CRM (anteriormente UCRM) que permite buscar direcciones IP disponibles en la red UISP/UNMS y asignarlas a clientes, evitando duplicados y mejorando la gestión de direcciones IP.

📋 Tabla de Contenidos

✨ Características

  • 🔍 Búsqueda de IPs disponibles por segmento de red (172.16.X.x)
  • 🌐 Interfaz web moderna con diseño responsive y atractivo
  • 🔌 API REST completa para integraciones externas
  • 📋 Copiar al portapapeles con un solo clic
  • 🎯 Filtrado inteligente de IPs administrativas vs. IPs para clientes
  • 📊 Estadísticas en tiempo real de IPs disponibles y en uso
  • 🔐 Integración nativa con UISP CRM y UNMS
  • 🪝 Soporte para webhooks y eventos personalizados
  • 📝 Sistema de logs detallado para debugging

📦 Requisitos

  • UISP CRM versión 1.0.0 o superior
  • UISP UNMS versión 1.0.0 o superior (opcional)
  • PHP 7.2 o superior
  • cURL habilitado en PHP
  • Token de API de UCRM
  • Token de API de UNMS (opcional, para búsqueda de IPs)

🚀 Instalación

Método 1: Instalación Manual

  1. Descarga o clona este repositorio
  2. Comprime la carpeta del plugin en formato .zip
  3. En UISP CRM, ve a Sistema → Plugins
  4. Haz clic en "Subir nuevo plugin"
  5. Selecciona el archivo .zip y súbelo
  6. Activa el plugin desde la lista de plugins

Método 2: Instalación desde Git

cd /path/to/ucrm/data/plugins/
git clone <repository-url> siip-available-ips
cd siip-available-ips
composer install

⚙️ Configuración

Después de instalar el plugin, configura los siguientes parámetros:

Parámetros Requeridos

Parámetro Descripción Ejemplo
Dirección IP o dominio del servidor IP o dominio donde se ejecuta UISP CRM 172.16.5.120 o sistema.empresa.com
Token de la API UCRM Token de autenticación de UCRM (36 caracteres) 3d3fa6c9-e268-6e8b-b4d5-aae394d99d7d

Parámetros Opcionales

Parámetro Descripción Uso
Token de la API UNMS Token de UNMS (34 caracteres) Para búsqueda de IPs en dispositivos de red
Debug Mode Modo de depuración Habilita logs más detallados
Enable debug logs Logs verbosos Información adicional en logs

Cómo obtener los tokens:

Token UCRM:

  1. Ve a Sistema → Seguridad → Claves de aplicación
  2. Crea una nueva clave con permisos de lectura/escritura
  3. Copia el token generado

Token UNMS:

  1. Accede al módulo UISP Network
  2. Ve a Ajustes → Usuarios → API Tokens
  3. Genera un nuevo token
  4. Copia el token generado

🖥️ Uso del Frontend Web

Acceso

El frontend web está disponible en:

  • Menú UCRM: Reportes → Consultar IP's Disponibles
  • URL directa: https://tu-servidor/plugins/siip-available-ips/public.php

Interfaz de Usuario

La interfaz incluye:

  1. Campo de búsqueda: Ingresa el tercer octeto del segmento (ej: 5 para buscar en 172.16.5.x)
  2. Botón "Buscar IPs": Ejecuta la búsqueda
  3. Tabla de resultados: Muestra las IPs disponibles con:
    • Dirección IP completa
    • Tipo de IP (Cliente / Administración)
    • Botón de copiar al portapapeles
  4. Estadísticas: Muestra contadores de IPs disponibles y en uso

Ejemplo de Uso

1. Ingresa "5" en el campo de búsqueda
2. Haz clic en "Buscar IPs"
3. Se mostrarán todas las IPs disponibles en el rango 172.16.5.x
4. Haz clic en el botón "Copiar" junto a la IP deseada
5. La IP se copia automáticamente al portapapeles

🔌 API REST

El plugin expone una API REST completa para integraciones externas, webhooks y automatizaciones.

Configuración Base

  • URL Base: https://tu-servidor/plugins/siip-available-ips/public.php
  • Método: POST
  • Content-Type: application/json
  • Autenticación: No requerida (el plugin usa los tokens configurados internamente)

Endpoints Disponibles

1. Buscar IPs Disponibles

Busca todas las IPs disponibles en un segmento de red específico.

Evento: event.ip_request

Request:

{
  "type": "event.ip_request",
  "segment": "5"
}

Response (Éxito):

{
  "success": true,
  "event": "event.ip_request",
  "segment": "172.16.5.x",
  "data": {
    "available": [
      "172.16.5.31",
      "172.16.5.32",
      "172.16.5.33"
    ],
    "used": [
      "172.16.5.1",
      "172.16.5.2"
    ]
  },
  "count": {
    "available": 223,
    "used": 31,
    "admin_filtered": 31
  },
  "message": "Se encontraron 223 IPs aptas para clientes en el segmento 172.16.5.x (31 IPs administrativas filtradas)"
}

Parámetros:

  • type (string, requerido): Tipo de evento, debe ser "event.ip_request"
  • segment (string, requerido): Tercer octeto del segmento (0-255)

Notas:

  • Las IPs administrativas (1-30 y 254) son filtradas automáticamente
  • Solo se devuelven IPs aptas para asignar a clientes (31-253)

2. Verificar Estado de una IP

Verifica si una IP específica está disponible o en uso.

Evento: event.ip_check

Request:

{
  "type": "event.ip_check",
  "ip": "172.16.5.100"
}

Response (IP Disponible):

{
  "success": true,
  "event": "event.ip_check",
  "ip": "172.16.5.100",
  "status": "available",
  "available": true,
  "used": false,
  "ip_type": {
    "type": "client",
    "label": "Apta para cliente",
    "recommended": true,
    "description": "Recomendada para asignar a clientes"
  }
}

Response (IP en Uso):

{
  "success": true,
  "event": "event.ip_check",
  "ip": "172.16.5.1",
  "status": "IP en uso y además para uso administrativo",
  "available": false,
  "used": true,
  "ip_type": {
    "type": "admin",
    "label": "Administración",
    "recommended": false,
    "description": "No recomendada para clientes"
  }
}

Parámetros:

  • type (string, requerido): Tipo de evento, debe ser "event.ip_check"
  • ip (string, requerido): Dirección IP completa en formato 172.16.X.X

Ejemplos de Uso

cURL - Buscar IPs Disponibles

curl -X POST https://tu-servidor/plugins/siip-available-ips/public.php \
  -H "Content-Type: application/json" \
  -d '{
    "type": "event.ip_request",
    "segment": "5"
  }'

cURL - Verificar IP Específica

curl -X POST https://tu-servidor/plugins/siip-available-ips/public.php \
  -H "Content-Type: application/json" \
  -d '{
    "type": "event.ip_check",
    "ip": "172.16.5.100"
  }'

PHP - Buscar IPs Disponibles

<?php
$url = 'https://tu-servidor/plugins/siip-available-ips/public.php';
$data = [
    'type' => 'event.ip_request',
    'segment' => '5'
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
print_r($result);
?>

JavaScript/Node.js - Verificar IP

const axios = require('axios');

const checkIp = async (ip) => {
  try {
    const response = await axios.post(
      'https://tu-servidor/plugins/siip-available-ips/public.php',
      {
        type: 'event.ip_check',
        ip: ip
      },
      {
        headers: {
          'Content-Type': 'application/json'
        }
      }
    );
    
    console.log(response.data);
  } catch (error) {
    console.error('Error:', error.message);
  }
};

checkIp('172.16.5.100');

Python - Buscar IPs Disponibles

import requests
import json

url = 'https://tu-servidor/plugins/siip-available-ips/public.php'
payload = {
    'type': 'event.ip_request',
    'segment': '5'
}

response = requests.post(
    url,
    json=payload,
    headers={'Content-Type': 'application/json'},
    verify=False
)

result = response.json()
print(json.dumps(result, indent=2))

Códigos de Error

Código Descripción Solución
Missing event type No se especificó el campo type Incluye "type" en el JSON
Unknown event type Tipo de evento no soportado Usa event.ip_request o event.ip_check
Missing segment Falta el campo segment Incluye "segment" en el request
Missing IP address Falta el campo ip Incluye "ip" en el request
Invalid IP format Formato de IP inválido Usa formato 172.16.X.X
Plugin not configured Configuración incompleta Verifica tokens en configuración del plugin
IP search failed Error en búsqueda Revisa logs del plugin

📁 Estructura del Proyecto

siip-available-ips/
├── manifest.json              # Configuración del plugin
├── composer.json              # Dependencias PHP
├── main.php                   # Punto de entrada principal
├── public.php                 # Frontend web + API REST
├── README.md                  # Este archivo
├── src/                       # Código fuente
│   ├── ApiHandlers.php        # Manejadores de API REST
│   └── IpSearchService.php    # Servicio de búsqueda de IPs
├── data/                      # Datos del plugin
│   ├── config.json            # Configuración (generado automáticamente)
│   └── plugin.log             # Archivo de logs
└── vendor/                    # Dependencias de Composer

Archivos Principales

public.php

  • Punto de entrada para frontend web y API REST
  • Detecta automáticamente el tipo de petición (HTML vs JSON)
  • Maneja errores globales y logging

src/ApiHandlers.php

Funciones para manejar peticiones API:

  • handleApiRequest(): Router principal de eventos
  • handleIpRequest(): Procesa event.ip_request
  • handleIpCheck(): Procesa event.ip_check

src/IpSearchService.php

Clase de servicio para búsqueda de IPs:

  • buscarIpsDisponibles(): Busca IPs en un segmento
  • obtenerIpsEnUso(): Obtiene IPs desde API UNMS
  • isAdminIp(): Determina si una IP es administrativa
  • getIpType(): Obtiene información del tipo de IP

🎯 Filtrado de IPs Administrativas

El plugin implementa un sistema inteligente de filtrado de IPs:

Rangos de IPs

Rango Tipo Uso Recomendación
.1 - .30 Administrativa Gateways, servidores, equipos de red ❌ No asignar a clientes
.31 - .253 Cliente Dispositivos de clientes finales ✅ Apto para clientes
.254 Broadcast Dirección de broadcast ❌ No asignar

Comportamiento

  • Frontend Web: Muestra todas las IPs con etiquetas de tipo
  • API REST: Filtra automáticamente IPs administrativas
  • event.ip_check: Indica el tipo de IP en la respuesta

📝 Logs y Debugging

Ubicación de Logs

Los logs se guardan en:

/data/plugin.log

Habilitar Debug Mode

  1. Ve a la configuración del plugin
  2. Activa "Debug Mode"
  3. Activa "Enable debug logs"
  4. Los logs incluirán información detallada de:
    • Peticiones recibidas
    • Respuestas de API UNMS
    • Errores y excepciones
    • Tiempos de ejecución

Ejemplo de Log

[2025-11-26 11:30:15] >>> Petición recibida en public.php
[2025-11-26 11:30:15] Método: POST
[2025-11-26 11:30:15] Content-Type: application/json
[2025-11-26 11:30:15] Procesando evento API: event.ip_request
[2025-11-26 11:30:15] API: Buscando IPs en segmento 5
[2025-11-26 11:30:16] Respuesta HTTP: 200
[2025-11-26 11:30:16] IPs obtenidas exitosamente: 254 direcciones
[2025-11-26 11:30:16] Búsqueda de IPs en segmento 172.16.5.x - Disponibles: 223, En uso: 31

📜 Changelog

Para ver el historial completo de cambios y versiones, consulta el archivo CHANGELOG.md.

Versión Actual: 1.1.0 (2025-11-26)

Cambios destacados:

  • ✨ API REST completa con endpoints event.ip_request y event.ip_check
  • 🔌 Soporte para webhooks y eventos personalizados
  • 🎯 Filtrado automático de IPs administrativas
  • 📚 Documentación completa con ejemplos en múltiples lenguajes

Ver changelog completo →

🆘 Soporte

Problemas Comunes

Error: "Plugin not configured"

Solución: Verifica que hayas configurado correctamente los tokens de API en la configuración del plugin.

Error: "Error al conectar con la API de UISP"

Solución:

  • Verifica que el servidor UNMS esté accesible
  • Comprueba que el token de API UNMS sea válido
  • Revisa los logs para más detalles

No se muestran IPs disponibles

Solución:

  • Verifica que el segmento ingresado sea válido (0-255)
  • Comprueba que existan dispositivos en ese segmento en UNMS
  • Revisa los logs con debug mode activado

Contacto

📄 Licencia

Este plugin es propiedad de SIIP Internet. Todos los derechos reservados.

🙏 Agradecimientos

  • Equipo de UISP/Ubiquiti por la plataforma
  • Comunidad de desarrolladores de plugins UCRM

Versión: 1.1.0
Última actualización: 26 de noviembre de 2025