Merge pull request #197883 from PatAltimore/patricka-dps

Add IoT Edge DPS reprovisioning detail

Author: AnnaMHuff

articles/iot-edge/how-to-provision-devices-at-scale-linux-symmetric.md

@@ -3,7 +3,7 @@ title: Create and provision IoT Edge devices using symmetric keys on Linux - Azu
 description: Use symmetric key attestation to test provisioning Linux devices at scale for Azure IoT Edge with device provisioning service
 author: PatAltimore
 ms.author: patricka
-ms.date: 10/29/2021
+ms.date: 05/12/2022
 ms.topic: conceptual
 ms.service: iot-edge
 services: iot-edge
@@ -66,18 +66,19 @@ Have the following information ready:
 
    The `provisioning:` line should have no preceding whitespace, and nested items should be indented by two spaces.
 
-   ```yml
-   # DPS TPM provisioning configuration
-   provisioning:
-     source: "dps"
-     global_endpoint: "https://global.azure-devices-provisioning.net"
-     scope_id: "PASTE_YOUR_SCOPE_ID_HERE"
-     attestation:
-       method: "symmetric_key"
-       registration_id: "PASTE_YOUR_REGISTRATION_ID_HERE"
-       symmetric_key: "PASTE_YOUR_PRIMARY_KEY_OR_DERIVED_KEY_HERE"
-   #  always_reprovision_on_startup: true
-   #  dynamic_reprovisioning: false
+    ```yml
+    # DPS TPM provisioning configuration
+    provisioning:
+      source: "dps"
+      global_endpoint: "https://global.azure-devices-provisioning.net"
+      scope_id: "PASTE_YOUR_SCOPE_ID_HERE"
+      attestation:
+        method: "symmetric_key"
+        registration_id: "PASTE_YOUR_REGISTRATION_ID_HERE"
+        symmetric_key: "PASTE_YOUR_PRIMARY_KEY_OR_DERIVED_KEY_HERE"
+
+   # always_reprovision_on_startup: true
+   # dynamic_reprovisioning: true
    ```
 
 1. Update the values of `scope_id`, `registration_id`, and `symmetric_key` with your DPS and device information.
@@ -110,26 +111,30 @@ Have the following information ready:
 
 1. Find the **Provisioning** section of the file. Uncomment the lines for DPS provisioning with symmetric key, and make sure any other provisioning lines are commented out.
 
-   ```toml
-   # DPS provisioning with symmetric key
-   [provisioning]
-   source = "dps"
-   global_endpoint = "https://global.azure-devices-provisioning.net"
-   id_scope = "PASTE_YOUR_SCOPE_ID_HERE"
-   
-   [provisioning.attestation]
-   method = "symmetric_key"
-   registration_id = "PASTE_YOUR_REGISTRATION_ID_HERE"
-
-   symmetric_key = { value = "PASTE_YOUR_PRIMARY_KEY_OR_DERIVED_KEY_HERE" }
-   ```
+    ```toml
+    # DPS provisioning with symmetric key
+    [provisioning]
+    source = "dps"
+    global_endpoint = "https://global.azure-devices-provisioning.net"
+    id_scope = "PASTE_YOUR_SCOPE_ID_HERE"
+    
+    [provisioning.attestation]
+    method = "symmetric_key"
+    registration_id = "PASTE_YOUR_REGISTRATION_ID_HERE"
+    
+    symmetric_key = { value = "PASTE_YOUR_PRIMARY_KEY_OR_DERIVED_KEY_HERE" }
+    
+    # auto_reprovisioning_mode = Dynamic
+    ```
 
 1. Update the values of `id_scope`, `registration_id`, and `symmetric_key` with your DPS and device information.
 
    The symmetric key parameter can accept a value of an inline key, a file URI, or a PKCS#11 URI. Uncomment just one symmetric key line, based on which format you're using.
 
    If you use any PKCS#11 URIs, find the **PKCS#11** section in the config file and provide information about your PKCS#11 configuration.
 
+1. Optionally, find the auto reprovisioning mode section of the file. Use the `auto_reprovisioning_mode` parameter to configure your device's reprovisioning behavior. **Dynamic** - Reprovision when the device detects that it may have been moved from one IoT Hub to another. This is the default. **AlwaysOnStartup** - Reprovision when the device is rebooted or a crash causes the daemon(s) to restart. **OnErrorOnly** - Never trigger device reprovisioning automatically. Each mode has an implicit device reprovisioning fallback if the device is unable to connect to IoT Hub during identity provisioning due to connectivity errors. For more information, see [IoT Hub device reprovisioning concepts](../iot-dps/concepts-device-reprovision.md).
+
 1. Save and close the config.toml file.
 
 1. Apply the configuration changes that you made to IoT Edge.

articles/iot-edge/how-to-provision-devices-at-scale-linux-tpm.md

@@ -4,7 +4,7 @@ description: Use a simulated TPM on a Linux device to test the Azure IoT Hub dev
 author: PatAltimore
 manager: lizross
 ms.author: patricka
-ms.date: 10/28/2021
+ms.date: 05/13/2022
 ms.topic: conceptual
 ms.service: iot-edge
 services: iot-edge
@@ -196,6 +196,7 @@ After the runtime is installed on your device, configure the device with the inf
      attestation:
        method: "tpm"
        registration_id: "REGISTRATION_ID_HERE"
+
    # always_reprovision_on_startup: true
    # dynamic_reprovisioning: false
    ```
@@ -238,11 +239,13 @@ After the runtime is installed on your device, configure the device with the inf
    [provisioning.attestation]
    method = "tpm"
    registration_id = "REGISTRATION_ID_HERE"
+
+   # auto_reprovisioning_mode = Dynamic
    ```
 
 1. Update the values of `id_scope` and `registration_id` with your device provisioning service and device information. The `scope_id` value is the **ID Scope** from your device provisioning service instance's overview page.
 
-1. Optionally, find the auto reprovisioning mode section of the file. Use the `auto_reprovisioning_mode` parameter to configure your device's reprovisioning behavior to either `Dynamic`, `AlwaysOnStartup`, or `OnErrorOnly`. For more information, see [IoT Hub device reprovisioning concepts](../iot-dps/concepts-device-reprovision.md).
+1. Optionally, find the auto reprovisioning mode section of the file. Use the `auto_reprovisioning_mode` parameter to configure your device's reprovisioning behavior. **Dynamic** - Reprovision when the device detects that it may have been moved from one IoT Hub to another. This is the default. **AlwaysOnStartup** - Reprovision when the device is rebooted or a crash causes the daemon(s) to restart. **OnErrorOnly** - Never trigger device reprovisioning automatically. Each mode has an implicit device reprovisioning fallback if the device is unable to connect to IoT Hub during identity provisioning due to connectivity errors. For more information, see [IoT Hub device reprovisioning concepts](../iot-dps/concepts-device-reprovision.md).
 
 1. Save and close the file.
 

articles/iot-edge/how-to-provision-devices-at-scale-linux-x509.md

@@ -3,7 +3,7 @@ title: Create and provision IoT Edge devices at scale using X.509 certificates o
 description: Use X.509 certificates to test provisioning devices at scale for Azure IoT Edge with device provisioning service
 author: PatAltimore
 ms.author: patricka
-ms.date: 02/28/2022
+ms.date: 05/13/2022
 ms.topic: conceptual
 ms.service: iot-edge
 services: iot-edge
@@ -107,8 +107,9 @@ Have the following information ready:
    #   registration_id: "OPTIONAL_REGISTRATION_ID_LEAVE_COMMENTED_OUT_TO_REGISTER_WITH_CN_OF_IDENTITY_CERT"
        identity_cert: "REQUIRED_URI_TO_DEVICE_IDENTITY_CERTIFICATE_HERE"
        identity_pk: "REQUIRED_URI_TO_DEVICE_IDENTITY_PRIVATE_KEY_HERE"
-   #  always_reprovision_on_startup: true
-   #  dynamic_reprovisioning: false
+
+   # always_reprovision_on_startup: true
+   # dynamic_reprovisioning: false
    ```
 
 1. Update the values of `scope_id`, `identity_cert`, and `identity_pk` with your DPS and device information.
