opengnsys
/
ogboot
2
0
Fork 0
Code Issues Pull Requests 2 Packages Projects Releases Wiki Activity
ogboot/docs/ogboot-ogcore-communication...

49 KiB
Raw Permalink Blame History

Documentación de Ogboot

1. Descripción General del Componente

  • 1.1 Introducción
  • 1.2 Funcionalidades
    • 1.2.1 Gestión de Imágenes de Arranque (ogLive)
    • 1.2.2 Monitoreo y Configuración
    • 1.2.3 Interfaz de Programación de Aplicaciones (API)
  • 1.3 Arquitectura General
    • 1.3.1 Componentes Principales
    • 1.3.2 Estructura del Proyecto
    • 1.3.3 Interacción entre Componentes
    • 1.3.4 Seguridad y Permisos

2. Instalación

  • 2.1 Requisitos Previos
    • 2.1.1 Software Necesario
    • 2.1.2 Hardware Requerido
    • 2.1.3 Permisos y Configuraciones Previas
  • 2.2 Instrucciones de Instalación
    • 2.2.1 Descarga del Software
    • 2.2.2 Instalación Paso a Paso
    • 2.2.3 Configuración Inicial

3. Endpoints y API

  • 3.1 Listado de Endpoints
    • 3.1.1 Métodos y Rutas
    • 3.1.2 Descripciones de los Endpoints
  • 3.2 Ejemplos de Solicitudes y Respuestas
  • 3.3 Manejo de Errores Comunes
  • 3.4 Middleware y Autenticación

4. Configuración del Servidor

  • 4.1 Configuración de Nginx
  • 4.2 Configuración de PHP-FPM
  • 4.3 Creación y Levantamiento del Demonio ogboot
  • 4.4 Configuración de Usuarios y Permisos

5. Funciones del CLI (oglivecli)

  • 5.1 Descripción de las Funciones
  • 5.2 Ejemplos de Uso
  • 5.3 Interacción con el Sistema y el Demonio

6. Integración con Otros Sistemas

  • 6.1 Integración con TFTP
  • 6.2 Configuración de PXE
  • 6.3 Otros Servicios y Configuraciones

7. Seguridad

  • 7.1 Consideraciones de Seguridad
  • 7.2 Medidas para Mitigar Riesgos
  • 7.3 Configuración Segura

8. Mantenimiento y Monitoreo

  • 8.1 Monitoreo del Estado del Demonio
  • 8.2 Procedimientos de Mantenimiento Recomendados
  • 8.3 Solución de Problemas Comunes

9. Actualización y Desinstalación

  • 9.1 Procedimientos de Actualización
  • 9.2 Pasos para Desinstalar ogboot

10. Anexos

  • 10.1 Ejemplos de Configuración de Archivos Relevantes
  • 10.2 Listado de Comandos Útiles
  • 10.3 Referencias a Documentación Externa

11. Ejemplos Prácticos

  • 11.1 Casos de Uso Comunes
  • 11.2 Scripts de Automatización
  • 11.3 Integraciones Prácticas

1. Descripción General del Componente

1.1 Introducción

El componente ogboot se encarga de la gestión y configuración de archivos de arranque (iPXE) y plantillas en un entorno de despliegue de imágenes. El servidor ogCore es el núcleo que interactúa con ogboot para realizar operaciones de administración y configuración. Este documento describe la lógica y la comunicación entre los endpoints del componente ogboot y el servidor ogCore.

1.2 Funcionalidades

1.2.1 ogLive

El ogLive es un sistema operativo diseñado para iniciarse en clientes PCs y llevar a cabo diversas operaciones indicadas por OpenGnsys, como la creación de particiones y la restauración de sistemas operativos. Este sistema operativo se carga y ejecuta completamente en la RAM y se distribuye a través de la red, lo que le permite realizar una regeneración completa de todos los discos de almacenamiento en un equipo.

Desde el punto de vista de su diseño, el ogLive se divide en dos componentes, cada uno con una función específica en el proceso de arranque:

  1. Primera Fase: Kernel e Initrd

    • Esta fase incluye un Kernel y un Initrd, elementos tradicionales de una distribución de Ubuntu, pero con la adición de un proceso alternativo llamado oginit.
    • El oginit permite cambiar el contexto (pivot_root) del Initrd a la partición raíz (rootfs) de manera rápida y flexible según las necesidades de OpenGnsys.
    • El oginit permite utilizar un rootfs ubicado en la red a través de sistemas de archivos distribuidos como NFS, Samba o SSHFS, y crea enlaces en el minisistema del Initrd con los archivos del rootfs, facilitando así el uso de programas y utilidades que no pueden ser instalados en el Initrd.
    • Este enfoque minimiza los problemas de red, ya que el sistema principal (Initrd) siempre reside en la RAM y solo accede al rootfs cuando se necesita una utilidad no presente en el Initrd.

  2. Segunda Fase: Rootfs en la Red

    • El rootfs, que es compartido por todos los clientes, se fusiona con el Initrd, lo que permite independizar los procesos de cada equipo.
    • Este diseño admite varias configuraciones de arranque, donde los elementos de las dos fases pueden estar en diferentes ubicaciones.

Para aumentar la velocidad de descarga, se utiliza HTTP configurado por Nginx para la carga de la imagen de inicialización y el kernel. Esto reduce significativamente los retardos en la primera fase, donde se cargan aproximadamente 40 MB del Kernel y el Initrd en la memoria RAM. Una vez cargados, la conexión con el rootfs a través de Samba se establece de forma inmediata.

1.3 Arquitectura General del Sistema

Flujo de Comunicación entre el Cliente y el Servidor OgDHCP

