Report and inventory hardware and OS information with Azure IoT and OSConfig

  • Article

Important

Version 1.0.3 (published 28 June 2022) includes breaking changes to member names which may impact existing users. For more information, see: Member names transition from PascalCase to camelCase in version 1.0.3

Audience and scope

This article is designed to support people who provision or manage devices with Azure IoT. If that doesn't sound like you, consider taking a look at Audiences for OSConfig documentation.

This article describes and demonstrates using the DeviceInformation and TPM modules to get device information including operating system, version, TPM presence, memory, and more.

Tip

If you are here for the object model reference, you can skip over the Use cases examples to the Reference information

Use cases examples

These examples can serve as starting points for you to adapt for your unique environment.

Prerequisites to try the examples on live systems

If you are using this article for reference (for example, you are here to copy a property name), there are no pre-requisites.

If you want to try the examples on live systems (recommended), then:

  1. You will need an Azure account with an IoT Hub

    This article assumes some familiarity with IoT Hub and related tools. For example, it assumes you are comfortable creating IoT Hubs and attaching devices. If you prefer a more prescriptive step-by-step introduction to installing and using OSConfig from scratch, see: Quickstart: Manage a single virtual IoT device using Azure CLI instead.

  2. You will need at least one Linux device with the OSConfig agent installed and connected to Azure IoT.

    For more information, see: How and where to install the OSConfig agent for Linux.

  3. You will use Azure Portal or Azure CLI to interact with the devices via your IoT Hub

    For further steps, choose your preferred experience:

  1. Ensure you are signed in to the Azure Portal and can access your IoT Hub's Overview page Screenshot showing IoT Hub and devices from the Azure Portal

Example A. Get all the device information properties

In this example we simply retrieve all of the device information available in these two namespaces. It is expected that you would use this information as part of an inventory scenario in your cloud solution, or in a diagnostic scenario.

Step by step instructions follow the screen capture

Browsing to OSConfig module twin to see device information

  1. Navigate to the OSConfig twin for the device of your choice
    1. From your IoT Hub's page in the Azure Portal, navigate to Device Management > Devices (or Device Management > IoT Edge if the device has IoT Edge installed)
    2. Click on the device name in the list of device IDs
    3. Under Module Identities click on the osconfig module ID
    4. Click on Module Identity Twin
  2. Scroll to view the DeviceInfo and Tpm sections under properties.reported, and note the available information including cpuType, osVersion, totalMemory, tpmVersion, and several more.

Example B. Generate a tabular report of OS and CPU info across devices

For this example, only the Bash / Cloud Shell, at-scale example is populated. This shows using IoT Hub Query functions along with Azure CLI's --output table feature. It is expected that you would integrate these data points into your own cloud workflows, displaying tables as needed to your solution operators.

Not applicable. Navigate to Prerequisites to try the examples on live systems in this document and choose "Bash / Cloud Shell".

Example C. Count devices with and without TPMs

This example will make use of Azure IoT Query's GROUP BY operator, applied over TPM information exposed by OSConfig.

Not applicable, see Azure Portal, at-scale.

Reference information

Object model description

This section describes the twin properties and corresponding behaviors.

Tip

In cases where the plain desired/reported twin point-of-view differs from DTDL enhanced point-of-view, the former is given first followed by the latter in parenthesis.

DeviceInfo

  • Path: properties.reported.DeviceInfo (DeviceInfo component)

  • Description: Device-wide information such as OS name, OS version, CPU type, etc.

  • Members

    Name Type Notes
    osName string OS name, like Ubuntu, Debian, etc.
    osVersion string OS version, like "20.04", etc.
    cpuType string High level ISA identifier, like "aarch64", "x86_64", etc.
    cpuVendorId string Vendor identifier, like "ARM", "GenuineIntel", etc.
    cpuModel string Processor identifier, like "Cortex-A72", etc.
    totalMemory int Installed RAM, as seen by the OS
    freeMemory int Available RAM (at service start time)¹, as seen by the OS
    kernelName string Kernel name, like "Linux"
    kernelVersion string Additional kernel build information, like "#75-Ubuntu SMP PREEMPT Fri Jun 3 14:24:57 UTC 2022"
    kernelRelease string Kernel build version identifier, like "5.4.0-1065-raspi"
    productVendor string Refers to the device's product vendor context, like "Contoso Systems, Inc"; often blank
    productName string Device product name, like "Raspberry Pi 4 Model B Rev 1.4"
    productVersion string Device product version; often blank
    systemCapabilities string From lshw -c system
    systemConfiguration string From lshw -c system
    osConfigVersion string Version number for the OSConfig agent representing the device

    ¹ The freeMemory property was designed for general system characterization, not for dynamic monitoring. As such, it only updates the value upon service start, avoiding the CPU and network expense of continually updating this value. For ongoing monitoring of free memory, see Azure Monitor.

  • Example payload (as seen in twin's properties.reported section)

    "DeviceInfo": {
     "__t": "c",
     "osName": "Ubuntu",
     "osVersion": "20.04.4",
     "cpuType": "aarch64",
     "cpuVendorId": "ARM",
     "cpuModel": "Cortex-A72",
     "totalMemory": 7998708,
     "freeMemory": 7168776,
     "kernelName": "Linux",
     "kernelVersion": "#75-Ubuntu SMP PREEMPT Fri Jun 3 14:24:57 UTC 2022",
     "kernelRelease": "5.4.0-1065-raspi",
     "productVendor": "",
     "productName": "Raspberry Pi 4 Model B Rev 1.4",
     "productVersion": "",
     "systemCapabilities": "smp cp15_barrier setend swp tagged_addr_disabled",
     "systemConfiguration": "",
     "osConfigVersion": "1.0.3.2022062801"
}
Tpm

  • Path: properties.reported.Tpm (Tpm component)

  • Description: Presence and status of TPM exposed to the OS

  • Members

    Name Type Notes
    tpmStatus enum of ints 0 (unknown), 1 (detected), 2 (not detected)
    tpmVersion string TPM interface version, for example "2.0"
    tpmManufacturer string Identifier, for example "IFX"

  • Example payload (as seen in twin's properties.reported section)

    "Tpm": {
     "__t": "c",
     "tpmStatus": 1,
     "tpmVersion": "2.0",
     "tpmManufacturer": "IFX"
}

Next steps

For an overview of OSConfig scenarios and capabilities, see:

For specific practical examples, see: