Skip to content

0. ZTM App Introduction and QuickStart

Jump to bottom
CaiShu edited this page Oct 8, 2024 · 3 revisions

ZTM App is a cross-platform application that can run on iOS, MacOS, Windows, Linux, and Android. ZTM App enables interactive graphical operation of ZTM-related functions, including configuration management and application functions, connect to ZTM Hub, etc. Specifically, it includes registering to ZTM Hub, viewing the list of registered End Points on ZTM Hub, viewing logs, and operating ZTM MiniApp. ZTM MiniApp is a small program used to extend the functionality of ZTM in the application domain, and these gadgets provide a variety of functions, such as remote desktop sharing, file sharing, intranet web access, and so on.

The following demonstrates how to build a ZTM environment from scratch, including a ZTM Hub running on aws cloud, and a ZTM App running on iphone and a ZTM App running on macOS, and share video files from macOS to iphone.

Step 1: Deploy ZTM Hub

Users can choose to deploy ZTM Hub by themselves, or start and run ZTM Hub directly from the AMI of aws marketplace. in this demo, we use the way to run ZTM Hub directly from the AMI of aws marketplace.

  1. Login to the aws console and select Create EC2

  2. On the create page, select the AMI step and enter "ztm"

1

  1. After enter, select “ZTM HomeConnect”

2

  1. Select “Subscribe Now”

3

  1. Leave the other default settings untouched and click “Launch Instance” to start EC2