El proceso de arranque en red utilizando ogboot sigue un flujo bien definido que comienza con la comunicación entre el cliente y el servidor DHCP, denominado OgDHCP en este contexto.

  1. Solicitud de Configuración de Red por Parte del Cliente:

    • Cuando un cliente se inicia, envía una solicitud al servidor OgDHCP para obtener los parámetros necesarios para arrancar en red. Este es el primer paso en el proceso de arranque PXE (Preboot Execution Environment).

  2. Asignación de IP y Parámetros de Arranque por OgDHCP:

    • El servidor OgDHCP responde a la solicitud del cliente asignándole una dirección IP. Además de la dirección IP, OgDHCP proporciona dos parámetros cruciales:
      • Next-server: Esta es la dirección IP del servidor ogBoot, que se encargará de proporcionar los archivos necesarios para que el cliente pueda arrancar.
      • Boot-file-name: Este parámetro especifica el archivo que el cliente debe cargar para continuar con el proceso de arranque. El nombre del archivo depende del tipo de firmware del cliente:
        • ipxe-efi: Se utiliza para sistemas con firmware EFI.
        • undionly.pxe: Se utiliza para sistemas con BIOS tradicional.

  3. Comunicación del Cliente con el Servidor ogBoot:

    • Con la dirección IP del servidor ogBoot (especificada en el next-server) y el nombre del archivo de arranque (boot-file-name), el cliente se comunica directamente con el servidor ogBoot.
    • ogBoot tiene un directorio tftpboot donde están alojados los archivos de arranque, como ipxe-efi y undionly.pxe.

  4. Ejecución de Scripts Embebidos en los Ficheros de Arranque:

    • Los archivos de arranque descargados por el cliente (como ipxe-efi o undionly.pxe) contienen scripts embebidos llamados dhcp_boot.ipxe.
    • Además de configurar la red del cliente, dhcp_boot.ipxe incluye instrucciones específicas que indican al cliente que ejecute un script de arranque basado en su dirección MAC.
    • Estos scripts de arranque suelen tener nombres como 01-XX:XX:XX:XX:XX:XX, donde XX:XX:XX:XX:XX:XX representa la dirección MAC del cliente. Por ejemplo, un nombre de archivo podría ser 01-00:50:56:34:48:11.

  5. Carga del Kernel y la Imagen de Inicialización:

    • Los scripts de arranque específicos para cada cliente se encargan de la carga del kernel y la imagen de inicialización. Además, estos scripts incluyen configuraciones personalizadas para cada cliente, tales como:
      • El nombre de la máquina.
      • La dirección IP asignada.
      • La versión de ogLive que el cliente utilizará para la carga.
      • Otras configuraciones específicas del entorno y las necesidades del cliente.

Requisitos Mínimos para la Instalación de ogBoot

  1. Requisitos de hardware:

    • Almacenamiento mínimo: Se requieren al menos 600 MB de espacio en disco, ya que se descargará ogLive 5.13 como parte de la instalación.
    • Memoria RAM: Dependiendo del número de clientes que se vayan a gestionar, pero se recomienda al menos 2 GB de RAM para un servidor que gestione despliegues pequeños.

  2. Sistema operativo compatible:

    • Distribuciones de Linux recomendadas:
      • Ubuntu 18.04 LTS o superior
      • CentOS 7 o superior
    • Nota: Es posible que otras distribuciones basadas en Linux también sean compatibles, pero se recomienda realizar pruebas en entornos similares a los descritos.

  3. Python:

    • Se requiere Python 3.7 o superior.

  4. Dependencias de software:

    • Las dependencias de software se instalan automáticamente durante el proceso de instalación. Estas incluyen:
      • tftpd-hpa
      • nginx
      • php-fpm
      • composer
      • Symfony
      • NFS y Samba para la configuración del sistema de archivos y la compartición de archivos.

  5. Permisos y usuarios:

    • La instalación requiere que se ejecute con privilegios de root.
    • Durante la instalación, se crearán usuarios específicos, como:
      • ogboot: Para ejecutar servicios y gestionar los componentes de ogBoot.
      • OPENGNSYS_CLIENT_USER: Usuario creado para gestionar la comunicación con OpenGnsys.

  6. Red y conectividad:

    • Se recomienda que el servidor tenga acceso a Internet para descargar dependencias y actualizaciones.
    • El servidor necesita estar en una red con un servidor DHCP activo para que los clientes puedan obtener sus configuraciones de red durante el arranque.

  7. Configuración de la red:

    • Es necesario un interfaz de red para la gestión del tráfico de los clientes, configurado automáticamente durante la instalación.

Directorios Clave de ogBoot Instalado:

  1. client:

    • Este directorio contiene el cliente que será servido por Samba para su uso en los despliegues. Los archivos en este directorio son accesibles para los clientes a través de la red, facilitando la instalación y el arranque remoto.

  2. bin:

    • Contiene los scripts de gestión de ogBoot, incluyendo:
      • oglivecli: Utilizado para la gestión de ogLive, permitiendo la instalación, borrado o consulta de imágenes de arranque.
      • setsmbpass: Script encargado de gestionar las contraseñas de Samba y configurar el acceso seguro a los clientes.

  3. tftpboot:

    • En este directorio se alojan los archivos de arranque como ipxe-efi y undionly.pxe, así como los ogLive montados que serán utilizados por estos archivos de arranque para lanzar los sistemas operativos en los clientes.

  4. Resto de directorios:

    • src, config, lib, etc, doc, composer.json, y installer contienen los archivos y configuraciones de Symfony, que es el framework utilizado por ogBoot para gestionar su estructura interna y flujos de trabajo.

Comandos y Funciones:

  1. help

    • Descripción: Muestra la ayuda del script, incluyendo una lista completa de los comandos disponibles y sus descripciones.
    • Uso: oglivecli help

  2. version

    • Descripción: Muestra la versión actual del script oglivecli.
    • Uso: oglivecli version

  3. config [Parámetro]

    • Descripción: Muestra los parámetros de configuración específicos que utiliza ogBoot. Puede recibir un parámetro para mostrar un valor específico.
    • Uso: oglivecli config [Parámetro]

  4. disk_usage

    • Descripción: Muestra información sobre el uso de disco en el servidor, lo que permite verificar cuánta capacidad de almacenamiento se está utilizando.
    • Uso: oglivecli disk_usage

  5. list_installed_oglives

    • Descripción: Lista todos los clientes ogLive instalados en el servidor, mostrando las imágenes disponibles para su despliegue.
    • Uso: oglivecli list_installed_oglives

  6. check_services_status

    • Descripción: Verifica el estado de los servicios críticos necesarios para el funcionamiento de ogBoot, como oglive_daemon, tftpd-hpa, y nginx.
    • Uso: oglivecli check_services_status

  7. download

    • Descripción: Muestra un menú interactivo para descargar una imagen ISO de ogLive desde el sitio web de OpenGnsys.
    • Uso: oglivecli download

  8. download Iso

    • Descripción: Permite descargar una imagen ISO específica de ogLive desde el sitio web de OpenGnsys.
    • Uso: oglivecli download [Iso]

  9. install Iso

    • Descripción: Instala un nuevo cliente ogLive desde una ISO previamente descargada.
    • Uso: oglivecli install [Iso]

  10. uninstall uuid

    • Descripción: Desinstala un cliente ogLive utilizando su UUID. Este comando elimina la imagen instalada del cliente.
    • Uso: oglivecli uninstall [uuid]

  11. get_default

    • Descripción: Obtiene el valor del índice correspondiente al cliente ogLive predeterminado actualmente en uso.
    • Uso: oglivecli get_default

  12. set_default uuid

    • Descripción: Establece un cliente ogLive como predeterminado utilizando su UUID.
    • Uso: oglivecli set_default [uuid]

  13. get_info uuid

    • Descripción: Obtiene información en formato JSON sobre un cliente ogLive instalado, identificado por su UUID.
    • Uso: oglivecli get_info [uuid]

