opengnsys
/
ogDocumentation
1
1
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
ogDocumentation/i18n-docu/docs/en/developer/ogboot.md

28 KiB
Raw Permalink Blame History

Boot System (ogBoot)

Ogboot is a standalone implementation that provides remote boot (PXE) functionality in environments managed by OpenGnsys. This component enables the remote loading of operating systems and other essential files during the workstation boot process.

Installation

Prerequisites

  • Operating System: Ubuntu 24.04
  • Python 3: Installation has been tested with version Python 3.12.3.
python3 --version
Python 3.12.3

Installing Python 3

Run the following command to install Python 3 and pip:

apt-get install -y python3 python3-pip

Initial Setup

The configuration file is included in the repository. You only need to modify it with the appropriate parameters:

{
    "ogCore_ServerIP": "172.17.8.82",
    "ogBoot_ServerIP": "172.17.8.37",
    "ogBoot_Dir": "/opt/opengnsys/ogboot",
    "ogBootSambaUser": "opengnsys",
    "ogBootSambaPass": "og"
}

Where:

Parameter Description
ogCore_ServerIP IP of the ogCore server
ogBoot_ServerIP IP of the ogboot server
ogBoot_Dir ogboot installation directory
ogBootSambaUser Samba user
ogBootSambaPass Samba password

Installation

  1. Ensure that Python 3 is installed
  2. Modify the existing configuration file with the necessary parameters

Ogboot API

The Ogboot API provides an interface to facilitate the remote boot initialization process of operating systems in environments managed by OpenGnsys. Ogboot enables efficient management of boot files for both local partitions and remote operating systems.

Below are the available endpoints, their input parameters, and the actions they perform.

Server Status

Get ogboot Status

Returns disk usage, the default ogLive client, the list of installed ogLives, and the status of the services.

URL: /ogboot/v1/status
Method: GET

Request Example

curl -X GET http://example.com/ogboot/v1/status

Responses

Success (200 OK)
{
    "success": "Status retrieved successfully",
    "message": {
        "disk_usage": {
            "total": "22591996",
            "used": "11995812",
            "available": "9542092",
            "percentage": "56%"
        },
        "default_oglive": "ogLive-6.8.0-i386-20241014",
        "installed_oglives": [
            {
                "id": "dcca1bf9762189e147cc4cde926392b1",
                "distribution": "noble",
                "kernel": "6.8.0-31-generic-amd64-r20240716",
                "architecture": "i386",
                "revision": "20241014",
                "directory": "/opt/ogboot/tftpboot//ogLive-6.8.0-i386-20241014"
            },
            {
                "id": "ad8222511753d4013be21602899d642e",
                "distribution": "noble",
                "kernel": "6.8.0-31-generic-amd64-r20240716",
                "architecture": "i386",
                "revision": "20241017",
                "directory": "/opt/ogboot/tftpboot//ogLive-6.8.0-i386-20241017"
            }
        ],
        "services_status": {
            "tftpboot": "active",
            "nginx": "active"
        }
    }
}
Error (404 Not Found)
{
    "error": "NOT_FOUND",
    "message": "No default or installed ogLives found."
}
Error (500 Internal Server Error)
{
    "error": "FAILED_TO_RETRIEVE_DISK_USAGE",
    "message": "Error to retrieve disk usage"
}

or

{
    "error": "FAILED_TO_RETRIEVE_OGLIVE_CONFIGURATION",
    "message": "Error to retrieve ogLive configuration"
}

or

{
    "error": "FAILED_TO_RETRIEVE_SERVICES_STATUS",
    "message": "Error to retrieve services status"
}

ogLive Management

Get ogLive Download Menu

Returns the list of available ogLive ISOs for download.

URL: /ogboot/v1/oglives/isos
Method: GET

Request Example

curl -X GET http://example.com/ogboot/v1/oglives/isos

Responses

Success (200 OK)
{
    "success": "ISOs retrieved successfully",
    "message": [
        {
          "id": "1",
          "filename": "ogLive-noble-6.8.0-31-generic-amd64-r20240716-20241014.iso",
          "url": "https://ognproject.evlt.uma.es/oglive//ogLive-noble-6.8.0-31-generic-amd64-r20240716-20241014.iso",
          "installed": true,
          "compatible": false
        },
        {
          "id": "2",
          "filename": "ogLive-noble-6.8.0-31-generic-amd64-r20240716-20241017.iso",
          "url": "https://ognproject.evlt.uma.es/oglive//ogLive-noble-6.8.0-31-generic-amd64-r20240716-20241017.iso",
          "installed": true,
          "compatible": false
        }
    ]
}
Error (500 Internal Server Error)
{
    "error": "FAILED_TO_RETRIEVE_ISOS",
    "message": "Error to retrieve ISO downloads"
}

Get List of All Installed ogLive Clients

Returns the list of installed ogLive clients, including the default ogLive client.

URL: /ogboot/v1/oglives
Method: GET

Request Example

curl -X GET \
  'http://172.17.8.37/ogboot/v1/oglives' \
  -H 'accept: application/json'

Responses

Success (200 OK)
{
    "success": "ogLive clients retrieved successfully",
    "message": {
        "default_oglive": "ogLive-6.8.0-i386-20241014",
        "installed_ogLives": [
            {
                "id": "dcca1bf9762189e147cc4cde926392b1",
                "distribution": "noble",
                "kernel": "6.8.0-31-generic-amd64-r20240716",
                "architecture": "i386",
                "revision": "20241014",
                "directory": "/opt/ogboot/tftpboot//ogLive-6.8.0-i386-20241014"
            },
            {
                "id": "ad8222511753d4013be21602899d642e",
                "distribution": "noble",
                "kernel": "6.8.0-31-generic-amd64-r20240716",
                "architecture": "i386",
                "revision": "20241017",
                "directory": "/opt/ogboot/tftpboot//ogLive-6.8.0-i386-20241017"
            }
        ]
    }
}
Error (404 Not Found)
{
    "error": "NOT_FOUND",
    "message": "No ogLive clients found."
}
Error (500 Internal Server Error)
{
    "error": "SERVER_ERROR",
    "message": "Failed to retrieve ogLive clients due to server error."
}

or

{
    "error": "UNKNOWN_ERROR",
    "message": "An unknown error occurred."
}

Get Information of an Installed ogLive Client

Returns the information of an installed ogLive client identified by its checksum.

URL: /ogboot/v1/oglives/{checksum}
Method: GET

Path Parameters

Parameter Type Description Example
checksum string Checksum of the installed ogLive client 9e49a085ba74f97a81bdf9b3d0785094

Request Example

curl -X GET \
  'http://172.17.8.37/ogboot/v1/oglives/9e49a085ba74f97a81bdf9b3d0785094' \
  -H 'accept: application/json'

Responses

Success (200 OK)
{
    "success": "ogLive client retrieved successfully",
    "message": {
        "id": "9e49a085ba74f97a81bdf9b3d0785094",
        "distribution": "noble",
        "kernel": "6.8.0-31-generic-amd64-r20240716",
        "architecture": "i386",
        "revision": "20241014",
        "directory": "/opt/ogboot/tftpboot//ogLive-6.8.0-i386-20241014"
    }
}
Error (404 Not Found)
{
    "error": "NOT_FOUND",
    "message": "ogLive client with checksum 9e49a085ba74f97a81bdf9b3d0785094 not found."
}
Error (500 Internal Server Error)
{
    "error": "SERVER_ERROR",
    "message": "Failed to retrieve ogLive client."
}

Get Default ogLive Client Information

Returns the information of the ogLive client configured as default.

URL: /ogboot/v1/oglives/default
Method: GET

Request Example

curl -X GET \
  'http://172.17.8.37/ogboot/v1/oglives/default' \
  -H 'accept: application/json'

Responses

Success (200 OK)
{
    "success": "se ha obtenido el oglive por defecto",
    "message": {
        "id": "default_oglive_id",
        "distribution": "noble",
        "kernel": "6.8.0-31-generic-amd64-r20240716",
        "architecture": "i386",
        "revision": "20241014",
        "directory": "/opt/ogboot/tftpboot//ogLive-6.8.0-i386-20241014"
    }
}
Error (500 Internal Server Error)
{
    "error": "SERVER_ERROR",
    "message": "Failed to retrieve default ogLive."
}

Set Default ogLive Client

Allows setting an ogLive client as default using its checksum.

URL: /ogboot/v1/oglives/default
Method: PUT

Request Body

{
    "checksum": "9e49a085ba74f97a81bdf9b3d0785094"
}
Parameter Type Description Required
checksum string Checksum of the ogLive client to set as default Yes

Request Example

curl -X PUT \
  'http://172.17.8.37/ogboot/v1/oglives/default' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
        "checksum": "9e49a085ba74f97a81bdf9b3d0785094"
      }'

Responses

Success (200 OK)
{
    "success": "ogLive client set as default successfully",
    "message": {
        "id": "9e49a085ba74f97a81bdf9b3d0785094",
        "distribution": "noble",
        "kernel": "6.8.0-31-generic-amd64-r20240716",
        "architecture": "i386",
        "revision": "20241014",
        "directory": "/opt/ogboot/tftpboot//ogLive-6.8.0-i386-20241014"
    }
}
Error (400 Bad Request)
{
    "error": "INVALID_INPUT",
    "message": "Invalid input data: checksum is required."
}
Error (500 Internal Server Error)
{
    "error": "SERVER_ERROR",
    "message": "Failed to set ogLive as default."
}

Start Installation of an ogLive Client

Initiates the installation of an ogLive client from a provided download URL. This endpoint is asynchronous and, after installation, sends a notification to the webhook URL configured in ogCore.

URL: /ogboot/v1/oglives/install
Method: POST

Request Body

{
    "url": "https://ognproject.evlt.uma.es/trac/downloads/ogLive-focal-5.11.0-22-generic-amd64-r20210413.992ebb9.iso",
    "id": "12345"
}
Parameter Type Description Required
url string URL of the ogLive ISO to download and install Yes
id string Unique transaction ID to track the installation process Yes

Request Example

curl -X POST \
  'http://172.17.8.37/ogboot/v1/oglives/install' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
        "url": "https://ognproject.evlt.uma.es/trac/downloads/ogLive-focal-5.11.0-22-generic-amd64-r20210413.992ebb9.iso",
        "id": "12345"
      }'

Responses

Success (202 Accepted)
{
    "success": "ogLive client installation started",
    "transaction_id": "12345"
}
Error (400 Bad Request)
{
    "error": "Invalid input data",
    "details": "URL and transaction ID are required."
}
Error (500 Internal Server Error)
{
    "error": "Failed to initiate ogLive installation",
    "details": "Detalles del error específico"
}

!!! note "Asynchronous Process" This endpoint runs the installation in the background and notifies ogCore via a webhook at the configured URL upon completion of the process, sending the status, the response code (200 if successful), and a message.

Uninstall an ogLive Client

Allows uninstalling an ogLive client identified by its checksum.

URL: /ogboot/v1/oglives/{checksum}
Method: DELETE

Path Parameters

Parameter Type Description Example
checksum string Checksum of the ogLive client to uninstall 9e49a085ba74f97a81bdf9b3d0785094

Request Example

curl -X DELETE \
  'http://172.17.8.37/ogboot/v1/oglives/9e49a085ba74f97a81bdf9b3d0785094' \
  -H 'accept: application/json'

Responses

Success (200 OK)
{
    "message": "ogLive client uninstalled successfully",
    "details": "Detalles adicionales de la desinstalación."
}
Error (404 Not Found)
{
    "error": "NOT_FOUND",
    "message": "ogLive client not found."
}
Error (403 Forbidden)
{
    "error": "FORBIDDEN",
    "message": "Cannot uninstall the default ogLive client."
}
Error (500 Internal Server Error)
{
    "error": "SERVER_ERROR",
    "message": "Failed to uninstall ogLive client."
}

or

{
    "error": "UNKNOWN_ERROR",
    "message": "An unknown error occurred."
}

PXE Files Management

Get All Boot Files

Returns the list of available PXE boot files.

URL: /ogboot/v1/pxes
Method: GET

Request Example

curl -X GET http://example.com/ogboot/v1/pxes

Responses