@@ -164,6 +165,8 @@ Have the following information ready:
    identity_cert = "DEVICE_IDENTITY_CERTIFICATE_HERE"
 
    identity_pk = "DEVICE_IDENTITY_PRIVATE_KEY_HERE"
+
+   # auto_reprovisioning_mode = Dynamic
    ```
 
 1. Update the value of `id_scope` with the scope ID you copied from your instance of DPS.
@@ -178,6 +181,8 @@ Have the following information ready:
 
    If you use any PKCS#11 URIs, find the **PKCS#11** section in the config file and provide information about your PKCS#11 configuration.
 
+1. Optionally, find the auto reprovisioning mode section of the file. Use the `auto_reprovisioning_mode` parameter to configure your device's reprovisioning behavior. **Dynamic** - Reprovision when the device detects that it may have been moved from one IoT Hub to another. This is the default. **AlwaysOnStartup** - Reprovision when the device is rebooted or a crash causes the daemon(s) to restart. **OnErrorOnly** - Never trigger device reprovisioning automatically. Each mode has an implicit device reprovisioning fallback if the device is unable to connect to IoT Hub during identity provisioning due to connectivity errors. For more information, see [IoT Hub device reprovisioning concepts](../iot-dps/concepts-device-reprovision.md).
+
 1. Save and close the file.
 
 1. Apply the configuration changes that you made to IoT Edge.

articles/iot-edge/troubleshoot-common-errors.md

@@ -153,7 +153,7 @@ Or
 ```output
 info: edgelet_docker::runtime -- Starting module edgeHub...
 warn: edgelet_utils::logging -- Could not start module edgeHub
-warn: edgelet_utils::logging -- 	caused by: failed to create endpoint edgeHub on network nat: hnsCall failed in Win32:  
+warn: edgelet_utils::logging --     caused by: failed to create endpoint edgeHub on network nat: hnsCall failed in Win32:  
         The process cannot access the file because it is being used by another process. (0x20)
 ```
 
@@ -317,6 +317,27 @@ Windows Registry Editor Version 5.00
 "TypesSupported"=dword:00000007
 ```
 
+## DPS client error
+
+**Observed behavior:**
+
+IoT Edge fails to start with error message `failed to provision with IoT Hub, and no valid device backup was found dps client error.`
+
+**Root cause:**
+
+A group enrollment is used to provision an IoT Edge device to an IoT Hub. The IoT Edge device is moved to a different hub. The registration is deleted in DPS. A new registration is created in DPS for the new hub. The device is not reprovisioned.
+
+**Resolution:**
+
+1. Verify your DPS credentials are correct.
+1. Apply your configuration using `sudo iotedge apply config`.
+1. If the device isn't reprovisioned, restart the device using `sudo iotedge system restart`.
+1. If the device isn't reprovisioned, force reprovisioning using `sudo iotedge system reprovision`.
+
+To automatically reprovision, set `dynamic_reprovisioning: true` in the device configuration file. Setting this flag to true opts in to the dynamic re-provisioning feature. IoT Edge detects situations where the device appears to have been reprovisioned in the cloud by monitoring its own IoT Hub connection for certain errors. IoT Edge responds by shutting itself and all Edge modules down. The next time the daemon starts up, it will attempt to reprovision this device with Azure to receive the new IoT Hub provisioning information.
+
+When using external provisioning, the daemon will also notify the external provisioning endpoint about the re-provisioning event before shutting down. For more information, see [IoT Hub device reprovisioning concepts](../iot-dps/concepts-device-reprovision.md).
+
 :::moniker-end
 <!-- end 1.1 -->
 
@@ -421,7 +442,7 @@ On Windows:
 
    1. If the parameter exists, set the value of the parameter to **1**.
 
-   1. If the paramter doesn't exist, add it as a new parameter with the following settings:
+   1. If the parameter doesn't exist, add it as a new parameter with the following settings:
 
       | Setting | Value |
       | ------- | ----- |