The macchina.io REMOTE SDK and Tools

About macchina.io REMOTE

macchina.io REMOTE provides secure remote access to connected devices via HTTP or other TCP-based protocols and applications such as secure shell (SSH), secure file transfer (SFTP), Virtual Network Computing (VNC) or remote desktop (RDP). With macchina.io REMOTE, any network-connected device running the macchina.io REMOTE Device Agent software (WebTunnelAgent, contained in this SDK) can be securely accessed remotely over the internet from browsers, mobile apps, desktop, server or cloud applications.

This even works if the device is behind a NAT router, firewall or proxy server. The device becomes just another host on the internet, addressable via its own URL and protected by the macchina.io REMOTE server against unauthorized or malicious access. macchina.io REMOTE is a great solution for secure remote support and maintenance, as well as for providing secure remote access to devices for end-users via web or mobile apps.

Visit macchina.io/remote to learn more and to register for a free account. Specifically, see the Getting Started page and the Frequently Asked Questions for information on how to use this SDK and the included WebTunnelAgent executable.

There is also a blog post showing step-by-step instructions to connect a Raspberry Pi.

About This SDK

The macchina.io REMOTE SDK is based on the POCO C++ Libraries. You may want to read README_POCO as well as it contains important information regarding the directory structure and the build system of the SDK.

The SDK contains the WebTunnel library, which implements the tunnel protocol used by macchina.io REMOTE. Furthermore, the following executables are included:

• WebTunnelAgent: This executable, also known as macchina.io REMOTE Device Agent, runs on the device and creates the secure tunnel between the device and the macchina.io REMOTE server. This is the most important component of the macchina.io REMOTE SDK.
• remote-client: This executable can run on a client machine (Windows, macOS or Linux) to create a secure tunnel from the client machine to the remote device, via the macchina.io REMOTE server. It is required for tunneling TCP-based protocols not directly supported by macchina.io REMOTE, such Modbus/TCP, OPC-UA, database connections, etc.
• remote-ssh: This is a variant of remote-client that first creates a tunnel connection from your local machine (Windows, macOS or Linux) to the remote device, then launches a SSH client using that tunnel connection.
• remote-scp: This is a variant of remote-client that first creates a tunnel connection from your local machine (Windows, macOS or Linux) to the remote device, then launches a SCP (Secure/SSH File Copy) client (scp) using that tunnel connection.
• remote-sftp: This is a variant of remote-client that first creates a tunnel connection from your local machine (Windows, macOS or Linux) to the remote device, then launches a SFTP (Secure/SSH File Transfer Protocol) client using that tunnel connection.
• remote-vnc: This is a variant of remote-client that first creates a tunnel connection from your local machine (Windows, macOS or Linux) to a remote device running a VNC (Virtual Network Computing) server, then launches a VNC remote desktop client using that tunnel connection.
• remote-rdp: This is a variant of remote-client that first creates a tunnel connection from your local machine (Windows, macOS) to a remote Windows device (which must have the remote desktop feature enabled), then launches a Microsoft Remote Desktop (RDP) client using that tunnel connection.

There are also WebTunnelAgentLib and WebTunnelClientLib, which provide the functionality of WebTunnelAgent and remote-client, respetively, in a C API, suitable for integration into applications (not written in C++).

The macchina.io REMOTE SDK, like the POCO C++ Libraries the SDK is based on, is licensed under the Boost Software License.

Pre-Built Executables

Pre-built executables for Windows, macOS and some Linux distributions (including Raspberry Pi OS) are available from the macchina.io website.

Easy Install from Source (Linux and macOS)

The easiest way to install the above mentioned executables on a Linux or macOS system from source is to download and run the installer script with the following command:

$ curl https://raw.githubusercontent.com/my-devices/agent-installer/master/install.sh | bash

The script should work on most Debian and RedHat-based Linux distributions including Ubuntu and Raspberry Pi OS. On macOS, Homebrew must be installed.

The script will install all required dependencies, then get the sources from GitHub and run the steps necessary (see below) to build and install the binaries in /usr/local/bin/.

