diff --git a/README.md b/README.md index 367fd0d..fb49f24 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,418 @@ -OpenGnsys Repository Manager README +OpenGnsys Repository Manager ======================================= -Este repositorio GIT contiene la estructura de datos del repositorio de datos de OpenGnsys. +Este repositorio GIT contiene la estructura de datos del repositorio de imágenes de OpenGnsys. -- bin -------- Binarios y scripts de gestión del repositorio. -- etc -------- Ficheros o plantillas de configuración del repositorio. -- py_scripts - Scripts en Python 3, algunos de los cuales son traducciones de los scripts bash situados en "bin". \ No newline at end of file +- **bin** -------------- Binarios y scripts de gestión del repositorio. +- **etc** -------------- Ficheros y plantillas de configuración del repositorio. +- **py_scripts** --- Scripts en Python 3, algunos de los cuales son traducciones de los scripts bash situados en "bin". + +--- + +## API de ogRepository + +La API de ogRepository proporciona una interfaz para facilitar la administración de las imágenes almacenadas en los repositorios de imágenes, permitiendo eliminarlas, enviarlas a clientes ogLive (con diferentes protocolos de transmisión), importarlas desde otros repositorios, etc. + +El presente documento detalla los endpoints de la API, con sus respectivos parámetros de entrada, así como las acciones que llevan a cabo. + +--- +### Tabla de Contenido: + +1. [Obtener Información de todas las Imágenes](#obtener-información-de-todas-las-imágenes) - `GET /ogrepository/v1/images` +2. [Obtener Información de una Imagen concreta](#obtener-información-de-una-imagen-concreta) - `GET /ogrepository/v1/images/{name}` +3. [Actualizar Información del Repositorio](#actualizar-información-del-repositorio) - `PUT /ogrepository/v1/images` +4. [Eliminar una Imagen](#eliminar-una-imagen) - `DELETE /ogrepository/v1/images/{name}` +5. [Importar una Imagen](#importar-una-imagen) - `POST /ogrepository/v1/images/import-image` +6. [Enviar una Imagen mediante UDPcast](#enviar-una-imagen-mediante-udpcast) - `POST /ogrepository/v1/images/{protocol}` +7. [Enviar una Imagen mediante UFTP](#enviar-una-imagen-mediante-uftp) - `POST /ogrepository/v1/images/{protocol}` +8. [Crear archivo ".torrent"](#crear-archivo-torrent) - `POST /ogrepository/v1/images/create-torrent` +9. [Enviar una Imagen mediante P2P](#enviar-una-imagen-mediante-p2p) - `POST /ogrepository/v1/images/{protocol}` +10. [Chequear integridad de Imagen](#chequear-integridad-de-imagen) - `GET /ogrepository/v1/images/check-image` +11. [Exportar una Imagen](#exportar-una-imagen) - `POST /ogrepository/v1/images/export-image` +12. [Definir Imagen Global](#definir-imagen-global) - `PUT /ogrepository/v1/images/set-global` +13. [Definir Imagen Local](#definir-imagen-local) - `PUT /ogrepository/v1/images/set-local` +14. [Ver Estado de Transmisiones Multicast-P2P](#ver-estado-de-transmisiones-multicast-p2p) - +15. [Cancelar Transmisión Multicast-P2P](#cancelar-transmisión-multicast-p2p) - + +--- +### Obtener Información de todas las Imágenes + +Se devolverá la informacion contenida en el archivo "**/opt/opengnsys/etc/repoinfo.json**" (que corresponde a todas las imágenes monolíticas almacenadas en el repositorio). +Se debe crear un script que devuelva dicha información, porque actualmente no hay ninguno. + +**URL:** `/ogrepository/v1/images` +**Método HTTP:** GET + +**Ejemplo de Solicitud:** + +```bash +curl -X GET -H "Authorization: $API_KEY" http://example.com/ogrepository/v1/images +``` + +**Respuestas:** +- **Código 500 Internal Server Error:** Ocurrió un error al consultar y/o devolver la información de las imágenes. +- **Código 200 OK:** La información de las imágenes se obtuvo exitosamente. + - **Contenido:** Información de imágenes en formato JSON. + ```json + { + "directory": "/opt/opengnsys/images", + "images": [ + { + "name": "UbuntuSATA", + "type": "img", + "clientname": "Ubuntu_SATA", + "clonator": "partclone", + "compressor": "lzop", + "filesystem": "EXTFS", + "datasize": 8704000000 + }, + { + "name": "Windows10", + "type": "img", + "clientname": "Windows_10", + "clonator": "partclone", + "compressor": "lzop", + "filesystem": "NTFS", + "datasize": 23654400000 + } + ], + "ous": [] + } + ``` + - **name**: Nombre de la imagen, sin extensión. + - **type**: Extensión de la imagen. + - **clientname**: Nombre asignado al modelo del que se ha obtenido la imagen. + - **clonator**: Programa utilizado para la clonación. + - **compressor**: Programa utilizado para la compresión. + - **filesystem**: Sistema de archivos utilizado en la partición clonada. + - **datasize**: Tamaño de la imagen una vez restaurada, en bytes (tamaño de los datos). + +--- +### Obtener Información de una Imagen concreta + +Se devolverá la informacion contenida en el archivo "**/opt/opengnsys/etc/repoinfo.json**" (correspondiente a la imagen especificada). +Se debe crear un script que devuelva dicha información, porque actualmente no hay ninguno. + +**URL:** `/ogrepository/v1/images/{name}` +**Método HTTP:** GET + +**Parámetros de la URL:** +- `{name}`: Nombre de la imagen. + +**Ejemplo de Solicitud:** + +```bash +curl -X GET -H "Authorization: $API_KEY" http://example.com/ogrepository/v1/images/Windows10 +``` + +**Respuestas:** +- **Código 500 Internal Server Error:** Ocurrió un error al consultar y/o devolver la información de las imágenes. +- **Código 400 Bad Request:** No se ha encontrado la imagen especificada. +- **Código 200 OK:** La información de la imagen se obtuvo exitosamente. + - **Contenido:** Información de la imagen en formato JSON. + ```json + { + "name": "Windows10", + "type": "img", + "clientname": "Windows_10", + "clonator": "partclone", + "compressor": "lzop", + "filesystem": "NTFS", + "datasize": 23654400000 + } + ``` + - **name**: Nombre de la imagen, sin extensión. + - **type**: Extensión de la imagen. + - **clientname**: Nombre asignado al modelo del que se ha obtenido la imagen. + - **clonator**: Programa utilizado para la clonación. + - **compressor**: Programa utilizado para la compresión. + - **filesystem**: Sistema de archivos utilizado en la partición clonada. + - **datasize**: Tamaño de la imagen una vez restaurada, en bytes (tamaño de los datos). + +--- +### Actualizar Información del Repositorio + +Se actualizará la información de las imágenes almacenadas en el repositorio, reflejándola en el archivo "**/opt/opengnsys/etc/repoinfo.json**". +Se puede hacer con el script "**checkrepo**", que actualmente se ejecuta a cada minuto por crontab (indirectamente, porque es llamado por el script "**deletepreimage**", que es el que realmente se ejecuta por crontab). +Creemos que este endpoint debe ser llamado por ogCore u ogLive cada vez que se haya creado una imagen, y ejecutado desde el propio ogRepository cada vez que se elimine una imagen. + +**URL:** `/ogrepository/v1/images` +**Método HTTP:** PUT + +**Ejemplo de Solicitud:** + +```bash +curl -X PUT -H "Authorization: $API_KEY" http://example.com/ogrepository/v1/images +``` +**Respuestas:** +- **Código 500 Internal Server Error:** Ocurrió un error al actualizar la información de las imágenes. +- **Código 200 OK:** La actualización se realizó exitosamente. + +--- +### Eliminar una Imagen + +Se eliminará la imagen especificada como parámetro. +Se puede hacer con el script "**deleteimage**", que actualmente no se utiliza (lo que se hace ahora es eliminar todas las imágenes marcadas con ".delete", mediante el script "deletepreimage", que se ejecuta por crontab a cada minuto). +Además, el script "deleteimage" debería llamar al script "**checkrepo**", para actualizar la información del repositorio una vez eliminada la imagen. + +**NOTA**: En el pliego se solicita una función "papelera", para lo que habría que modificar los scripts existentes (y posiblemente crear otros endpoints, como "recuperar imagen de la papelera", por ejemplo). + +**URL:** `/ogrepository/v1/images/{name}` +**Método HTTP:** DELETE + +**Ejemplo de Solicitud:** + +```bash +curl -X DELETE -H "Authorization: $API_KEY" http://example.com/ogrepository/v1/images/Windows10 +``` +**Respuestas:** +- **Código 500 Internal Server Error:** Ocurrió un error al eliminar la imagen. +- **Código 400 Bad Request:** No se ha encontrado la imagen especificada. +- **Código 200 OK:** La imagen se eliminó exitosamente. + +--- +### Importar una Imagen + +Se importará una imagen de un repositorio remoto al repositorio local. +Se puede hacer con el script "**importimage**", que actualmente no se utiliza. + +**URL:** `/ogrepository/v1/images/import-image` +**Método HTTP:** POST + +**Cuerpo de la Solicitud (JSON):** +- **user**: Usuario con el que acceder al repositorio remoto (por defecto, usuario local). +- **repo**: IP o hostname del repositorio remoto. +- **image**: Nombre de la imagen a importar. + +**Ejemplo de Solicitud:** + +```bash +curl -X POST -H "Authorization: $API_KEY" -H "Content-Type: application/json" -d '{"user":"user_name", "repo":"192.168.56.100", "image":"Windows10"}' http://example.com/ogrepository/v1/images/import-image +``` +**Respuestas:** +- **Código 500 Internal Server Error:** Ocurrió un error al importar la imagen. +- **Código 400 Bad Request:** No se ha encontrado la imagen y/o el equipo remoto especificados. +- **Código 200 OK:** La imagen se ha importado exitosamente. + +--- +### Enviar una Imagen mediante UDPcast + +Se enviará una imagen por Multicast, mediante la aplicación UDPcast. +Se puede hacer con el script "**sendFileMcast**", que a su vez llama al binario "**udp-sender**", que es quien realmente realiza el envío. + +**URL:** `/ogrepository/v1/images/{protocol}` +**Método HTTP:** POST + +**Parámetros de la URL:** +- `{protocol}`: Protocolo que se utilizará para enviar la imagen (en este caso, "udpcast"). + +**Cuerpo de la Solicitud (JSON):** +- **image**: Nombre completo de la imagen a enviar, con extensión (con o sin ruta). +- **port**: Puerto Multicast. +- **method**: Modalidad half-duplex o full-duplex. +- **ip**: IP Multicast. +- **bitrate**: Velocidad de transmisión (en Mbps). +- **nclients**: Número mínimo de clientes. +- **maxtime**: Tiempo máximo de espera. + +**Ejemplo de Solicitud:** + +```bash +curl -X POST -H "Authorization: $API_KEY" -H "Content-Type: application/json" -d '{"image":"Windows10.img", "port":"9000", "method":"full", "ip":"239.194.17.2", "bitrate":"70M", "nclients":"20", "maxtime":"120"}' http://example.com/ogrepository/v1/images/udpcast +``` +**Respuestas:** +- **Código 500 Internal Server Error:** Ocurrió un error al enviar la imagen. +- **Código 400 Bad Request:** No se ha encontrado la imagen especificada. +- **Código 200 OK:** La imagen se ha enviado exitosamente. + +--- +### Enviar una Imagen mediante UFTP + +Se enviará una imagen por Unicast o Multicast, mediante el protocolo "UFTP". +Se puede hacer con el script "**sendFileUFTP.py**", que requiere que previamente los clientes ogLive destino se pongan en escucha con un daemon "UFTPD" (ejecutando el script "**listenUFTPD.py**"). +**NOTA**: Los envíos mediante "UFTP" funcionan al revés que los envíos mediante "UDPcast" (con este último, primero se debe ejecutar un comando en el servidor, y luego en los clientes). + +**URL:** `/ogrepository/v1/images/{protocol}` +**Método HTTP:** POST + +**Parámetros de la URL:** +- `{protocol}`: Protocolo que se utilizará para enviar la imagen (en este caso, "uftp"). + +**Cuerpo de la Solicitud (JSON):** +- **image**: Nombre completo de la imagen a enviar, con extensión (con o sin ruta). +- **port**: Puerto Multicast. +- **ip**: IP Unicast/Multicast. +- **bitrate**: Velocidad de transmisión (con "K" para Kbps, "M" para Mbps o "G" para Gbps). + +**Ejemplo de Solicitud:** + +```bash +curl -X POST -H "Authorization: $API_KEY" -H "Content-Type: application/json" -d '{"image":"Windows10.img", "port":"9000", "ip":"239.194.17.2", "bitrate":"1G"}' http://example.com/ogrepository/v1/images/uftp +``` +**Respuestas:** +- **Código 500 Internal Server Error:** Ocurrió un error al enviar la imagen. +- **Código 400 Bad Request:** No se ha encontrado la imagen especificada. +- **Código 200 OK:** La imagen se ha enviado exitosamente. + +--- +### Crear archivo .torrent + +Se creará un archivo ".torrent" para la imagen especificada como parámetro. +Se debe crear un script que realice dicha tarea, porque actualmente se hace mediante el script "**torrent-creator**", que se ejecuta por crontab a cada minuto (y crea un archivo ".torrent" por cada imagen que no tenga uno asociado). +**NOTA**: Puede que sea preferible que esta acción la realice el propio ogLive al crear una imagen, ya que también tiene las herramientas para hacerlo. + +**URL:** `/ogrepository/v1/images/create-torrent` +**Método HTTP:** POST + +**Cuerpo de la Solicitud (JSON):** +- **image**: Nombre completo de la imagen a la que asociar un archivo torrent. + +**Ejemplo de Solicitud:** + +```bash +curl -X POST -H "Authorization: $API_KEY" -H "Content-Type: application/json" -d '{"image":"Windows10.img"}' http://example.com/ogrepository/v1/images/create-torrent +``` +**Respuestas:** +- **Código 500 Internal Server Error:** Ocurrió un error al crear el archivo torrent. +- **Código 400 Bad Request:** No se ha encontrado la imagen especificada. +- **Código 200 OK:** El archivo torrent se ha creado exitosamente. + +--- +### Enviar una Imagen mediante P2P + +Se debe hacer tracking de los torrents almacenados en ogRepository, e iniciar la transferencia de la imagen especificada (además, los clientes deben disponer del torrent asociado, y añadirlo a su cliente torrent). +No tengo claro cómo se haría con los scripts existentes (que utilizan "bttrack" y "ctorrent"), pero si usáramos "opentracker" y "transmission", se debería crear nuevos scripts. + +**URL:** `/ogrepository/v1/images/{protocol}` +**Método HTTP:** POST + +**Parámetros de la URL:** +- `{protocol}`: Protocolo que se utilizará para enviar la imagen (en este caso, "p2p"). + +**Cuerpo de la Solicitud (JSON):** +- **image**: Nombre completo de la imagen a enviar, con extensión (con o sin ruta). + +**Ejemplo de Solicitud:** + +```bash +curl -X POST -H "Authorization: $API_KEY" -H "Content-Type: application/json" -d '{"image":"Windows10.img"}' http://example.com/ogrepository/v1/images/p2p +``` +**Respuestas:** +- **Código 500 Internal Server Error:** Ocurrió un error al enviar la imagen. +- **Código 400 Bad Request:** No se ha encontrado la imagen especificada. +- **Código 200 OK:** La imagen se ha enviado exitosamente. + +--- +### Chequear Integridad de Imagen + +Se comprobará la integridad de todos los ficheros asociados a la imagen especificada como parámetro. +Para esto, entiendo que se debe crear un script que compare los ficheros asociados a la imagen (especialmente los archivos "**.sum**" y "**.full.sum**"), con la información almacenada en el archivo "**/opt/opengnsys/etc/repoinfo.json**". + +**URL:** `/ogrepository/v1/images/check-image` +**Método HTTP:** GET + +**Cuerpo de la Solicitud (JSON):** +- **image**: Nombre completo de la imagen a chequear, con extensión (con o sin ruta). + +**Ejemplo de Solicitud:** + +```bash +curl -X POST -H "Authorization: $API_KEY" -H "Content-Type: application/json" -d '{"image":"Windows10.img"}' http://example.com/ogrepository/v1/images/check-image +``` +**Respuestas:** +- **Código 500 Internal Server Error:** Ocurrió un error al chequear la imagen. +- **Código 400 Bad Request:** No se ha encontrado la imagen especificada. +- **Código 200 OK:** La imagen se ha chequeado exitosamente. +- **Código 200 KO:** La imagen se ha chequeado correctamente, pero no ha pasado el test. + +--- +### Exportar una Imagen + +Se exportará una imagen del repositorio local a un repositorio remoto. +Se debe crear un script que realice dicha tarea (o se puede utilizar el script "**importimage**", que realiza la acción contraria, pero que actualmente no se utiliza). + +**NOTA**: Aunque no se indica en el pliego, entendemos que también será necesario especificar credenciales de acceso al repositorio remoto como parámetros de entrada. + +**URL:** `/ogrepository/v1/images/export-image` +**Método HTTP:** POST + +**Cuerpo de la Solicitud (JSON):** +- **repo**: IP o hostname del repositorio remoto. +- **ou**: Unidad Organizativa del repositorio remoto. +- **image**: Nombre de la imagen a exportar. + +**Ejemplo de Solicitud:** + +```bash +curl -X POST -H "Authorization: $API_KEY" -H "Content-Type: application/json" -d '{"repo":"192.168.56.200", "ou":"OU_Ejemplo", "image":"Windows10"}' http://example.com/ogrepository/v1/images/export-image +``` +**Respuestas:** +- **Código 500 Internal Server Error:** Ocurrió un error al exportar la imagen. +- **Código 400 Bad Request:** No se ha encontrado la imagen y/o el equipo remoto especificados. +- **Código 200 OK:** La imagen se ha exportado exitosamente. + +--- +### Definir Imagen Global + +Se marcará como "global" la imagen especificada como parámetro. +En principio, esto requerirá agregar una nueva clave al archivo "**/opt/opengnsys/etc/repoinfo.json**" (por ejemplo, "scope"), modificando el script "**checkrepo**", para que realice dicha modificación. +También debe crearse un script que realice la definición de la imagen especificada (modificando el valor de la nueva clave del archivo "**/opt/opengnsys/etc/repoinfo.json**", de "local" a "global", por ejemplo). +Además, deberá llamarse a un script que exporte dicha imagen a los demás repositorios gestionados por el servidor de administración (que aun no está creado). + +**URL:** `/ogrepository/v1/images/set-global` +**Método HTTP:** PUT + +**Cuerpo de la Solicitud (JSON):** +- **image**: Nombre completo de la imagen a definir como global, con extensión (con o sin ruta). + +**Ejemplo de Solicitud:** + +```bash +curl -X PUT -H "Authorization: $API_KEY" -H "Content-Type: application/json" -d '{"image":"Windows10.img"}' http://example.com/ogrepository/v1/images/set-global +``` +**Respuestas:** +- **Código 500 Internal Server Error:** Ocurrió un error al definir la imagen. +- **Código 400 Bad Request:** No se ha encontrado la imagen especificada. +- **Código 200 OK:** La definición se realizó exitosamente. + +--- +### Definir Imagen Local + +Se marcará como "local" la imagen especificada como parámetro, que previamente habría sido marcada como "global" (ya que de forma predeterminada, todas las imágenes estarán marcadas como "local"). +Como comentábamos en el endpoint precedentte, esto requerirá agregar una nueva clave al archivo "**/opt/opengnsys/etc/repoinfo.json**" (por ejemplo, "scope"), modificando el script "**checkrepo**", para que realice dicha modificación. +También debe crearse un script que realice la definición de la imagen especificada (modificando el valor de la nueva clave del archivo "**/opt/opengnsys/etc/repoinfo.json**", de "global" a "local", por ejemplo). +Este endpoint deberá ser llamado en todos los repositorios gestionados por el mismo servidor de administración (para que todos hagan la modificación). + +**URL:** `/ogrepository/v1/images/set-local` +**Método HTTP:** PUT + +**Cuerpo de la Solicitud (JSON):** +- **image**: Nombre completo de la imagen a definir como local, con extensión (con o sin ruta). + +**Ejemplo de Solicitud:** + +```bash +curl -X PUT -H "Authorization: $API_KEY" -H "Content-Type: application/json" -d '{"image":"Windows10.img"}' http://example.com/ogrepository/v1/images/set-local +``` +**Respuestas:** +- **Código 500 Internal Server Error:** Ocurrió un error al definir la imagen. +- **Código 400 Bad Request:** No se ha encontrado la imagen especificada. +- **Código 200 OK:** La definición se realizó exitosamente. + +--- +### Ver Estado de Transmisiones Multicast-P2P + +Se devolverá información del estado de las transmisiones existentes, con un identificador de cada sesión multicast o P2P, y la imagen asociada. +Se debe estudiar como realizar esta tarea para cada uno de los protocolos de transmisión, ya que cada uno tiene sus particularidades, y habitualmente no tienen comandos asociados para comprobar el estado de las transmisiones. +Y tampoco está claro que protocolo se utilizará para transimisiones Multicast (¿"UDPcast", "UFTP", o ambos?), ni qué programas se utilizarán para P2P (¿"ctorrent/bttrack" u "opentracker/Transmission"?). +**NOTA**: Posiblemente deba crearse un endpoint específico para cada uno de los protocolos que se utilicen. + +--- +### Cancelar Transmisión Multicast-P2P + +Se cancelará la transmisión Multicast o P2P cuyo identificador se especifique como parámetro. +Aunque cancelar una transmisión Multicast o P2P es una tarea sencilla (independientemente del protocolo o programa que se utilice), en principio deberá crearse un script para cada uno de ellos. +Y la definición del endpoint depende de como se defina el endpoint anterior ("**Ver Estado de Transmisiones Multicast-P2P**"), ya que será el que determine cómo se especifica el identificador de la transmisión. + +--- \ No newline at end of file