Working with host names using 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 is about getting and setting device host names with the OS on the device.

Prerequisites

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:

Azure Portal

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

Bash / Cloud Shell

1. Sign in to the Azure Portal with the account you wish to use
2. Launch Azure Cloud Shell in bash mode
3. (optional) Use the command az account show to ensure you are signed into the context you wish to use for the examples.

The object model

The following are the key desired and reported properties related to host name.

	Primary use	Populated by	Notes
reported.HostName.name	Get scenarios	OSConfig agent	Name reported by the OS, analogous to cat /etc/hostname on most Linux systems
desired.HostName.desiredName	Set scenarios	Admin or admin tools	Admin's intended host name for the device
reported.HostName.desiredName.value	Set scenarios	OSConfig agent	Acknowledges receipt of desired host name; should match desired name
reported.HostName.desiredName.ac	Set scenarios	OSConfig agent	Status for reaching desired state (host name set with OS); 200 indicates success

To see these properties with example values in the context of an OSConfig twin from IoT Hub, see the reference section at the end of this article.

A. Examples for individual devices

The following demonstrate specific use cases. You can use these as starting points and adapt for your unique environment.

Example A.1. Set a new host name on a specific device

Azure Portal

1. Using Azure Portal, you can change or update the host name on a specific device by editing the module twin for OSConfig.

   

2. You can verify the change is made successfully from the module twin itself or you can verify the hostname on the device has been updated. Scroll down the module twin to find reported properties for HostName .

   

Bash / Cloud Shell

1. (optional step for context)
   Use the following example to examine the existing host name, replacing <device id> and/or <hub name> to match your environment.

   az iot hub query -q \
   "SELECT deviceId, properties.reported.HostName.name AS HostName
   FROM devices.modules
   WHERE moduleId='osconfig'
   AND deviceID='<device id>'" --hub-name <hub name>
   

   

2. Express the new name through the desiredName property

   az iot hub module-twin update -m osconfig --desired \
   '{
     "HostName": {
       "__t": "c",
       "desiredName": "NewName001"
   }}' \
   --device-id <device id> --hub-name <hub name> 
   

   

3. (optional step for context)
   Use the following example to show that the new name is in place, replacing <device id> and/or <hub name> to match your environment.

   az iot hub query -q \
   "SELECT deviceId, properties.reported.HostName.name, properties.reported.   HostName.desiredName.ac AS Status
   FROM devices.modules
   WHERE moduleId='osconfig'
   AND deviceID='<device id>'" --hub-name <hub name>
   

   

Note

For the curious, some notes about this example:

• To set the host name, only the az iot hub module-twin update ... step is required; the other commands are provided for context
• The output of the az iot hub module-twin update ... command is the twin as modified by the command (showing that desiredName is now populated)
• In the last step, we see two indicators that our desiredName change was successful.
  • The new name is reported
  • The status code (called ac in the twin) associated with desiredName is 200 (OK)

B. At-scale examples for fleets of devices

Example B.1. At scale, inventory or audit the host names of all devices connected to the IoT Hub

Solution portals, security audits, and other inventory-oriented workflows often rely on having host name information for all devices. Choose your preferred experience to see examples:

Azure Portal

1. From your Azure IoT Hub's portal page, choose Device management --> Queries in the left hand navigation.

2. Execute this query: SELECT deviceId,properties.reported.HostName.name FROM devices.modules WHERE moduleId='osconfig'"

   

Bash / Cloud Shell

1. Use the IoT Hub Query service to get the host names of all devices, replacing <device id> and/or <hub name> to match your environment.

   az iot hub query -q \
   "SELECT deviceId,properties.reported.HostName.name \
   FROM devices.modules WHERE moduleId='osconfig'" \
   --output table --hub-name <hub name> 
   

   

Example B.2. At scale, dynamically set a unique host name on each device

In this example, we imagine an environment where we want all the host names to match the IoT Hub devices IDs. This way logs and other data from the devices will be easy to reconcile and contextualize on the back end of our cloud solution.

Azure Portal

This scenario cannot be completed directly from the IoT Hub portal pages. It could be done via Azure Portal using another service for automation, such as Azure Functions.

For reference on the logic and object model, see the Bash / Cloud Shell example.

Bash / Cloud Shell

1. Store you IoT Hub's name in bash variable hub_name

   The following examples refer repeatedly to your IoT Hub name, so we will use a bash variable rather than editing each example separately. Replace <hub name> with your IoT Hub name in the below.

   hub_name="<hub name>"
   

   

2. (optional step for context)
   Show the original host names

   az iot hub query -q \
   "SELECT deviceId,properties.reported.HostName.name FROM devices.modules WHERE moduleId='osconfig'" \
   --hub-name "$hub_name"
   

   In the example shown here, the original host names are disorganized.

   

3. Calculate and set the new host name for each device

   for deviceId in $(az iot hub query -q "SELECT deviceId FROM devices.modules WHERE moduleId='osconfig'" --hub-name "$hub_name" --output tsv )
   do
       az iot hub module-twin update -m osconfig --desired \
       "{ \"HostName\": {\"desiredName\": \"$deviceId\" }}" \
      --device-id "$deviceId" --hub-name "$hub_name"
   done
   

   

4. (optional step for context)
   Show that the OS level host names now match the IoT Hub device IDs

   Tip

   Due to caching behavior in the IoT Hub Query service, there may be a delay of around 1 minute before the new names appear in the results of this query

   az iot hub query -q \
   "SELECT deviceId,properties.reported.HostName.name FROM devices.modules WHERE moduleId='osconfig'" \
   --hub-name $hub_name
   

   In the example below, we see that the host names now follow a consistent pattern: matching the IoT Hub device IDs.

   

Reference: Example twin from Iot Hub

The following is excerpted from an osconfig module twin in IoT Hub. For context it includes most of the raw twin, with certain properties (like $metadata) removed for brevity. The properties related to this article are highlighted.

{
    "deviceId": "device03",
    "moduleId": "osconfig",
    "connectionState": "Connected",
    "modelId": "dtmi:osconfig:deviceosconfiguration;5",
    "version": 28,
    "properties": {
        "desired": {
            "Settings": {
                "__t": "c",
                "DeviceHealthTelemetryConfiguration": 2,
                "DeliveryOptimizationPolicies": {
                    "PercentageDownloadThrottle": 50,
                    "CacheHostSource": 1,
                    "CacheHost": "http://mycachehost"
                }
            },
            "CommandRunner": {
                "__t": "c",
                "CommandArguments": {
                    "CommandId": "set_timezone__And_report_back",
                    "Arguments": "timedatectl set-timezone UTC; timedatect l grep zone | tr -d '[:space:]'",
                    "SingleLineTextResult": false,
                    "Action": 3
                }
            },
            "HostName": {
                "__t": "c",
                "DesiredName": "NewHostName123",
                "DesiredHosts": "127.0.0.1 localhost;::1 ip6-localhost ip6-loopback;fe00::0 ip6-localnet;ff00::0 ip6-mcastprefix;ff02::1 ip6-allnodes;ff02::2 ip6-allrouters;ff02::3 ip6-allhosts;10.1.2.3 my-on-prem-equipment"
            },
            "Ztsi": {
                "__t": "c",
                "DesiredServiceUrl": "https://my-attestation-endpoint",
                "DesiredEnabled": true
            },
            "$version": 8
        },
        "reported": {
            "Firewall": {
                "__t": "c",
                "FirewallState": 1,
                "FirewallFingerprint": "86cadaa93d8c0e0ee42e36190413265c2e218c87a0c494c026cf7de601765e72"
            },
            "CommandRunner": {
                "__t": "c",
                "CommandStatus": {
                    "CommandId": "set_timezone__And_report_back",
                    "ResultCode": 0,
                    "TextResult": "",
                    "CurrentState": 2
                },
                "CommandArguments": {
                    "value": {
                        "CommandId": "set_timezone__And_report_back",
                        "Arguments": "timedatectl set-timezone UTC; timedatect l grep zone | tr -d '[:space:]'",
                        "SingleLineTextResult": false,
                        "Action": 3
                    },
                    "ac": 200,
                    "ad": "-",
                    "av": 4
                }
            },
            "HostName": {
                "__t": "c",
                "Name": "NewHostName123",
                "Hosts": "127.0.0.1 localhost;::1 ip6-localhost ip6-loopback;fe00::0 ip6-localnet;ff00::0 ip6-mcastprefix;ff02::1 ip6-allnodes;ff02::2 ip6-allrouters;ff02::3 ip6-allhosts;10.1.2.3 my-on-prem-equipment",
                "DesiredName": {
                    "value": "NewHostName123",
                    "ac": 200,
                    "ad": "-",
                    "av": 5
                },
                "DesiredHosts": {
                    "value": "127.0.0.1 localhost;::1 ip6-localhost ip6-loopback;fe00::0 ip6-localnet;ff00::0 ip6-mcastprefix;ff02::1 ip6-allnodes;ff02::2 ip6-allrouters;ff02::3 ip6-allhosts;10.1.2.3 my-on-prem-equipment",
                    "ac": 200,
                    "ad": "-",
                    "av": 6
                }
            },
            "Networking": {
                "__t": "c",
                "NetworkConfiguration": {
                    "InterfaceTypes": "eth0=ether;lo=loopback",
                    "MacAddresses": "eth0=00:22:48:7b:04:39;lo=00:00:00:00:00:00",
                    "IpAddresses": "eth0=10.0.0.6,fe80::222:48ff:fe7b:439;lo=127.0.0.1,::1",
                    "SubnetMasks": "eth0=/24,/64;lo=/8,/128",
                    "DefaultGateways": "eth0=10.0.0.1",
                    "DnsServers": "eth0=168.63.129.16",
                    "DhcpEnabled": "eth0=false;lo=false",
                    "Enabled": "eth0=true;lo=unknown",
                    "Connected": "eth0=true;lo=true"
                }
            },
            "Tpm": {
                "__t": "c",
                "TpmStatus": 2
            },
            "Ztsi": {
                "__t": "c",
                "Enabled": 0,
                "ServiceUrl": "",
                "DesiredServiceUrl": {
                    "value": "https://my-attestation-endpoint",
                    "ac": 200,
                    "ad": "-",
                    "av": 7
                },
                "DesiredEnabled": {
                    "value": true,
                    "ac": 200,
                    "ad": "-",
                    "av": 8
                }
            },
            "Settings": {
                "__t": "c",
                "DeviceHealthTelemetryConfiguration": {
                    "value": 2,
                    "ac": 200,
                    "ad": "-",
                    "av": 2
                },
                "DeliveryOptimizationPolicies": {
                    "value": {
                        "PercentageDownloadThrottle": 50,
                        "CacheHostSource": 1,
                        "CacheHost": "http://mycachehost"
                    },
                    "ac": 400,
                    "ad": "-",
                    "av": 3
                }
            },
            "$version": 20
        }
    }
}

Next steps

For an overview of OSConfig scenarios and capabilities, see:

• What is OSconfig for IoT

For specific practical examples, see:

• Create an OSConfig (with Azure IoT) lab environment in 5 minutes
• Quickstart: Query examples for getting started with OSConfig and Azure IoT
• What can I provision and manage?