2. HOWTO : using ztm for secure RDP access
Remote Desktop Protocol (RDP) is a remote desktop sharing software developed by Microsoft and is the built-in remote desktop tool for Windows. RDP communicates through port 3389 by default and requires a direct connection between the client and the server. However, by using ZTM, RDP clients and servers can connect even without direct network access, such as when accessing an office Windows desktop from a hotel Wi-Fi during a business trip.
The "ZTM + RDP" solution offers an alternative to remote access tools like TeamViewer, ToDesk, and Sunflower(向日葵), with significant advantages in security and privacy protection. Unlike tools like TeamViewer, ToDesk, and Sunflower(向日葵), which require users to register and use their SaaS services—thereby routing RDP client-server communication through their servers and potentially risking information leakage.ZTM operates entirely within the user's controlled environment. This includes running the ZTM relay server (a.k.a ZTM Hub), which is managed and accessed exclusively by the user, offering greater privacy protection and enhanced security.
This guide introduces and demonstrates the following use case: using ZTM on macOS to remotely access a Windows desktop computer in the office via RDP from a coffee shop Wi-Fi. We will use the ZTM AMI on AWS to set up the ZTM environment and deploy the ZTM Hub with a single click. The process is outlined as follows:
- Deploy ZTM Hub using AMI on AWS
- Install ZTM on macOS and connect to ZTM Hub
- Install ZTM on Windows and connect to ZTM Hub
- Configure the tunnel on macOS's ZTM console to establish an RDP connection from macOS to Windows
- Verify the connection
-
Log in to the AWS console and choose "Launch Instance." In this example, we select the Singapore Region.
-
When selecting an AMI, enter ZTM and "search" as shown in the image:
- On the search results page, you can see the Flomesh ZTM AMI information. Click the "Select" button, as shown:
- Returning to the instance creation page, the default type is T3.Small. If it's for personal use, you can choose a smaller instance type, such as T3.Micro, as shown:
-
Click "Create Instance." ZTM AMI is free for 7 days, and you can unsubscribe at any time within those 7 days. If you want to continue using it, the cost is 1 cent per hour, automatically charged on the AWS monthly bill.
-
After the instance is launched, SSH into the EC2 instance and view the
/root/.ztm/ztm-permit.jsonfile. This file contains all the information needed to connect to the ZTM Hub, including the keys and Hub address:
root@ip-172-31-43-150:~# cat .ztm/ztm-permit.json
{"ca":"-----BEGIN CERTIFICATE-----\nMIICoTCCAYkCFCMS6GYjC6Yedc2xjfvFs4eJaj/OMA0GCSqGSIb3DQEBCwUAMA0x\nCzAJBgNVBAMMAmNhMB4XDTI0MDcyOTEwMTkxM1oXDTI1MDcyOTEwMTkxM1owDTEL\nMAkGA1UEAwwCY2EwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQC69592\nlVV+TFUOLXezcc7KUlXmpvpCH8YvnUdnwPaQTupyAMTIiIKnjOaJsZ/UlUi7aSHB\nD5cWbelOF7r1CjmyXJJhHH3kp5e8jNBt4L8+zqXoDKa0q0IhUYM1KX1+2KDuqQaF\nAndgl2O8/lFAoyib6l+wSPZKY85MIgnuvdkvMSKQyCDaOjFI9Onh3k/PeS/2uKYB\n6b6JRo35zqHSUaq4MVyRM/+THE9Tl93J2rYZffHt6D94LyZeWhkJD3mdiZOA7upU\nRxtOG0wO/DxcJ7YD9GfwDtpY7tQfUmF4VpMdsGeMK0RMn3Sb5N3nMrBwNY7MY5lF\n8T8o2xA/HIncIGvbAgMBAAEwDQYJKoZIhvcNAQELBQADggEBAChL8iGawye6hfUk\nHxtDqfCxCEK9QPttBexr0A0hYoFBbTIROQC78nkO5+0C/uhiUxqGwOhIsyBs/ilE\nQ/bPjTooq50/XooBVjz5v5YB1d0KItBSzJIBVWOVNxWBRFO6BusFRJIfqHULWjLB\nNUhq3VXJwcgTQALZKZI1SjDYhY0B/ZTaJn2mSwuBVhM4hMGxkuqI+zfUZhYrM0V8\n5VWYOrLYHMNBy+WM6dREuxPUvdNVe10f7QRJqAh8Zv7cwanwbu5xm2lX1mysSmRF\nFNbznsOzAgKV/T9oHAkdUGCGCJx+SoK+W0/HqW/qUftAmYDhvSAK+JJtVBsVp91+\nviaOEbs=\n-----END CERTIFICATE-----\n","agent":{"certificate":"-----BEGIN CERTIFICATE-----\nMIICozCCAYsCFADCU21/DU5I7rcyTXiPv+GPkNxOMA0GCSqGSIb3DQEBCwUAMA0x\nCzAJBgNVBAMMAmNhMB4XDTI0MDcyOTEwMTkxM1oXDTI1MDcyOTEwMTkxM1owDzEN\nMAsGA1UEAwwEcm9vdDCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAMHm\n6p1EwERfQb6FJzuDX/mzaUdsUOW7C/jGpsmTsPyYpOhXjg/CcCD3llhGyqESJ2pi\nJD3vPfCCxCWGJ8AVvKEc3vwflfv6ym+9hgBBYP1CjqLuBp4UNq9XhSRb0RgKz9QO\nGBDxyfhWGY5YCpxb4juwWVLw9X5TTUVNIJ0ntPZUocBQ/JM76fNks0CaIxpPEkVc\nh6uUGwRCAOMb3h+7bBct/tWt7sCav7wqRjKCueuBTCO/zUhbifjAaOyg3W70VnVD\n1blKxTIMKO7NsS7gQh9mkarEdDV9v5NKkTHjsqo6F6oBKKUER7z16qikA4HrJBr2\nG31R6Uf7CIc63+9baCsCAwEAATANBgkqhkiG9w0BAQsFAAOCAQEAXpziWlO9k5Y0\nhaK+npkqCZtujY02dy1nrkwfTOOfxrvk0QiLNIp5CMGlWDS6I8o8h0a50SUQQd54\nnZXpZP++TjI/hhQShQ3cZC8KKvkP7AV6rgUWO3SpCWHLL32CeqDI5o87lvb77+Uc\n5aMDK/kol1TUN635ruC7CJCJNiy+gTjJrxdl7/DiaYsez7G30IzwV+t5qvAxoJAs\nq4QilxsLMPg/8Y3xZ7HowlLxzy3QCV1paceFedja9wxqym7se5e++lbdqYPvE9If\nuU4Rzbrj5QGnNV1WJRXlhnuNW3TO5/hHryK1wi8EHHIWyzP4Xs7yVivmOplEksXU\nYSrbdu+n+Q==\n-----END CERTIFICATE-----\n","privateKey":"-----BEGIN PRIVATE KEY-----\nMIIEvAIBADANBgkqhkiG9w0
BAQEFAASCBKYwggSiAgEAAoIBAQDB5uqdRMBEf0G+\nhSc7g1/5s2lHbFDluwv4xrZk7D8mKToWOED9OeM/Hd8w8nAt3QJe0lRhYYaRIjam\nIkPe89zwsQlhifAFbyhHN78H5X7+spvvYYAQUI/I4i7gKOFdanpLbO/UKLOFL53/\ng8S28CxgHi/YcAuIoGHl2C+7eDLoJcl2ZsuknN4O+akXoVB2itOVAVuwjOE3ZBQ6\nFAu98nvjeeeGh5xUV5ndxrmFbMmUgftFCnEn9B7JCVrYzNY4QtJmMumP5zCSPaZE\nf3t5PrzKf4ewB/3+GmrXOsqCVLhhPtSyQl15Lv68gDAjZ8yMCtSQAt8DLVMD5Yj3\nHp3NxOD9AgMBAAECggEACxkST/Zis9c5jNqVXDX60eZT0pH3r9blFeRZmWc54Ip6\nP5XppDnIz6oMEQa5JxYMBbUgVS5EEp7XE+34rZmD4tBRcl9U9Vhd3oI7PvrsyeRM\n/YxG2XtSN+ApzO5A5s4kyd4LlcKHa+dC32No9fpoAnplLB8k2B7shVx57i/vbCxQ\nPoW2On5yxj7Y1RdPA/g6E8Y7dHWkV+XqfqfpYop7aOVreEysdb5UUV4EPjEXIlcl\n1mxevRnEGAaQKsn9H/lZ9ALcTLgB6IUNgAoKkqS/sOUAz6hJhmTAfX0IcCaZSkLp\nR8AN7jeM3Na8CmrH26enpx5okTTyVmZczpPSbgNbnwKBgQDSaEbpF0Xw7ClmWq1/\nHH6FjI9c25l4MQm7D0cU9VgAme1t5PrMv9XrFQFEOtJ0smh+MALtKPLOE+ZDrXXy\nD6Fuknp+t2BG6TmqVvWLGYaXvTe4AsTrMwmD3BKlA8yPfKCuTgpxkzWw7iFBMC8o\nJQGcKiMvStF0y99n5X09aKDsMwKBgQDWeWCsR78qX3m5BqopOJKShZLiJ7Cl9UDe\n1sVoK63vYr81XM5W23IuAxmhOp9x04+SkBgZrbb5WL9rVh+gA16O6eicqY0AnLkH\nFZ7TOkShUcpBWkd50SgkLyWdi8GVrIiGF5DPClU56YoEw07ve6+kXShhERhL8OpO\nRRk0jFX4swKBgA6B0KDiGi2hPquFZhdm4AgEERWfn9bDe+Loy0jGbWxeT0Zg6T6Q\n4mc74S4IC9hql1s68QW4hG+QtgGkJUkZK2ae8SazUSIQ6y1IcfT7gdgH7n+uA40E\ngIufpR/ZqemJPoDIdcUkwJBy9uGbbDGLB3S7C3xWJH/ZxwtXZ5EJhOeFAoGAbmQ4\nFGGWomMGKjqBtTf7/3pC0K3lD1B7Ba6GZSeM/d80kMXhGAB+j2DzvcK0jHnBlIhH\naNEbmnkVDv8M9qfS8yhjxRItje8YIMm2ccs3UkL7HqazGx/Rzk2jPBrKZ3r/nmyN\nH0FJf1rnIPDtdt5DbZ67dFXKyEwD1gyisJjcRfMCgYBofb5cR0/MH1D12iH1gjy8\nUIOXOSYdsf3HC9YoY1GTPm9rT77A7NSRW0TyX37BdOpJ+PPffLSu5G2rQtwa5Rh+\nG6lXox3mlc8ClPyJkJ7V4N8hIzbnwPoZoGlirIr9lgUeZQViMMWTJckq/bGQ5Aft\nO1SYlVDshtOt3RPVpBzCVQ==\n-----END PRIVATE KEY-----\n"}}In the following tutorial, use the information from the ztm-permit.json file to connect to ZTM Hub.
Download the appropriate .dmg file for macOS from the ZTM release page. Be sure to choose the version that matches your processor type, either M1 or x86. For example, I am using a MacBook Air with an M1 processor, so I downloaded this one: https://github.com/flomesh-io/ztm/releases/download/v0.1.0/ztm-app-v0.1.0-macos-arm64.dmg. Note that files with a .dmg extension are for graphical interface users, while .tar.gz files are for command-line users. Their functionality is the same, but the user experience differs. After installation, run the application as shown below:
Click the plus sign and select “Join Mesh.” In the pop-up window, click the "+ Join" button at the top right, as shown:
On the add page, enter a "Mesh Name" which can be anything. Enter "Join As," which can also be anything, to identify the local node. In the "Permit" section on the right, click the pencil icon and input the contents of the ztm-permit.json file copied from step #1.6. After filling in the details, click "Save," as shown:
After saving, the Mesh status will display as Connected on the Mesh list page, as shown:
Note that the "Hubs" section will show a number. "1" indicates that one endpoint (EP) is connected to this Hub.
Installing ZTM on Windows is very similar to the process on macOS—simple and straightforward. After installation and startup, just add the mesh. Once added successfully, click on "Endpoints" on the left, and you should see two endpoints (EPs) connected to the Hub, as shown:
Next, we will configure a tunnel in ZTM. After setting up the tunnel, the two endpoints (EPs) can communicate over the internet without needing a direct network connection between them. The following steps are performed on macOS. Access http://127.0.0.1:7777/ in your browser; this address is provided by ZTM. Select the "Apps" menu from the left sidebar, then click the "Tunnel" icon, as shown:
In the Tunnel page, click the "+" icon in the top right corner to create a Tunnel, as shown:
Create the tunnel as shown in the image below:
In ZTM, "Tunnel" is a core network feature. Here, we will explain what a "Tunnel" is in ZTM, its purpose, and how to configure it.
In a typical IP network, to establish a network connection from A to B, you need a route from A to B, and B must be listening on a specific port. This is called "route reachability from A to B." In the real world, this "route reachability" is not always straightforward, as in our example where the connection from a coffee shop Wi-Fi network to an office desktop computer is often "route unreachable." One of ZTM's core functions is to address this "route unreachable" issue while still allowing mutual access—this is the ZTM Tunnel.
In the configuration shown above, first give the Tunnel a name and configure it in the Metadata section. In this example, the name is "office-rdp" and we select TCP for the Protocol.
Next, configure the Inbound settings. In a ZTM network, any two EndPoints can use a Tunnel to communicate. For instance, in our case, the Mac in the coffee shop network can access the office Windows desktop computer, and vice versa, the office Windows desktop computer can also access the Mac in the coffee shop. When more devices join the same ZTM network, you can use the Tunnel to establish connections between any two devices. However, devices in the same ZTM network cannot communicate without a Tunnel. We must explicitly create a Tunnel between two devices and configure the correct access permissions to allow communication. This approach enhances security and reflects the Zero Trust (ZT) concept in ZTM. For a Tunnel from A to B, A is referred to as "Inbound" and B as "Outbound." Think of the Tunnel as a pipe where water flows in one direction: the end where the water enters is the Inbound, and the end where the water exits is the Outbound.
In our example, the Mac end is the Inbound, and the Windows end is the Outbound. So in the configuration, for the Inbound EndPoint, select "Caishu-macair"; for the Outbound EndPoint, select "win."
Next, configure the Inbound Listens, in the format "IP:Port, IP:Port". We can set one such as "127.0.0.1:3390". Note that the IP here should be the IP of the Mac end, typically 127.0.0.1 or 0.0.0.0. Using 127.0.0.1 is more secure, as it prevents other computers from connecting. The port 3390 is chosen arbitrarily, as long as it's not in use locally. Usually, ports above 1024 are selected, as ports below 1024 require special privileges to listen.
Similarly, configure the Outbound Targets, which specify the IP and port of the RDP service, in this case, port 3389 on "win."
Then configure Allowed Exits and Allowed Entrances. These parameters can be left unconfigured if not needed. When configured, they constrain which EPs can connect to the Tunnel. EPs listed in Allowed Exits are allowed to exit through the Tunnel, so here we configure "win," meaning the Tunnel from "Caishu-macair" can only exit through "win." On the Outbound side, Allowed Entrances specifies that only the Tunnel from "Caishu-macair" can connect to "win." You might wonder why we need these restrictions when a Tunnel already specifies a connection from "Caishu-macair" to "win." This is because multiple Inbounds and Outbounds can be configured for a single Tunnel. For example, if besides Macair, a ThinkPad also needs access to "win", we can configure two EPs. Similarly, multiple Outbounds can be configured if there are multiple RDP services, such as an office "win" and a backup "win-backup". Multiple Outbounds are uncommon in office environments but are typical in server environments, where high availability and disaster recovery require multiple service providers. These configurations might seem complex, so for common scenarios, it's sufficient to leave them unconfigured, even though this slightly contradicts the principle of "least privilege."
The Tunnel configuration is now complete. Click the checkmark icons for Inbound and Outbound, and save the settings. The result is shown below:
At this point, you can use an RDP client tool on your Mac to connect to 127.0.0.1:3390, which will route through the ZTM Tunnel to the office desktop computer's Windows RDP. Below is the configuration for the RDP client tool I used:
