Merge pull request #204785 from fcabrera23/eflow-gateway

19BMG00 · web-flow · commit 5667376e7fcb · 2022-07-21T20:15:18.000-07:00
Eflow gateway
diff --git a/articles/iot-edge/how-to-create-transparent-gateway.md b/articles/iot-edge/how-to-create-transparent-gateway.md
@@ -47,7 +47,7 @@ For a device to act as a gateway, it needs to securely connect to its downstream
 
 <!-- 1.1 -->
 :::moniker range="iotedge-2018-06"
-A downstream device can be any application or platform that has an identity created with the [Azure IoT Hub](../iot-hub/index.yml) cloud service. These applications often use the [Azure IoT device SDK](../iot-hub/iot-hub-devguide-sdks.md). A downstream device could even be an application running on the IoT Edge gateway device itself. However, an IoT Edge device cannot be downstream of an IoT Edge gateway.
+A downstream device can be any application or platform that has an identity created with the [Azure IoT Hub](../iot-hub/index.yml) cloud service. These applications often use the [Azure IoT device SDK](../iot-hub/iot-hub-devguide-sdks.md). A downstream device could even be an application running on the IoT Edge gateway device itself. However, an IoT Edge device can't be downstream of an IoT Edge gateway.
 :::moniker-end
 <!-- end 1.1 -->
 
@@ -66,9 +66,22 @@ The following steps walk you through the process of creating the certificates an
 
 ## Prerequisites
 
+# [IoT Edge](#tab/iotedge)
+
 A Linux or Windows device with IoT Edge installed.
 
-If you do not have a device ready, you can create one in an Azure virtual machine. Follow the steps in [Deploy your first IoT Edge module to a virtual Linux device](quickstart-linux.md) to create an IoT Hub, create a virtual machine, and configure the IoT Edge runtime.
+If you don't have a device ready, you can create one in an Azure virtual machine. Follow the steps in [Deploy your first IoT Edge module to a virtual Linux device](quickstart-linux.md) to create an IoT Hub, create a virtual machine, and configure the IoT Edge runtime.
+
+# [IoT Edge for Linux on Windows](#tab/eflow)
+
+>[!WARNING]
+> Because the IoT Edge for Linux on Windows (EFLOW) virtual machine needs to be accessible from external devices, ensure to deploy EFLOW with an _external_ virtual switch. For more information about EFLOW networking configurations, see [Networking configuration for Azure IoT Edge for Linux on Windows](./how-to-configure-iot-edge-for-linux-on-windows-networking.md).
+
+A Windows device with IoT Edge for Linux on Windows installed.
+
+If you don't have a device ready, you should create one before continuing with this guide. Follow the steps in [Create and provision an IoT Edge for Linux on Windows device using symmetric keys](./how-to-provision-single-device-linux-on-windows-symmetric.md) to create an IoT Hub, create an EFLOW virtual machine, and configure the IoT Edge runtime.
+
+---
 
 ## Set up the device CA certificate
 
@@ -89,16 +102,69 @@ Have the following files ready:
 
 For production scenarios, you should generate these files with your own certificate authority. For development and test scenarios, you can use demo certificates.
 
+### Create demo certificates
+
 If you don't have your own certificate authority and want to use demo certificates, follow the instructions in [Create demo certificates to test IoT Edge device features](how-to-create-test-certificates.md) to create your files. On that page, you need to take the following steps:
 
