Compartir vía

Manifiesto de amenaza avanzada persistente de Azure Device Update for IoT Hub

  • Artículo

En este artículo se describe el manifiesto de APT, un archivo JSON que describe los detalles de actualización requeridos por el controlador de actualización de APT. Puede importar este archivo en Device Update igual que cualquier otra actualización. Para obtener más información, consulte Importación de una actualización a Device Update.

Al entregar un manifiesto APT a un agente de Device Update como una actualización, el agente procesa el manifiesto y lleva a cabo las operaciones necesarias. Estas operaciones incluyen la descarga y la instalación de los paquetes especificados en el archivo de manifiesto APT y sus dependencias desde un repositorio designado.

Device Update admite el tipo de actualización de APT y controlador de actualizaciones. Esta compatibilidad permite al agente de Device Update evaluar los paquetes de Debian instalados y actualizar los paquetes necesarios.

Puede usar un manifiesto de APT para actualizar el propio agente de Device Update y sus dependencias. Enumere el nombre del agente de Device Update y la versión deseada en el manifiesto APT, como haría con cualquier otro paquete. A continuación, puede importar este manifiesto de APT e implementarlo a través de la canalización de Device Update.

Schema

Un archivo de manifiesto APT es un archivo JSON que incluye un esquema con versiones.

{
    "name": "<name>",
    "version": "<version>",
    "packages": [
        {
            "name": "<package name>",
            "version": "<version specifier>"
        }
    ]
}

Por ejemplo:

{
    "name": "contoso-iot-edge",
    "version": "1.0.0.0",
    "packages": [
        {
            "name" : "thermocontrol",
            "version" : "1.0.1"
        },
        {
            "name" : "tempreport",
            "version" : "2.0.0"
        }
    ]
}

Cada manifiesto APT incluye las propiedades siguientes:

  • Nombre: un nombre para este manifiesto de APT, que puede ser cualquier nombre o identificador significativo que se ajuste a su escenario. Por ejemplo, contoso-iot-edge.
  • Versión: un número de versión para este manifiesto de APT, por ejemplo, 1.0.0.0.
  • Paquetes: lista de objetos que contiene propiedades específicas de los paquetes.
    • Nombre: nombre o identificador del paquete, por ejemplo, iotedge.
    • Versión: los criterios de versión de paquete deseados, por ejemplo, 1.0.8-2.

Control de versiones

El manifiesto de APT solo admite números de versión exactos. El número de versión es la versión del paquete de Debian deseada en formato <epoch>:<upstream_version>-<debian_revision>, donde epoch es un entero sin signo y upstream_version comienza con un dígito y puede incluir caracteres alfanuméricos y caracteres como ., ,, +, - y ~. El valor de versión no debe contener un signo igual.

Por ejemplo, "name":"iotedge" y "version":"1.0.8-2" es equivalente a instalar un paquete mediante el comando apt-get install iotedge=1.0.8-2. La versión 1.0.8 es igual a 1.0.8-0.

Si se omite la versión, Device Update instala la versión más reciente disponible del paquete especificado. Para obtener más información sobre cómo se versionan los paquetes de Debian, consulte el Manual de directivas de Debian.

Nota:

El administrador de paquetes APT omite los requisitos de control de versiones que indica un paquete cuando los paquetes dependientes que se van a instalar se resuelven automáticamente. A menos que se proporcionen versiones explícitas de los paquetes dependientes, se usa la más reciente, aunque el propio paquete pueda especificar un requisito estricto (=) en una versión determinada. Esta resolución automática puede provocar errores relacionados con una dependencia que no se ha cumplido.

Por lo tanto, al instalar una versión específica de un paquete, es mejor incluir también las versiones explícitas de los paquetes dependientes que se van a instalar. Para obtener más información, consulte apt-get no resuelve correctamente una dependencia de una versión fija en un paquete de Debian/Ubuntu.

Si actualiza una versión específica del demonio de seguridad de Azure IoT Edge, debe incluir la versión deseada del paquete de aziot-edge y su paquete de aziot-identity-service dependiente en el manifiesto de APT. Para más información, consulte Actualización de IoT Edge.

Criterios instalados

El valor de criterios instalados recomendado para un manifiesto de APT es <name>-<version>, donde <name> es el nombre del manifiesto de APT y <version> es su versión. Por ejemplo, contoso-iot-edge-1.0.0.0.

Eliminación de paquetes

También puede usar un manifiesto de APT para quitar los paquetes instalados de los dispositivos. Puede usar un único manifiesto de APT para quitar, agregar y actualizar varios paquetes.

Para quitar un paquete, agregue un signo menos - después del nombre del paquete. No incluya un número de versión para los paquetes que va a quitar. La eliminación de un paquete mediante un manifiesto APT no quita sus dependencias ni configuraciones.

Por ejemplo, el siguiente manifiesto de APT quita el paquete contoso1 de los dispositivos en los que se implementa.

{
    "name": "contoso-video",
    "version": "2.0.0.1",
    "packages": [
        {
            "name" : "contoso1-"
        }
    ]
}

Directrices de creación de manifiestos de APT

Tenga en cuenta las siguientes directrices al crear un manifiesto de APT:

  • Asegúrese de que el manifiesto de APT es un archivo JSON bien formado.

  • Asigne a cada manifiesto de APT una versión única. Intente crear una metodología estandarizada para incrementar la versión del manifiesto de APT, de modo que tenga sentido para sus escenarios y sea fácil de seguir.

  • Para el estado deseado de cada paquete individual, especifique el nombre exacto y la versión del paquete que desea instalar en el dispositivo. Valide siempre los valores con el contenido del repositorio de paquetes de origen.

  • Enumere los paquetes en el manifiesto de APT en el orden en que se deben instalar o quitar.

  • Valide siempre la instalación de paquetes en un dispositivo de prueba para garantizar el resultado deseado.

  • Al instalar una versión específica de un paquete, por ejemplo, iotedge 1.0.9-1, incluya también las versiones explícitas de los paquetes dependientes que se van a instalar, por ejemplo, libiothsm 1.0.9-1.

  • Aunque no es necesario, siempre hacer que el manifiesto de APT sea acumulativo evita que los dispositivos entren en un estado desconocido. Una actualización acumulativa garantiza que los dispositivos tengan la versión deseada de todos los paquetes pertinentes, incluso si el dispositivo omitió una actualización debido a un error de instalación o estar sin conexión.

    Por ejemplo, considere el siguiente manifiesto de APT base:

    {
    "name": "contoso-iot-edge",
    "version": "1.0",
    "packages": [
        {
            "name": "contoso1",
            "version": "1.0.1"
        }
    ]
}

    La siguiente actualización de la versión 2.0 incluye el paquete contoso2, pero no el paquete de contoso1. Es posible que todos los dispositivos que reciben la actualización 2.0 no tengan el paquete contoso1.

    {
    "name": "contoso-iot-edge",
    "version": "2.0",
    "packages": [
       {
            "name": "contoso2",
            "version": "3.0.2"
        }
    ]
}

    La siguiente actualización acumulativa de la versión 2.0 incluye los paquetes contoso1 y contoso2:

    {
    "name": "contoso-iot-edge",
    "version": "2.0",
    "packages": [
        {
            "name": "contoso1",
            "version": "1.0.1"
        },
        {
            "name": "contoso2",
            "version": "3.0.2"
        }
    ]
}

Contenido relacionado