4. Configuración del Servidor

4.1 Configuración de Nginx

El servidor Nginx se configura para manejar las solicitudes de ogBoot y servir archivos tanto del proyecto Symfony como del directorio TFTP. A continuación se detalla la configuración relevante para ogBoot:

server {
    listen 80;
    server_name 172.17.8.37 localhost;  # IP del servidor

    # Raíz del documento para el proyecto Symfony
    root /opt/ogboot/public;

    # Bloque para manejar las solicitudes a /ogboot
    location /ogboot {
        try_files $uri $uri/ /index.php?$query_string;
        # Aumentar el tiempo de espera por el install oglive
        proxy_read_timeout 600;
        proxy_connect_timeout 600;
        proxy_send_timeout 600;
        send_timeout 600;
    }

    # Bloque para manejar las solicitudes a index.php
    location ~ ^/index.php(/|$) {
        include fastcgi_params;
        fastcgi_pass unix:/run/php/php8.3-fpm.sock; # Asegúrate de que esto sea correcto
        fastcgi_split_path_info ^(.+\.php)(/.*)$;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_param PATH_INFO $fastcgi_path_info;
        fastcgi_param DOCUMENT_ROOT $document_root;
        internal;
    }

    # Bloque para devolver 404 en cualquier solicitud a archivos PHP que no sean index.php
    location ~ \.php$ {
        return 404;
    }

    # Logs de error y acceso para el proyecto Symfony
    error_log /var/log/nginx/ogboot_error.log;
    access_log /var/log/nginx/ogboot_access.log;

    # Manejo de la documentación de la API
    location /api/doc {
        try_files $uri /index.php?$query_string;
    }

    # Ruta base para servir archivos de TFTP
    location /tftpboot {
        alias /opt/ogboot/tftpboot;
        autoindex on;               # Permitir listado de directorios
        try_files $uri $uri/ =404;   # Intentar servir archivos, si no se encuentra devolver 404

        # Seguridad: Bloquear el acceso a archivos PHP en el directorio tftpboot
        location ~ \.php$ {
            return 404;
        }

        # Logs para el directorio tftpboot
        error_log /var/log/nginx/tftpboot_error.log;
        access_log /var/log/nginx/tftpboot_access.log;
    }
}
Puntos importantes:
  • Root del documento: Se especifica que el contenido principal de ogBoot se sirve desde /opt/ogboot/public, que es la raíz del proyecto Symfony.
  • Tiempos de espera aumentados: Se incrementa el tiempo de espera (timeout) en la sección de /ogboot debido a la duración de algunas operaciones críticas, como la instalación de ogLive.
  • Archivos TFTP: El contenido del directorio /tftpboot es accesible mediante la ruta /tftpboot, y está configurado para permitir el listado de archivos y bloquear cualquier intento de ejecutar archivos PHP desde este directorio.
  • Logs de Nginx: Los logs de error y acceso se guardan en archivos dedicados para facilitar la depuración de problemas.

4.2 Configuración de PHP-FPM

La configuración de PHP-FPM es crucial para que ogBoot maneje adecuadamente las solicitudes a través de Nginx. En este caso, PHP-FPM está configurado para ejecutarse con el usuario www-data y el grupo ogboot:

  • fastcgi_pass: El parámetro fastcgi_pass está configurado para utilizar el socket Unix en /run/php/php8.3-fpm.sock, asegurando que las solicitudes PHP se manejen correctamente.
  • Usuarios y permisos:
    • Usuario: www-data
    • Grupo: ogboot

Esto asegura que los procesos PHP tengan los permisos adecuados para leer y escribir en los directorios relevantes, como los de Symfony y ogLive.

4.3 Creación y Levantamiento del Demonio ogBoot

El demonio ogboot es esencial para el funcionamiento del sistema, y debe ser levantado tras la configuración del servidor. La creación del demonio implica los siguientes pasos:

  1. Creación del usuario ogboot:

    • Se crea un usuario específico para ejecutar los servicios relacionados con ogBoot, con los permisos adecuados para manejar el contenido del servidor.

  2. Levantamiento del servicio:

    • El demonio ogboot se levanta automáticamente tras la configuración, ejecutando las tareas esenciales para la gestión de imágenes y el arranque de clientes.

4.4 Configuración de Samba

La configuración de Samba permite compartir los directorios necesarios con los clientes que se conectan a ogBoot. A continuación se detallan las configuraciones relevantes:

[tftpboot]
   comment = OpenGnsys init files
   browseable = no
   writeable = no
   path = /opt/opengnsys/tftpboot
   guest ok = no

[ogclient]
   comment = OpenGnsys Client
   browseable = no
   writeable = no
   locking = no
   path = /opt/opengnsys/client
   guest ok = no
Puntos importantes:

  • Directorio tftpboot:

    • Uso: Se comparte el directorio /opt/opengnsys/tftpboot para servir los archivos de arranque a los clientes.
    • Permisos: No es navegable (browseable = no), y no se permite escribir en él (writeable = no). Los clientes solo pueden acceder a los archivos necesarios.

  • Directorio ogclient:

    • Uso: Comparte el directorio /opt/opengnsys/client, que contiene el cliente OpenGnsys.
    • Permisos: Al igual que en tftpboot, este directorio no es navegable ni escribible desde los clientes. Además, el bloqueo de archivos está deshabilitado (locking = no).

Comandos del Script oglivecli

El script oglivecli es una herramienta de línea de comandos diseñada para gestionar las imágenes de ogLive, permitiendo realizar diversas operaciones relacionadas con la instalación, configuración y administración de estos clientes de arranque en el entorno ogBoot.

6. Integración con Otros Sistemas

6.1 Integración con TFTP

En ogBoot, el servicio TFTP (Trivial File Transfer Protocol) es esencial para servir los archivos necesarios para el arranque de los clientes. El directorio tftpboot aloja los archivos de arranque y las imágenes de ogLive que serán utilizados en el proceso de arranque PXE.

En el directorio /opt/ogboot/tftpboot, se encuentran los siguientes archivos y directorios clave:

  • ipxe.efi: El archivo de arranque para sistemas EFI.
  • undionly.kpxe: El archivo de arranque para sistemas BIOS.
  • ipxe_scripts: Scripts IPXE personalizados que gestionan el arranque de los clientes.
  • ogLive: Directorio que contiene las imágenes del sistema operativo ogLive que serán utilizadas por los clientes.
  • ogclient: El cliente OpenGnsys, que se carga a través de Samba.

El TFTP se configura para servir estos archivos a los clientes, permitiendo que accedan a los recursos necesarios para iniciar el proceso de arranque.

6.2 Configuración de PXE

El PXE (Preboot Execution Environment) es utilizado para inicializar los clientes a través de la red. En el caso de ogBoot, el proceso PXE está configurado para proporcionar archivos de arranque según el firmware de los clientes (EFI o BIOS) y luego ejecutar scripts de IPXE personalizados.

Estructura de los Scripts IPXE

En el directorio /opt/ogboot/tftpboot/ipxe_scripts, se encuentran varios archivos de configuración de IPXE, incluyendo archivos como default.ipxe, dhcp_boot.ipxe, y plantillas específicas de arranque como 01-D05099AA8C06, que están basadas en la dirección MAC del cliente.

  • Archivos de arranque personalizados: Los scripts IPXE como 01-D05099AA8C06 están vinculados a clientes específicos basados en su dirección MAC. Esto permite configurar un arranque personalizado para cada cliente.
Ejemplo de una plantilla IPXE (mi_plantilla.ipxe)
#!ipxe
set timeout 0
set timeout-style hidden
set ISODIR __OGLIVE__
set default 0
set kernelargs __INFOHOST__
:try_iso
kernel http://__SERVERIP__/tftpboot/${ISODIR}/ogvmlinuz ${kernelargs} || goto fallback
initrd http://__SERVERIP__/tftpboot/${ISODIR}/oginitrd.img
boot

:fallback
set ISODIR ogLive
kernel http://__SERVERIP__/tftpboot/${ISODIR}/ogvmlinuz ${kernelargs}
initrd http://__SERVERIP__/tftpboot/${ISODIR}/oginitrd.img
boot
Parámetros Relevantes de la Plantilla:
  • __SERVERIP__: Este parámetro se reemplaza con la dirección IP del servidor ogBoot, que sirve los archivos necesarios para el arranque.
  • __INFOHOST__: Se sustituye con los parámetros del kernel específicos de la máquina que está arrancando. Estos parámetros pueden incluir configuraciones específicas como el nombre de la máquina, la dirección IP, y otros detalles necesarios para el arranque.
  • __OGLIVE__: Se reemplaza con la versión de ogLive que será utilizada para arrancar la máquina cliente. Esto permite cargar diferentes versiones de ogLive según la configuración de cada cliente.

Este sistema de plantillas facilita la personalización del proceso de arranque para diferentes clientes, permitiendo que ogBoot adapte el arranque PXE según los requerimientos de cada máquina.

Endpoints del Componente ogboot

Endpoints del Recurso oglive

  1. Ver todos los ogLives instalados

    • URL: /ogboot/v1/oglives
    • Método HTTP: GET
    • Descripción: Obtiene información sobre todos los ogLives instalados.
    • Respuesta: 
         [
   "ogLive-5.0.0-r20190605",
   "ogLive-5.11.0-r20210413",
   "ogLive-5.13.0-27-r20210706"
   ]

  2. Obtener Información de un ogLive

    • URL: /ogboot/v1/oglives/{uuid}
    • Método HTTP: GET
    • Descripción: Obtiene información sobre un cliente ogLive instalado utilizando su nombre.
    • Parámetros:
      • uuid (string): uuid del ogLive.
    • Respuesta: 
      {
  "distribution": "uuid",
  "distribution": "focal",
  "kernel": "5.13.0-27",
  "architecture": "amd64",
  "revision": "r20210706.5b4bf5f",
  "directory": "ogLive-focal-5.13.0-27-beta-amd64-r20210706.5b4bf5f",
  "iso": "ogLive-focal-5.13.0-27-beta-amd64-r20210706.5b4bf5f.iso"
}
    • Respuestas:
      • 200 OK: Información del ogLive obtenida exitosamente.
      • 404 Not Found: ogLive no encontrado.

  3. Obtener Información del ogLive Predeterminado

    • URL: /ogboot/v1/oglives/default

    • Método HTTP: GET

    • Descripción: Obtiene información sobre el cliente ogLive predeterminado.

    • Ejemplo de Solicitud:

      curl -X GET -H "Authorization: $API_KEY" http://example.com/ogboot/v1/oglives/default

    • Respuesta:

      {
  "distribution": "focal",
  "kernel": "5.13.0-27",
  "architecture": "amd64",
  "revision": "r20210706.5b4bf5f",
  "directory": "ogLive-focal-5.13.0-27-beta-amd64-r20210706.5b4bf5f",
  "iso": "ogLive-focal-5.13.0-27-beta-amd64-r20210706.5b4bf5f.iso"
}

    • Respuestas:

      • 200 OK: Información del ogLive predeterminado obtenida exitosamente.
      • 500 Internal Server Error: Error al obtener la información del ogLive predeterminado.

  4. Establecer ogLive Predeterminado

    • URL: /ogboot/v1/oglives/default/{uuid}
    • Método HTTP: POST
    • Descripción: Establece un cliente ogLive como predeterminado utilizando su nombre.
    • Parámetros:
      • uuid (string): uuid del ogLive a establecer como predeterminado.
    • Respuestas:
      • 200 OK: ogLive establecido como predeterminado exitosamente.
      • 404 Not Found: ogLive no encontrado.
      • 500 Internal Server Error: Error al establecer el ogLive como predeterminado.

  5. Ver la lista de ogLives disponibles para descargar

    • URL: /ogboot/v1/oglives/isos
    • Método HTTP: GET
    • Respuesta: 
         [
   {
       "id": "1",
       "filename": "ogLive-focal-5.13.0-27-beta-amd64-r20210706.5b4bf5f.iso",
       "installed": false,
       "compatible": true
   },
   {
       "id": "2",
       "filename": "ogLive-focal-5.11.0-22-generic-amd64-r20210413.992ebb9.iso",
       "installed": false,
       "compatible": true
   },
   {
       "id": "3",
       "filename": "ogLive-focal-5.8.0-50-generic-amd64-r20210413.992ebb9.iso",
       "installed": false,
       "compatible": true
   },
   {
       "id": "4",
       "filename": "ogLive-bionic-5.4.0-40-generic-amd64-r20200629.85eceaf.iso",
       "installed": false,
       "compatible": true
   },

   ]
      • 500 Internal Server Error: Error en la conexión.

  6. Crear un ogLive

    • URL: /ogboot/v1/oglives
    • Método HTTP: POST
    • Descripción: Crea un nuevo ogLive utilizando el nombre del ISO proporcionado.
    • Cuerpo de la Solicitud: 
      {
  "isoName": "ogLive-focal-5.13.0-27-beta-amd64-r20210706.5b4bf5f.iso"
}
    • Ejemplo de Solicitud: 
      curl -X POST -H "Authorization: $API_KEY" -d '{"isoName": "ogLive-focal-5.13.0-27-beta-amd64-r20210706.5b4bf5f.iso"}' http://example.com/ogboot/v1/oglives
    • Respuestas:
      • 200 OK: ogLive creado exitosamente.
      • 400 Bad Request: Error en los datos proporcionados.
      • 500 Internal Server Error: Error al crear el ogLive.

  7. Eliminar un ogLive

    • URL: /ogboot/v1/oglives/{uuid}
    • Método HTTP: DELETE
    • Descripción: Elimina un ogLive específico utilizando su nombre.
    • Parámetros:
      • name (string): Nombre del ogLive.
    • Respuestas:
      • 200 OK: ogLive eliminado exitosamente.
      • 404 Not Found: ogLive no encontrado.
      • 500 Internal Server Error: Error al eliminar el ogLive.

Endpoints del Recurso pxe y pxe-template

  1. Obtener Todos los Archivos de Arranque

    • URL: /ogboot/v1/pxes
    • Método HTTP: GET
    • Descripción: Obtiene una lista de todos los archivos de arranque disponibles.
    • Respuesta: Lista de archivos de arranque en formato JSON.

  2. Obtener Configuración de Arranque

    • URL: /ogboot/v1/pxes/{mac}
    • Método HTTP: GET
    • Descripción: Obtiene el contenido del archivo de configuración de arranque específico para un cliente utilizando su dirección MAC.
    • Respuesta: Archivo de arranque en formato adecuado. 
         {
   "template_name": "pxe",
   "mac": "00:50:56:22:11:12",
   "lang": "es_ES.UTF-8",
   "ip": "192.168.2.11",
   "server_ip": "192.168.2.1",
   "router": "192.168.2.1",
   "netmask": "255.255.255.0",
   "computer_name": "pc11",
   "netiface": "eth0",
   "group": "Aula_virtual",
   "ogrepo": "192.168.2.1",
   "oglive": "192.168.2.1",
   "oglog": "192.168.2.1",
   "ogshare": "192.168.2.1",
   "oglivedir": "ogLive",
   "ogprof": "false",
   "hardprofile": "",
   "ogntp": "",
   "ogdns": "",
   "ogproxy": "",
   "ogunit": "",
   "resolution": "788"
   }

  3. Crear Archivo de Arranque

    • URL: /ogboot/v1/pxes
    • Método HTTP: POST
    • Descripción: Crea un nuevo archivo de arranque utilizando los parámetros proporcionados.
    • Cuerpo de la Solicitud: 
         {
   "template_name": "pxe",
   "mac": "00:50:56:22:11:12",
   "lang": "es_ES.UTF-8",
   "ip": "192.168.2.11",
   "server_ip": "192.168.2.1",
   "router": "192.168.2.1",
   "netmask": "255.255.255.0",
   "computer_name": "pc11",
   "netiface": "eth0",
   "group": "Aula_virtual",
   "ogrepo": "192.168.2.1",
   "oglive": "192.168.2.1",
   "oglog": "192.168.2.1",
   "ogshare": "192.168.2.1",
   "oglivedir": "ogLive",
   "ogprof": "false",
   "hardprofile": "",
   "ogntp": "",
   "ogdns": "",
   "ogproxy": "",
   "ogunit": "",
   "resolution": "788"
   }
    • Respuesta: Mensaje de éxito o error.

  4. Eliminar Archivo de Arranque

    • URL: /ogboot/v1/pxes/{name}
    • Método HTTP: DELETE
    • Descripción: Elimina un archivo de arranque específico utilizando su dirección MAC.
    • Respuesta: Mensaje de éxito o error.

  5. Obtener Todas las Plantillas de Arranque

    • URL: /ogboot/v1/pxe-templates
    • Método HTTP: GET
    • Descripción: Obtiene una lista de todas las plantillas de arranque disponibles.
    • Respuesta: Lista de plantillas en formato JSON. 
      {
"templates": [
    "pxe",
    "pxe2",
    "pxe_default"
]
}

  6. Obtener Contenido de una Plantilla

    • URL: /ogboot/v1/pxe-templates/{name}
    • Método HTTP: GET
    • Descripción: Obtiene el contenido de una plantilla de arranque específica utilizando su nombre.
    • Respuesta: Contenido de la plantilla en formato adecuado.

  7. Crear Plantilla de Arranque

    • URL: /ogboot/v1/pxe-templates
    • Método HTTP: POST
    • Descripción: Crea una nueva plantilla de arranque utilizando los datos proporcionados.
    • Cuerpo de la Solicitud: 
      {
  "name_template": "pxe",
  "content_template": "contenido_de_la_plantilla"
}
    • Respuesta: Mensaje de éxito o error.

  8. Eliminar Plantilla de Arranque

    • URL: /ogboot/v1/pxe-templates/{name}
    • Método HTTP: DELETE
    • Descripción: Elimina una plantilla de arranque específica utilizando su nombre.
    • Respuesta: Mensaje de éxito o error.