-   1. To start, set up the scripts for generating certificates on your device.
-   2. Create a root CA certificate. At the end of those instructions, you'll have a root CA certificate file:
-      * `<path>/certs/azure-iot-test-only.root.ca.cert.pem`.
-   3. Create IoT Edge device CA certificates. At the end of those instructions, you'll have a device CA certificate and its private key:
-      * `<path>/certs/iot-edge-device-ca-<cert name>-full-chain.cert.pem` and
-      * `<path>/private/iot-edge-device-ca-<cert name>.key.pem`
+1. To start, set up the scripts for generating certificates on your device.
+1. Create a root CA certificate. At the end of those instructions, you'll have a root CA certificate file `<path>/certs/azure-iot-test-only.root.ca.cert.pem`.
+1. Create IoT Edge device CA certificates. At the end of those instructions, you'll have a device CA certificate `<path>/certs/iot-edge-device-ca-<cert name>-full-chain.cert.pem` its private key `<path>/private/iot-edge-device-ca-<cert name>.key.pem`.
+
+### Copy certificates to device
+
+# [IoT Edge](#tab/iotedge)
+
+If you created the certificates on a different machine, copy them over to your IoT Edge device then proceed with the next steps. You can use a USB drive, a service like [Azure Key Vault](../key-vault/general/overview.md), or with a function like [Secure file copy](https://www.ssh.com/ssh/scp/). Choose one of these methods that best matches your scenario.
+
+# [IoT Edge for Linux on Windows](#tab/eflow)
+
+Now, you need to copy the certificates to the Azure IoT Edge for Linux on Windows virtual machine.
+
+1. Open an elevated _PowerShell_ session by starting with **Run as Administrator**.
+
+   Connect to the EFLOW virtual machine.
+
+   ```powershell
+   Connect-EflowVm
+   ```
+
+1. Create the certificates directory. You can select any writeable directory. For this tutorial, we'll use the _iotedge-user_ home folder.
+
+   ```bash
+   cd ~
+   mkdir certs
+   cd certs
+   mkdir certs
+   mkdir private
+   ```
+
+1. Exit the EFLOW VM connection.
+
+   ```bash
+   exit
+   ```
+
+1. Copy the certificates to the EFLOW virtual machine.
 
-If you created the certificates on a different machine, copy them over to your IoT Edge device then proceed with the next steps.
+   ```powershell
+   # Copy the IoT Edge device CA certificates
+   Copy-EflowVMFile -fromFile <path>\certs\iot-edge-device-ca-<cert name>-full-chain.cert.pem -toFile /home/iotedge-user/certs/certs/iot-edge-device-ca-<cert name>-full-chain.cert.pem -pushFile
+   Copy-EflowVMFile -fromFile <path>\private\iot-edge-device-ca-<cert name>.key.pem -toFile /home/iotedge-user/certs/private/iot-edge-device-ca-<cert name>.key.pem -pushFile
+
+   # Copy the root CA certificate
+   Copy-EflowVMFile -fromFile <path>\certs\azure-iot-test-only.root.ca.cert.pem -toFile /home/iotedge-user/certs/certs/azure-iot-test-only.root.ca.cert.pem -pushFile
+   ```
+
+1. Invoke the following commands on the EFLOW VM to grant iotedge permissions to the certificate files since `Copy-EflowVMFile` copies files with root only access permissions.
+
+   ```powershell
+   Invoke-EflowVmCommand "sudo chown -R iotedge /home/iotedge-user/certs/"
+   Invoke-EflowVmCommand "sudo chmod 0644 /home/iotedge-user/certs/"  
+   ```
+
+----
+
+### Configure certificates on device
 
 <!-- 1.1 -->
 :::moniker range="iotedge-2018-06"
@@ -107,26 +173,32 @@ If you created the certificates on a different machine, copy them over to your I
 
    * Windows: `C:\ProgramData\iotedge\config.yaml`
    * Linux: `/etc/iotedge/config.yaml`
+   * IoT Edge for Linux on Windows: `/etc/iotedge/config.yaml`
+
+    >[!TIP]
+    > If you are using IoT Edge for Linux on Windows (EFLOW) you'll have to connect to the EFLOW virtual machine and change the file inside the VM. You can connect to the EFLOW VM using the PowerShell cmdlet `Connect-EflowVm` and then use your preferred editor.
 
 1. Find the **Certificate settings** section of the file. Uncomment the four lines starting with **certificates:** and provide the file URIs to your three files as values for the following properties:
    * **device_ca_cert**: device CA certificate
    * **device_ca_pk**: device CA private key
    * **trusted_ca_certs**: root CA certificate
 
-   Make sure there is no preceding whitespace on the **certificates:** line, and that the other lines are indented by two spaces.
+   Make sure there's no preceding whitespace on the **certificates:** line, and that the other lines are indented by two spaces.
 
 1. Save and close the file.
 
 1. Restart IoT Edge.
    * Windows: `Restart-Service iotedge`
    * Linux: `sudo systemctl restart iotedge`
+   * IoT Edge for Linux on Windows: `sudo systemctl restart iotedge`
+
 :::moniker-end
 <!-- end 1.1 -->
 
 <!-- iotedge-2020-11 -->
 :::moniker range=">=iotedge-2020-11"
 
-1. On your IoT Edge device, open the config file: `/etc/aziot/config.toml`
+1. On your IoT Edge device, open the config file: `/etc/aziot/config.toml`. If you're using IoT Edge for Linux on Windows, you'll have to connect to the EFLOW virtual machine using the `Connect-EflowVm` PowerShell cmdlet.
 
    >[!TIP]
    >If the config file doesn't exist on your device yet, then use `/etc/aziot/config.toml.edge.template` as a template to create one.
@@ -194,14 +266,43 @@ To deploy the IoT Edge hub module and configure it with routes to handle incomin
 
 Standard IoT Edge devices don't need any inbound connectivity to function, because all communication with IoT Hub is done through outbound connections. Gateway devices are different because they need to receive messages from their downstream devices. If a firewall is between the downstream devices and the gateway device, then communication needs to be possible through the firewall as well.
 
-For a gateway scenario to work, at least one of the IoT Edge hub's supported protocols must be open for inbound traffic from downstream devices. The supported protocols are MQTT, AMQP, HTTPS, MQTT over WebSockets, and AMQP over WebSockets.
+# [IoT Edge](#tab/iotedge)
+
+For a gateway scenario to work, at least one of the IoT Edge Hub's supported protocols must be open for inbound traffic from downstream devices. The supported protocols are MQTT, AMQP, HTTPS, MQTT over WebSockets, and AMQP over WebSockets.
 
 | Port | Protocol |
 | ---- | -------- |
 | 8883 | MQTT |
 | 5671 | AMQP |
 | 443 | HTTPS <br> MQTT+WS <br> AMQP+WS |
 
+# [IoT Edge for Linux on Windows](#tab/eflow)
+
+For a gateway scenario to work, at least one of the IoT Edge Hub's supported protocols must be open for inbound traffic from downstream devices. The supported protocols are MQTT, AMQP, HTTPS, MQTT over WebSockets, and AMQP over WebSockets.
+
+| Port | Protocol |
+| ---- | -------- |
+| 8883 | MQTT |
+| 5671 | AMQP |
+| 443 | HTTPS <br> MQTT+WS <br> AMQP+WS |
+
+Finally, you must open the EFLOW virtual machine ports. You can open the three ports mentioned above using the following PowerShell cmdlets.
+
+   ```powershell
+   # Open MQTT port
+   Invoke-EflowVmCommand "sudo iptables -A INPUT -p tcp --dport 8883 -j ACCEPT"
+
+   # Open AMQP port
+   Invoke-EflowVmCommand "sudo iptables -A INPUT -p tcp --dport 5671 -j ACCEPT"
+
+   # Open HTTPS/MQTT+WS/AMQP+WS port
+   Invoke-EflowVmCommand "sudo iptables -A INPUT -p tcp --dport 443 -j ACCEPT"
+
+   # Save the iptables rules
+   Invoke-EflowVmCommand "sudo iptables-save | sudo tee /etc/systemd/scripts/ip4save"
+   ```
+---
+
 ## Next steps
 
 Now that you have an IoT Edge device set up as a transparent gateway, you need to configure your downstream devices to trust the gateway and send messages to it. Continue on to [Authenticate a downstream device to Azure IoT Hub](how-to-authenticate-downstream-device.md) for the next steps in setting up your transparent gateway scenario.
