Share via

az iot hub module-identity

  • Reference

Note

This reference is part of the azure-iot extension for the Azure CLI (version 2.46.0 or higher). The extension will automatically install the first time you run an az iot hub module-identity command. Learn more about extensions.

Manage IoT device modules.

Commands

Name Description Type Status
az iot hub module-identity connection-string

Manage IoT device module's connection string.

 Extension GA
az iot hub module-identity connection-string show

Show a target IoT device module connection string.

 Extension GA
az iot hub module-identity create

Create a module on a target IoT device in an IoT Hub.

 Extension GA
az iot hub module-identity delete

Delete a device in an IoT Hub.

 Extension GA
az iot hub module-identity list

List modules located on an IoT device in an IoT Hub.

 Extension GA
az iot hub module-identity renew-key

Renew target keys of IoT Hub device modules with sas authentication.

 Extension GA
az iot hub module-identity show

Get the details of an IoT device module in an IoT Hub.

 Extension GA
az iot hub module-identity update

Update an IoT Hub device module.

 Extension GA

az iot hub module-identity create

Create a module on a target IoT device in an IoT Hub.

When using the auth method of shared_private_key (also known as symmetric keys), if no custom keys are provided the service will generate them for the module.

az iot hub module-identity create --device-id
                                  --module-id
                                  [--am {shared_private_key, x509_ca, x509_thumbprint}]
                                  [--auth-type {key, login}]
                                  [--hub-name]
                                  [--login]
                                  [--od]
                                  [--pk]
                                  [--primary-thumbprint]
                                  [--resource-group]
                                  [--secondary-key]
                                  [--secondary-thumbprint]
                                  [--valid-days]

Required Parameters

--device-id -d

Target Device Id.

--module-id -m

Target Module Id.

Optional Parameters

--am --auth-method

The authorization method an entity is to be created with.

Accepted values: shared_private_key, x509_ca, x509_thumbprint
Default value: shared_private_key
--auth-type

Indicates whether the operation should auto-derive a policy key or use the current Azure AD session. If the authentication type is login and the resource hostname is provided, resource lookup will be skipped unless needed.You can configure the default using az configure --defaults iothub-data-auth-type={auth-type-value}.

Accepted values: key, login
Default value: key
--hub-name -n

IoT Hub name or hostname. Required if --login is not provided.

--login -l

This command supports an entity connection string with rights to perform action. Use to avoid session login via "az login". If both an entity connection string and name are provided the connection string takes priority. Required if --hub-name is not provided.

--od --output-dir

Generate self-signed cert and use its thumbprint. Output to specified target directory.

--pk --primary-key

The primary symmetric shared access key stored in base64 format.

--primary-thumbprint --ptp

Self-signed certificate thumbprint to use for the primary thumbprint.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

--secondary-key --sk

The secondary symmetric shared access key stored in base64 format.

--secondary-thumbprint --stp

Self-signed certificate thumbprint to use for the secondary thumbprint.

--valid-days --vd

Generate self-signed cert and use its thumbprint. Valid for specified number of days. Default: 365.

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

Accepted values: json, jsonc, none, table, tsv, yaml, yamlc
Default value: json
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

az iot hub module-identity delete

Delete a device in an IoT Hub.

az iot hub module-identity delete --device-id
                                  --module-id
                                  [--auth-type {key, login}]
                                  [--etag]
                                  [--hub-name]
                                  [--login]
                                  [--resource-group]

Required Parameters

--device-id -d

Target Device Id.

--module-id -m

Target Module Id.

Optional Parameters

--auth-type

Indicates whether the operation should auto-derive a policy key or use the current Azure AD session. If the authentication type is login and the resource hostname is provided, resource lookup will be skipped unless needed.You can configure the default using az configure --defaults iothub-data-auth-type={auth-type-value}.

Accepted values: key, login
Default value: key
--etag -e

Etag or entity tag corresponding to the last state of the resource. If no etag is provided the value '*' is used.

--hub-name -n

IoT Hub name or hostname. Required if --login is not provided.

--login -l

This command supports an entity connection string with rights to perform action. Use to avoid session login via "az login". If both an entity connection string and name are provided the connection string takes priority. Required if --hub-name is not provided.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

Accepted values: json, jsonc, none, table, tsv, yaml, yamlc
Default value: json
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

az iot hub module-identity list

List modules located on an IoT device in an IoT Hub.

az iot hub module-identity list --device-id
                                [--auth-type {key, login}]
                                [--hub-name]
                                [--login]
                                [--resource-group]
                                [--top]

Required Parameters

--device-id -d

Target Device Id.

Optional Parameters

--auth-type

Indicates whether the operation should auto-derive a policy key or use the current Azure AD session. If the authentication type is login and the resource hostname is provided, resource lookup will be skipped unless needed.You can configure the default using az configure --defaults iothub-data-auth-type={auth-type-value}.

Accepted values: key, login
Default value: key
--hub-name -n

IoT Hub name or hostname. Required if --login is not provided.

--login -l

This command supports an entity connection string with rights to perform action. Use to avoid session login via "az login". If both an entity connection string and name are provided the connection string takes priority. Required if --hub-name is not provided.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

--top

Maximum number of elements to return. Use -1 for unlimited.

Default value: 1000
Global Parameters
--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

Accepted values: json, jsonc, none, table, tsv, yaml, yamlc
Default value: json
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

