diff --git a/README.md b/README.md index 63cbaf1..a40e445 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,45 @@ -## Ogboot +# Ogboot Ogboot es una implementación independiente que facilita la funcionalidad de arranque remoto (PXE) en entornos gestionados por Opengnsys. Este componente permite la carga remota de sistemas operativos y otros archivos esenciales durante el proceso de arranque de las estaciones de trabajo. +## Instalación + +### Requisitos Previos: +- **Sistema Operativo**: Ubuntu 24. +- **Python 3**: La instalación se ha probado con la versión **Python 3.12.3**. + ```bash + python3 --version + Python 3.12.3 + ``` + +### Instalación de Python 3: +Ejecuta el siguiente comando para instalar Python 3 y `pip`: +```bash +apt-get install -y python3 python3-pip +``` + +### Configuración Inicial: +El archivo de configuración ya viene incluido en el repositorio, por lo que solo necesitas modificarlo con los parámetros adecuados: + +```json +{ + "ogCore_ServerIP": "172.17.8.82", + "ogBoot_ServerIP": "172.17.8.37", + "ogBoot_Dir": "/opt/opengnsys/ogboot", + "ogBootSambaUser": "opengnsys", + "ogBootSambaPass": "og" +} +``` + +- **`ogCore_ServerIP`**: IP del servidor ogcore. +- **`ogBoot_ServerIP`**: IP del servidor ogboot. +- **`ogBoot_Dir`**: Directorio de instalación de ogboot. +- **`ogBootSambaUser`** y **`ogBootSambaPass`**: Usuario y contraseña de Samba. + +### Instalación: +1. Asegúrate de que Python 3 esté instalado. +2. Modifica el archivo de configuración existente con los parámetros necesarios. + ## API de Ogboot @@ -32,283 +70,512 @@ El presente documento detalla los endpoints del API con sus respectivos parámet 18. [Regenerar plantilla](#regenerar-plantilla) - `PUT /ogboot/v1/pxe-templates` -### Obtener Configuración de ogboot -Devuelve la configuración actual del ogboot. +### Obtener Estado de ogboot -**URL:** `/ogboot/v1/config` +Devuelve el uso de disco, el cliente `ogLive` predeterminado, la lista de `ogLives` instalados y el estado de los servicios. + +**URL:** `/ogboot/v1/status` **Método HTTP:** GET **Ejemplo de Solicitud:** ```bash -curl -X GET -H "Authorization: $API_KEY" http://example.com/ogboot/v1/config +curl -X GET http://example.com/ogboot/v1/status ``` **Respuestas:** -- **Código 200 OK:** La configuración del ogboot se obtuvo exitosamente. - - **Contenido:** Configuración del ogboot en formato JSON. + +- **Código 200 OK:** El estado de ogboot se obtuvo exitosamente. + - **Contenido:** ```json { - "config-file": "/opt/opengnsys/etc/ogliveinfo.json", - "download-url": "https://opengnsys.es/trac/downloads", - "download-dir": "/opt/opengnsys/lib", - "install-dir": "/opt/opengnsys/tftpboot", - "default-name": "ogLive", - "min-release": "r20190601" + "success": "Status retrieved successfully", + "message": { + "disk_usage": { + "total": "22591996", + "used": "11995812", + "available": "9542092", + "percentage": "56%" + }, + "default_oglive": "ogLive-6.8.0-i386-20241014", + "installed_oglives": [ + { + "id": "dcca1bf9762189e147cc4cde926392b1", + "distribution": "noble", + "kernel": "6.8.0-31-generic-amd64-r20240716", + "architecture": "i386", + "revision": "20241014", + "directory": "/opt/ogboot/tftpboot//ogLive-6.8.0-i386-20241014" + }, + { + "id": "ad8222511753d4013be21602899d642e", + "distribution": "noble", + "kernel": "6.8.0-31-generic-amd64-r20240716", + "architecture": "i386", + "revision": "20241017", + "directory": "/opt/ogboot/tftpboot//ogLive-6.8.0-i386-20241017" + } + ], + "services_status": { + "tftpboot": "active", + "nginx": "active" + } + } } ``` -- **config-file**: Ruta del archivo de configuración que usa oglivecli para guardar los oglives instalados. - -- **download-url**: URL base desde la cual se descargan las imágenes de oglive. - -- **download-dir**: Ruta del directorio en el cual se almacenan las imágenes de oglive descargadas - -- **install-dir**: La ruta del directorio donde se instalan las imágenes de oglive - -- **default-name**: Nombre predeterminado utilizado para los clientes ogLive. - -- **min-release**: La versión mínima recomendada para la instalación de imágenes oglives. - -- **Código 400 Bad Request:** La solicitud es incorrecta. La configuración del ogboot no se ha obtenido correctamente. - - - -### Obtener estado de ogboot - -Devuelve la consistencia, errores de incompatibilidad y de configuración - -**URL:** `/ogboot/v1/status` -**Método HTTP:** GET - -**Ejemplo de Solicitud:** - -```bash -curl -X GET -H "Authorization: $API_KEY" http://example.com/ogboot/v1/status -``` - -**Respuestas:** -- **Código 200 OK:** El status de ogboot se obtuvo exitosamente. +- **Código 404 Not Found:** No se encontraron clientes `ogLive` instalados ni predeterminados. - **Contenido:** - ``` - Some installed ogLive aren't fully compatible: , , ogLive-3.19.0-i386-r4795 - Problems detected: + ```json + { + "error": "NOT_FOUND", + "message": "No default or installed ogLives found." + } + ``` + +- **Código 500 Internal Server Error:** Se produjo un error del servidor al recuperar el estado. + - **Posibles respuestas:** + ```json + { + "error": "FAILED_TO_RETRIEVE_DISK_USAGE", + "message": "Error to retrieve disk usage" + } + ``` + o + ```json + { + "error": "FAILED_TO_RETRIEVE_OGLIVE_CONFIGURATION", + "message": "Error to retrieve ogLive configuration" + } + ``` + o + ```json + { + "error": "FAILED_TO_RETRIEVE_SERVICES_STATUS", + "message": "Error to retrieve services status" + } ``` -- **Código 400 Bad Request:** La solicitud es incorrecta. La status de ogboot no se ha obtenido correctamente. +### Obtener Menú de Descargas de ogLive +Devuelve la lista de ISOs de ogLive disponibles para descargar. -### Mostrar Información de Todos los Clientes ogLive Instalados - -Muestra información en formato JSON sobre todos los clientes ogLive instalados. - -**URL:** `/ogboot/v1/oglives` +**URL:** `/ogboot/v1/oglives/isos` **Método HTTP:** GET **Ejemplo de Solicitud:** ```bash -curl -X GET -H "Authorization: $API_KEY" http://example.com/ogboot/v1/clients/oglives/ - -[ - { - "distribution": "focal", - "kernel": "5.11.0-22-generic", - "architecture": "amd64", - "revision": "r20210413", - "directory": "ogLive-5.11.0-r20210413", - "iso": "ogLive-focal-5.11.0-22-generic-amd64-r20210413.992ebb9.iso" - }, - { - "distribution": "focal", - "kernel": "5.13.0-27-beta", - "architecture": "amd64", - "revision": "r20210706", - "directory": "ogLive-5.13.0-r20210706", - "iso": "ogLive-focal-5.13.0-27-beta-amd64-r20210706.5b4bf5f.iso" - } -] - -``` -- **distribution**: Distribución del sistema operativo de la imagen ogLive - -- **kernel**: Versión del kernel del sistema operativo utilizado por la imagen ogLive - -- **architecture**: Arquitectura del hardware de la imagen ogLive - -- **revision**: Versión de la imagen ogLive - -- **directory**: Directorio donde se encuentra instalado el cliente ogLive en el sistema. - -- **iso**: Nombre del archivo ISO utilizado para instalar el cliente ogLive. - -**Respuestas:** -- **Código 200 OK:** La información sobre todos los clientes ogLive instalados se obtuvo exitosamente. - - **Contenido:** Información sobre todos los clientes ogLive instalados en formato JSON. - - -### Mostrar Información de un Cliente ogLive Instalado - -Muestra información en formato JSON sobre un cliente ogLive instalado específico. - -**URL:** `/ogboot/v1/oglives/{Index}` -**Método HTTP:** GET - -**Parámetros de la URL:** -- `{Index}`: El índice o directorio del cliente ogLive instalado. - -**Ejemplo de Solicitud:** - -```bash -curl -X GET -H "Authorization: $API_KEY" http://example.com/ogboot/v1/clients/oglives/1 - -{ - "distribution": "focal", - "kernel": "5.11.0-22-generic", - "architecture": "amd64", - "revision": "r20210413", - "directory": "ogLive-5.11.0-r20210413", - "iso": "ogLive-focal-5.11.0-22-generic-amd64-r20210413.992ebb9.iso" -} +curl -X GET http://example.com/ogboot/v1/oglives/isos ``` **Respuestas:** -- **Código 200 OK:** La información sobre el cliente ogLive instalado se obtuvo exitosamente. - - **Contenido:** Información sobre el cliente ogLive instalado en formato JSON. -- **Código 404 Not Found:** No se encontró ningún cliente ogLive instalado con el índice o directorio proporcionado. -### Mostrar Información del Cliente ogLive Predeterminado +- **Código 200 OK:** Las ISOs se obtuvieron exitosamente. + - **Contenido:** + ```json + { + "success": "ISOs retrieved successfully", + "message": [ + { + "id": "1", + "filename": "ogLive-noble-6.8.0-31-generic-amd64-r20240716-20241014.iso", + "url": "https://ognproject.evlt.uma.es/oglive//ogLive-noble-6.8.0-31-generic-amd64-r20240716-20241014.iso", + "installed": true, + "compatible": false + }, + { + "id": "2", + "filename": "ogLive-noble-6.8.0-31-generic-amd64-r20240716-20241017.iso", + "url": "https://ognproject.evlt.uma.es/oglive//ogLive-noble-6.8.0-31-generic-amd64-r20240716-20241017.iso", + "installed": true, + "compatible": false + } + + ] + } + ``` -Muestra información en formato JSON sobre el cliente ogLive predeterminado. +- **Código 500 Internal Server Error:** Ocurrió un error al intentar recuperar las ISOs. + - **Contenido:** + ```json + { + "error": "FAILED_TO_RETRIEVE_ISOS", + "message": "Error to retrieve ISO downloads" + } + ``` -**URL:** `/ogboot/v1/oglives/default` + +### Obtener Lista de Todos los Clientes ogLive Instalados + +Devuelve la lista de clientes ogLive instalados, incluyendo el cliente `ogLive` predeterminado. + +**URL:** `/ogboot/v1/oglives` **Método HTTP:** GET **Ejemplo de Solicitud:** ```bash -curl -X GET -H "Authorization: $API_KEY" http://example.com/ogboot/v1/clients/oglives/default - -{ - "distribution": "focal", - "kernel": "5.11.0-22-generic", - "architecture": "amd64", - "revision": "r20210413", - "directory": "ogLive-5.11.0-r20210413", - "iso": "ogLive-focal-5.11.0-22-generic-amd64-r20210413.992ebb9.iso" -} +curl -X 'GET' \ + 'http://172.17.8.37/ogboot/v1/oglives' \ + -H 'accept: application/json' ``` **Respuestas:** -- **Código 200 OK:** La información sobre el cliente ogLive predeterminado se obtuvo exitosamente. - - **Contenido:** Información sobre el cliente ogLive predeterminado en formato JSON. + +- **Código 200 OK:** La lista de clientes ogLive instalados se obtuvo exitosamente. + - **Contenido:** + ```json + { + "success": "ogLive clients retrieved successfully", + "message": { + "default_oglive": "ogLive-6.8.0-i386-20241014", + "installed_ogLives": [ + { + "id": "dcca1bf9762189e147cc4cde926392b1", + "distribution": "noble", + "kernel": "6.8.0-31-generic-amd64-r20240716", + "architecture": "i386", + "revision": "20241014", + "directory": "/opt/ogboot/tftpboot//ogLive-6.8.0-i386-20241014" + }, + { + "id": "ad8222511753d4013be21602899d642e", + "distribution": "noble", + "kernel": "6.8.0-31-generic-amd64-r20240716", + "architecture": "i386", + "revision": "20241017", + "directory": "/opt/ogboot/tftpboot//ogLive-6.8.0-i386-20241017" + } + ] + } + } + ``` + +- **Código 404 Not Found:** No se encontraron clientes `ogLive` instalados. + - **Contenido:** + ```json + { + "error": "NOT_FOUND", + "message": "No ogLive clients found." + } + ``` + +- **Código 500 Internal Server Error:** Se produjo un error del servidor o un error desconocido al recuperar la lista de clientes. + - **Posibles respuestas:** + ```json + { + "error": "SERVER_ERROR", + "message": "Failed to retrieve ogLive clients due to server error." + } + ``` + o + ```json + { + "error": "UNKNOWN_ERROR", + "message": "An unknown error occurred." + } + ``` +### Obtener Información de un Cliente ogLive Instalado +Devuelve la información de un cliente `ogLive` instalado identificado por su checksum. +**URL:** `/ogboot/v1/oglives/{checksum}` +**Método HTTP:** GET -### Cambiar ogLive Predeterminado - -Establece un nuevo cliente ogLive como predeterminado utilizando su índice. - -**URL:** `/ogboot/v1/oglives/default` -**Método HTTP:** POST - -**Parámetros de la URL:** -- `{Index}`: El índice del cliente ogLive que se establecerá como predeterminado. +**Parámetros de Ruta:** +- **`checksum`** (string): Checksum del cliente `ogLive` instalado. + - **Ejemplo**: `9e49a085ba74f97a81bdf9b3d0785094` **Ejemplo de Solicitud:** ```bash -curl -X POST -H "Authorization: $API_KEY" http://example.com/ogboot/v1/clients/oglives/default/1 +curl -X 'GET' \ + 'http://172.17.8.37/ogboot/v1/oglives/9e49a085ba74f97a81bdf9b3d0785094' \ + -H 'accept: application/json' ``` **Respuestas:** -- **Código 200 OK:** El cliente ogLive se estableció como predeterminado exitosamente. -- **Código 404 Not Found:** No se encontró ningún cliente ogLive con el índice proporcionado. + +- **Código 200 OK:** El cliente `ogLive` se obtuvo exitosamente. + - **Contenido:** + ```json + { + "success": "ogLive client retrieved successfully", + "message": { + "id": "9e49a085ba74f97a81bdf9b3d0785094", + "distribution": "noble", + "kernel": "6.8.0-31-generic-amd64-r20240716", + "architecture": "i386", + "revision": "20241014", + "directory": "/opt/ogboot/tftpboot//ogLive-6.8.0-i386-20241014" + } + } + ``` + +- **Código 404 Not Found:** No se encontró el cliente `ogLive` con el checksum proporcionado. + - **Contenido:** + ```json + { + "error": "NOT_FOUND", + "message": "ogLive client with checksum 9e49a085ba74f97a81bdf9b3d0785094 not found." + } + ``` + +- **Código 500 Internal Server Error:** Error del servidor al intentar recuperar la información del cliente `ogLive`. + - **Contenido:** + ```json + { + "error": "SERVER_ERROR", + "message": "Failed to retrieve ogLive client." + } + ``` -### Descargar e Instalar Nuevo Cliente ogLive desde Imagen Descargada -Descarga y luego instala un nuevo cliente ogLive utilizando la imagen descargada, especificada por su nombre de archivo ISO en el parámetro de entrada. +### Obtener Información del Cliente ogLive por Defecto -**URL:** `/ogboot/v1/oglive` -**Método HTTP:** POST +Devuelve la información del cliente `ogLive` configurado como predeterminado. -**Parámetros de Entrada:** -- `ISO: Nombre de la ISO que se desea descargar e instalar +**URL:** `/ogboot/v1/oglives/default` +**Método HTTP:** GET **Ejemplo de Solicitud:** ```bash -curl -X POST -H "Authorization: $API_KEY" -d "ISO=ogLive-focal-5.13.0-27-beta-amd64-r20210706.5b4bf5f.iso" http://example.com/ogboot/v1/oglive +curl -X 'GET' \ + 'http://172.17.8.37/ogboot/v1/oglives/default' \ + -H 'accept: application/json' ``` **Respuestas:** -- **Código 200 OK:** La descarga e instalación del nuevo cliente ogLive desde la imagen descargada fue exitosa. -- **Código 404 Not Found:** No se encontró ninguna imagen ogLive con el índice o nombre de archivo ISO proporcionado. + +- **Código 200 OK:** La información del cliente `ogLive` por defecto se obtuvo exitosamente. + - **Contenido:** + ```json + { + "success": "se ha obtenido el oglive por defecto", + "message": { + "id": "default_oglive_id", + "distribution": "noble", + "kernel": "6.8.0-31-generic-amd64-r20240716", + "architecture": "i386", + "revision": "20241014", + "directory": "/opt/ogboot/tftpboot//ogLive-6.8.0-i386-20241014" + } + } + ``` + +- **Código 500 Internal Server Error:** Ocurrió un error al intentar recuperar el cliente `ogLive` por defecto. + - **Contenido:** + ```json + { + "error": "SERVER_ERROR", + "message": "Failed to retrieve default ogLive." + } + ``` +### Establecer Cliente ogLive por Defecto -### Desinstalar Cliente ogLive +Permite establecer un cliente `ogLive` como predeterminado usando su checksum. -Desinstala un cliente ogLive específico y elimina su imagen asociada. - -**URL:** `/ogboot/v1/oglives/{Index}` -**Método HTTP:** DELETE - -**Parámetros de la URL:** -- `{Index}`: El índice deL archivo ISO del cliente ogLive que se desinstalará y eliminará. - -**Ejemplo de Solicitud:** - -```bash -curl -X DELETE -H "Authorization: $API_KEY" http://example.com/ogboot/v1/oglives/1 -``` - -**Respuestas:** -- **Código 200 OK:** El cliente ogLive se desinstaló y su imagen asociada se eliminó correctamente. -- **Código 404 Not Found:** No se encontró ningún cliente ogLive con el índice o nombre de archivo ISO proporcionado. - - -### Regenerar Archivo de Información de los ogLive - -Regenera el archivo de información de los clientes ogLive instalados. - -**URL:** `/ogboot/v1/oglives` +**URL:** `/ogboot/v1/oglives/default` **Método HTTP:** PUT -**Ejemplo de Solicitud:** - -```bash -curl -X PUT -H "Authorization: $API_KEY" http://example.com/ogboot/v1/oglives -``` - -**Respuestas:** -- **Código 200 OK:** El archivo de información de los clientes ogLive se regeneró correctamente. -- **Código 500 Internal Server Error:** Ocurrió un error al intentar regenerar el archivo de información de los clientes ogLive. - - - -### Mostrar Menú de Descarga de Imagen de ogLive - -Muestra un menú con opciones para descargar imágenes de ogLive disponibles. - -**URL:** `/ogboot/v1/images/download` -**Método HTTP:** GET +**Cuerpo de la Solicitud:** +- Debe enviarse un JSON con la siguiente estructura: + ```json + { + "checksum": "9e49a085ba74f97a81bdf9b3d0785094" + } + ``` + - **`checksum`** (string): El checksum del cliente `ogLive` que se va a establecer como predeterminado. **Ejemplo de Solicitud:** ```bash -curl -X GET -H "Authorization: $API_KEY" http://example.com/ogboot/v1/images/download +curl -X 'PUT' \ + 'http://172.17.8.37/ogboot/v1/oglives/default' \ + -H 'accept: application/json' \ + -H 'Content-Type: application/json' \ + -d '{ + "checksum": "9e49a085ba74f97a81bdf9b3d0785094" + }' ``` **Respuestas:** -- **Código 200 OK:** El menú de descarga de imágenes de ogLive se obtuvo exitosamente. - - **Contenido:** Menú de descarga de imágenes de ogLive en formato JSON. + +- **Código 200 OK:** El cliente `ogLive` se estableció como predeterminado exitosamente. + - **Contenido:** + ```json + { + "success": "ogLive client set as default successfully", + "message": { + "id": "9e49a085ba74f97a81bdf9b3d0785094", + "distribution": "noble", + "kernel": "6.8.0-31-generic-amd64-r20240716", + "architecture": "i386", + "revision": "20241014", + "directory": "/opt/ogboot/tftpboot//ogLive-6.8.0-i386-20241014" + } + } + ``` + +- **Código 400 Bad Request:** Los datos de entrada son inválidos. + - **Contenido:** + ```json + { + "error": "INVALID_INPUT", + "message": "Invalid input data: checksum is required." + } + ``` + +- **Código 500 Internal Server Error:** Ocurrió un error al intentar establecer el cliente `ogLive` como predeterminado. + - **Contenido:** + ```json + { + "error": "SERVER_ERROR", + "message": "Failed to set ogLive as default." + } + ``` + + +### Iniciar Instalación de un Cliente ogLive + +Inicia el proceso de instalación de un cliente `ogLive` a partir de una URL de descarga proporcionada. Este endpoint es asincrónico y, tras la instalación, envía una notificación a la URL del webhook configurada en `ogCore`. + +**URL:** `/ogboot/v1/oglives/install` +**Método HTTP:** POST + +**Cuerpo de la Solicitud:** +- Se debe enviar un JSON con la siguiente estructura: + ```json + { + "url": "https://ognproject.evlt.uma.es/trac/downloads/ogLive-focal-5.11.0-22-generic-amd64-r20210413.992ebb9.iso", + "id": "12345" + } + ``` + - **`url`** (string): URL del archivo ISO de `ogLive` a descargar e instalar. + - **`id`** (string): ID único de transacción para rastrear el proceso de instalación. + +**Ejemplo de Solicitud:** + +```bash +curl -X 'POST' \ + 'http://172.17.8.37/ogboot/v1/oglives/install' \ + -H 'accept: application/json' \ + -H 'Content-Type: application/json' \ + -d '{ + "url": "https://ognproject.evlt.uma.es/trac/downloads/ogLive-focal-5.11.0-22-generic-amd64-r20210413.992ebb9.iso", + "id": "12345" + }' +``` + +**Respuestas:** + +- **Código 202 Accepted:** La instalación del cliente `ogLive` se ha iniciado correctamente. + - **Contenido:** + ```json + { + "success": "ogLive client installation started", + "transaction_id": "12345" + } + ``` + +- **Código 400 Bad Request:** Los datos de entrada no son válidos. + - **Contenido:** + ```json + { + "error": "Invalid input data", + "details": "URL and transaction ID are required." + } + ``` + +- **Código 500 Internal Server Error:** Fallo al iniciar la instalación del cliente `ogLive`. + - **Contenido:** + ```json + { + "error": "Failed to initiate ogLive installation", + "details": "Detalles del error específico" + } + ``` + +**Nota:** +Este endpoint ejecuta la instalación en segundo plano y notifica al `ogCore` a través de un webhook en la URL configurada al finalizar el proceso, enviando el estado, el código de respuesta (200 si es exitoso) y un mensaje. + + + +### Desinstalar un Cliente ogLive + +Permite desinstalar un cliente `ogLive` identificado por su checksum. + +**URL:** `/ogboot/v1/oglives/{checksum}` +**Método HTTP:** DELETE + +**Parámetros de Ruta:** +- **`checksum`** (string): Checksum del cliente `ogLive` a desinstalar. + - **Ejemplo**: `9e49a085ba74f97a81bdf9b3d0785094` + +**Ejemplo de Solicitud:** + +```bash +curl -X 'DELETE' \ + 'http://172.17.8.37/ogboot/v1/oglives/9e49a085ba74f97a81bdf9b3d0785094' \ + -H 'accept: application/json' +``` + +**Respuestas:** + +- **Código 200 OK:** El cliente `ogLive` se desinstaló exitosamente. + - **Contenido:** + ```json + { + "message": "ogLive client uninstalled successfully", + "details": "Detalles adicionales de la desinstalación." + } + ``` + +- **Código 404 Not Found:** No se encontró el cliente `ogLive` con el checksum proporcionado. + - **Contenido:** + ```json + { + "error": "NOT_FOUND", + "message": "ogLive client not found." + } + ``` + +- **Código 403 Forbidden:** No se puede desinstalar el cliente `ogLive` predeterminado. + - **Contenido:** + ```json + { + "error": "FORBIDDEN", + "message": "Cannot uninstall the default ogLive client." + } + ``` + +- **Código 500 Internal Server Error:** Ocurrió un error al intentar desinstalar el cliente `ogLive`. + - **Contenido:** + ```json + { + "error": "SERVER_ERROR", + "message": "Failed to uninstall ogLive client." + } + ``` + +- **Otros errores no previstos:** + ```json + { + "error": "UNKNOWN_ERROR", + "message": "An unknown error occurred." + } + ``` +