4

  1. After EC2 starts, copy the /root/.ztm/ztm-permit.json file from EC2 and save it to a file. Note that this file needs to be kept private, it contains the key to connect to the ZTM Hub (it's very dangerous to try to post the contents to the wiki like I did)
caishu@caishu-macair4 pipy % ssh -i ~/.ssh/us-ca.pem ubuntu@54.183.136.214
Welcome to Ubuntu 24.04 LTS (GNU/Linux 6.8.0-1016-aws x86_64)

 * Documentation: https://help.ubuntu.com
 * Management: https://landscape.canonical.com
 * Support: https://ubuntu.com/pro

 System information as of Mon Sep 30 03:58:12 UTC 2024

  System load: 0.0 Temperature: -273.1 C
  Usage of /: 24.8% of 8.65GB Processes: 109
  Memory usage: 33% Users logged in: 0
  Swap usage: 0% IPv4 address for ens5: 172.31.29.4

 * Ubuntu Pro delivers the most comprehensive open source security and compliance features.
   Ubuntu Pro delivers the most comprehensive open source security and compliance features.

   https://ubuntu.com/aws/pro

Expanded Security Maintenance for Applications is not enabled.

111 updates can be applied immediately.
To see these additional updates run: apt list --upgradable

Enable ESM Apps to receive additional future security updates.
See https://ubuntu.com/esm or run: sudo pro status


Last login: Fri Sep 27 02:16:18 2024 from 18.206.107.29
ubuntu@ip-172-31-29-4:~$ sudo su -
root@ip-172-31-29-4:~# cat ~/.ztm/ztm-
ztm-hub.db ztm-permit.json
root@ip-172-31-29-4:~# cat ~/.ztm/ztm-permit.json
{"ca":"-----BEGIN CERTIFICATE-----\nMIICoTCCAYkCFHqvFOArK6yQVP3Hp3Hrg0EYGVjDMA0GCSqGSIb3DQEBCwUAMA0x\nCzAJBgNVBAMMAmNhMB4XDTI0MDkzMDAzNDYwNloXDTI1MDkzMDAzNDYwNlowDTEL\nMAkGA1UEAwwCY2EwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCuHp9o\nRC5uxu+R7530bPAlFs16ocA0SSA07pQ2iK5QjtfoaAs/FlEOMX8nUIEXI8QaQkpL\neHfEH9x++XhAmhAZXCloVjaq1Xg7T2XVjqRY6DTh36bRnLUrNcANHUBCAkxtoUdg\nqTMVD3IqMLQdjD3hcyEFmCtVg3+Wx13I35lz6N0HWiumXXGtpWAyC3F25/x2XayC\nCeFTDm7V9mDaFegd4L1S73I1pJxTmMCrFv59/5ncT3qk6fuc3eKlPiEU85Fm70gI\npE6zLMjs7lmtdi4zYE3pNnfh9C8Nr4RgDsiMVWP8bFpPnCQDhKuqIPNc+WS2HYyl\n0b8SsuX0HlSQPchhAgMBAAEwDQYJKoZIhvcNAQELBQADggEBABkFTY6m+soi9Q0/\nCtbvlUYAVj1K6dg41UDjUphItYXLaHYJm/pd5QOYRMJ+QvLC0w85W8nkeqJMKW/u\nwzVXvHhKSwhddTBWMKuxELTaVlykWpym4WP4LP+p5jhOUIZ4A3rZ8g/aCNIPzI1G\npRpqn0Bb1Z71LCZ9LFDEPdcN3axEWEQoCmJoOyaJo89hEKP74aFL1Jm7OAafHojC\neTxY+L3BzDoORjvW7psOm+aOv6a2yhHMfN17lKAoz/8UXybeWF5nEjgjqtoDpV3D\nVKB0wkO85lypgdS/kzBxFNkEf0SbpvkAl+QDWzZ4CN2Xeg/U/sk38JliwqwKr+T7\nVImZ11w=\n-----END CERTIFICATE-----\n","agent":{"certificate":"-----BEGIN CERTIFICATE-----\nMIICozCCAYsCFEXLF43oon7cSdEfb06YhjVBNBfcMA0GCSqGSIb3DQEBCwUAMA0x\nCzAJBgNVBAMMAmNhMB4XDTI0MDkzMDAzNDYwNloXDTI1MDkzMDAzNDYwNlowDzEN\nMAsGA1UEAwwEcm9vdDCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBALQP\n2T9qjWOjAzRSkkdZRcvhe7M9FLjwzzXRbY5L0V01u1dF1xHQ0HwuOi7zwC+vl6BW\nhjkoWrX0IhE0TUvDLiNDTBhGTofafOdShYbTdyv66V7MfZPmB+gynv5sVOudHuVU\npXx6MNG9DYJln8igRZHijEtMBsEGlXEOdgdHgr3j2XFqfHiTxyyv8abzkpA7xseL\nfXacnZ8o1b3PI8N1L4pxkm9lzNryTpDCyvkEJOuZLw1gro5Hxwl1kjj5sJbN64lm\nm6jU2vpedBZr2mjXhrz+iIiEu7UZXHsx+djnk1S6HMCct7btD9JcwTK2Vo+6Auqv\nflpdzbXZZmB5+j5gnFsCAwEAATANBgkqhkiG9w0BAQsFAAOCAQEAozt2IF2OhuCz\nH4IsQ8hF7d3zwrlxDsGTx1cXjEE1/dT1MjadsGcowEI4Fjsxjou0hR6JR+U4xlmG\nCSPCiZVNVmhOqZcHvFVmtqMZAo1eDjDUJlLx9q4YwDBdCKR9ectcgTS8MT6J7DK2\nbZM17rkANgclAC7UwL192roOoPXuokx/9yQH5m9QLJNRlLm1VRPkcwQAeyv6GiI1\n/HYB7G5KISo63blY20ZaoGS5B3JjmLVqFOwX3Iu63KY9VlqQduWSwNFgU4+62788\npNLZSKGRhqKjVBWcX9FG4w39IXBqSFdAos8h225EvBy7SJ671G6vBY/yL0oeMmUR\nCHDrCu9l1Q==\n-----END CERTIFICATE-----\n","privateKey":"-----BEGIN PRIVATE KEY-----\nMIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQC0D9k/ao1jowM0\nUpJHWUXL4XuzPRS48M810W2OS9FdNbtXRdcR0NB8Ljou88Avr5egVoY5KFq19CIR\nNE1Lwy4jQ0wYRk6H2nznUoWG03cr+ulezH2T5gfoMp7+bFTrnR7lVKV8ejDRvQ2C\nZZ/IoEWR4oxLTAbBBpVxDnYHR4K949lxanx4k8csr/Gm85KQO8bHi312nJ2fKNW9\nzyPDdS+KcZJvZcza8k6Qwsr5BCTrmS8NYK6OR8cJdZI4+bCWzeuJZpuo1Nr6XnQW\na9po14a8/oiIhLu1GVx7MfnY55NUuhzAnLe27Q/SXMEytlaPugLqr35aXc212WZg\nefo+YJxbAgMBAAECggEAEDBomPdh36EgFaE4PlVRctjtappwStx5KjPlL2kJBDdj\nhko6NwODldargTMwhq5j6eo9m9VRVTtY9huyDhYYsi+dH4WauUOJ/VusXl3plg5e\nKG7RpO2GrSLNVr9eDJJjh7z05VyFwnsb7tW86FM4o2WEtZ8P8GTrehm8aj/MtSPT\nlzXsKC7jPYheE1rFTfP8wZXnbrgp1yWn7fp7wxLO+FXaKsIMwHbHNUZBRBhIRK7D\n1CLG7RHdusu2YwDVgF0SKDPOfVv3VBkvJYNeAXU78hRO89bSBlXiee3nTT30R0G8\nPUzJR061QnemlfNEpnBYGLZlxZhe+fHOgrKtxAD6OQKBgQDidbjw9ftIom3sKMg1\n1hwtgPMKxTjJhen12mVNtC8eqJdvtjzIrTGmT8TM5C9D7sR4JQ0XlS+Y83xpm7YL\ngSaF8ngfDD2B7vI9rSfozjeT6jVXQYQHleX1nGyfoCxu4zzlcO0UBehj7CSqtCwP\nCo35qWw8L3QqVq3hY+ca7nrXjQKBgQDLjL0HHDhFdlyvfuomULl7zwvMEFZv7UzC\ncpgs+LNGBnh2BtjkycYsuCUsC/z2yOHXjfJIJ1SQiQsUXcArQKt4/4mPWCS8UQt5\n2lzcARqqsF2LsnhCW7X+vM7xq0X1qC/52QTIksQHGZOVXD0I5drP0QT+Tgo90va6\nGXjFGUv1hwKBgQCHBK1JbT9u5Pkozn/gKVIPh0xg5YmgDWmanaW8mGtnmhkAD+VZ\nuHlbsT+i8YGEvT0CbQTLRLVmOfW5eY8meNAhGJmp2UBq0a44O58J3LmiRQeciIFR\njHvY3nSdD4CudGmAWr3fLE6MFOUfqeCC70YKzoqrr5dRDvEI6umFUx6GmQKBgQC1\nQxI+F7JAoUOugI2RK0fR6jHuOgpPR/mYGyZKvfoffLmfGT/ilZBl2GI51D8joQYE\nx4IfIO8cev2j2Ey996v7Z0wfm3WzQVS/4WXaAR23LLFRKtAO/86VF5wN9+Cn/2sh\nylGJL7FjRTJ4ypgLqWzurYsNz38tSQWv+ejjVEChVwKBgGO62ZOrHEmIqw8vUMnl\naX2alpyXgfXw6kWzidr6CWmAucymjdPc+sMxpqtByi+zeQUQuDYwb4RQ8ZEhJPs9\nLSbkrMy37BgaJD4XCzbYqVQkZaS1Y/VVGHqGsVpnwP3CvJPRd+sNBsK741bTfUt0\n54XL1tkYa634EGhh5qMnLPkq\n-----END PRIVATE KEY-----\n"},"bootstraps":["54.183.136.214:443"]}

Step 2: Install the macOS ZTM App

Install ZTM App

ZTM provides 3 installation media and modes:

  1. ztm-aio (all-in-one), which is a command line executable. You can download it now from the ztm release page, for example, I downloaded this one https://github.com/flomesh-io/ztm/releases/download/v0.3.0/ztm-aio-v0.3.0-macos-arm64.tar.gz . For those familiar with Unix/Linux command line operations, this package provides a Linux-like experience.

  2. brew installer. MacOS users who are familiar with brew can install ztm with the command "brew install flomesh-io/ztm/ztm"

  3. ztm-app, a GUI installer for MacOS users familiar with dmg installations. Again, the installation media is on the release's download page. We're in the process of getting the dmg installer up on the App Store, which takes some process and time. TestFlight is ready here : https://testflight.apple.com/join/1wQfMD85

In this example, I'm taking the second approach, using a brew install, which is a very simple process:

caishu@caishu-macair4 ztm % brew search ztm
==> Formulae
flomesh-io/ztm/ztm zim mtm dtm

==> Casks
utm
caishu@caishu-macair4 ztm % brew install ztm
==> Downloading https://formulae.brew.sh/api/formula.jws.json
 ################################################################################################################################################# 100.0%
==> Downloading https://formulae.brew.sh/api/cask.jws.json
 ################################################################################################################################################# 100.0% ==> Fetching flomesh-io/ztm/ztm
==> Fetching flomesh-io/ztm/ztm
==> Downloading https://github.com/flomesh-io/homebrew-ztm/releases/download/ztm-0.3.0/ztm-0.3.0.arm64_sonoma.bottle.tar.gz
 ################################################################################################################################################# 100.0% ==> Installing ztm from flomesh-io/ztm/ztm
==> Installing ztm from flomesh-io/ztm
==> Pouring ztm-0.3.0.arm64_sonoma.bottle.tar.gz
🍺 /opt/homebrew/Cellar/ztm/0.3.0: 6 files, 22.7MB
==> Running `brew cleanup ztm`...
Disable this behavior by setting HOMEBREW_NO_INSTALL_CLEANUP.
Hide these hints with HOMEBREW_NO_ENV_HINTS (see `man brew`).
Removing: /Users/caishu/Library/Caches/Homebrew/ztm-0.2.0.arm64_sonoma.bottle.tar.gz... (9.8MB)

Start ZTM App (Aka 'ztm agent')

caishu@caishu-macair4 ztm % ztm run agent
2024-10-02 10:26:21.786 [INF] [listener] Listening on TCP port 7777 at 127.0.0.1

Open the GUI console

Open http://127.0.0.1:7777/ in your browser to access the ZTM App using the GUI:

6

Inside ZTM App, all operations can be done in GUI mode or CLI mode. For those who prefer CLI mode, you can try to execute the following command in another term window:

caishu@caishu-macair4 ztm % ztm get mesh
NAME JOINED AS USER HUBS STATUS

In this tutorial, we will introduce equivalent CLI commands for each operation performed through the GUI. However, for the user, it is sufficient to use either the GUI or the CLI.

Connect to the ZTM Hub

Click “Join Mesh” in the browser's console, then enter the mesh name and the current agent's name (you can use any name you want), click the pencil icon in the “Permit” field and enter the content of the json of the permissions recorded during the deployment of the ZTM Hub.

7

Click “OK”, click “Save”, then you can see in the console that you have connected to the ZTM Hub.

8

The CLI can be used to connect to a ZTM Hub with the following commands, which are equivalent to the GUI operations described above.

ztm join ztm-demo --as cai-macair --permit ztm-permit.json

Sharing files on macOS

There are several Mini-Apps built into the ZTM App, and one of them, called Cloud, allows you to share files between ZTM devices.

In the web console of your browser, click on the “App” menu on the left, then click on “Cloud”:

Click on the “App” menu on the left, then click on “Cloud”.

9

Copy a file to the *~/ztmCloud/users/root/ directory, then click “users” and “root” in the browser console to see the copied file:

10

11

12

You can see the status of the copied sample.mp4 file is “New”. Right click on the sample.mp4 file and select “Upload”. Note that the file itself is not uploaded, it's still on MacOS locally; however, the metadata of the file, such as filename, size, hash value, etc. are uploaded to the ZTM Hub, so that other ZTM clients can “see” the file. After the upload is complete, you can see that the status is no longer “New”.

13

Now, the file sample.mp4 has been “shared”, and we will show you how to download it on your iPhone later. In CLI mode, you can do the following, which is equivalent to the GUI operation:

caishu@caishu-macair4 ztm % cp ~/Downloads/sample.mp4 ~/ztmCloud/users/root/
caishu@caishu-macair4 ztm % ztm cloud ls /users/root
NAME STATE SIZE DATE SOURCES SHARED
sample.MP4 new 2186317 Sun Sep 29 06:56:32 2024 1 -
caishu@caishu-macair4 ztm % ztm cloud upload /users/root/sample.mp4
File uploaded: /users/root/sample.mp4
caishu@caishu-macair4 ztm % ztm cloud ls /users/root
NAME STATE SIZE DATE SOURCES SHARED
sample.MP4 synced 2186317 Sun Sep 29 06:56:32 2024 1 -

Step 3: Install ios ZTM App and download sample.mp4 from macOS

The current iOS version of ZTM App is still in internal testing on TestFlight and will be officially available on the App Store soon. Below we demonstrate installing ZTM App from TestFlight, connecting to ZTM Hub and downloading the file from MacOS.

  1. Open TestFlight, you can see the installation option of ZTM App, click “Install”:

14

  1. After installation, open the ZTM App, the first time you run it, it will ask for permissions, the “location” permission does not actually use the location information, but to keep the app running in the background. Similar to the MacOS version of ZTM App, the first step is “Join Mesh”:

15

16

17

  1. After confirming the connection to ZTM Hub, select “Cloud” from the bottom menu “Apps”. Click on the users and root directories, and finally we can see samples.mp4 with the status of missing, which means that this file has not been downloaded on the iPhone:

18

19

20

21

  1. Click sample.mp4 file, select “Download” in the popup menu, you can see the progress bar of download; the download will be finished soon, you can see that the status of sample.mp4 is no longer missing, which means that the file has been downloaded to the local area:

22

23

  1. In the iPhone's file browser, you can see the “ztm” folder in “My iPhone”, and in the ztmCloud/users/root directory, you can see the sample.mp4 file downloaded from macOS:

24

Downloading the file using the CLI

ios doesn't provide a TERM, so we use a Linux node to connect to the ZTM Hub and use the CLI to download this sample.mp4 from the share, refer to the procedure below:

root@ip-172-31-17-110:~# ztm cloud ls /users/root
NAME STATE SIZE DATE SOURCES SHARED
sample.MP4 missing 2186317 Sat Sep 28 22:56:32 2024 2 -
root@ip-172-31-17-110:~# ztm cloud download /users/root/sample.MP4
root@ip-172-31-17-110:~# ztm cloud download --list
PATH SIZE SPEED PROGRESS ERROR
/users/root/sample.MP4 2186317 221.125KB/s 50% -
root@ip-172-31-17-110:~# ztm cloud ls /users/root/
NAME STATE SIZE DATE SOURCES SHARED
sample.MP4 synced 2186317 Sat Sep 28 22:56:32 2024 3 -

In the final output, you can see that SOURCES is “3”, which means that the sample.mp4 file is copied on three nodes, MacOS, iPhone/iOS, and Linux.

Summary

In this example, we completely covered running a ZTM Hub from aws marketplace as a cloud host; then installing the ZTM App on MacOS and iPhone respectively and joining the ZTM Hub; and finally sharing the file from MacOS using the Cloud Mini-App and downloading the file on iPhone.

ZTM provides the underlying decentralized network capability, on top of which developers can implement application-layer functionality through Mini-Apps. the ZTM App has several built-in Mini-Apps, of which the Cloud Mini-App implements the ability to share files across different endpoints. the ZTM App can run on almost all endpoint platforms, including ios, macos, Linux, Windows, Andriod, etc. Therefore, developers can quickly build their own decentralized, adapted to a variety of platforms applications on top of ZTM without relying on specific network, ZTM provides all the necessary infrastructure, including decentralized network.

Clone this wiki locally