Success (200 OK)
{
    "success": "Boot files retrieved successfully",
    "message": [
        "01-00-50-56-aa-bb-cc",
        "01-00-50-56-dd-ee-ff"
    ]
}
Error (404 Not Found)
{
    "error": "NOT_FOUND",
    "message": "No boot files found."
}
Error (500 Internal Server Error)
{
    "error": "SERVER_ERROR",
    "message": "Failed to retrieve boot files: directory not found."
}

Get Boot File

Returns the boot file for a specific MAC address, including configuration parameters.

URL: /ogboot/v1/pxes/{mac}
Method: GET

Path Parameters

Parameter Type Description Example
mac string MAC address for which the boot file will be retrieved 00:50:56:22:11:12

Request Example

curl -X GET \
  'http://172.17.8.37/ogboot/v1/pxes/00:50:56:22:11:12' \
  -H 'accept: application/json'

Responses

Success (200 OK) - Case 1: Boot file with parameters
{
    "success": "Boot file retrieved successfully",
    "message": {
        "template_name": "pxe",
        "mac": "00:50:56:22:11:12",
        "lang": "es_ES.UTF-8",
        "ip": "192.168.2.11",
        "server_ip": "192.168.2.1",
        "router": "192.168.2.1",
        "netmask": "255.255.255.0",
        "computer_name": "pc11",
        "netiface": "eth0",
        "group": "Aula_virtual",
        "ogrepo": "192.168.2.1",
        "oglive": "192.168.2.1",
        "oglog": "192.168.2.1",
        "ogshare": "192.168.2.1",
        "oglivedir": "ogLive",
        "ogprof": "false",
        "hardprofile": "",
        "ogntp": "",
        "ogdns": "",
        "ogproxy": "",
        "ogunit": "",
        "resolution": "788"
    }
}
Success (200 OK) - Case 2: Disk-based boot file (no parameters)
{
    "success": "Boot file retrieved successfully",
    "message": {
        "template_name": "disk_boot",
        "mac": "00:50:56:22:11:12",
        "message": "Boot file without parameters, possibly a disk boot template."
    }
}
Error (404 Not Found)
{
    "error": "NOT_FOUND",
    "message": "No boot file found for the specified MAC address."
}
Error (500 Internal Server Error)
{
    "error": "SERVER_ERROR",
    "message": "An error occurred while retrieving the boot file."
}

Create PXE File

This endpoint allows creating a PXE boot file with the specified MAC and template, along with additional parameters such as IP, ogLive directory, server, and more.

URL: /ogboot/v1/pxes
Method: POST

Request Body

{
    "mac": "00:50:56:22:11:12",
    "template_name": "mi_plantilla.ipxe",
    "server_ip": "192.168.2.1",
    "oglivedir": "ogLive",
    "lang": "es_ES.UTF-8",
    "ip": "192.168.2.11",
    "router": "192.168.2.1",
    "netmask": "255.255.255.0",
    "computer_name": "pc11",
    "netiface": "eth0",
    "group": "Aula_virtual",
    "ogrepo": "192.168.2.1",
    "oglive": "192.168.2.1",
    "oglog": "192.168.2.1",
    "ogshare": "192.168.2.1",
    "ogprof": "false",
    "hardprofile": "",
    "ogntp": "192.168.2.1",
    "ogdns": "192.168.2.1",
    "ogproxy": "192.168.2.1",
    "ogunit": "unit",
    "resolution": "788"
}
Parameter Type Description Required
mac string MAC address for the boot file Yes
template_name string Name of the template to use Yes
server_ip string Server IP address No
oglivedir string ogLive directory to use in the boot No
lang string Locale language No
ip string IP address No
router string Gateway IP address No
netmask string Network mask No
computer_name string Computer name No
netiface string Network interface No
group string Machine group No
ogrepo string IP of the repository server No
oglive string IP of the tftpboot server No
oglog string IP of the logs server No
ogshare string IP of the ogclient server No
ogprof string Indicates if it’s a teacher No
hardprofile string Hardware profile No
ogntp string IP of the NTP server No
ogdns string IP of the DNS server No
ogproxy string IP of the proxy server No
ogunit string Unit directory No
resolution string Screen resolution No

Request Example

curl -X POST \
  'http://172.17.8.37/ogboot/v1/pxes' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
        "mac": "00:50:56:22:11:12",
        "template_name": "mi_plantilla.ipxe",
        "server_ip": "192.168.2.1",
        "oglivedir": "ogLive"
      }'

Responses

Success (200 OK)
{
    "success": "PXE file created successfully",
    "message": "#!ipxe\n#Template: mi_plantilla.ipxe\nset kernelargs ro boot=oginit quiet splash irqpoll ..."
}
Error (400 Bad Request)
{
    "error": "INVALID_INPUT",
    "message": "Missing required fields: mac and template_name"
}
Error (404 Not Found)
{
    "error": "TEMPLATE_NOT_FOUND",
    "message": "No se encontró la plantilla especificada"
}
Error (500 Internal Server Error)
{
    "error": "FAILED_TO_CREATE_PXE_FILE",
    "message": "Error al crear el archivo PXE"
}

Delete PXE File

This endpoint allows deleting a specific PXE boot file using the client’s MAC address.

URL: /ogboot/v1/pxes/{mac}
Method: DELETE

Path Parameters

Parameter Type Description Example
mac string MAC address of the client whose boot file will be deleted 00:11:22:33:44:55

Request Example

curl -X DELETE \
  'http://172.17.8.37/ogboot/v1/pxes/00:11:22:33:44:55' \
  -H 'accept: application/json'

Responses

Success (200 OK)
{
    "success": "Boot file deleted successfully",
    "message": "The boot file for MAC 00:11:22:33:44:55 has been deleted."
}
Error (404 Not Found)
{
    "error": "NOT_FOUND",
    "message": "No boot file found for the specified MAC address."
}
Error (500 Internal Server Error)
{
    "error": "SERVER_ERROR",
    "message": "Failed to delete the boot file due to server error."
}

PXE Template Management

Get All PXE Templates

This endpoint returns a list of all available PXE boot templates in the system.

URL: /ogboot/v1/pxe-templates
Method: GET

Request Example

curl -X GET \
  'http://172.17.8.37/ogboot/v1/pxe-templates' \
  -H 'accept: application/json'

Responses

Success (200 OK)
{
    "success": "Lista de plantillas obtenida con éxito",
    "message": [
        "mi_plantilla.ipxe",
        "otra_plantilla.ipxe"
    ]
}
Error (500 Internal Server Error)
{
    "error": "SERVER_ERROR",
    "message": "Directorio de plantillas no encontrado"
}

Get Content of a PXE Template

This endpoint retrieves the content of a specific PXE boot template by its name.

URL: /ogboot/v1/pxe-templates/{templateName}
Method: GET

Path Parameters

Parameter Type Description Example
templateName string Name of the PXE template to retrieve my_template.ipxe

Request Example

curl -X GET \
  'http://172.17.8.37/ogboot/v1/pxe-templates/mi_plantilla.ipxe' \
  -H 'accept: application/json'

Responses

Success (200 OK)
{
    "success": "Plantilla obtenida con éxito",
    "template_name": "mi_plantilla.ipxe",
    "template_content": "#!ipxe\nset timeout 0\nset timeout-style hidden\n\nset ISODIR ogLive\nset default 0\nset kernelargs INFOHOST\nkernel tftp://SERVERIP/ogLive/ogvmlinuz ${kernelargs}\ninitrd tftp://SERVERIP/ogLive/oginitrd.img\nboot"
}
Error (404 Not Found)
{
    "error": "TEMPLATE_NOT_FOUND",
    "message": "No se encontró la plantilla especificada"
}
Error (500 Internal Server Error)
{
    "error": "FAILED_TO_READ_TEMPLATE",
    "message": "Error al leer la plantilla"
}

Create Template

This endpoint creates a new PXE boot template on the server using the provided name and content.

URL: /ogboot/v1/pxe-templates
Method: POST

Request Body

