4. HOWTO : File Sharing between ZTM End Points

ztm introduced an app in release 0.2, called ztm app. ztm app is a kind of independent program that can be launched, called, and managed by ztm. ztm app needs to follow some interfaces, and ztm app can use and access to some context information provided by ztm, such as ep and user. The ztm-app can be compared to the mini-app that is common in many software applications. By running the ztm-app inside the ztm, the application scenarios of the ztm can be quickly extended. From the perspective of controlling process execution, one can also use kubernetes and service/pod to analogize ztm with ep and ztm app, where ztm schedules the execution of ztm app on ep. Before we dive into the principles, mechanisms, and interfaces of ztm apps, let's take a look at a built-in ztm app called “cloud”, which can be found at https://github.com/flomesh-io/ztm/tree/main/agent/apps/ztm/cloud . It is called “cloud”, and the code is available at . Hereafter, it is called cloud app for short.

The cloud app implements the ability to share files between different ep's. The following is an example to demonstrate and introduce it. The following is an example to demonstrate and introduce the cloud app. In this example, we have two ep's, one running on macos, which is a mobile office laptop, and the other running at home, which is Ubuntu Linux. demonstrate how to send the files from the laptop to Ubuntu.

Deployment

First we need to build the ztm environment with one hub and two ep's (macos and ubuntu). The process of deploying hub and macOS can be found in this document: https://github.com/flomesh-io/ztm/wiki/2.-HOWTO-:-using-ztm-for-secure-RDP-access . Deploying ZTM Agent on ubuntu is very simple, first download ztm, you can download it from the ztm release page on github, or you can compile it yourself from source code, refer to https://github.com/flomesh-io/ztm/blob/main/docs/Build. md . After downloading or compiling the ztm executable, simply execute the following commands to start the ZTM Agent:

sudo systemctl start ztm-agent
~~~bash sudo systemctl start ztm-agent

Then register the ubuntu node to the ztm hub, usually a command like this will do:
~~~bash
ztm join my-mesh --as my-ubuntu --permit root.json

After successful registration, you can view the mesh, ep, and app with the following commands:

ubuntu@ip-172-31-11-117:~$ ztm get mesh
NAME JOINED AS USER HUBS STATUS
ca-mi hub-local root 99.79.67.33:443 Connected
ubuntu@ip-172-31-11-117:~$ ztm get ep
NAME USER IP PORT STATUS
hub-local (local) root 99.79.67.33 44320 Online
macos root 175.162.13.165 49478 Online
ubuntu root 119.109.35.231 60620 Online
ubuntu@ip-172-31-11-117:~$ ztm get apps
NAME TAG STATE
root/files downloaded, published, running
ztm/cloud builtin, running
ztm/proxy builtin, running
ztm/script builtin
ztm/terminal builtin
ztm/tunnel builtin, running
ztm/script builtin ztm/terminal builtin

Share files on macOS

As in the last step above, we see that the status of ztm/cloud is running, indicating that the cloud app is already running. Next we share a file on macos. On each ep, ztm uses a separate directory to store the files that need to be shared, which ensures that only the files in the directory are accessible, similar to how a web server needs to set up a Root Directory. This directory is ~/ztmCloud by default, but of course you can also specify this directory yourself by specifying the phone number of the directory with the command:

ztm cloud config --local-dir /path/to/my/local

So the first step in sharing files is to copy the files that need to be shared to this directory, the demo file I used is called a.jar, this file is about 74M.

cp ~/a.jar ~/ztmCloud/users/root/

Here, users is the word directory specified by ztm; root is the current username, and the files are all placed in the username's word directory. Then use the ztm cloud ls command to see the newly added files:

caishu@caishu-macair4 % ztm cloud ls /users/root
NAME STATE SIZE DATE SOURCES SHARED
a.jar new 74384901 Tue Sep 17 21:50:19 2024 0 -

Note that the STATE here is new, which means that the file is currently on the macos ep. We need to use the ztm cloud upload command to upload this file information to the hub so that other ep can see this file:

caishu@caishu-macair4 % ztm cloud upload /users/root/a.jar
File uploaded: /users/root/a.jar

At this point, if you use the ztm cloud ls command again, you will see that STATE has changed to SYNCHRONIZED:

caishu@caishu-macair4 % ztm cloud ls /users/root
NAME STATE SIZE DATE SOURCES SHARED
a.jar synced 74384901 Tue Sep 17 21:50:19 2024 1 -

Download the file on ubuntu

Next, we download the file a.jar on ubuntu. Note that in ztm, ubuntu is downloaded directly from macos, and the file is not uploaded to the cloud, so it has a high level of security and privacy protection; this feature is also different from the web2.0 file sharing mechanism such as netdisk. In ztm, the transmission mechanism behind is similar to the establishment of a tunnel, forming a kind of p2p transmission capability. First let's look at this file on ubuntu:

ubuntu@ip-172-31-11-117:~$ ztm cloud ls /users/root/
NAME STATE SIZE DATE SOURCES SHARED
a.jar missing 74384901 Tue Sep 17 13:53:41 2024 1 -

You can see that STATE is missing, which means that ubuntu does not have this file locally. Let's use the ztm cloud download command to download the file:

ubuntu@ip-172-31-11-117:~$ ztm cloud download /users/root/a.jar
ubuntu@ip-172-31-11-117:~$ ztm cloud ls /users/root/a.jar
NAME STATE SIZE DATE SOURCES SHARED
a.jar synced 74384901 Tue Sep 17 13:53:41 2024 2 -

After the download is successful, STATE becomes synced. the file is now saved to the ~/ztmCloud/ directory because we started it with the systemctl start ztm-agent command, which runs under the root user, so the file is saved under /root/ztmCloud.

ubuntu@ip-172-31-11-117:~$ sudo ls -lh /root/ztmCloud/users/root/
total 71M
-rw-r--r-- 1 root root 71M Sep 17 13:53 a.jar

At this point, we are done with the file sharing and downloading demo. Take it a step further and see what the cloud app is capable of.

View files on macOS

After downloading on ubuntu, the a.jar file is now saved on both ep's of ztm, one on macos and one on ubuntu. Therefore, when we run ztm cloud ls on macOS again, we can see that the sources of the file has changed to 2.

caishu@caishu-macair4 files % ztm files ls /users/root
NAME STATE SIZE DATE SOURCES SHARED
a.jar synced 74384901 Tue Sep 17 21:50:19 2024 2 -

At this point, if another user downloads the file from a third ep, ztm will automatically try to download parts of the file from each of the two sources, and then assemble the finished file. If one of the ep's goes offline, ztm will automatically download the file from the remaining surviving ep's. cool~