Merge pull request #227700 from w-azure/winona-proxy

Updates based on support team feedback

Author: American-Dipper

articles/iot-edge/how-to-configure-proxy-support.md

@@ -14,15 +14,15 @@ ms.custom: [amqp, contperf-fy21q1]
 
 [!INCLUDE [iot-edge-version-1.4](includes/iot-edge-version-1.4.md)]
 
-IoT Edge devices send HTTPS requests to communicate with IoT Hub. If your device is connected to a network that uses a proxy server, you need to configure the IoT Edge runtime to communicate through the server. Proxy servers can also affect individual IoT Edge modules if they make HTTP or HTTPS requests that aren't routed through the IoT Edge hub.
+IoT Edge devices send HTTPS requests to communicate with IoT Hub. If you connected your device to a network that uses a proxy server, you need to configure the IoT Edge runtime to communicate through the server. Proxy servers can also affect individual IoT Edge modules if they make HTTP or HTTPS requests that you haven't routed through the IoT Edge hub.
 
 This article walks through the following four steps to configure and then manage an IoT Edge device behind a proxy server:
 
 1. [**Install the IoT Edge runtime on your device**](#install-iot-edge-through-a-proxy)
 
    The IoT Edge installation scripts pull packages and files from the internet, so your device needs to communicate through the proxy server to make those requests. For Windows devices, the installation script also provides an offline installation option.
 
-   This step is a one-time process to configure the IoT Edge device when you first set it up. The same connections are also required when you update the IoT Edge runtime.
+   This step is a one-time process to configure the IoT Edge device when you first set it up. You also need these same connections when you update the IoT Edge runtime.
 
 2. [**Configure IoT Edge and the container runtime on your device**](#configure-iot-edge-and-moby)
 
@@ -32,13 +32,13 @@ This article walks through the following four steps to configure and then manage
 
 3. [**Configure the IoT Edge agent properties in the config file on your device**](#configure-the-iot-edge-agent)
 
-   The IoT Edge daemon starts the edgeAgent module initially. Then, the edgeAgent module retrieves the deployment manifest from IoT Hub and starts all the other modules. For the IoT Edge agent to make the initial connection to IoT Hub, configure the edgeAgent module environment variables manually on the device itself. After the initial connection, you can configure the edgeAgent module remotely.
+   The IoT Edge daemon starts the edgeAgent module initially. Then, the edgeAgent module retrieves the deployment manifest from IoT Hub and starts all the other modules. Configure the edgeAgent module environment variables manually on the device itself, so that the IoT Edge agent can make the initial connection to IoT Hub. After the initial connection, you can configure the edgeAgent module remotely.
 
    This step is a one-time process to configure the IoT Edge device when you first set it up.
 
 4. [**For all future module deployments, set environment variables for any module communicating through the proxy**](#configure-deployment-manifests)
 
-   Once your IoT Edge device is set up and connected to IoT Hub through the proxy server, you need to maintain the connection in all future module deployments.
+   Once you set up and connect an IoT Edge device to IoT Hub through the proxy server, you need to maintain the connection in all future module deployments.
 
    This step is an ongoing process done remotely so that every new module or deployment update maintains the device's ability to communicate through the proxy server.
 
@@ -60,11 +60,11 @@ Whether your IoT Edge device runs on Windows or Linux, you need to access the in
 
 ### Linux devices
 
-If you're installing the IoT Edge runtime on a Linux device, configure the package manager to go through your proxy server to access the installation package. For example, [Set up apt-get to use a http-proxy](https://help.ubuntu.com/community/AptGet/Howto/#Setting_up_apt-get_to_use_a_http-proxy). Once your package manager is configured, follow the instructions in [Install Azure IoT Edge runtime](how-to-provision-single-device-linux-symmetric.md) as usual.
+If you're installing the IoT Edge runtime on a Linux device, configure the package manager to go through your proxy server to access the installation package. For example, [Set up apt-get to use a http-proxy](https://help.ubuntu.com/community/AptGet/Howto/#Setting_up_apt-get_to_use_a_http-proxy). Once you configure your package manager, follow the instructions in [Install Azure IoT Edge runtime](how-to-provision-single-device-linux-symmetric.md) as usual.
 
 ### Windows devices using IoT Edge for Linux on Windows
 
-If you're installing the IoT Edge runtime using IoT Edge for Linux on Windows, IoT Edge is installed by default on your Linux virtual machine. No additional installation or update steps are required.
+If you're installing the IoT Edge runtime using IoT Edge for Linux on Windows, IoT Edge is installed by default on your Linux virtual machine. You're not required to install or update any other steps.
 
 ### Windows devices using Windows containers
 
@@ -84,7 +84,7 @@ The following steps demonstrate an example of a windows installation using the `
    . {Invoke-WebRequest -proxy <proxy URL> -useb aka.ms/iotedge-win} | Invoke-Expression; Initialize-IoTEdge
    ```
 
-If you have complicated credentials for the proxy server that can't be included in the URL, use the `-ProxyCredential` parameter within `-InvokeWebRequestParameters`. For example,
+If you have complicated credentials for the proxy server that you can't include in the URL, use the `-ProxyCredential` parameter within `-InvokeWebRequestParameters`. For example,
 
 ```powershell
 $proxyCredential = (Get-Credential).GetNetworkCredential()
@@ -98,7 +98,7 @@ For more information about proxy parameters, see [Invoke-WebRequest](/powershell
 
 IoT Edge relies on two daemons running on the IoT Edge device. The Moby daemon makes web requests to pull container images from container registries. The IoT Edge daemon makes web requests to communicate with IoT Hub.
 
-Both the Moby and the IoT Edge daemons need to be configured to use the proxy server for ongoing device functionality. This step takes place on the IoT Edge device during initial device setup.
+You must configure both the Moby and the IoT Edge daemons to use the proxy server for ongoing device functionality. This step takes place on the IoT Edge device during initial device setup.
 
 ### Moby daemon
 
@@ -113,13 +113,12 @@ Choose the article that applies to your IoT Edge device operating system:
 
 ### IoT Edge daemon
 
-The IoT Edge daemon is configured in a similar manner to the Moby daemon. Use the following steps to set an environment variable for the service, based on your operating system.
+The IoT Edge daemon is similar to the Moby daemon. Use the following steps to set an environment variable for the service, based on your operating system.
 
 The IoT Edge daemon always uses HTTPS to send requests to IoT Hub.
 
 #### Linux
 
-
 Open an editor in the terminal to configure the IoT Edge daemon.
 
 ```bash
@@ -158,7 +157,7 @@ Restart the IoT Edge system services for the changes to both daemons to take eff
 sudo iotedge system restart
 ```
 
-Verify that your environment variables were created, and the new configuration was loaded.
+Verify that your environment variables and the new configuration are present.
 
 ```bash
 systemctl show --property=Environment aziot-edged
@@ -167,13 +166,13 @@ systemctl show --property=Environment aziot-identityd
 
 #### Windows using IoT Edge for Linux on Windows
 
-Log in to your IoT Edge for Linux on Windows virtual machine:
+Sign in to your IoT Edge for Linux on Windows virtual machine:
 
 ```powershell
 Connect-EflowVm
 ```
 
-Follow the same steps as the Linux section above to configure the IoT Edge daemon.
+Follow the same steps as the Linux section of this article to configure the IoT Edge daemon.
 
 #### Windows using Windows containers
 
@@ -191,13 +190,13 @@ Restart-Service iotedge
 
 ## Configure the IoT Edge agent
 
-The IoT Edge agent is the first module to start on any IoT Edge device. It's started for the first time based on the information in the IoT Edge config file. The IoT Edge agent then connects to IoT Hub to retrieve deployment manifests, which declare what other modules should be deployed on the device.
+The IoT Edge agent is the first module to start on any IoT Edge device. This module starts for the first time based on information in the IoT Edge config file. The IoT Edge agent then connects to IoT Hub to retrieve deployment manifests. The manifest declares which other modules the device should deploy.
 
 This step takes place once on the IoT Edge device during initial device setup.
 
-1. Open the config file on your IoT Edge device: `/etc/aziot/config.toml`. The configuration file is protected, so you need administrative privileges to access it. On Linux systems, use the `sudo` command before opening the file in your preferred text editor.
+1. Open the config file on your IoT Edge device: `/etc/aziot/config.toml`. You need administrative privileges to access the configuration file. On Linux systems, use the `sudo` command before opening the file in your preferred text editor.
 
-2. In the config file, find the `[agent]` section, which contains all the configuration information for the edgeAgent module to use on startup. Check and make sure that the `[agent]`section is uncommented or add it if it is not included in the `config.toml`. The IoT Edge agent definition includes an `[agent.env]` subsection where you can add environment variables.
+2. In the config file, find the `[agent]` section, which contains all the configuration information for the edgeAgent module to use on startup. Check to make sure the `[agent]` section is without comments. If the `[agent]` section is missing, add it to the `config.toml`. The IoT Edge agent definition includes an `[agent.env]` subsection where you can add environment variables.
 
 3. Add the **https_proxy** parameter to the environment variables section, and set your proxy URL as its value.
 
@@ -261,17 +260,17 @@ This step takes place once on the IoT Edge device during initial device setup.
    sudo iotedge config apply
    ```
 
-6. Verify that your proxy settings are propagated using `docker inspect edgeAgent` in the `Env` section. If not, the container must be recreated.
+6. Verify that your proxy settings are propagated using `docker inspect edgeAgent` in the `Env` section. If not, you must recreate the container.
 
    ```bash
    sudo docker rm -f edgeAgent
    ```
 
-7. The IoT Edge runtime should recreate `edgeAgent` within a minute. Once `edgeAgent` container is running again, `docker inspect edgeAgent` and verify the proxy settings matches the configuration file. 
+7. The IoT Edge runtime should recreate `edgeAgent` within a minute. Once the `edgeAgent` container is running again, use the `docker inspect edgeAgent` command to verify that the proxy settings match the configuration file. 
 
 ## Configure deployment manifests  
 
-Once your IoT Edge device is configured to work with your proxy server, you need to continue to declare the HTTPS_PROXY environment variable in future deployment manifests. You can edit deployment manifests either using the Azure portal wizard or by editing a deployment manifest JSON file.
+Once you configure your IoT Edge device to work with your proxy server, declare the HTTPS_PROXY environment variable in future deployment manifests. You can edit deployment manifests either using the Azure portal wizard or by editing a deployment manifest JSON file.
 
 Always configure the two runtime modules, edgeAgent and edgeHub, to communicate through the proxy server so they can maintain a connection with IoT Hub. If you remove the proxy information from the edgeAgent module, the only way to reestablish connection is by editing the config file on the device, as described in the previous section.
 
@@ -291,11 +290,11 @@ Add the **https_proxy** environment variable to both the IoT Edge agent and IoT
 
 ![Set https_proxy environment variable](./media/how-to-configure-proxy-support/edgehub-environmentvar.png)
 
-All other modules that you add to a deployment manifest follow the same pattern.
+All other modules that you add to a deployment manifest follow the same pattern. Select **Apply** to save your changes.
 
 ### JSON deployment manifest files
 
-If you create deployments for IoT Edge devices using the templates in Visual Studio Code or by manually creating JSON files, you can add the environment variables directly to each module definition.
+If you create deployments for IoT Edge devices using the templates in Visual Studio Code or by manually creating JSON files, you can add the environment variables directly to each module definition. If you didn't add them in the Azure portal, add them here to your JSON manifest file. Replace `<proxy URL>` with your own value.
 
 Use the following JSON format:
 
@@ -313,7 +312,7 @@ With the environment variables included, your module definition should look like
 "edgeHub": {
     "type": "docker",
     "settings": {
-        "image": "mcr.microsoft.com/azureiotedge-hub:1.1",
+        "image": "mcr.microsoft.com/azureiotedge-hub:1.4",
         "createOptions": "{}"
     },
     "env": {
@@ -341,9 +340,9 @@ If you included the **UpstreamProtocol** environment variable in the confige.yam
 
 ## Working with traffic-inspecting proxies
 
-Some proxies like [Zscaler](https://www.zscaler.com) can inspect TLS-encrypted traffic. During TLS traffic inspection, the certificate returned by the proxy isn't the certificate from the target server, but instead is the certificate signed by the proxy's own root certificate. By default, this proxy's certificate isn't trusted by IoT Edge modules (including *edgeAgent* and *edgeHub*), and the TLS handshake fails.
+Some proxies like [Zscaler](https://www.zscaler.com) can inspect TLS-encrypted traffic. During TLS traffic inspection, the certificate returned by the proxy isn't the certificate from the target server, but instead is the certificate signed by the proxy's own root certificate. By default, IoT Edge modules (including *edgeAgent* and *edgeHub*) don't trust this proxy's certificate and the TLS handshake fails.
 
-To resolve this, the proxy's root certificate needs to be trusted by both the operating system and IoT Edge modules.
+To resolve the failed handshake, configure both the operating system and IoT Edge modules to trust the proxy's root certificate with the following steps.
 
 1. Configure proxy certificate in the trusted root certificate store of your host operating system. For more information about how to install a root certificate, see [Install root CA to OS certificate store](how-to-manage-device-certificates.md#install-root-ca-to-os-certificate-store).
 
@@ -353,7 +352,7 @@ To configure traffic inspection proxy support for containers not managed by IoT
 
 ## Fully qualified domain names (FQDNs) of destinations that IoT Edge communicates with
 
-If your proxy has a firewall that requires you to allowlist all FQDNs for internet connectivity, review the list from [Allow connections from IoT Edge devices](production-checklist.md#allow-connections-from-iot-edge-devices) to determine which FQDNs to add.
+If your proxy's firewall requires you to add all FQDNs to your allowlist for internet connectivity, review the list from [Allow connections from IoT Edge devices](production-checklist.md#allow-connections-from-iot-edge-devices) to determine which FQDNs to add.
 
 ## Next steps