macchina.io REMOTE Connect (remote-connect)

remote-connect is a command-line program that sets up a TCP connection from your local machine (e.g., your PC, Mac, etc.) to a device connected to the macchina.io REMOTE server. The connection is then exposed via standard input/output. This enables remote-connect to be used in a similar way to netcat (nc).

Additionally, remote-connect can be used with the ProxyCommand configuration directive of OpenSSH, enabling an alternative way of connecting to a remote device via SSH in addition to the remote-ssh command.

An interesting use case is using remote-connect with Visual Studio Code's Remote-SSH feature to do remote development on a device connected to the macchina.io REMOTE server.

Running remote-connect

remote-connect usually does not need a configuration file, most parameters can be passed via command-line arguments. Some settings can be set using a configuration file (see the remote-client documentation for more information on configuration files).

At startup, remote-connect will look for a configuration file named .remote-connect.properties or .remote-client.properties in the current user's home directory, and read it if it's present.

To run remote-connect, you'll need to specify the host name of the remote device to connect to, as well as the port number, e.g. 8ba57423-ec1a-4f31-992f-a66c240cbfa0.remote.macchina.io:22.

Username and password or an authentication token for the macchina.io REMOTE server must be either passed via command-line options, via a configuration file or remote-login, or via environment variables REMOTE_USERNAME and REMOTE_PASSWORD. remote-connect will not prompt for username and password, and will fail to connect if username and password are not specified. The recommended way to authenticate remote-connect is by using remote-login.

Example:

remote-connect -u johndoe -p s3cr3t 8ba57423-ec1a-4f31-992f-a66c240cbfa0.remote.macchina.io:80

The above command connects to port 80 (web server) of the target device. It's then possible to send a HTTP request to the device via standard input.

Using remote-connect with OpenSSH

The OpenSSH ProxyCommand can be used to have the OpenSSH client connect via remote-connect. This has some advantages over the remote-ssh program. Most importantly, other programs that use ssh to connect to a device can now be used with remote devices via macchina.io REMOTE, by providing a ProxyCommand configuration directive, either on the command-line or via the OpenSSH configuration file (~/.ssh/config). An example for such a program is Visual Studio Code, with the Remote-SSH feature.

Command Line

export REMOTE_USERNAME=johndoe
export REMOTE_PASSWORD=s3cr3t
ssh -o 'ProxyCommand remote-connect 8ba57423-ec1a-4f31-992f-a66c240cbfa0.remote.macchina.io:22' pi@8ba57423-ec1a-4f31-992f-a66c240cbfa0.remote.macchina.io

Configuration File

~/.ssh/config:

Host 188d3d96-b14e-4804-a6c6-4407af5108a3.remote.macchina.io
  ProxyCommand remote-connect -u johndue -p s3cr3t 188d3d96-b14e-4804-a6c6-4407af5108a3.remote.macchina.io:22

SSH Command:

ssh pi@188d3d96-b14e-4804-a6c6-4407af5108a3.remote.macchina.io

Command-Line Arguments Help

You can run remote-connect without command-line options (or with --help or /help on Windows) to see a help screen with available command-line options.