|
1 | | -# Configuring a remote device<a name="configure-remote-device"></a> |
| 1 | +# Configuring a remote device and using IoT agent<a name="configure-remote-device"></a> |
2 | 2 |
|
3 | | -If you want to deliver the destination client access token to the remote device through methods other than subscribing to the reserved IoT MQTT topic, you might need two components on the remote device: |
4 | | -+ A destination client access token listener\. |
5 | | -+ A local proxy\. |
| 3 | +The IoT agent is used to receive the MQTT message that includes the client access token and start a local proxy on the remote device\. You must install and run the IoT agent on the remote device if you want secure tunneling to deliver the client access token using MQTT\. The IoT agent must subscribe to the following reserved IoT MQTT topic: |
6 | 4 |
|
7 | | -The destination client access token listener should work with the client access token delivery mechanism of your choice\. It must be able to start a local proxy in destination mode\. |
| 5 | +**Note** |
| 6 | +If you want to deliver the destination client access token to the remote device through methods other than subscribing to the reserved MQTT topic, you might need a destination client access token \(CAT\) listener and a local proxy\. The CAT listener must work with your chosen client access token delivery mechanism and be able to start a local proxy in destination mode\. |
| 7 | + |
| 8 | +## IoT agent snippet<a name="agent-snippet"></a> |
| 9 | + |
| 10 | +The IoT agent must subscribe to the following reserved IoT MQTT topic so that it can receive the MQTT message and start the local proxy: |
| 11 | + |
| 12 | +`$aws/things/thing-name/tunnels/notify` |
| 13 | + |
| 14 | +Where `thing-name` is the name of AWS IoT thing associated with the remote device\. |
| 15 | + |
| 16 | +The following is an example MQTT message payload: |
| 17 | + |
| 18 | +``` |
| 19 | +{ |
| 20 | + "clientAccessToken": "destination-client-access-token", |
| 21 | + "clientMode": "destination", |
| 22 | + "region": "aws-region", |
| 23 | + "services": ["destination-service"] |
| 24 | +} |
| 25 | +``` |
| 26 | + |
| 27 | +After it receives an MQTT message, the IoT agent must start a local proxy on the remote device with the appropriate parameters\. |
| 28 | + |
| 29 | +The following Java code demonstrates how to use the [AWS IoT Device SDK](https://github.com/aws/aws-iot-device-sdk-java) and [ProcessBuilder](https://docs.oracle.com/javase/8/docs/api/java/lang/ProcessBuilder.html) from the Java library to build a simple IoT agent to work with secure tunneling\. |
| 30 | + |
| 31 | +``` |
| 32 | +// Find the IoT device endpoint for your AWS account |
| 33 | +final String endpoint = iotClient.describeEndpoint(new DescribeEndpointRequest().withEndpointType("iot:Data-ATS")).getEndpointAddress(); |
| 34 | +
|
| 35 | +// Instantiate the IoT Agent with your AWS credentials |
| 36 | +final String thingName = "RemoteDeviceA"; |
| 37 | +final String tunnelNotificationTopic = String.format("$aws/things/%s/tunnels/notify", thingName); |
| 38 | +final AWSIotMqttClient mqttClient = new AWSIotMqttClient(endpoint, thingName, |
| 39 | + "your_aws_access_key", "your_aws_secret_key"); |
| 40 | +
|
| 41 | +try { |
| 42 | + mqttClient.connect(); |
| 43 | + final TunnelNotificationListener listener = new TunnelNotificationListener(tunnelNotificationTopic); |
| 44 | + mqttClient.subscribe(listener, true); |
| 45 | +} |
| 46 | +finally { |
| 47 | + mqttClient.disconnect(); |
| 48 | +} |
| 49 | +
|
| 50 | +private static class TunnelNotificationListener extends AWSIotTopic { |
| 51 | + public TunnelNotificationListener(String topic) { |
| 52 | + super(topic); |
| 53 | + } |
| 54 | +
|
| 55 | + @Override |
| 56 | + public void onMessage(AWSIotMessage message) { |
| 57 | + try { |
| 58 | + // Deserialize the MQTT message |
| 59 | + final JSONObject json = new JSONObject(message.getStringPayload()); |
| 60 | + |
| 61 | + final String accessToken = json.getString("clientAccessToken"); |
| 62 | + final String region = json.getString("region"); |
| 63 | + |
| 64 | + final String clientMode = json.getString("clientMode"); |
| 65 | + if (!clientMode.equals("destination")) { |
| 66 | + throw new RuntimeException("Client mode " + clientMode + " in the MQTT message is not expected"); |
| 67 | + } |
| 68 | +
|
| 69 | + final JSONArray servicesArray = json.getJSONArray("services"); |
| 70 | + if (servicesArray.length() > 1) { |
| 71 | + throw new RuntimeException("Services in the MQTT message has more than 1 service"); |
| 72 | + } |
| 73 | + final String service = servicesArray.get(0).toString(); |
| 74 | + if (!service.equals("SSH")) { |
| 75 | + throw new RuntimeException("Service " + service + " is not supported"); |
| 76 | + } |
| 77 | +
|
| 78 | + // Start the destination local proxy in a separate process to connect to the SSH Daemon listening port 22 |
| 79 | + final ProcessBuilder pb = new ProcessBuilder("localproxy", |
| 80 | + "-t", accessToken, |
| 81 | + "-r", region, |
| 82 | + "-d", "localhost:22"); |
| 83 | + pb.start(); |
| 84 | + } |
| 85 | + catch (Exception e) { |
| 86 | + log.error("Failed to start the local proxy", e); |
| 87 | + } |
| 88 | + } |
| 89 | +} |
| 90 | +``` |
0 commit comments