opengnsys
/
ogboot
2
0
Fork 0
Code Issues Pull Requests 2 Packages Projects Releases Wiki Activity

refs #1095 updates readme with installation steps and oglive api

ogboot-log
Luis Gerardo Romero Garcia 2024-11-05 14:25:02 +01:00
parent 6576a4c9ec
commit 780d17310b
1 changed files with 467 additions and 200 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

667
README.md
View File

@ -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."
}
```