From b03e60a7eabf6565d162e04d1c6c7df0ba808342 Mon Sep 17 00:00:00 2001 From: lgromero Date: Tue, 10 Sep 2024 10:18:39 +0200 Subject: [PATCH] refs #449 adds installation requisites, configuration parameters of nginx, samba and php-fpm and oglivecli commands documentation --- docs/ogboot-ogcore-communication-design.md | 308 ++++++++++++++++++++- 1 file changed, 306 insertions(+), 2 deletions(-) diff --git a/docs/ogboot-ogcore-communication-design.md b/docs/ogboot-ogcore-communication-design.md index 0dcb25a..948ee45 100644 --- a/docs/ogboot-ogcore-communication-design.md +++ b/docs/ogboot-ogcore-communication-design.md @@ -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`