How to access and control your Thing remotely – and securely.
Linux-based single-board computers like the Raspberry Pi, BeagleBone, RED Brick, UDOO, Galileo or Cubieboard are very popular choices in the Maker scene for building all kinds of devices needing plenty of computing power and internet connectivity - the Things in the so-called Internet of Things. And not just in the Maker scene - these low-cost, but powerful devices are increasingly used to build prototypes for commercial products as well.
The Perils of The Internet
So now you've built your own super-awesome home automation, garden irrigation, weather station or security camera system, or something even more intriguing. And you start to think... "what if I could access my device not just from my home network, but from anywhere." Your first thought is to forward a port (e.g. for the web server) through your broadband router and use DynDNS or a similar technology to find your device on the internet. But then you remember that strange search engine, Shodan, and how it can search for devices on the internet. And suddenly you feel not entirely comfortable exposing your precious little device to the perils of the internet. So what can you do? A VPN may be an option, but then you'll have to run your own VPN server at home, which is not really that much fun to set-up (remember all the ports you'll need to forward on your router for L2TP?). Also, you'll have to set-up a VPN connection to your home every time you want to check your device. Not fun. So, what can you do?
macchina.io Remote Manager To The Rescue!
macchina.io Remote Manager to the rescue! Remote Manager is cloud-ready service providing secure remote access to connected devices via HTTP(S) or other TCP-based protocols and applications such as secure shell (SSH) or Virtual Network Computing (VNC). With Remote Manager, any network-connected device running the Remote Manager agent software (WebTunnelAgent) 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 Remote Manager server against unauthorized or malicious access. And the best: macchina.io Remote Manager is a free for connecting up to five devices. You don't even have to run your own server. There is a public server available that you can readily use. (Professional users prefer run their own instance of the Remote Manager server, though.)
Secure remote access via HTTP, SSH or VNC
So what can Remote Manager do for you? Basically, Remote Manager allows you to access your device from anywhere there's an internet connection, via HTTP, SSH, VNC or any other TCP-based protocol. The most frequent scenario is to access the built-in web user interface of the device remotely. However, Remote Manager can also be used to access the device via SSH, and, with the latest release, even via VNC. There's even a web-based VNC client (noVNC) integrated into Remote Manager. So you can access the desktop of your Raspberry Pi (or any other device with a display and graphical user interface) from anywhere using just a web browser. Ain't that cool?
Getting Started With Remote Manager
How to get started with Remote Manager? Well, follow the steps described at the macchina.io website. Specifically:
Go to the Remote Manager Sign Up page and create a new account by providing your name and email address, as well as a password. Click the "Sign up" button and a couple of seconds later you'll receive a confirmation email. (Provided you've given the correct email address, of course. So please double-check it for typos before hitting "Sign up".) Click the activation link in that email and follow the instructions to sign in with your email address and password to activate your account.
Building The Device SDK
The next step is to install the WebTunnelAgent software on your device. For a couple of popular platforms (e.g. Raspberry Pi) there are readily-built executables available. You can also build the WebTunnelAgent daemon yourself. To do so, download the SDK and build it.
Following are the steps to build the SDK on a Linux system with a native toolchain (i.e., the GCC on your Raspberry Pi, not a cross-toolchain for your device on your PC. Cross-compiling the API is of course possible as well, and you can check the README file in the SDK for how it's done, but it's beyond the scope of this blog post). The following steps are done in the shell on your device so it's a good idea now to open a SSH session to your device. Or open a terminal window on your device's desktop if you have a display and keyboard connected to your device.
The SDK is written in C++, so obviously you'll need a C++ compiler - g++ - to build the SDK. On most Debian-based systems (such as Raspbian) you can run:
sudo apt-get install g++
to install the compiler. While at apt-getting stuff, also be sure to get the other prerequisites: GNU Make:
sudo apt-get install make
and the OpenSSL libraries and headers:
sudo apt-get install libssl-dev
Next, get the SDK source code from GitHub and unpack it:
git clone https://github.com/my-devices/sdk.git
Now we're ready to build the SDK:
cd sdk
./buildsdk.sh
Building the SDK takes a couple of minutes (depending on the performance of your device), so you may want to have a quick coffee now. Or check Twitter or Facebook and tell your friends about macchina.io.
After the build completes you'll find the WebTunnelAgent executable in ./WebTunnel/samples/WebTunnelAgent/bin/Linux/armv7l/.
If you're on a first-generation Raspberry Pi or another device with armv6l or other non-armv7l architecture, the path to the executable will be different in the last component. But you have probably figured that out yourself.
Configuring The Device For Remote Access
The only thing now preventing you from connecting your device to the Remote Manager server is a proper configuration file for WebTunnelAgent. There's one included in the SDK (./WebTunnel/samples/WebTunnelAgent/WebTunnelAgent.properties), but you'll need to make a little change to it before it can be used. Specifically, you need to put your "Domain UUID" into the configuration file. The "Domain UUID" is a unique string (hence, UUID - Universally Unique IDentifier) that is used by the Remote Manager server to determine which devices a particular user account may access. So now is a good time to try out your newly created Remote Manager account. You have already clicked the activation link in the registration confirmation email, and signed-in with your email address and password, haven't you? If not, now would be a really good time. After logging in to the Remote Manager server, you'll see the Dashboard page. At this point you obviously don't have any devices connected, so it says "No devices found.", which, admittedly, is a bit disappointing. But we'll fix that in a minute.
Click on the "user" icon or your email address at the top right of the page to go to your Account page. Under the "User Properties" heading you'll see your username and email address (which will be the same), and below that the "Domain UUID", something like "2c687a83-a00a-4f82-9efe-d5779a72e9d9". Copy that string to the clipboard, you'll need to paste it into the WebTunnelAgent.properties file next. So, on the device, open the ./WebTunnel/samples/WebTunnelAgent/WebTunnelAgent.properties file with your favorite editor, and locate the line that says:
webtunnel.domain = 00000000-0000-0000-0000-000000000000
It's the first line after the comments at the top (comments are those lines starting with a '#'). Replace the 00000000-0000-0000-0000-000000000000 with the Domain UUID from your Remote Manager server account page. Next, locate the line that says
webtunnel.ports = 80
If the web server on your device does not run on port 80, replace 80 with the actual port of your web server. Also, you may want to add the SSH (22) and VNC (5900) ports, as well:
webtunnel.ports = 22, 80, 5900
If your web server does not run on port 80, you'll also have to find the line (it's the next non-comment line below) that says:
webtunnel.httpPort = 80
and change the port number accordingly. Finally, if you also want to access your device via VNC as well, uncomment the line that says
# webtunnel.vncPort = 5900
by removing the "#" at the beginning. Also, make sure that the port number specified here matches the port number of your VNC server. If you don't have a VNC server on the device (or don't want to access it remotely), leave the line as-is.
Now you're ready for the first connection. Simply run the WebTunnelAgent binary:
./bin/Linux/armv7l/WebTunnelAgent
You should see the following output:
2015-09-22 16:43:16.720 [Information] Application<1>: Connecting to https://reflector.my-devices.net...
2015-09-22 16:43:17.461 [Information] Application<1>: WebTunnel connection established.
Now go to the Dashboard page in the Remote Manager server web interface (click the Home button on the top left), or, if you're already there, click the Refresh button. You should now see your device.
Clicking the device name will open a new web browser tab with the web user interface of your device. If you have also configured a VNC port for your device, and have a VNC server running (you can find instructions for doing so on a Raspberry Pi and similar Debian-based systems here), you can click on the VNC icon to the right to launch the web-based noVNC client.
Enter the VNC password for your device and click Connect to see your device's desktop in your browser. Awesome, ain't it?
Now there's one thing left to do: the WebTunnelAgent has been manually started from the command-line. You may want to run it as a daemon, starting automatically when your device boots. To do this, you'll need to create a startup script and place it in the /etc/init.d directory. A suitable script is shown in the following:
#!/bin/sh -e
### BEGIN INIT INFO
# Provides: WebTunnelAgent
# Required-Start: $local_fs $remote_fs $network $syslog
# Required-Stop: $local_fs $remote_fs $network $syslog
# Default-Start: 2 3 4 5
# Default-Stop: 0 1 6
# X-Interactive: true
# Short-Description: Start/stop my-devices.net WebTunnelAgent
### END INIT INFO
. /lib/lsb/init-functions
SERVICE=WebTunnelAgent
PIDFILE=/var/run/${SERVICE}.pid
EXEC=/usr/local/sbin/$SERVICE
CONFIG=/etc/${SERVICE}.properties
if [ ! -x $EXEC ] ; then
echo "No $EXEC executable found"
exit 0
fi
start() {
log_daemon_msg "Starting $SERVICE: "
$EXEC --pidfile=$PIDFILE --daemon --config=$CONFIG
log_end_msg 0
}
stop() {
log_daemon_msg "Stopping $SERVICE: "
if [ -f $PIDFILE ] ; then
pid=`cat $PIDFILE`
kill $pid
log_end_msg 0
else
log_end_msg 1
fi
}
case "$1" in
start)
start
;;
stop)
stop
;;
restart|reload|condrestart)
stop
sleep 5
start
;;
*)
echo $"Usage: $0 {start|stop|restart|reload}"
exit 1
esac
exit 0
Copy the above script to /etc/init.d/WebTunnelAgent and make it executable:
chmod +x /etc/init.d/WebTunnelAgent
Then copy the WebTunnelAgent executable to /usr/local/bin:
sudo cp WebTunnel/bin/Linux/armv7l/WebTunnelAgent /usr/local/sbin
Next, copy the WebTunnelAgent.properties configuration file to the /etc directory:
sudo cp WebTunnel/WebTunnelAgent.properties /etc
Then run the following commands to enable the WebTunnelAgent daemon at system startup:
sudo update-rc.d WebTunnelAgent defaults
sudo update-rc.d WebTunnelAgent enable
The last step is to make a small change to the WebTunnelAgent.properties configuration file. Open /etc/WebTunnelAgent.properties in your favorite editor (with sudo) and locate the line that says:
logging.loggers.root.channel = console
Change that line to:
logging.loggers.root.channel = syslog
and uncomment these lines further down in the file:
# On Linux we can use syslogd for logging.
logging.channels.syslog.class = SyslogChannel
logging.channels.syslog.pattern = %s: %t
logging.channels.syslog.name = webtunnels
logging.channels.syslog.facility = SYSLOG_LOCAL0
This way, the logging output of WebTunnelAgent will go to the system logfile. Alternatively, you can also change the line to:
logging.loggers.root.channel = file
to direct the logging output to a file of your choice. Specify the log file path by changing the line:
logging.channels.file.path = ${application.dir}${application.baseName}.log
to something like:
logging.channels.file.path = /var/log/${application.baseName}.log
Now you can enter the command:
/etc/init.d/WebTunnelAgent start
to start WebTunnelAgent as a daemon. Furthermore, WebTunnelAgent will start automatically whenever your system boots.
Congratulations, you can now access your device securely, from everywhere you have internet access.
Be sure to check out the macchina.io website for more information.
Updated July 27, 2018 - my-devices.net has been renamed to macchina.io Remote Manager