Reboot or shut down devices with Azure IoT and OSConfig

Article
10/03/2022

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 is about how to reboot or shutdown devices using the CommandRunner feature of OSConfig. This article focuses on practical examples with minimal explanation. For technical background on the CommandRunner feature, the interaction model, etc. see How to interact with the CommandRunner feature of OSConfig and Azure IoT.

Use-case examples

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:

Azure Portal
Bash / Cloud Shell

Ensure you are signed in to the Azure Portal and can access your IoT Hub's Overview page

Example A. Reboot one or several devices

For the single device examples, you can add the reboot directive directly to the OSConfig twin of the device you wish to reboot.

For the at-scale examples, we imagine working with an outside process which is adding and removing needsReboot tags to devices. We will create an IoT Hub Configuration which dynamically targets devices where the needsReboot tag is set in the osconfig twin. We will simulate this outside process by explicitly setting the tag.

Azure Portal, with one device
Azure Portal, at-scale
Bash / Cloud Shell, with one device
Bash / Cloud Shell, at-scale

From your IoT Hub's portal page, navigate to the OSConfig twin for the device you wish to manage, and add the following to the properties.desired section, followed by a comma to separate it from the next item in properties.desired. action=1 below specifies reboot.
```
"CommandRunner": {
   "__t": "c",
   "commandArguments": {
      "commandId": "reboot_single_device_cmd",
      "arguments": "",
      "timeout": 30,
      "singleLineTextResult": false,
      "action": 1
   }
}
```
Optional: Once the device is back online (this will take a few minutes), you can check the properties.reported section and check for the commandStatus that will show reboot action completed successfully, as shown below.
```
"CommandRunner": {
   "__t": "c",
   "commandStatus": {
      "commandId": "reboot_single_device_cmd",
      "resultCode": 0,
      "textResult": "",
      "currentState": 2
   }
}
```

1.Optional: You can also log into your device or VM to validate after the device has rebooted.

First we will simulate the outside process described above by manually applying a "needsReboot" tag to one or more devices of your choice. This will provide targeting criteria for the IoT Hub Configuration job (which will be created in a later step). To do this, navigate to the device's Azure IoT Hub page in the portal, to the OSConfig module twin, and add the following prior to the properties section of the twin.
```
{
   {"tags": {"needsReboot": "true"}}
}
```
From your Azure IoT Hub's portal page, choose Device management --> Configurations --> Add Module Configuration.

Specify a name and set the Twin Settings with the desired package manager configuration. Set Module Twin Property to properties.desired.CommandRunner and set the Module Twin Property Content to the following:

{
     "__t": "c",
     "commandArguments": {
         "commandId": "reboot_devices_by_tag",
         "arguments": "",
         "timeout": 30,
         "singleLineTextResult": false,
         "action": 1
     }
 }

For the Target Modules, specify the criteria for which devices are in scope. In this example, we will target all OSConfig-enabled devices that have the specified tag needsReboot, by specifying a Target Condition of FROM devices.modules where moduleId='osconfig' AND tags.needsReboot = 'true'
Optional: To observe which devices' twins have been updated (cloud side), see the Applied metric (also known as appliedCount)
Optional: You can observe the devices that rebooted successfully using IoT Hub Queries. Navigate to Device Management --> Queries and run the following query.
```
SELECT deviceId from devices.modules where moduleId='osconfig' 
AND tags.needsReboot = 'true' 
AND properties.reported.CommandRunner.CommandStatus.CommandId = 'reboot_devices_by_tag' 
AND properties.reported.CommandRunner.CommandStatus.ResultCode = 0
```
Note that there will be some delay (~5-10 minutes) for the commandStatus to get updated as this requires the device to complete the reboot cycle and get back online.
Optional: For development and debugging purposes, you can check if connectionState for OSConfig module (or any other module) shows up as Connected. For this, navigate to Device Management --> Queries and run the query SELECT deviceId, connectionState FROM devices.modules where moduleId = 'osconfig'. For more info, see: DeviceHeartbeat.
Optional: To monitor device connect and disconnect events in production, see: MonitorConnectandDisconnect.

Use the following example command to reboot a single device by updating the OSConfig module twin, replacing <device id> and/or <hub name> to match your environment.

az iot hub module-twin update -m osconfig --desired \
'{
"CommandRunner": {
     "__t": "c",
     "commandArguments": {
         "commandId": "reboot_single_device_cmd",
         "arguments": "",
         "timeout": 30,
         "singleLineTextResult": false,
         "action": 1
      }
   }
}' -d <device id> --hub-name <hub name>

Screen capture showing how to reboot a device using bash.

Optional: To verify that the device(s) has rebooted successfully using IoT Hub Queries, Navigate to Device Management --> Queries and run the following query. Note that there will be some delay (~5-10 minutes) for the reported commandStatus to get updated as this requires the device to complete the reboot cycle and get back online.
```
SELECT deviceId from devices.modules where moduleId='osconfig' 
AND properties.reported.CommandRunner.CommandStatus.CommandId = 'reboot_single_device_cmd' 
AND properties.reported.CommandRunner.CommandStatus.ResultCode = 0
```
Optional: You can also log into your device or VM to validate after the device has rebooted.

First we will simulate the outside process described above by manually applying a "needsReboot" tag to one or more devices of your choice. This will provide targeting criteria for the IoT Hub Configuration job (which will be created in a later step).

az iot hub module-twin update -m osconfig --tags '{"needsReboot": "true"}' -n <hub name> -d <device id>

Use the following example command to create an IoT Hub Configuration. This Configuration includes targeting criteria, the desired configuration. Be sure to replace <hub name> with your IoT Hub name.

az iot hub configuration create -c "reboot_devices_by_tag" --content \
'{"moduleContent":
  {"properties.desired.CommandRunner":
   {"commandArguments":
   {"commandId": "reboot_devices_by_tag",
     "arguments": "",      
     "timeout": 30,
     "singleLineTextResult": false,
     "action": 1            
   }}}}' \
--target-condition "from devices.modules where moduleId='osconfig' and tags.needsReboot = 'true'" --priority 10 \
--hub-name <hub name>

Screen capture showing how to create a package manager configuration for a fleet of devices from bash

Optional: Observe the Applied metric

To see which devices have the reboot directive applied to them by this Configuration, run the following command. It may take up to 5 minutes after creating the Configuration before it is applied to targeted twins.
```
  az iot hub configuration show-metric --metric-id appliedCount -c "reboot_devices_by_tag" \
  -n <hub name> --metric-type system
```
Optional: For development and debugging purposes, you can check if connectionState for OSConfig module (or any other module) shows up as Connected. For this, navigate to Device Management --> Queries and run the query SELECT deviceId, connectionState FROM devices.modules where moduleId = 'osconfig'. For more info, see: DeviceHeartbeat.
Optional: To monitor device connect and disconnect events in production, please refer to this documentation, MonitorConnectandDisconnect.

Example B. Shutdown instead of reboot

Remotely shutting down (as opposed to rebooting) edge/IoT devices is a less common operation, due the the device being subsequently unavailable (barring an out-of-band way to boot it back up). Even so, there are real-world cases which call for remote shut down. Imagine a problem device which is sending corrupt data, is over-consuming precious satellite transmission bytes, is believed to be compromised, or is otherwise doing more harm than good. In such cases it can be desirable to shut down the device until it can be replaced or repaired.

To perform shutdown of devices through OSConfig, you can use the same cloud workflows as Example A, but using "action": 2 (shutdown) rather than "action": 1 (reboot) in commandArguments. Please be aware that each request in CommandRunner needs a new commandId value. For example, if you already performed a reboot in Example A and now want to switch to shutdown, you will need to modify commandArguments not just with "action": 2 but also with a not-previously-used value for commandId, such as "commandId": "my_shutdown_cmd". For more on the CommandRunner interaction model, see: How to interact with the CommandRunner feature of OSConfig and Azure IoT.

Next steps

For an overview of OSConfig scenarios and capabilities, see:

What is OSconfig for IoT

For specific practical examples, see:

Share via