Flujos de Trabajo

Para los nuevos flujos de trabajo, asumimos que habrá al menos una nueva tabla en ogCore para almacenar la información de los ogLives y su estado. Esta tabla permitirá a ogCore gestionar y sincronizar la información con ogBoot.

Propuesta de definición de la tabla ogLive

Atributo Tipo de Dato Descripción
id SERIAL Identificador del ogLive que corresponde a su suma de comprobación
distribution VARCHAR(50) Nombre de la distribución del ogLive (por ejemplo, "focal").
kernel VARCHAR(100) Versión del kernel del ogLive.
architecture VARCHAR(10) Arquitectura del ogLive (por ejemplo, "amd64").
revision VARCHAR(50) Revisión del ogLive (por ejemplo, "r20210706").
directory VARCHAR(100) Nombre del directorio del ogLive en el sistema de archivos.
iso VARCHAR(255) Nombre del archivo ISO del ogLive.
is_default BOOLEAN Indica si el ogLive es el predeterminado (true o false).

Ejemplo de Registro

id distribution kernel architecture revision directory iso is_default
1 focal 5.13.0-27-beta amd64 r20210706 ogLive-5.13.0-r20210706 ogLive-focal-5.13.0-27-beta-amd64-r20210706.5b4bf5f.iso true

Flujo de trabajo para instalar un ogLive

1. Consultar los ogLives Instalados

  • Descripción: Obtener la lista de ogLives que están actualmente instalados en el sistema.
  • Interacción en la Web:
    • El usuario navega a la sección de ogLives en el panel de administración.
    • Hace clic en "Ver ogLives instalados".
    • El sistema realiza una llamada a la API para obtener la lista de ogLives instalados.

Realización: Puede realizarse directamente desde ogCore mediante una consulta a la base de datos oglives.

Consulta SQL:

SELECT * FROM oglives;

Realización 2: También se puede llevar a cabo desde ogBoot haciendo una consulta al endpoint

Endpoint:

  • ogBoot: /ogboot/v1/oglives
  • Método: GET

2. Consultar los ogLives disponibles para descargar

  • Descripción: Obtener una lista de ogLives disponibles para descargar desde el servidor.
  • Interacción en la Web:
    • El usuario selecciona "Descargar nuevos ogLives" en la interfaz.
    • Aparece una lista de ogLives disponibles, obtenida mediante una consulta al servidor.

Realización: Necesita comunicación con ogBoot. Nota: Este proceso requiere de una consulta a Trac (o web) que se podría llevar a cabo desde el ogCore.

Endpoint:

  • ogBoot: /ogboot/v1/isos
  • Método: GET

3. Instalar un ogLive

  • Descripción: Instalar un ogLive seleccionado en el sistema.
  • Interacción en la Web:
    • El usuario selecciona un ogLive de la lista de disponibles y hace clic en "Instalar".
    • El sistema muestra un cuadro de confirmación, y al confirmar, se inicia el proceso de instalación.

Realización: Requiere comunicación con ogBoot para iniciar la instalación. Primero, se construye el JSON con los parámetros necesarios. La inserción en la base de datos ogCore solo se realiza después de que la instalación en ogBoot sea confirmada como exitosa.

  • Proceso de Instalación:
    1. Generación de JSON: ogCore genera un JSON con los detalles del ogLive.
    2. Solicitud de Instalación:
      • Endpoint: /ogboot/v1/oglives
      • Método: POST
      • Cuerpo de la Solicitud: 
        {
  "iso": "ogLive-focal-5.11.0-22-generic-amd64-r20210413.992ebb9.iso"
}
      • Respuesta: 
        {
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "directory": "ogLive-5.11.0-r20210413",
  "distribution": "focal",
  "kernel": "5.11.0-22-generic",
  "architecture": "amd64",
  "revision": "r20210413",
  "iso": "ogLive-focal-5.11.0-22-generic-amd64-r20210413.992ebb9.iso"
}
    3. Actualización de Base de Datos:
      • Instalación Exitosa: Si ogBoot confirma el éxito, ogCore inserta el nuevo ogLive en la base de datos: 
        INSERT INTO oglives (uuid, distribution, kernel, architecture, revision, directory, iso, is_default)
VALUES ('550e8400-e29b-41d4-a716-446655440000', 'focal', '5.11.0-22-generic', 'amd64', 'r20210413', 'ogLive-5.11.0-r20210413', 'ogLive-focal-5.11.0-22-generic-amd64-r20210413.992ebb9.iso', false);
      • Instalación Fallida: Si ogBoot reporta un fallo, no se realiza ninguna inserción y se maneja el error adecuadamente en la interfaz de usuario.

4. Revisar un ogLive Instalado

  • Descripción: Obtener detalles sobre un ogLive específico que está instalado.
  • Interacción en la Web:
    • El usuario selecciona un ogLive de la lista de instalados para ver detalles.
    • Se muestra la información detallada del ogLive seleccionado.

Realización: Puede realizarse desde ogCore mediante una consulta a la base de datos oglives.

Consulta SQL:

SELECT * FROM oglives WHERE directory = 'ogLive-5.13.0-r20210706';

Flujo de trabajo para cambiar el oglive por defecto

1. Consultar los ogLives Instalados

  • Descripción: Obtener la lista de ogLives que están actualmente instalados en el sistema.
  • Interacción en la Web:
    • El usuario navega a la sección de ogLives en el panel de administración.
    • Hace clic en "Ver ogLives instalados".
    • El sistema realiza una llamada a la API para obtener la lista de ogLives instalados.

Realización: Puede realizarse directamente desde ogCore mediante una consulta a la base de datos oglives. Lo ideal sería hacerlo hacia ogBoot ya que tiene la fuente de información fidedigna del estado de los ogLives en el componente.

Consulta SQL:

SELECT * FROM oglives;