If you do not want to or cannot run the installer script, please see the following instructions.

External Dependecies

Libraries

The macchina.io REMOTE SDK requires OpenSSL 1.0 or newer on Linux and macOS systems. We recommend using OpenSSL version 1.1.1l or newer (including OpenSSL 3).

Most Unix/Linux systems already have OpenSSL preinstalled. If your system does not have OpenSSL, please get it from https://www.openssl.org or another source. You do not have to build OpenSSL yourself - a binary distribution is fine. For example, via Debian APT:

$ apt-get install openssl libssl-dev

On macOS, the easiest way to install OpenSSL is via Homebrew:

$ brew install openssl

On Windows, OpenSSL is optional. The default (with CMake) is to build using Windows native SSL/TLS support. However, it's also possible to use OpenSSL instead. The easiest way to install OpenSSL on Windows is to use a binary (prebuild) release, for example the one from Shining Light Productions that comes with a Windows installer.

Toolchain

A C++ compiler (C++14 or newer) is required to build the SDK and applications. The system's default compiler (gcc on Linux, clang on macOS) should be fine on reasonably recent systems. On Windows, Visual C++ is recommended (any version from 2015 to 2019 will do).

CMake 3.2 (or newer) is the recommended way to build the SDK.

Installing All Dependencies (Linux and macOS)

All dependencies can be installed with the following commands:

Debian Linux (including Ubuntu and Raspberry Pi OS)

$ sudo apt-get -y update && sudo apt-get -y install git g++ make cmake libssl-dev

RedHat Linux

$ sudo yum install -y git gcc-c++ make cmake3 openssl-devel

macOS (with Homebrew)

$ brew install cmake openssl

Building with CMake (Linux, macOS, Windows)

CMake (version 3.2 or newer) is the recommended build system for building the macchina.io REMOTE SDK.

$ git clone https://github.com/my-devices/sdk.git
$ cd sdk
$ mkdir cmake-build
$ cd cmake-build
$ cmake ..
$ cmake --build . --config Release

On macOS, it's necessary to tell CMake where to find the OpenSSL headers and libraries by setting the OPENSSL_ROOT_DIR CMake variable. For example, if OpenSSL 1.1.x has been installed with Homebrew, the cmake invocation becomes:

$ cmake .. -DOPENSSL_ROOT_DIR=/usr/local/opt/openssl

On an Apple Silicon Mac, Homebrew installs packages in /opt/homebrew, so the command becomes:

$ cmake .. -DOPENSSL_ROOT_DIR=/opt/homebrew/opt/openssl

If you want to link statically with OpenSSL libraries (recommended on macOS), add the -DOPENSSL_USE_STATIC_LIBS=TRUE option, e.g.:

$ cmake .. -DOPENSSL_ROOT_DIR=/usr/local/opt/openssl@1.1 -DOPENSSL_USE_STATIC_LIBS=TRUE

Other common ways of building with CMake (e.g., cmake-gui) will also work.

There are also a number of project-specific CMake variables that can be changed, e.g., to build with OpenSSL on Windows.

Cross-Compiling

With a proper CMake toolchain file (specified via the CMAKE_TOOLCHAIN_FILE CMake variable), the SDK can be cross-compiled for embedded Linux systems:

$ cmake .. -DCMAKE_TOOLCHAIN_FILE=/path/to/mytoolchain.cmake -DCMAKE_INSTALL_PREFIX=/path/to/target

If the cross-compiling toolchain does not contain OpenSSL, you'll also have to build it prior to building this project. See Cross Compiling with CMake for instructions.

Note: The resulting executables may contain debug information, which significantly increases their size. You should run xxx-yyy-linux-strip on the resulting executables to reduce their size before deploying them to the device.

NOTE: See README_iOS.md for iOS builds and README_Android.md for Android builds.

Installing

The SDK can be optionally be installed by building the install target. However, in most cases this is not necessary. The resulting executables in the cmake-build/bin directory are statically linked per default and can be moved to any directory desired.

If required, the SDK header files and libraries can be installed with:

$ sudo cmake --