Quickstart: Enable SSH and RDP over an IoT Hub device stream by using a C proxy application (preview)

Azure IoT Hub currently supports device streams as a preview feature.

IoT Hub device streams allow service and device applications to communicate in a secure and firewall-friendly manner. For an overview of the setup, see the Local Proxy Sample page.

This quickstart describes the setup for tunneling Secure Shell (SSH) traffic (using port 22) through device streams. The setup for Remote Desktop Protocol (RDP) traffic is similar and requires a simple configuration change. Because device streams are application- and protocol-agnostic, you can modify this quickstart to accommodate other types of application traffic.

How it works

The following figure illustrates how the device- and service-local proxy programs enable end-to-end connectivity between the SSH client and SSH daemon processes. During public preview, the C SDK supports device streams on the device side only. As a result, this quickstart covers instructions to run only the device-local proxy application. You should run one of the following service-side quickstarts:

Local proxy setup

  1. The service-local proxy connects to the IoT hub and starts a device stream to the target device.

  2. The device-local proxy completes the stream initiation handshake and establishes an end-to-end streaming tunnel through the IoT hub's streaming endpoint to the service side.

  3. The device-local proxy connects to the SSH daemon that's listening on port 22 on the device. This setting is configurable, as described in the "Run the device-local proxy application" section.

  4. The service-local proxy waits for new SSH connections from a user by listening on a designated port, which in this case is port 2222. This setting is configurable, as described in the "Run the device-local proxy application" section. When the user connects via SSH client, the tunnel enables SSH application traffic to be transferred between the SSH client and server programs.

Note

SSH traffic that's sent over a device stream is tunneled through the IoT hub's streaming endpoint rather than sent directly between service and device. For more information, see the benefits of using Iot Hub device streams. Furthermore, the figure illustrates the SSH daemon that's running on the same device (or machine) as the device-local proxy. In this quickstart, providing the SSH daemon IP address allows the device-local proxy and the daemon to run on different machines as well.

Use Azure Cloud Shell

Azure hosts Azure Cloud Shell, an interactive shell environment that you can use through your browser. Cloud Shell lets you use either bash or PowerShell to work with Azure services. You can use the Cloud Shell pre-installed commands to run the code in this article without having to install anything on your local environment.

To launch Azure Cloud Shell:

Option Example/Link
Select Try It in the upper-right corner of a code block. Selecting Try It doesn't automatically copy the code to Cloud Shell. Example of Try It for Azure Cloud Shell
Go to https://shell.azure.com or select the Launch Cloud Shell button to open Cloud Shell in your browser.
Select the Cloud Shell button on the top-right menu bar in the Azure portal. Cloud Shell button in the Azure portal

To run the code in this article in Azure Cloud Shell:

  1. Launch Cloud Shell.
  2. Select the Copy button on a code block to copy the code.
  3. Paste the code into the Cloud Shell session with Ctrl+Shift+V on Windows and Linux, or Cmd+Shift+V on macOS.
  4. Press Enter to run the code.

If you don’t have an Azure subscription, create a free account before you begin.

Prerequisites

  • The preview of device streams is currently supported only for IoT hubs that are created in the following regions:

    • Central US
    • Central US EUAP
  • Install Visual Studio 2019 with the Desktop development with C++ workload enabled.

  • Install the latest version of Git.

  • Run the following command to add the Azure IoT Extension for Azure CLI to your Cloud Shell instance. The IOT Extension adds IoT Hub, IoT Edge, and IoT Device Provisioning Service (DPS)-specific commands to the Azure CLI.

    az extension add --name azure-cli-iot-ext
    

Prepare the development environment

For this quickstart, you use the Azure IoT device SDK for C. You prepare a development environment used to clone and build the Azure IoT C SDK from GitHub. The SDK on GitHub includes the sample code that's used in this quickstart.

  1. Download the CMake build system.

    It's important that the Visual Studio prerequisites (Visual Studio and the Desktop development with C++ workload) are installed on your machine, before you start the CMake installation. After the prerequisites are in place and the download is verified, you can install the CMake build system.

  2. Open a command prompt or Git Bash shell. Execute the following command to clone the Azure IoT C SDK GitHub repository:

    git clone https://github.com/Azure/azure-iot-sdk-c.git --recursive -b public-preview
    

    You should expect this operation to take a few minutes.

  3. Create a cmake subdirectory in the root directory of the Git repository, as shown in the following command, and navigate to that folder.

    cd azure-iot-sdk-c
    mkdir cmake
    cd cmake
    
  4. Run the following commands from the cmake directory to build a version of the SDK that's specific to your development client platform.

    • In Linux:

      cmake ..
      make -j
      
    • In Windows, run the following commands in Developer Command Prompt for Visual Studio 2015 or 2017. A Visual Studio solution for the simulated device will be generated in the cmake directory.

      rem For VS2015
      cmake .. -G "Visual Studio 14 2015"
      
      rem Or for VS2017
      cmake .. -G "Visual Studio 15 2017"
      
      rem Then build the project
      cmake --build . -- /m /p:Configuration=Release
      

Create an IoT hub