az iot hub module-identity renew-key

Renew target keys of IoT Hub device modules with sas authentication.

Currently etags and key type swap are not supported for bulk key regeneration. Bulk Key regeneration will yeild a different output format from single module key regeneration.

az iot hub module-identity renew-key --device-id
                                     --hub-name
                                     --key-type {both, primary, secondary, swap}
                                     --module-id
                                     [--auth-type {key, login}]
                                     [--etag]
                                     [--login]
                                     [--no-progress {false, true}]
                                     [--resource-group]

Examples

Renew the primary key.

az iot hub module-identity renew-key -m {module_name} -d {device_id} -n {iothub_name} --kt primary

Swap the primary and secondary keys.

az iot hub module-identity renew-key -m {module_name} -d {device_id} -n {iothub_name} --kt swap

Renew the secondary key for two modules.

az iot hub module-identity renew-key -m {module_name} {module_name} -d {device_id} -n {iothub_name} --kt secondary

Renew both keys for all modules in the device.

az iot hub module-identity renew-key -m * -d {device_id} -n {iothub_name} --kt both

Required Parameters

--device-id -d

Target Device Id.

--hub-name -n

IoT Hub name or hostname. Required if --login is not provided.

--key-type --kt

Target key type to regenerate.

Accepted values: both, primary, secondary, swap
--module-id -m

Space seperated list of target Module Ids. Use * for all modules.

Optional Parameters

--auth-type

Indicates whether the operation should auto-derive a policy key or use the current Azure AD session. If the authentication type is login and the resource hostname is provided, resource lookup will be skipped unless needed.You can configure the default using az configure --defaults iothub-data-auth-type={auth-type-value}.

Accepted values: key, login
Default value: key
--etag -e

Etag or entity tag corresponding to the last state of the resource. If no etag is provided the value '*' is used. This arguement only applies to swap.

--login -l

This command supports an entity connection string with rights to perform action. Use to avoid session login via "az login". If both an entity connection string and name are provided the connection string takes priority. Required if --hub-name is not provided.

--no-progress

Hide the progress bar for bulk key regeneration.

Accepted values: false, true
--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

Accepted values: json, jsonc, none, table, tsv, yaml, yamlc
Default value: json
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

az iot hub module-identity show

Get the details of an IoT device module in an IoT Hub.

az iot hub module-identity show --device-id
                                --module-id
                                [--auth-type {key, login}]
                                [--hub-name]
                                [--login]
                                [--resource-group]

Required Parameters

--device-id -d

Target Device Id.

--module-id -m

Target Module Id.

Optional Parameters

--auth-type

Indicates whether the operation should auto-derive a policy key or use the current Azure AD session. If the authentication type is login and the resource hostname is provided, resource lookup will be skipped unless needed.You can configure the default using az configure --defaults iothub-data-auth-type={auth-type-value}.

Accepted values: key, login
Default value: key
--hub-name -n

IoT Hub name or hostname. Required if --login is not provided.

--login -l

This command supports an entity connection string with rights to perform action. Use to avoid session login via "az login". If both an entity connection string and name are provided the connection string takes priority. Required if --hub-name is not provided.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

Accepted values: json, jsonc, none, table, tsv, yaml, yamlc
Default value: json
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

az iot hub module-identity update

Update an IoT Hub device module.

Use --set followed by property assignments for updating a module. Leverage properties returned from 'iot hub module-identity show'.

az iot hub module-identity update --device-id
                                  --module-id
                                  [--add]
                                  [--auth-type {key, login}]
                                  [--etag]
                                  [--force-string]
                                  [--hub-name]
                                  [--login]
                                  [--remove]
                                  [--resource-group]
                                  [--set]

Examples

Regenerate module symmetric authentication keys

az iot hub module-identity update -m {module_name} -d {device_id} -n {iothub_name} --set authentication.symmetricKey.primaryKey="" authentication.symmetricKey.secondaryKey=""

Required Parameters

--device-id -d

Target Device Id.

--module-id -m

Target Module Id.

Optional Parameters

--add

Add an object to a list of objects by specifying a path and key value pairs. Example: --add property.listProperty <key=value, string or JSON string>.

Default value: []
--auth-type

Indicates whether the operation should auto-derive a policy key or use the current Azure AD session. If the authentication type is login and the resource hostname is provided, resource lookup will be skipped unless needed.You can configure the default using az configure --defaults iothub-data-auth-type={auth-type-value}.

Accepted values: key, login
Default value: key
--etag -e

Etag or entity tag corresponding to the last state of the resource. If no etag is provided the value '*' is used.

--force-string

When using 'set' or 'add', preserve string literals instead of attempting to convert to JSON.

Default value: False
--hub-name -n

IoT Hub name or hostname. Required if --login is not provided.

--login -l

This command supports an entity connection string with rights to perform action. Use to avoid session login via "az login". If both an entity connection string and name are provided the connection string takes priority. Required if --hub-name is not provided.

--remove

Remove a property or an element from a list. Example: --remove property.list <indexToRemove> OR --remove propertyToRemove.

Default value: []
--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

--set

Update an object by specifying a property path and value to set. Example: --set property1.property2=<value>.

Default value: []
Global Parameters
--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

Accepted values: json, jsonc, none, table, tsv, yaml, yamlc
Default value: json
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.