ogrepository/README.md

19 KiB

ogRepository - OpenGnsys Repository Manager

Este repositorio GIT contiene la estructura de datos del repositorio de imágenes de OpenGnsys.

  • admin -------- Archivos de configuración del repositorio.
  • 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 - GET /ogrepository/v1/images/get-info
  2. Obtener Información de una Imagen concreta - GET /ogrepository/v1/images/get-info
  3. Actualizar Información del Repositorio - PUT /ogrepository/v1/images
  4. Eliminar una Imagen - DELETE /ogrepository/v1/images/delete-image
  5. Recuperar una Imagen - POST /ogrepository/v1/images/recover-image
  6. Importar una Imagen - POST /ogrepository/v1/images/import-image
  7. Enviar una Imagen mediante UDPcast - POST /ogrepository/v1/images/send-udpcast
  8. Enviar una Imagen mediante UFTP - POST /ogrepository/v1/images/send-uftp
  9. Crear archivo ".torrent" - POST /ogrepository/v1/images/create-torrent
  10. Enviar una Imagen mediante P2P - POST /ogrepository/v1/images/send-p2p
  11. Chequear integridad de Imagen - GET /ogrepository/v1/images/check-image
  12. Ver Estado de Transmisiones Multicast-P2P -
  13. 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 almacenadas en el repositorio), y en el archivo "/opt/opengnsys/etc/trashinfo.json" (que corresponde a las imágenes que fueron eliminadas, que estarán en la papelera).
Se puede utilizar el script "getRepoInfo.py, que hemos programado recientemente.

URL: /ogrepository/v1/images/get-info
Método HTTP: GET

Cuerpo de la Solicitud (JSON):

  • image: Nombre de la imagen (con extensión), pero en este caso "all".
  • ou_subdir: Subdirectorio correspondiente a la OU, pero en este caso "none".

Ejemplo de Solicitud:

curl -X GET -H "Authorization: $API_KEY" -H "Content-Type: application/json" -d '{"image":"all","ou_subdir":"none"}' http://example.com/ogrepository/v1/images/get-info  

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.
      
      {
        "REPOSITORY": {
          "directory": "/opt/opengnsys/images",
          "images": [
            {
              "name": "Ubuntu24",
              "type": "img",
              "clientname": "Ubuntu_24",
              "clonator": "partclone",
              "compressor": "lzop",
              "filesystem": "EXTFS",
              "datasize": 9859634200
            },
            {
              "name": "Windows10",
              "type": "img",
              "clientname": "Windows_10",
              "clonator": "partclone",
              "compressor": "lzop",
              "filesystem": "NTFS",
              "datasize": 23654400000
            }
          ],
          "ous": [
            {
              "subdir": "OU_subdir",
              "images": [
                {
                  "name": "Ubuntu20",
                  "type": "img",
                  "clientname": "Ubuntu_20",
                  "clonator": "partclone",
                  "compressor": "lzop",
                  "filesystem": "EXTFS",
                  "datasize": 8704000000
                }
              ]   
            }
          ]
        }
      },
        "TRASH": {
          "directory": "/opt/opengnsys/images_trash",
          "images": [],
          "ous": [
            {
              "subdir": "CentroVirtual",
              "images": [
                {
                  "name": "Ubuntu20OLD",
                  "type": "img",
                  "clientname": "Ubuntu_20",
                  "clonator": "partclone",
                  "compressor": "lzop",
                  "filesystem": "EXTFS",
                  "datasize": 8704000000
                }
              ]
            }
          ]
        }
      
      • 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 de la imagen especificada, que puede estar en el archivo "/opt/opengnsys/etc/repoinfo.json" o en el archivo "/opt/opengnsys/etc/trashinfo.json" (en este último caso, si la imagen está en la papelera).
Se puede utilizar el script "getRepoInfo.py, que hemos programado recientemente.

URL: /ogrepository/v1/images/get-info
Método HTTP: GET

Cuerpo de la Solicitud (JSON):

  • image: Nombre de la imagen (con extensión).
  • ou_subdir: Subdirectorio correspondiente a la OU (o "none" si no es el caso).

Ejemplo de Solicitud:

curl -X GET -H "Authorization: $API_KEY" -H "Content-Type: application/json" -d '{"image":"Windows10.img","ou_subdir":"none"}' http://example.com/ogrepository/v1/images/get-info

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.
      
      {
        "directory": "/opt/opengnsys/images",
        "images": [
          {
            "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 "updateRepoInfo.py", que hemos programado recientemente (y que es similar al script bash original "checkrepo").
Este endpoint es llamado por el script "deleteImage.py" (para actualizar la información cada vez que se elimine una imagen), y creemos que también debe ser llamado por ogCore u ogLive cada vez que se haya creado una imagen.

URL: /ogrepository/v1/images
Método HTTP: PUT

Ejemplo de Solicitud:

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, pudiendo eliminarla permanentemente o enviarla a la papelera.
Se puede hacer con el script "deleteimage.py", que hemos programado recientemente (y que incluye la funcionalidad "papelera"), y que a su vez llama al script "updateRepoInfo.py", para actualizar la información del repositorio.

URL: /ogrepository/v1/images/delete-image
Método HTTP: DELETE

Cuerpo de la Solicitud (JSON):

  • image: Nombre de la imagen (con extensión).
  • ou_subdir: Subdirectorio correspondiente a la OU (o "none" si no es el caso).
  • method: Método de eliminación (puede ser "trash" o "permanent").

Ejemplo de Solicitud:

curl -X DELETE -H "Authorization: $API_KEY" -H "Content-Type: application/json" -d '{"image":"Windows10.img", "ou_subdir":"none", "method":"trash"}' http://example.com/ogrepository/v1/images/delete-image

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.

Recuperar una Imagen

Se recuperará la imagen especificada como parámetro, desde la papelera.
Se puede hacer con el script "recoverImage.py", que hemos programado recientemente, y que a su vez llama al script "updateRepoInfo.py", para actualizar la información del repositorio.

URL: /ogrepository/v1/images/recover-image
Método HTTP: POST

Cuerpo de la Solicitud (JSON):

  • image: Nombre de la imagen (con extensión).
  • ou_subdir: Subdirectorio correspondiente a la OU (o "none" si no es el caso).

Ejemplo de Solicitud:

curl -X POST -H "Authorization: $API_KEY" -H "Content-Type: application/json" -d '{"image":"Windows10.img", "ou_subdir":"none"}' http://example.com/ogrepository/v1/images/recover-image

Respuestas:

  • Código 500 Internal Server Error: Ocurrió un error al recuperar la imagen.
  • Código 400 Bad Request: No se ha encontrado la imagen especificada.
  • Código 200 OK: La imagen se recuperó exitosamente.

Importar una Imagen

Se importará una imagen de un repositorio remoto al repositorio local.
Se puede hacer con el script "importImage.py", que hemos programado recientemente.

URL: /ogrepository/v1/images/import-image
Método HTTP: POST

Cuerpo de la Solicitud (JSON):

  • image: Nombre de la imagen (con extensión).
  • ou_subdir: Subdirectorio correspondiente a la OU (o "none" si no es el caso).
  • repo: IP o hostname del repositorio remoto.
  • user: Usuario con el que acceder al repositorio remoto.

Ejemplo de Solicitud:

curl -X POST -H "Authorization: $API_KEY" -H "Content-Type: application/json" -d '{"image":"Windows10.img", "ou_subdir":"none", "repo":"192.168.56.100", "user":"user_name"}' 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.py", que a su vez llama al binario "udp-sender", que es quien realmente realiza el envío.

URL: /ogrepository/v1/images/send-udpcast
Método HTTP: POST

Cuerpo de la Solicitud (JSON):

  • image: Nombre de la imagen (con extensión).
  • ou_subdir: Subdirectorio correspondiente a la OU (o "none" si no es el caso).
  • 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:

curl -X POST -H "Authorization: $API_KEY" -H "Content-Type: application/json" -d '{"image":"Windows10.img", "ou_subdir":"none", "port":"9000", "method":"full", "ip":"239.194.17.2", "bitrate":"70M", "nclients":"20", "maxtime":"120"}' http://example.com/ogrepository/v1/images/send-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/send-uftp
Método HTTP: POST

Cuerpo de la Solicitud (JSON):

  • image: Nombre de la imagen (con extensión).
  • ou_subdir: Subdirectorio correspondiente a la OU (o "none" si no es el caso).
  • 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:

curl -X POST -H "Authorization: $API_KEY" -H "Content-Type: application/json" -d '{"image":"Windows10.img", "ou_subdir":"none", "port":"9000", "ip":"239.194.17.2", "bitrate":"1G"}' http://example.com/ogrepository/v1/images/send-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 de la imagen (con extensión).
  • ou_subdir: Subdirectorio correspondiente a la OU (o "none" si no es el caso).

Ejemplo de Solicitud:

curl -X POST -H "Authorization: $API_KEY" -H "Content-Type: application/json" -d '{"image":"Windows10.img", "ou_subdir":"none"}' 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" (como se había propuesto), se debería crear nuevos scripts.

URL: /ogrepository/v1/images/send-p2p
Método HTTP: POST

Cuerpo de la Solicitud (JSON):

  • image: Nombre de la imagen (con extensión).
  • ou_subdir: Subdirectorio correspondiente a la OU (o "none" si no es el caso).

Ejemplo de Solicitud:

curl -X POST -H "Authorization: $API_KEY" -H "Content-Type: application/json" -d '{"image":"Windows10.img", "ou_subdir":"none"}' http://example.com/ogrepository/v1/images/send-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 el contenido de los ficheros ".sum" y ".full.sum" con una nueva obtención del checksum de la imagen, pero no veo como comprobar la integridad de todos los archivos asociados.

URL: /ogrepository/v1/images/check-image
Método HTTP: GET

Cuerpo de la Solicitud (JSON):

  • image: Nombre de la imagen (con extensión).
  • ou_subdir: Subdirectorio correspondiente a la OU (o "none" si no es el caso).

Ejemplo de Solicitud:

curl -X POST -H "Authorization: $API_KEY" -H "Content-Type: application/json" -d '{"image":"Windows10.img", "ou_subdir":"none"}' 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.

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 qué 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.