Endpoint:

  • ogBoot: /ogboot/v1/oglives
  • Método: GET

2. Ver el ogLive por Defecto

  • Descripción: Obtener el ogLive que está configurado como predeterminado.
  • Interacción en la Web:
    • El usuario navega a la sección de configuración de ogLives en el panel de administración.
    • Hace clic en en el ogLive que está marcado por defecto.
    • El sistema realiza una consulta a la base de datos para obtener el ogLive predeterminado.

Realización: Puede realizarse desde ogCore mediante una consulta a la base de datos oglives.

Consulta SQL:

SELECT * FROM oglives WHERE directory = 'ogLive-5.13.0-r20210706';

3. Asignar ogLive por Defecto

  • Descripción: Configurar un ogLive instalado como el predeterminado.
  • Interacción en la Web:
    • El usuario selecciona un ogLive de la lista de instalados.
    • Hace clic en "Configurar como ogLive por defecto".
    • Tras la confirmación, el sistema envía una solicitud para actualizar el ogLive por defecto.
    • El sistema actualiza la base de datos y comunica el cambio a ogBoot.

Realización: Requiere comunicación con ogBoot para modificar el ogLive por defecto en el TFTP boot del ogBoot.

Consulta SQL:

SELECT * FROM oglives WHERE directory = 'ogLive-5.13.0-r20210706';

Endpoint:

  • ogBoot: /ogboot/v1/oglives/default/550e8400-e29b-41d4-a716-446655440000
  • Método: POST

Actualizar Base de Datos:

  • Tras la actualización en ogBoot, se debe actualizar la base de datos para reflejar el nuevo ogLive por defecto: 
    UPDATE oglives SET is_default = false WHERE is_default = true;
UPDATE oglives SET is_default = true WHERE uuid = '550e8400-e29b-41d4-a716-446655440000';

Flujo de trabajo para desinstalar un ogLive

1. Consultar los ogLives Instalados

  • Descripción: Obtener la lista de ogLives que están actualmente instalados en el sistema.
  • Interacción en la Web:
    • El usuario navega a la sección de ogLives en el panel de administración.
    • Hace clic en "Ver ogLives instalados".
    • El sistema realiza una llamada a la API para obtener la lista de ogLives instalados.

Realización: Puede realizarse directamente desde ogCore mediante una consulta a la base de datos oglives.

Consulta SQL:

SELECT * FROM oglives;

Endpoint:

  • ogBoot: /ogboot/v1/oglives
  • Método: GET

2. Desinstalar ogLive

  • Descripción: Iniciar el proceso de desinstalación del ogLive seleccionado en ogBoot.
  • Interacción en la Web:
    • En la lista de ogLives instalados, el usuario elige el ogLive a desinstalar.
    • Hace clic en el botón "Desinstalar" junto al ogLive seleccionado.
    • El sistema muestra un cuadro de confirmación preguntando si el usuario está seguro de desinstalar el ogLive.
    • El usuario hace clic en "Confirmar" para proceder.
    • El sistema envía una solicitud a ogBoot para desinstalar el ogLive.

Realización:

  • Endpoint: /ogboot/v1/oglives/550e8400-e29b-41d4-a716-446655440000
  • Método: DELETE
  • Validación de Instalación: ogBoot intenta desinstalar el ogLive y devuelve un estado de éxito o fallo.
  • Actualización de Base de Datos: - Desinstalación Exitosa: Si ogBoot confirma el éxito, ogCore elimina el ogLive en la base de datos: sql DELETE FROM oglives WHERE uuid = '550e8400-e29b-41d4-a716-446655440000'; - Instalación Fallida: Si ogBoot reporta un fallo, no se realiza ningún borrado y se maneja el error adecuadamente en la interfaz de usuario.

Flujo de trabajo para corregir las incongruencias entre ogCore y ogBoot

8. Revisar estado de ogboot

  • Descripción: Comparar el estado actual de ogboot con la base de datos de ogCore, generando un informe de discrepancias.
  • Realización: Requiere comunicación con ogBoot para obtener el estado actual de los ogLives instalados, el ogLive por defecto, y las plantillas de arranque (pxes). Luego, ogCore compara estos datos con su base de datos y devuelve un informe de discrepancias.

Endpoint:

  • ogBoot: /ogboot/v1/oglive/status
  • Método: GET
  • Resultado de la Solicitud: 
    {
  "installed_oglives": [
    {
      "name": "ogLive-5.13.0-r20210706",
      "kernel": "5.13.0-27-beta",
      "revision": "r20210706",
      "default": true
    },
    {
      "name": "ogLive-5.11.0-r20210413",
      "kernel": "5.11.0-22-generic",
      "revision": "r20210413",
      "default": false
    }
  ],
  "installed_pxe_templates": [
    "default.ipxe",
    "template1.ipxe"
  ]
}

Informe de Discrepancias (Ejemplo):

{
  "discrepancies": {
    "oglives": [
      {
        "expected": {
          "name": "ogLive-5.13.0-r20210706",
          "default": true
        },
        "actual": {
          "name": "ogLive-5.11.0-r20210413",
          "default": true
        }
      }
    ],
    "pxe_templates": [
      {
        "expected": "default.ipxe",
        "actual": "template1.ipxe"
      }
    ]
  }
}

9. Sincronizar Datos de ogboot con ogCore

  • Descripción: ogCore sincroniza su base de datos con el estado actual de ogboot. Este proceso solo actualiza las discrepancias detectadas.
  • Realización: Requiere comunicación con ogBoot para obtener el estado actual. Luego, ogCore actualiza su base de datos con cualquier cambio detectado en los ogLives instalados, el ogLive por defecto, y las plantillas de arranque (pxes).

Endpoint:

  • ogBoot: /ogboot/v1/sync
  • Método: GET
  • Resultado de la Solicitud: 
    {
  "installed_oglives": [
    {
      "name": "ogLive-5.13.0-r20210706",
      "kernel": "5.13.0-27-beta",
      "revision": "r20210706",
      "default": true
    },
    {
      "name": "ogLive-5.11.0-r20210413",
      "kernel": "5.11.0-22-generic",
      "revision": "r20210413",
      "default": false
    }
  ],
  "installed_pxe_templates": [
    "default.ipxe",
    "template1.ipxe"
  ]
}

