What problem does macchina.io REMOTE solve?
Many embedded and IoT devices are equipped with a built-in web server for configuration, control or monitoring purposes. This would be a great tool for remote access to the device. However, access to the device's web server from a remote location is rarely possible. Embedded devices in the field are often connected to private networks behind NAT routers or firewalls. Even devices connected to a mobile network (4G/LTE) in most cases do not have public IP addresses and thus are not directly reachable. Furthermore, it is rarely a good idea to expose a device directly to the internet for security reasons. Existing solutions to this problem like Virtual Private Networks (VPNs) or NAT port forwarding with Dynamic DNS are complicated to setup and operate (or in case of NAT port forwarding, just plain insecure), and don't work in all cases.
How does macchina.io REMOTE work?
macchina.io REMOTE uses a HTTP-based tunneling protocol based on RFC-6455 WebSockets. An agent application (WebTunnelAgent) running either directly on the device, or on another device in the same network (a router, gateway or desktop system) opens a WebTunnel connection to the reflector server. The reflector server then uses this tunneling connection to send HTTP requests or other TCP protocol payloads to the device.
Since the device actively opens the connection, NAT routers or firewalls do not block the connection. Furthermore, the WebTunnel protocol is based on the standard WebSocket protocol, which again is based on HTTP. This makes the connection work even across a HTTP proxy server and also a firewall is less likely to block the connection.
In a typical usage scenario, more than one device will be connected to a reflector server. Therefore, when the reflector receives a HTTP request from a client, it needs to find out to which device the request must be forwarded. The domain name system (DNS) is used for that purpose, by giving each device a unique domain name (e.g.: device1.remote.macchina.io). This requires setting up a wildcard DNS record in the DNS server which resolves all requests for *.remote.macchina.io to the reflector server remote.macchina.io. The reflector server can then use the Host header in the HTTP request together with an internal table to associate the request with a specific device and forward the request appropriately.
Won't IPv6 make solutions like macchina.io REMOTE obsolete?
Absolutely not. While IPv6 saves the IPv4 address shortage issue, making it possible to given every device a universally unique IP address, nobody with at least a little sense of security will expose embedded devices directly to the internet. Firewalls will still be used to shield devices from the open internet and solutions like macchina.io macchina.io REMOTE will still be necessary.
Is macchina.io REMOTE secure?
Short answer: Yes! Long answer: Three features make macchina.io REMOTE secure. First, both connections, from the device to the reflector server and from the client browser to the reflector server are encrypted using TLS. Second, the device does not need to have any ports open. The reflector server (and only the reflector server) can send requests to the device only over the WebTunnel connection initiated by the device. Third, all requests to the device over the reflector server require authentication with username and password. Two-factor authentication based on Time-based One-Time Passwords (TOTP) is supported.
How can I connect my own devices to macchina.io REMOTE?
The WebTunnelAgent application is used to connect a device to the reflector server using the WebTunnel protocol, a custom protocol based on the WebSocket specification. The WebTunnelAgent application usually runs directly on the device, but it can also run on a separate device (e.g. a router or gateway), or desktop system.
The WebTunnelAgent is part of the macchina.io REMOTE Device SDK. The SDK is available in source code, written in portable C++, based on the POCO C++ Libraries and can be built for embedded Linux, Windows Embedded and other embedded operating systems.
My device has a REST or SOAP API. Can I access it with macchina.io REMOTE?
Yes, the reflector server transparently forwards HTTP requests to device, so macchina.io REMOTE can also be used to make your device's REST or SOAP API available remotely. In fact, this makes macchina.io REMOTE a great solution for integrating remote devices with mobile or tablet apps, as well as enterprise applications. HTTP requests sent to the device via the reflector server must include authentication information, either in the form of a session cookie or a special authentication header, so your client software must support that. Please see the API documentation for more information regarding authentication.
Can I access my device via SSH or other TCP-based protocols?
Yes, the reflector server can securely forward virtually all TCP-based protocols from the device to a remote client via the WebTunnel connection. In order to set up the tunnel through the reflector server to the device, the client computer must run the macchina.io REMOTE Helper application for Windows, or the remote-client (or remote-ssh) command-line tool. The WebTunnel client SDK can also be integrated directly into the client application.
To use remote-client or remote-ssh, please download the macchina.io REMOTE Command-Line Client Tools, or get the macchina.io REMOTE SDK, which also the client applications, and build it from source, as described in the README file.
Configure the WebTunnelAgent on the device to forward port 22 (or any other TCP ports) by adding the respective port number(s) to the webtunnel.ports property in the WebTunnelAgent.properties configuration file:
webtunnel.ports = 80, 22
webtunnel.sshPort = 22Also set the webtunnel.sshPort property in the WebTunnelAgent.properties configuration file, so you'll get a dedicated SSH button in the web user interface, which will launch the macchina.io REMOTE Helper application on Windows, which will set up the SSH connection to the device.
Then restart WebTunnelAgent.
If you cannot run macchina.io REMOTE Helper, use the remote-ssh command-line utility. On your client device, run remote-ssh with the URL of your device as agument, e.g., https://54c87bb9-6984-4be5-b658-d747090b204d.remote.macchina.io. You'll have to replace the UUID with the one of your device. This is the address shown in your browser when you click on the device name in the reflector server dashboard.)
Start remote-ssh like this:
remote-ssh https://54c87bb9-6984-4be5-b658-d747090b204d.remote.macchina.ioYou can also specify the remote username for the SSH session, using the --login-name (or short -l; on Windows use /login) option:
remote-ssh -p pi https://54c87bb9-6984-4be5-b658-d747090b204d.remote.macchina.ioOn Windows, use:
remote-ssh /login pi https://54c87bb9-6984-4be5-b658-d747090b204d.remote.macchina.ioremote-ssh will prompt you for your macchina.io REMOTE username and password, and then start the SSH client on your system. On Linux and macOS, this is /usr/bin/ssh. On Windows, remote-ssh will try to launch ssh.exe (which is available in Windows 10 since April 2018 as an optional install) or, if not found, putty.exe as SSH client. Make sure the path to ssh.exe or putty.exe is in your PATH environment variable.
Can I access my device via VNC?
Yes, the reflector server can securely forward the Remote Frame Buffer protocol (RFB) used by Virtual Network Computing. The reflector server even includes noVNC, a purely web-based VNC viewer, allowing you to remote control a device directly from your web browser.
To enable VNC remote access via macchina.io REMOTE, install a VNC server on your device and configure WebTunnelAgent to enable and forward the VNC port, usually 5900.
webtunnel.ports = 80, 5900
webtunnel.vncPort = 5900You are now able to open a VNC session directly from the reflector server's web interface.
Can the reflector server act as a HTTP proxy for connected devices?
Yes, starting with release 1.10 the reflector server can act as a HTTP proxy for connected devices. Clients can send a HTTP CONNECT request (with proper proxy credentials) to open a tunnel connection to a specific port on a connected device. This means that any network client supporting connections through a HTTP proxy server can be used with the reflector server.
Can I run my own reflector server?
Yes. Customers wanting to operate their own reflector server can license the server software from Applied Informatics. The server software is fully customizable and extensible through plug-ins and web service APIs, enabling building customer-specific device management solutions on top of it. Please contact us for more information and pricing.
Is there an API?
Yes. Here is the REST API documentation.
Can I customize or modify the reflector server web interface to match my corporate design?
Yes, there are multiple ways to add a custom-styled web interface to the reflector server. The simplest way is by providing a custom style sheet for the server, along with configuration file settings. This allows modifications like custom logos and a custom color scheme, as well as localization or customization of all text in the user interface. Furthermore, it is also possible to integrate custom login, dashboard and error pages, which can be hosted on an external web server (e.g., Apache with PHP, etc.).
What are the restrictions of a free account?
The free account has the following restrictions:
- You can create and connect up to ten devices.
- Authentication for devices (device password) is not available.
- Users and permissions management features are not available.
- We make no guarantees regarding the availability of the reflector server.
- We reserve the right to disable or terminate a free account at any time, without cause or notice.
- For more information, please see our Terms of Service.