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

refs #449 adds installation requisites, configuration parameters of nginx, samba and php-fpm and oglivecli commands documentation

ogboot-api-documentation
Luis Gerardo Romero Garcia 2024-09-10 10:18:39 +02:00
parent 2636f0fe4d
commit b03e60a7ea
1 changed files with 306 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

308
docs/ogboot-ogcore-communication-design.md
View File

@ -125,21 +125,325 @@ El proceso de arranque en red utilizando ogboot sigue un flujo bien definido que
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.
- El cliente descarga el archivo especificado desde el servidor ogBoot y lo utiliza para continuar con el proceso de arranque, que generalmente incluye la carga del kernel y otros archivos necesarios para arrancar el sistema operativo.
- **ogBoot** tiene un directorio **tftpboot** donde están alojados los archivos de arranque, como **ipxe-efi** y **undionly.pxe**.
Este flujo de comunicación asegura que el cliente reciba todos los parámetros necesarios para un arranque en red exitoso, permitiendo a ogboot gestionar de manera eficiente el despliegue de sistemas operativos y configuraciones en un entorno de red.
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:
```nginx
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:
```ini
[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
#!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`