Flujo de Trabajo: pxe y pxe-template

NOTA

En la implementación actual de OpenGnsys, se realiza una consulta SQL a la tabla ordenadores, haciendo joins con tablas como aulas, centros, entidades, etc. (consultar fichero opengnsys/server/bin/setclientmode) para obtener todos los parámetros necesarios para la creación de archivos PXE. Es necesario estudiar si existe la necesidad de crear una tabla pxe para almacenar estos parámetros. En caso de decidirse la creación de dicha tabla, podría tener los siguientes atributos:

  • template_name (nombre de la plantilla)
  • mac (dirección MAC)
  • lang (idioma)
  • ip (dirección IP)
  • server_ip (dirección IP del servidor)
  • router (router)
  • netmask (máscara de red)
  • computer_name (nombre del equipo)
  • netiface (interfaz de red)
  • group (grupo)
  • ogrepo (IP del repositorio)
  • oglive (IP del servidor en vivo)
  • oglog (IP del servidor de logs)
  • ogshare (IP del servidor compartido)
  • oglivedir (directorio en vivo)
  • ogprof (es profesor)
  • hardprofile (perfil de hardware)
  • ogntp (servidor NTP)
  • ogdns (servidor DNS)
  • ogproxy (servidor proxy)
  • ogunit (directorio de unidad)
  • resolution (resolución de pantalla)

NOTA 2

¿Tiene sentido hacer una tabla para las plantillas pxe-templates? Solo tendrian dos atributos: template-name y content. ¿No sería mejor que quedasen guardadas en el ogboot y se usen cuando se vaya a crear un fichero de arranque?

Para estos flujos asumiremos que NO se han creado tablas a mayores de pxe ni de pxe-templates. Este es el flujo original que se produce actualmente en ogboot.

  1. Obtener Todos los Archivos de Arranque

    • URL: /ogboot/v1/pxes
    • Método HTTP: GET
    • Cuerpo de la Solicitud:
    {
     {
     "boot_files": [
         "01-00:50:56:20:69:11",
         "01-00:50:56:20:69:12"
     ]
     }
}

  2. Obtener Configuración de Arranque por MAC

    • URL: /ogboot/v1/pxes/{mac}
    • Método HTTP: GET
    • Cuerpo de la Solicitud:
    • Respuesta:
         {
     "template_name": "pxe",
     "mac": "00:50:56:22:11:12",
     "lang": "es_ES.UTF-8",
     "ip": "192.168.2.11",
     "server_ip": "192.168.2.1",
     "router": "192.168.2.1",
     "netmask": "255.255.255.0",
     "computer_name": "pc11",
     "netiface": "eth0",
     "group": "Aula_virtual",
     "ogrepo": "192.168.2.1",
     "oglive": "192.168.2.1",
     "oglog": "192.168.2.1",
     "ogshare": "192.168.2.1",
     "oglivedir": "ogLive",
     "ogprof": "false",
     "hardprofile": "",
     "ogntp": "",
     "ogdns": "",
     "ogproxy": "",
     "ogunit": "",
     "resolution": "788"
     }

  3. Obtener Todas las Plantillas de Arranque

    • URL: /ogboot/v1/pxe-templates
    • Método HTTP: GET
    • Respuesta:
     {
     "templates": [
         "pxe",
         "pxe_default"
     ]
 }

  4. Crear Plantilla de Arranque

    • URL: /ogboot/v1/pxes-templates
    • Método HTTP: POST
    • Cuerpo de la Solicitud:
         {
     "name_template": "pxe2",
     "content_template": "#!ipxe\\nset timeout 0\\nset timeout-style hidden\\n\\nset ISODIR ogLive\\nset default 0\\nset kernelargs INFOHOST\\nkernel tftp://SERVERIP/ogLive/ogvmlinuz ${kernelargs}\\ninitrd tftp://SERVERIP/ogLive/oginitrd.img\\nboot"
     }
    • Respuesta:
         {
     "message": "Plantilla creada exitosamente.",
     "template": "#!ipxe\\nset timeout 0\\nset timeout-style hidden\\n\\nset ISODIR ogLive\\nset default 0\\nset kernelargs INFOHOST\\nkernel tftp://SERVERIP/ogLive/ogvmlinuz ${kernelargs}\\ninitrd tftp://SERVERIP/ogLive/oginitrd.img\\nboot"
     }

  5. Obtener Todas las Plantillas de Arranque

    • URL: /ogboot/v1/pxe-templates
    • Método HTTP: GET
    • Respuesta:
     {
     "templates": [
         "pxe",
         "pxe2"
         "pxe_default"
     ]
 }

  6. Crear archivo de Arranque

    • URL: /ogboot/v1/pxes
    • Método HTTP: POST
    • Respuesta:
         {
     "template_name": "pxe2",
     "mac": "00:50:56:22:11:13",
     "lang": "es_ES.UTF-8",
     "ip": "192.168.2.11",
     "server_ip": "192.168.2.1",
     "router": "192.168.2.1",
     "netmask": "255.255.255.0",
     "computer_name": "pc13",
     "netiface": "eth0",
     "group": "Aula_virtual",
     "ogrepo": "192.168.2.1",
     "oglive": "192.168.2.1",
     "oglog": "192.168.2.1",
     "ogshare": "192.168.2.1",
     "oglivedir": "ogLive",
     "ogprof": "false",
     "hardprofile": "",
     "ogntp": "",
     "ogdns": "",
     "ogproxy": "",
     "ogunit": "",
     "resolution": "788"
     }

  7. Obtener Todos los Archivos de Arranque

    • URL: /ogboot/v1/pxes
    • Método HTTP: GET
    • Cuerpo de la Solicitud:
    {
     {
     "boot_files": [
         "01-00:50:56:20:69:11",
         "01-00:50:56:20:69:12",
         "01-00:50:56:20:69:13"
     ]
     }
}

  8. Borrado de un fichero de arranque

    • URL: /ogboot/v1/pxes/{mac}
    • Método HTTP: DELETE
    • Respuesta:
     {
 "message": "El archivo de arranque se eliminó correctamente"
 }

  9. Borrado de una plantilla

    • URL: /ogboot/v1/pxe-templates/{name}
    • Método HTTP: DELETE
    • Respuesta:
     {
 "message": "Plantilla eliminada correctamente."
 }