{
    "name_template": "mi_plantilla.ipxe",
    "content_template": "#!ipxe\nset timeout 0\nset timeout-style hidden\nset ISODIR __OGLIVE__\nset default 0\nset kernelargs __INFOHOST__\n:try_iso\nkernel http://__SERVERIP__/tftpboot/${ISODIR}/ogvmlinuz ${kernelargs} || goto fallback\ninitrd http://__SERVERIP__/tftpboot/${ISODIR}/oginitrd.img\nboot\n\n:fallback\nset ISODIR ogLive\nkernel http://__SERVERIP__/tftpboot/${ISODIR}/ogvmlinuz ${kernelargs}\ninitrd http://__SERVERIP__/tftpboot/${ISODIR}/oginitrd.img\nboot\n"
}
Parameter Type Description Required
name_template string Name of the new template Yes
content_template string Template content, must include boot script Yes

Request Example

curl -X POST \
  'http://172.17.8.37/ogboot/v1/pxe-templates' \
  -H 'Content-Type: application/json' \
  -d '{
        "name_template": "mi_plantilla.ipxe",
        "content_template": "#!ipxe\nset timeout 0\nset timeout-style hidden\nset ISODIR __OGLIVE__\nset default 0\nset kernelargs __INFOHOST__\n:try_iso\nkernel http://__SERVERIP__/tftpboot/${ISODIR}/ogvmlinuz ${kernelargs} || goto fallback\ninitrd http://__SERVERIP__/tftpboot/${ISODIR}/oginitrd.img\nboot\n\n:fallback\nset ISODIR ogLive\nkernel http://__SERVERIP__/tftpboot/${ISODIR}/ogvmlinuz ${kernelargs}\ninitrd http://__SERVERIP__/tftpboot/${ISODIR}/oginitrd.img\nboot\n"
      }'

Responses

Success (200 OK)
{
    "success": "Plantilla creada con éxito",
    "message": {
        "template_name": "mi_plantilla.ipxe",
        "template_content": "#!ipxe\nset timeout 0\nset timeout-style hidden\nset ISODIR __OGLIVE__\nset default 0\nset kernelargs __INFOHOST__\n:try_iso\nkernel http://__SERVERIP__/tftpboot/${ISODIR}/ogvmlinuz ${kernelargs} || goto fallback\ninitrd http://__SERVERIP__/tftpboot/${ISODIR}/oginitrd.img\nboot\n\n:fallback\nset ISODIR ogLive\nkernel http://__SERVERIP__/tftpboot/${ISODIR}/ogvmlinuz ${kernelargs}\ninitrd http://__SERVERIP__/tftpboot/${ISODIR}/oginitrd.img\nboot\n"
    }
}
Error (400 Bad Request)
{
    "error": "INVALID_INPUT",
    "message": "Faltan datos requeridos: name_template y content_template son necesarios."
}
Error (403 Forbidden)
{
    "error": "UNAUTHORIZED_ACCESS",
    "message": "Intento de acceso no autorizado fuera del directorio de plantillas."
}
Error (500 Internal Server Error)
{
    "error": "FILE_CREATION_ERROR",
    "message": "Ocurrió un error al crear la plantilla de arranque."
}

Delete Template

This endpoint deletes a PXE boot template on the server using the provided name.

URL: /ogboot/v1/pxe-templates/{name}
Method: DELETE

Path Parameters

Parameter Type Description Example
name string Name of the boot template to delete my_template.ipxe

Request Example

curl -X DELETE \
  'http://172.17.8.37/ogboot/v1/pxe-templates/mi_plantilla.ipxe' \
  -H 'accept: application/json'

Responses

Success (200 OK)
{
    "success": "Plantilla eliminada",
    "message": "La plantilla mi_plantilla se ha borrado correctamente"
}
Error (404 Not Found)
{
    "error": "TEMPLATE_NOT_FOUND",
    "message": "No se encontró la plantilla especificada"
}
Error (500 Internal Server Error)
{
    "error": "FAILED_TO_DELETE_TEMPLATE",
    "message": "Ocurrió un error al intentar eliminar la plantilla"
}

Glossary of Terms

Term Description
PXE Preboot Execution Environment – Environment that allows a computer to boot over the network
ogLive Remote boot client used by OpenGnsys
ogBoot OpenGnsys component that provides remote boot functionality
ogCore Main OpenGnsys server that manages system operations
Checksum Hash value that uniquely identifies an installed ogLive client
ISO Image file containing an ogLive client
TFTP Trivial File Transfer Protocol – Protocol used to transfer files during remote boot