This section describes how to create an IoT hub by using the Azure portal.

  1. Sign in to the Azure portal.

  2. Select Create a resource, and then select Internet of Things.

  3. In the list at the right, select Iot Hub. The first page for creating an IoT hub opens.

    Creating an IoT hub in the Azure portal

    Fill in the fields:

    a. In the Subscription drop-down list, select the subscription to use for your IoT hub.

    b. For Resource Group, do either of the following:

    • To create a new resource group, select Create new and enter the name you want to use.

    • To use an existing resource group, select Use existing and then, in the drop-down list, select the resource group.

      For more information, see Manage Azure Resource Manager resource groups.

    c. In the Region drop-down list, select the region in which you want your hub to be located. Select a region that supports the IoT Hub device streams preview, either Central US or Central US EUAP.

    d. In the IoT Hub Name box, enter the name for your IoT hub. The name must be globally unique. If the name you enter is available, a green check mark appears.

    Important

    Because the IoT hub will be publicly discoverable as a DNS endpoint, be sure to avoid entering any sensitive or personally identifiable information when you name it.

  4. To continue creating your IoT hub, select Next: Size and scale.

    Setting size and scale for a new IoT hub using the Azure portal

    In this pane, you can accept the default settings and select Review + create at the bottom. Consider the following options:

    • In the Pricing and scale tier drop-down list, select one of the standard tiers (S1, S2, or S3) or F1: Free tier. This choice can also be guided by the size of your fleet and the non-streaming workloads that you expect in your hub (for example, telemetry messages). For example, the free tier is intended for testing and evaluation. It allows 500 devices to be connected to the IoT hub and up to 8,000 messages per day. Each Azure subscription can create one IoT hub in the free tier.

    • For Number of IoT Hub units: This choice depends on non-streaming workload you expect in your hub. You can select 1 for now.

    For more information about tier options, see Choose the right IoT hub tier.

  5. To review your choices, select the Review + create tab. The pane that opens is similar to the following:

    Information for creating the new IoT hub

  6. To create your new IoT hub, select Create. The process takes a few minutes.

Register a device

A device must be registered with your IoT hub before it can connect. In this section, you use Azure Cloud Shell with the IoT extension to register a simulated device.

  1. To create the device identity, run the following command in Cloud Shell:

    Note

    • Replace the YourIoTHubName placeholder with the name you choose for your IoT hub.
    • Use MyDevice, as shown. It's the name given for the registered device. If you choose a different name for your device, use that name throughout this article, and update the device name in the sample applications before you run them.
    az iot hub device-identity create --hub-name YourIoTHubName --device-id MyDevice
    
  2. To get the device connection string for the device that you just registered, run the following commands in Cloud Shell:

    Note

    Replace the YourIoTHubName placeholder with the name you choose for your IoT hub.

    az iot hub device-identity show-connection-string --hub-name YourIoTHubName --device-id MyDevice --output table
    

    Note the device connection string for later use in this quickstart. It looks like the following example:

    HostName={YourIoTHubName}.azure-devices.net;DeviceId=MyDevice;SharedAccessKey={YourSharedAccessKey}

SSH to a device via device streams

In this section, you establish an end-to-end stream to tunnel SSH traffic.

Run the device-local proxy application

  1. Edit the source file iothub_client_c2d_streaming_proxy_sample.c in the folder iothub_client/samples/iothub_client_c2d_streaming_proxy_sample, and provide your device connection string, target device IP/hostname, and the SSH port 22:

    /* Paste in your iothub connection string  */
    static const char* connectionString = "[Connection string of IoT Hub]";
    static const char* localHost = "[IP/Host of your target machine]"; // Address of the local server to connect to.
    static const size_t localPort = 22; // Port of the local server to connect to.
    
  2. Compile the sample:

    # In Linux
    # Go to the sample's folder cmake/iothub_client/samples/iothub_client_c2d_streaming_proxy_sample
    make -j
    
    rem In Windows
    rem Go to cmake at root of repository
    cmake --build . -- /m /p:Configuration=Release
    
  3. Run the compiled program on the device:

    # In Linux
    # Go to the sample's folder cmake/iothub_client/samples/iothub_client_c2d_streaming_proxy_sample
    ./iothub_client_c2d_streaming_proxy_sample
    
    rem In Windows
    rem Go to the sample's release folder cmake\iothub_client\samples\iothub_client_c2d_streaming_proxy_sample\Release
    iothub_client_c2d_streaming_proxy_sample.exe
    

Run the service-local proxy application

As discussed in the "How it works" section, establishing an end-to-end stream to tunnel SSH traffic requires a local proxy at each end (on both the service and the device sides). During public preview, the IoT Hub C SDK supports device streams on the device side only. To build and run the service-local proxy, follow the instructions in one of the following quickstarts:

Establish an SSH session

After both the device- and service-local proxies are running, use your SSH client program and connect to the service-local proxy on port 2222 (instead of the SSH daemon directly).

ssh <username>@localhost -p 2222

At this point, the SSH sign-in window prompts you to enter your credentials.

The following image shows the console output on the device-local proxy, which connects to the SSH daemon at IP_address:22:

Device-local proxy output

The following image shows the console output of the SSH client program. The SSH client communicates to the SSH daemon by connecting to port 22, which the service-local proxy is listening on:

SSH client output

Clean up resources

If you plan to continue to the next recommended article, you can keep and reuse the resources you've already created.

Otherwise, to avoid charges, you can delete the Azure resources that you created in this article.

Important

Deleting a resource group is irreversible. The resource group and all the resources contained in it are permanently deleted. Make sure that you don't accidentally delete the wrong resource group or resources. If you created the IoT hub inside an existing resource group that contains resources that you want to keep, delete only the IoT hub resource itself, not the resource group.

To delete a resource group by name:

  1. Sign in to the Azure portal, and then select Resource groups.

  2. In the Filter by name box, enter the name of the resource group that contains your IoT hub.

  3. In the result list, to the right of your resource group, select the ellipsis (...), and then select Delete resource group.

    The "Delete resource group" button

  4. To confirm the deletion of the resource group, reenter the resource group name, and then select Delete. After a few moments, the resource group and all its contained resources are deleted.

Next steps

In this quickstart, you've set up an IoT hub, registered a device, deployed a device- and a service-local proxy program to establish a device stream through IoT Hub, and used the proxies to tunnel SSH traffic.

To learn more about device streams, see: