Skip to content

Commit cf690e7

Browse files
kgrembankgremban
committed
Fixed links; added disappearing modules common error
1 parent b147724 commit cf690e7

File tree

4 files changed

+108
-93
lines changed

4 files changed

+108
-93
lines changed

‎articles/iot-edge/offline-capabilities.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -103,7 +103,7 @@ One way to create this trust relationship is described in detail in the followin
103103

104104
## Specify DNS servers
105105

106-
To improve robustness, it is highly recommended you specify the DNS server addresses used in your environment. To set your DNS server for IoT Edge, see the resolution for [Edge Agent module continually reports 'empty config file' and no modules start on device](troubleshoot.md#edge-agent-module-continually-reports-empty-config-file-and-no-modules-start-on-the-device) in the troubleshooting article.
106+
To improve robustness, it is highly recommended you specify the DNS server addresses used in your environment. To set your DNS server for IoT Edge, see the resolution for [Edge Agent module continually reports 'empty config file' and no modules start on device](troubleshoot-common-errors.md#edge-agent-module-reports-empty-config-file-and-no-modules-start-on-the-device) in the troubleshooting article.
107107

108108
## Optional offline settings
109109

‎articles/iot-edge/production-checklist.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -100,7 +100,7 @@ The IoT Edge hub is optimized for performance by default, so it attempts to allo
100100

101101
When **OptimizeForPerformance** is set to **true**, the MQTT protocol head uses the PooledByteBufferAllocator, which has better performance but allocates more memory. The allocator does not work well on 32-bit operating systems or on devices with low memory. Additionally, when optimized for performance, RocksDb allocates more memory for its role as the local storage provider.
102102

103-
For more information, see [Stability issues on resource constrained devices](troubleshoot.md#stability-issues-on-resource-constrained-devices).
103+
For more information, see [Stability issues on smaller devices](troubleshoot-common-errors.md#stability-issues-on-smaller-devices).
104104

105105
#### Disable unused protocols
106106

@@ -193,7 +193,7 @@ Next, be sure to update the image references in the deployment.template.json fil
193193

194194
### Review outbound/inbound configuration
195195

196-
Communication channels between Azure IoT Hub and IoT Edge are always configured to be outbound. For most IoT Edge scenarios, only three connections are necessary. The container engine needs to connect with the container registry (or registries) that holds the module images. The IoT Edge runtime needs to connect with IoT Hub to retrieve device configuration information, and to send messages and telemetry. And if you use automatic provisioning, the IoT Edge daemon needs to connect to the Device Provisioning Service. For more information, see [Firewall and port configuration rules](troubleshoot.md#firewall-and-port-configuration-rules-for-iot-edge-deployment).
196+
Communication channels between Azure IoT Hub and IoT Edge are always configured to be outbound. For most IoT Edge scenarios, only three connections are necessary. The container engine needs to connect with the container registry (or registries) that holds the module images. The IoT Edge runtime needs to connect with IoT Hub to retrieve device configuration information, and to send messages and telemetry. And if you use automatic provisioning, the IoT Edge daemon needs to connect to the Device Provisioning Service. For more information, see [Firewall and port configuration rules](troubleshoot.md#check-your-firewall-and-port-configuration-rules).
197197

198198
### Allow connections from IoT Edge devices
199199

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

Lines changed: 104 additions & 87 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,76 @@ The IoT Edge runtime sets up a network for each of the modules to communicate on
4040

4141
Ensure that there is a route to the internet for the IP addresses assigned to this bridge/NAT network. Sometimes a VPN configuration on the host overrides the IoT Edge network.
4242

43+
## IoT Edge agent can't access a module's image (403)
44+
45+
**Observed behavior:**
46+
47+
A container fails to run, and the edgeAgent logs show a 403 error.
48+
49+
**Root cause:**
50+
51+
The IoT Edge agent doesn't have permissions to access a module's image.
52+
53+
**Resolution:**
54+
55+
Make sure that your registry credentials are correctly specified in your deployment manifest.
56+
57+
## Edge Agent module reports 'empty config file' and no modules start on the device
58+
59+
**Observed behavior:**
60+
61+
The device has trouble starting modules defined in the deployment. Only the edgeAgent is running but continually reporting 'empty config file...'.
62+
63+
**Root cause:**
64+
65+
By default, IoT Edge starts modules in their own isolated container network. The device may be having trouble with DNS name resolution within this private network.
66+
67+
**Resolution:**
68+
69+
**Option 1: Set DNS server in container engine settings**
70+
71+
Specify the DNS server for your environment in the container engine settings, which will apply to all container modules started by the engine. Create a file named `daemon.json` specifying the DNS server to use. For example:
72+
73+
```json
74+
{
75+
"dns": ["1.1.1.1"]
76+
}
77+
```
78+
79+
The above example sets the DNS server to a publicly accessible DNS service. If the edge device cannot access this IP from its environment, replace it with DNS server address that is accessible.
80+
81+
Place `daemon.json` in the right location for your platform:
82+
83+
| Platform | Location |
84+
| --------- | -------- |
85+
| Linux | `/etc/docker` |
86+
| Windows host with Windows containers | `C:\ProgramData\iotedge-moby\config` |
87+
88+
If the location already contains `daemon.json` file, add the **dns** key to it and save the file.
89+
90+
Restart the container engine for the updates to take effect.
91+
92+
| Platform | Command |
93+
| --------- | -------- |
94+
| Linux | `sudo systemctl restart docker` |
95+
| Windows (Admin Powershell) | `Restart-Service iotedge-moby -Force` |
96+
97+
**Option 2: Set DNS server in IoT Edge deployment per module**
98+
99+
You can set DNS server for each module's *createOptions* in the IoT Edge deployment. For example:
100+
101+
```json
102+
"createOptions": {
103+
"HostConfig": {
104+
"Dns": [
105+
"x.x.x.x"
106+
]
107+
}
108+
}
109+
```
110+
111+
Be sure to set this configuration for the *edgeAgent* and *edgeHub* modules as well.
112+
43113
## IoT Edge hub fails to start
44114

45115
**Observed behavior:**
@@ -121,23 +191,11 @@ In the deployment.json file:
121191

122192
4. Save the file and apply it to your IoT Edge device again.
123193

124-
## IoT Edge agent can't access a module's image (403)
125-
126-
A container fails to run, and the edgeAgent logs show a 403 error.
127-
128-
**Root cause:**
129-
130-
The IoT Edge agent doesn't have permissions to access a module's image.
131-
132-
**Resolution:**
133-
134-
Make sure that your registry credentials are correctly specified in your deployment manifest
135-
136194
## IoT Edge security daemon fails with an invalid hostname
137195

138196
**Observed behavior:**
139197

140-
The command `sudo journalctl -u iotedge` fails and prints the following message:
198+
Attempting to [check the IoT Edge security manager logs](troubleshoot.md#check-the-status-of-the-iot-edge-security-manager-and-its-logs) fails and prints the following message:
141199

142200
```output
143201
Error parsing user input data: invalid hostname. Hostname cannot be empty or greater than 64 characters
@@ -172,11 +230,34 @@ When you see this error, you can resolve it by configuring the DNS name of your
172230
notepad C:\ProgramData\iotedge\config.yaml
173231
```
174232

233+
## Can't get the IoT Edge daemon logs on Windows
234+
235+
**Observed behavior:**
236+
237+
You get an EventLogException when using `Get-WinEvent` on Windows.
238+
239+
**Root cause:**
240+
241+
The `Get-WinEvent` PowerShell command relies on a registry entry to be present to find logs by a specific `ProviderName`.
242+
243+
**Resolution:**
244+
245+
Set a registry entry for the IoT Edge daemon. Create a **iotedge.reg** file with the following content, and import in to the Windows Registry by double-clicking it or using the `reg import iotedge.reg` command:
246+
247+
```reg
248+
Windows Registry Editor Version 5.00
249+
250+
[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\EventLog\Application\iotedged]
251+
"CustomSource"=dword:00000001
252+
"EventMessageFile"="C:\\ProgramData\\iotedge\\iotedged.exe"
253+
"TypesSupported"=dword:00000007
254+
```
255+
175256
## Stability issues on smaller devices
176257

177258
**Observed behavior:**
178259

179-
You may encounter stability problems on constrained devices like the Raspberry Pi, especially when used as a gateway. Symptoms include out of memory exceptions in the edge hub module, downstream devices cannot connect or the device stops sending telemetry messages after a few hours.
260+
You may encounter stability problems on resource constrained devices like the Raspberry Pi, especially when used as a gateway. Symptoms include out of memory exceptions in the IoT Edge hub module, downstream devices failing to connect, or the device failing to send telemetry messages after a few hours.
180261

181262
**Root cause:**
182263

@@ -206,37 +287,13 @@ In the deployment manifest:
206287
"value": "false"
207288
}
208289
},
209-
...
210-
```
211-
212-
## Can't get the IoT Edge daemon logs on Windows
213-
214-
**Observed behavior:**
215-
216-
If you get an EventLogException when using `Get-WinEvent` on Windows, check your registry entries.
217-
218-
**Root cause:**
219-
220-
The `Get-WinEvent` PowerShell command relies on a registry entry to be present to find logs by a specific `ProviderName`.
221-
222-
**Resolution:**
223-
224-
Set a registry entry for the IoT Edge daemon. Create a **iotedge.reg** file with the following content, and import in to the Windows Registry by double-clicking it or using the `reg import iotedge.reg` command:
225-
226-
```reg
227-
Windows Registry Editor Version 5.00
228-
229-
[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\EventLog\Application\iotedged]
230-
"CustomSource"=dword:00000001
231-
"EventMessageFile"="C:\\ProgramData\\iotedge\\iotedged.exe"
232-
"TypesSupported"=dword:00000007
233290
```
234291
235-
## IoT Edge module fails to send a message to the edgeHub with 404 error
292+
## IoT Edge module fails to send a message to edgeHub with 404 error
236293
237294
**Observed behavior:**
238295
239-
A custom IoT Edge module fails to send a message to the edgeHub with a 404 `Module not found` error. The IoT Edge daemon prints the following message to the logs:
296+
A custom IoT Edge module fails to send a message to the IoT Edge hub with a 404 `Module not found` error. The IoT Edge daemon prints the following message to the logs:
240297
241298
```output
242299
Error: Time:Thu Jun 4 19:44:58 2018 File:/usr/sdk/src/c/provisioning_client/adapters/hsm_client_http_edge.c Func:on_edge_hsm_http_recv Line:364 executing HTTP request fails, status=404, response_buffer={"message":"Module not found"}u, 04 )
@@ -248,65 +305,25 @@ The IoT Edge daemon enforces process identification for all modules connecting t
248305
249306
**Resolution:**
250307
251-
As of version 1.0.7, all module processes are authorized to connect. If upgrading to 1.0.7 isn't possible, complete the following steps. For more information, see the [1.0.7 release changelog](https://github.com/Azure/iotedge/blob/master/CHANGELOG.md#iotedged-1).
308+
As of version 1.0.7, all module processes are authorized to connect. For more information, see the [1.0.7 release changelog](https://github.com/Azure/iotedge/blob/master/CHANGELOG.md#iotedged-1).
252309
253-
Make sure that the same process ID is always used by the custom IoT Edge module to send messages to the edgeHub. For instance, make sure to `ENTRYPOINT` instead of `CMD` command in your Docker file, since `CMD` will lead to one process ID for the module and another process ID for the bash command running the main program whereas `ENTRYPOINT` will lead to a single process ID.
310+
If upgrading to 1.0.7 isn't possible, complete the following steps. Make sure that the same process ID is always used by the custom IoT Edge module to send messages to the edgeHub. For instance, make sure to `ENTRYPOINT` instead of `CMD` command in your Docker file, since `CMD` will lead to one process ID for the module and another process ID for the bash command running the main program whereas `ENTRYPOINT` will lead to a single process ID.
254311
255-
## Edge Agent module continually reports 'empty config file' and no modules start on the device
312+
## IoT Edge module deploys successfully then disappears from device
256313
257314
**Observed behavior:**
258315
259-
The device has trouble starting modules defined in the deployment. Only the edgeAgent is running but continually reporting 'empty config file...'.
316+
After setting modules for an IoT Edge device, the modules are deployed successfully but after a few minutes they disappear from the device and from the device details in the Azure portal. Perhaps other modules than the ones defined appear on the device.
260317
261318
**Root cause:**
262319
263-
By default, IoT Edge starts modules in their own isolated container network. The device may be having trouble with DNS name resolution within this private network.
320+
If an automatic deployment targets a device, it takes priority over manually setting the modules for a single device. The **Set modules** functionality in Azure portal or **Create deployment for single device** functionality in Visual Studio Code will take effect for a moment. You see the modules that you defined start on the device. Then the automatic deployment's priority kicks in and overwrites the device's desired properties.
264321
265322
**Resolution:**
266323
267-
**Option 1: Set DNS server in container engine settings**
324+
Only use one type of deployment mechanism per device, either an automatic deployment or individual device deployments. If you have multiple automatic deployments targeting a device, you can change priority or target descriptions to make sure the correct one applies to a given device. If the automatic deployment targets tags in the device twin, you can update the device twin to no longer match the target description.
268325
269-
Specify the DNS server for your environment in the container engine settings, which will apply to all container modules started by the engine. Create a file named `daemon.json` specifying the DNS server to use. For example:
270-
271-
```json
272-
{
273-
"dns": ["1.1.1.1"]
274-
}
275-
```
276-
277-
The above example sets the DNS server to a publicly accessible DNS service. If the edge device cannot access this IP from its environment, replace it with DNS server address that is accessible.
278-
279-
Place `daemon.json` in the right location for your platform:
280-
281-
| Platform | Location |
282-
| --------- | -------- |
283-
| Linux | `/etc/docker` |
284-
| Windows host with Windows containers | `C:\ProgramData\iotedge-moby\config` |
285-
286-
If the location already contains `daemon.json` file, add the **dns** key to it and save the file.
287-
288-
Restart the container engine for the updates to take effect.
289-
290-
| Platform | Command |
291-
| --------- | -------- |
292-
| Linux | `sudo systemctl restart docker` |
293-
| Windows (Admin Powershell) | `Restart-Service iotedge-moby -Force` |
294-
295-
**Option 2: Set DNS server in IoT Edge deployment per module**
296-
297-
You can set DNS server for each module's *createOptions* in the IoT Edge deployment. For example:
298-
299-
```json
300-
"createOptions": {
301-
"HostConfig": {
302-
"Dns": [
303-
"x.x.x.x"
304-
]
305-
}
306-
}
307-
```
308-
309-
Be sure to set this configuration for the *edgeAgent* and *edgeHub* modules as well.
326+
For more information, see [Understand IoT Edge automatic deployments for single devices or at scale](module-deployment-monitoring.md).
310327
311328
## Next steps
312329

‎articles/iot-edge/troubleshoot.md

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -63,9 +63,7 @@ iotedge support-bundle --since 6h
6363
6464
## Check your IoT Edge version
6565

66-
If you're running an older version of IoT Edge, then upgrading may resolve your issue. The `iotedge check` tool checks that the IoT Edge security daemon is the latest version, but does not check the versions of the IoT Edge hub and agent modules.
67-
68-
To check the version of the runtime modules on your device, use the commands `iotedge logs edgeAgent` and `iotedge logs edgeHub`. The version number is declared in the logs when the module starts up.
66+
If you're running an older version of IoT Edge, then upgrading may resolve your issue. The `iotedge check` tool checks that the IoT Edge security daemon is the latest version, but does not check the versions of the IoT Edge hub and agent modules. To check the version of the runtime modules on your device, use the commands `iotedge logs edgeAgent` and `iotedge logs edgeHub`. The version number is declared in the logs when the module starts up.
6967

7068
For instructions on how to update your device, see [Update the IoT Edge security daemon and runtime](how-to-update-iot-edge.md).
7169

0 commit comments

Comments
 (0)