Quickstart: Query examples for getting started with OSConfig and Azure IoT

  • Article

The following are examples of Azure IoT Hub Queries to get useful information from OSConfig-enabled devices. These examples are reporting-only in nature, and can be used independently of whether you use OSConfig to set any configuration on the devices.

The examples invoke the Azure IoT Hub Queries feature via Azure CLI, and use Azure CLI's --output options to format the information as a table rather than raw JSON. You can adapt these examples to work with different tool chains and different device properties. For links to the full list of available properties, see: What can I provision and manage?.

Prerequisites

  1. An Azure account with an active subscription. If your don't have an account already, you can create a trial account for free

  2. An IoT Hub with OSConfig-enabled devices (or VMs as stand-ins for devices) connected. If you don't already have these, use these steps to create them: Create an OSConfig (with Azure IoT) lab environment in 5 minutes.

  3. Open Azure Cloud Shell in a new tab: Azure Cloud Shell

    1. If you prefer to use your own bash environment rather than Cloud Shell, you will need to install Azure CLI and sign in to you Azure account

  4. Ensure your Cloud Shell session is in bash mode (not PowerShell mode) for exact compatibility with the examples in this article

    1. If you prefer PowerShell, you can adapt the examples in this article by adjusting line breaks, character escaping, etc.

  5. Run the following command to install the IoT extension for Azure CLI

    az extension add --name azure-iot

Query examples

Example A. List the OSConfig enabled devices connected to your hub

Remember to replace <YOUR_HUB_NAME> with your IoT Hub's name.

az iot hub query -q \
"SELECT deviceId AS _deviceId_,connectionState FROM devices.modules where moduleId='osconfig'" \
--output table --hub-name <YOUR_HUB_NAME>

Screen capture of the given command, returning a list of deviceIds and connection state

Example B. Report on the OS level host name and OS version details

Remember to replace <YOUR_HUB_NAME> with your IoT Hub's name.

For more information on available properties related to host name and OS information, see: Report and inventory hardware and OS information with Azure IoT and OSConfig, Working with host names using Azure IoT and OSConfig, and Manage host firewall with Azure IoT and OSConfig.

az iot hub query -q \
"SELECT deviceId AS _deviceId_,properties.reported.HostName.name AS hostName,properties.reported.DeviceInfo.osName,properties.reported.DeviceInfo.osVersion,properties.reported.DeviceInfo.kernelName,properties.reported.DeviceInfo.kernelRelease FROM devices.modules where moduleId='osconfig'" \
--output table --hub-name <YOUR_HUB_NAME>

Screen capture of given example command, returning a list of devices and OS properties.

Example C. Report on hardware properties like CPU type, RAM, Tpm presence

Remember to replace <YOUR_HUB_NAME> with your IoT Hub's name.

For more information on available properties related to device hardware, see: Report and inventory hardware and OS information with Azure IoT and OSConfig.

az iot hub query -q \
"SELECT deviceId AS _deviceId_,properties.reported.DeviceInfo.cpuType,properties.reported.DeviceInfo.cpuModel,properties.reported.DeviceInfo.totalMemory,properties.reported.Tpm.tpmStatus FROM devices.modules where moduleId='osconfig'" \
--output table --hub-name <YOUR_HUB_NAME>

Screen capture of given example command, returning device hardware properties

Example D. Report on network properties like IP addresses, firewall status, and more

Remember to replace <YOUR_HUB_NAME> with your IoT Hub's name.

For more information on available properties, see Working with host names using Azure IoT and OSConfig, and Manage host firewall with Azure IoT and OSConfig, and Working with network adapter status, IP addresses, etc., using OSConfig and Azure IoT.

az iot hub query -q \
"SELECT deviceId AS _deviceId_,properties.reported.Networking.networkConfiguration.ipAddresses,properties.reported.Networking.networkConfiguration.dnsServers,properties.reported.Networking.networkConfiguration.connected,properties.reported.Firewall.firewallState FROM devices.modules where moduleId='osconfig'" \
--output table --hub-name <YOUR_HUB_NAME>

Screen capture of given example command, returning device network properties.

Next steps

For an overview of OSConfig scenarios and capabilities, see:

For specific practical examples, see: