20 KiB

Raw Blame History

ogRepository - OpenGnsys Repository Manager

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 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:

Obtener Información de todas las Imágenes - GET /ogrepository/v1/images
Obtener Información de una Imagen concreta - GET /ogrepository/v1/images/{name}
Actualizar Información del Repositorio - PUT /ogrepository/v1/images
Eliminar una Imagen - DELETE /ogrepository/v1/images/{name}
Importar una Imagen - POST /ogrepository/v1/images/import-image
Enviar una Imagen mediante UDPcast - POST /ogrepository/v1/images/{protocol}
Enviar una Imagen mediante UFTP - POST /ogrepository/v1/images/{protocol}
Crear archivo ".torrent" - POST /ogrepository/v1/images/create-torrent
Enviar una Imagen mediante P2P - POST /ogrepository/v1/images/{protocol}
Chequear integridad de Imagen - GET /ogrepository/v1/images/check-image
Exportar una Imagen - POST /ogrepository/v1/images/export-image
Definir Imagen Global - PUT /ogrepository/v1/images/set-global
Definir Imagen Local - PUT /ogrepository/v1/images/set-local
Ver Estado de Transmisiones 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:

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.

{
"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:

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.
```
{
  "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:

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:

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:

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:

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:

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:

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:

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 el contenido de los ficheros ".sum" y ".full.sum" con una nueva extracció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 completo de la imagen a chequear, con extensión (con o sin ruta).

Ejemplo de Solicitud:

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:

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:

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:

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.

20 KiB Raw Blame History

ogRepository - OpenGnsys Repository Manager

API de ogRepository

Tabla de Contenido:

Obtener Información de todas las Imágenes

Obtener Información de una Imagen concreta

Actualizar Información del Repositorio

Eliminar una Imagen

Importar una Imagen

Enviar una Imagen mediante UDPcast

Enviar una Imagen mediante UFTP

Crear archivo .torrent

Enviar una Imagen mediante P2P

Chequear Integridad de Imagen

Exportar una Imagen

Definir Imagen Global

Definir Imagen Local

Ver Estado de Transmisiones Multicast-P2P

Cancelar Transmisión Multicast-P2P

20 KiB

Raw Blame History