Setting up CrossBox 2

CrossBox 2 uses SSH co communicate between client and server, so no or very little setup is required to be able to connect to your Mac, Linux or Windows machines from your IDE.

SSH can use passwords (usually not recommended/used) or public/private key pairs for authentication.

If password authentication is enabled, connecting is easy – simply provide your username and password in the IDE when connecting, and you're done.

To use key based authentication, you will have two key files, a public and a private key. The private key should be kept secret and not shared with anybody; you need this key on the client (e.g. in Fire, Water or Visual Studio) to connect. On the server, only the public key is needed. This key file, as the name implies, is safe to share freely and unsecurely.

  • If you already have an existing key pair on the client, you can also simply add the public key on the server, as described below.
  • If not, you can create a new key pair on any Mac or Linux machine. Copy the private key over to where you're running Fire, Water or Visual Studio.

1. Creating or Finding a Key Pair

If you already know about SSH and know you have a key pair you can use, you can skip this step.

Mac

macOS comes with SSH already installed, and you might already have a key pair. Open Terminal.app on your Mac and look at the ~/.ssh folder (if it exists), by typing ld ~/.ssh. If the folder exists and contains two files called id_rsa and id_rsa.pub, you are already set, and can use these files as private and public key file.

If they do not exist, you can run the following command: ssh-keygen -m PEM -t rsa -C "you@example.com", replacing the email address with your real address. This should create id_rsa and id_rsa.pub files for you.

Linux

Most Linux environments come with SSH already installed, in the form of OpenSSH. You can see if your Linux machine is reachable by SSH using the ssh command. If OpenSSH is not installed (or not configured for remote access), please consult your distribution's documentation for setting up SSH (usually by running something like sudo apt install openssh-server).

...

Windows

There's currently no easy way to create a key pair on Windows, so if you are using Water or Visual Studio and want to connect to a Mac or a Linux machine, we recommend generating the key file there, with the steps outlined above, and then copying/moving the private key file to your client machine.

2. Enabling SSH Access on the Server

Mac and Linux

Enabling access to your Mac or Linux machine via SSH is easy. Simply take the contents of your public key file and add it as a new line to the ~/.ssh/authorized_keys files in the home directory of the appropriate user. If the file does not exist, you can simply copy the id_rsa.pub into ~/.ssh/ and rename it to authorized_keys.

On Mac, you might also need to enable SSH by opening the "System Preferences" app, selecting "Sharing" and then checking the "Remote Login" option.

If you have any Firewalls installed/active, also make sure that port 22 is open.

3. Connecting from the Client

If in the first step above you used an existing (or created a new) key pair on your client machine, then Fire, Water or Visual Studio should automatically pick that file up and use it when you try to register a new server. If not, you can copy the id_rsa perivate key file to any location of your choosing, and browse to it from the "Register CrossBox Server" dialog.

Additional Steps

Most Linux environments also already come with GDB, the GNU Debugger, installed. You can confirm this by running gdb from the command line. If GDB is not installed yet, please consult your distribution's docs on how to install it (usually by running something like sudo apt-get install gdb).

REMEMBER to keep your private key file private and never share it with anyone. It is like a password, and anyone getting access to your private key will be able to connect to any servers where your public key is configured to allow access.

See Also