FAQ Remote Kernels

If you don't already have a private-public dsa key pair on your local machine (skye.local, in this example) you must generate a set. (In fact if this all fails to work after a system upgrade or some other upset, the first thing to try when recovering, is to regenerate the key pair.) The easiest way to do this is with the OS X Terminal application and the ssh-keygen command. It is essential that you do not set a password on the key pair (just type return when prompted by ssh-keygen).

ssh-keygen -d

Secure copy the public key to the remote Mac OS X machine on which you intend to run the remote kernel (skye.local in this example). We assume here the same user name on both machines. If different, the path will have to include the user name on the remote machine. The public key (id_dsa.pub) is being copied to the file authorized_keys2 by the following scp command.

scp ~/.ssh/id_dsa.pub skye.local:.ssh/authorized_keys2

When this is done you should be able to run the remote kernel from a local Terminal session (no Front End), with no password, by executing the following line, assuming you have defined a unix shell script called math.sh that is sitting in your top directory on the remote machine, here skye.local.

ssh skye.local ./math.sh

The script math.sh contains the following 2 lines:

 #!/bin/sh
 /Applications/Mathematica.app/Contents/MacOS/MathKernel $@

You have to make the script executable in an OS X Terminal window, using:

chmod +x math.sh

If you don't have the script installed, you have to provide the complete path to the Mathematica kernel with something close to the following command:

ssh skye.local "/Applications/Mathematica.app/Contents/MacOS/MathKernel"

If this works and starts up the Kernel in an OS X Terminal window, without a password request, then this is a necessary, but not sufficient condition, for the Front End to connect to the kernel, using a similar command.

The Remote Kernel Configuration Options box will now have to be edited to add an entry for the new remote machine (skye.local). The entry will look like:

ssh skye.local "/Applications/Mathematica.app/Contents/MacOS/MathKernel" -mathlink 
 -LinkMode Connect -LinkProtocol TCPIP -LinkName "`linkname`" -LinkHost `ipaddress`

where we put in the complete path to the kernel, or we could have used the script math.sh also:

ssh skye.local "./math.sh" -mathlink -LinkMode Connect -LinkProtocol TCPIP -LinkName
 "`linkname`" -LinkHost `ipaddress`

This presumes the same user name on both machines. If different names, then the new user name goes in as ssh user@machine.name, ...

In the Kernel Configuration Options, if you select Append name to In/Out prompts you can see that skye.local is doing the calculations. If there are problems, you can set the Verbose option to ssh (using ssh -v ) and the ssh message traffic will appear in the Messages window.

All this works perfectly on Mathematica 5.2, and Mac OS 10.5 and later versions, but requires the OS X firewalls be shutdown on both machines. If you want the firewalls left on, they have to be configured to allow traffic on 2 ports, and these ports have to be specified in the LinkName in the Kernel Configurations Options. This is described below.

Mathematica Version 5.2 comes with a built-in implementation of ssh, which is available in the Kernel Configuration Options window as the default choice. The Version 5.2 mathssh client supports both password and publickey (RSA and DSA) authentication. The WolframSSHKeyGen application (located in SystemFiles/Java) can be used to create keys but I have not tried this. I used ssh-keygen as described above to make the keys.

The ssh implementation in Version 5.2 requires both Front End and remote kernel be Version 5.2. If you have to connect a 5.2 Front End to an older kernel, use the methods described above, which continue to work.

Here is an example of the Kernel Configuration Options window for Version 5.2 that works, and connects to the computer skye.local without needing a password, and assuming the user account is named "username".

`java` -jar "`mathssh`" username@skye.local ./math.sh -mathlink -LinkMode Connect -LinkProtocol TCPIP -LinkName "`linkname`" -LinkHost   `ipaddress`

Houston, we have a problem- Anyone with a proven way to set up Kernel Configuration Options for Mathematica 7 and Leopard (OS X 10.5.x) please comment here.

The following custom launch command works for me when launching remote kernels (Mathematica 7 on OS 10.5.x) from the Remote Kernels dialog box:

ssh `1` \"/Applications/Mathematica 7.app/Contents/MacOS/MathKernel\" -mathlink -linkmode Connect `4` -linkname `2` -subkernel -noinit >& /dev/null &

Using the built-in firewall with remote kernels

First, make sure you have a working set-up as described above - I used the ssh way to do things, with a dsa key-pair. This may or may not work with the mathssh java applet under Mathematica 5.2. For this example, Mathematica 5.2 was used.

In the Remote Kernel Configuration Options box (found under Kernel-Kernel Configuration Options..., click Edit for the apropriate kernel config, and then navigate to the Advanced Options), edit the Arguments to MLOpen to read

-LinkName 53001,53002 -LinkMode Listen -LinkProtocol TCPIP -LinkOptions MLDontInteract

i.e. change the 'linkname' entry to two specific ports, separated by a comma (no space).

Then, the Launch Command may have to be edited (this took a while to figure out); it should look something like this:

ssh remotehostname "./math.sh" -mathlink -LinkMode Connect -LinkProtocol TCPIP -LinkName `linkname` -LinkHost `ipaddress`

but it must not read

ssh remotehostname "./math.sh" -mathlink -LinkMode Connect -LinkProtocol TCPIP -LinkName "`linkname`" -LinkHost `ipaddress`

where the only subtle change is two double-quotes around `linkname`: make sure you remove them if present. Optionally, the same ports could be repeated from the MLOpen arguments, but that makes it more cumbersome to change ports.

With the firewall still turned off, you can try this to verify that your setting still works with your new changes. Add an exception in the firewall for the TCP ports you specified, and you should now be able to quit and restart the remote kernel. If it does not work, enable the firewall logging: click the "Advanced settings" button in the System Prefs pane. Check the ipwf.log-file in the Console.app found under /var/log as you try to start the remote kernel: this will tell you if you are having problems with the firewall set-up.

Notes:

• In the Kernel Configuration box, do not switch back to the "Basic Options" pane after you have entered anything in the "Advanced Options", or your changes will be lost
• While debugging, it is convenient to use the "Exit" command to quit the mathkernel. Sometimes, if you use "Quit kernel" menu command instead, you get an error message stating that the linkname is already in use. Wait a few minutes and try again, and it will probably work. Otherwise, try to see if the mathkernel is still running on the other machine. In some cases, it may be necessary to kill the remote process manually.
• Someone with more time and knowledge about firewalls and TCP/IP -traffic could add how to configure things for an external firewall, and integrate that in the original text to one, solid document.

Remote kernel via SSH tunnel (to get through firewall/NAT)

-LinkMode Listen -LinkProtocol TCPIP -LinkName 31415@127.0.0.1,31416@127.0.0.1 -LinkOptions MLDontInteract

For the launch command, I'm using:

ssh -R 31415:127.0.0.1:31415 -R 31416:127.0.0.1:31416 username@remote.host.name
 "math -mathlink -LinkMode Connect -LinkProtocol TCPIP
 -LinkName 31415@127.0.0.1,31416@127.0.0.1 -LinkHost 127.0.0.1"

The port numbers 31415 and 31416 are arbitrary non-privileged ports.

The important bit here is the use of the numeric "127.0.0.1" instead of "localhost", and the explicit specification of the host IP address in the LinkName. If either of these are missing, ssh may spit back a "Connection reset by peer" error as part of the forwarding process gets confused by naming semantics.

This can almost certainly be made cleaner, but the basic idea works for me.