Report and inventory hardware and OS information with Azure IoT and OSConfig
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:
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.
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.
You will use Azure Portal or Azure CLI to interact with the devices via your IoT Hub
For further steps, choose your preferred experience:
- Ensure you are signed in to the Azure Portal and can access your IoT Hub's Overview page
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
- Navigate to the OSConfig twin for the device of your choice
- 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)
- Click on the device name in the list of device IDs
- Under Module Identities click on the osconfig module ID
- Click on Module Identity Twin
- Scroll to view the
DeviceInfo
andTpm
sections underproperties.reported
, and note the available information includingcpuType
,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: