<commit_before>Tunnel Manual
=============

Tunnel is a set of scripts that simplify launching remote *Mathematica* kernels, where all
established MathLink connections are automatically tunneled through a secure shell connection.

Tunnel is an improved version of the [Remote Kernel Strategies][remote_kernel_strategies] solution
originally presented at the *Mathematica* User Conference 2008. The new version contains
compatibility fixes for newer versions of *Mathematica* and also supports remote compute kernels.

Beginning with *Mathematica* version 10, MathLink has been rebranded as [WSTP][wstp]. This manual
sticks with the name MathLink.

Features
--------

* Supports launching of remote *Mathematica* controller kernels from the *Mathematica* front end.
* Supports launching remote *Mathematica* compute kernels with the Parallel package.
* MathLink connections to the remote kernel are tunneled over SSH. This simplifies connecting to a
  remote kernel behind a firewall or a NAT router over the Internet.
* Works with Windows, Linux and OS X versions of *Mathematica*.
* Compatible with *Mathematica* versions from 7.0 to 10.1.

Requirements
------------

* A Wolfram [*Mathematica*][wmma] product (Mathematica, gridMathematica, Wolfram Finance Platform).
* OpenSSH client and server under Linux and OS X.
* [PuTTY][putty] on a Windows *Mathematica* front end machine.
* An SSH server on a remote Windows *Mathematica* kernel machine (see below).

Installation
------------

### script-aided installation

Execute the shell script `install-tunnel.sh` under Linux or OS X to install the required scripts
to the correct locations for an existing *Mathematica* installation. Under Windows, execute the
batch script `install-tunnel.bat` to install the required scripts.

The installation must be performed on both the local machine that runs the *Mathematica* front end,
and on the remote machine that runs the *Mathematica* kernel.

### manual installation

The file `tunnel.m` needs to be installed on the remote *Mathematica* kernel machine. It needs to
be placed into the `Kernel` sub-directory of the *Mathematica* base directory. To determine the
Mathematica base directory evaluate the expression `$BaseDirectory` in a *Mathematica* session.
E.g., under OS X launch Terminal.app and run:

    $ /Applications/Mathematica.app/Contents/MacOS/MathKernel
    Mathematica 10.1.0 for Mac OS X x86 (64-bit)
    Copyright 1988-2015 Wolfram Research, Inc.

    In[1]:= $BaseDirectory
    Out[1]= /Library/Mathematica

`$BaseDirectory` usually evaluates to `C:\ProgramData\Mathematica` under Windows 7, to
`/Library/Mathematica` under OS X and to `/usr/share/Mathematica` under Linux.

The accompanying script files `tunnel.sh` and `tunnel_sub.sh` (or `tunnel_sub.bat` and `tunnel.bat`
for Windows) need to be installed on the local *Mathematica* front end machine. They need to be
placed in the `FrontEnd` sub-directory of the *Mathematica* user-specific base directory.
To determine the *Mathematica* user-specific base directory evaluate the *Mathematica* expression
`$UserBaseDirectory` in a *Mathematica* session. E.g., under Windows launch cmd.exe and run:

    C:\>"C:\Program Files\Wolfram Research\Mathematica\10.1\math.exe"
    Mathematica 10.1.0 for Microsoft Windows (64-bit)
    Copyright 1988-2015 Wolfram Research, Inc.

    In[1]:= $UserBaseDirectory
    Out[1]= C:\Users\sakra\AppData\Roaming\Mathematica

`$UserBaseDirectory` usually evaluates to `C:\Users\user_name\AppData\Roaming\Mathematica` under
Windows, to `~/Library/Mathematica` under OS X and to `~/.Mathematica` under Linux.

Under Linux and OS X make sure to check that the executable bit of the copied scripts `tunnel.sh`
and `tunnel_sub.sh` is set.

Setup
-----

Tunnel requires setting up third party software on both the local front end machine and on the
remote kernel machine.

### Linux

Install OpenSSH client on the local front end machine:

    sudo apt-get install openssh-client

Install an launch OpenSSH server on the remote kernel machine:

    sudo apt-get install openssh-server

To make OpenSSH work, additional configuration may be required depending on the Linux distribution
used.

### OS X

OpenSSH is installed under OS X out-of-the-box. On a remote OS X kernel machine, start the OpenSSH
server by enabling Remote Login in the Sharing panel of the System Preferences application.

### Windows

Install [PuTTY][putty] on the local front end machine.

On the remote kernel machine an SSH server needs to be installed. Tunnel has been tested with the
following third party SSH servers:

  * [Bitvise SSH Server][winsshd]
  * [Cygwin][cygwin] OpenSSH is a heavy weight solution that you should only consider, if you are
    comfortable with a POSIX shell environment.
  * [freeSSHd][freesshd]

Configuration
-------------

### Remote controller kernels

To set up launching of a remote *Mathematica* controller kernel with Tunnel in the *Mathematica*
front end, choose the menu command `Kernel Configuration Options...` from the `Evaluation` menu and
create a new kernel configuration. In the kernel configuration dialog activate the<commit_msg>manual updates<commit_after>Tunnel Manual
=============

Tunnel is a set of scripts that simplify launching remote *Mathematica* kernels, where all
established MathLink connections are automatically tunneled through a secure shell connection.

Tunnel is an improved version of the [Remote Kernel Strategies][remote_kernel_strategies] solution
originally presented at the *Mathematica* User Conference 2008. The new version contains
compatibility fixes for newer versions of *Mathematica* and also supports remote compute kernels.

Beginning with *Mathematica* version 10, MathLink has been rebranded as [WSTP][wstp]. This manual
sticks with the name MathLink.

Features
--------

* Supports launching of remote *Mathematica* controller kernels from the *Mathematica* front end.
* Supports launching remote *Mathematica* compute kernels with the Parallel package.
* MathLink connections to the remote kernel are tunneled over SSH. This simplifies connecting to a
  remote kernel behind a firewall or a NAT router over the Internet.
* Works with Windows, Linux and OS X versions of *Mathematica*.
* Compatible with *Mathematica* versions from 7.0 to 10.1.

Requirements
------------

* A Wolfram [*Mathematica*][wmma] product (Mathematica, gridMathematica, Wolfram Finance Platform).
* OpenSSH client and server under Linux and OS X.
* [PuTTY][putty] on a Windows *Mathematica* front end machine.
* An SSH server on a remote Windows *Mathematica* kernel machine (see below).

Installation
------------

### script-aided installation

Execute the shell script `install-tunnel.sh` under Linux or OS X to install the required scripts
to the correct locations for an existing *Mathematica* installation. Under Windows, execute the
batch script `install-tunnel.bat` to install the required scripts.

The installation must be performed on both the local machine that runs the *Mathematica* front end,
and on the remote machine that runs the *Mathematica* kernel.

### manual installation

The file `tunnel.m` needs to be installed on the remote *Mathematica* kernel machine. It needs to
be placed into the `Kernel` sub-directory of the *Mathematica* base directory. To determine the
Mathematica base directory evaluate the expression `$BaseDirectory` in a *Mathematica* session.
E.g., under OS X launch Terminal.app and run:

    $ /Applications/Mathematica.app/Contents/MacOS/MathKernel
    Mathematica 10.1.0 for Mac OS X x86 (64-bit)
    Copyright 1988-2015 Wolfram Research, Inc.

    In[1]:= $BaseDirectory
    Out[1]= /Library/Mathematica

`$BaseDirectory` usually evaluates to `C:\ProgramData\Mathematica` under Windows 7, to
`/Library/Mathematica` under OS X and to `/usr/share/Mathematica` under Linux.

The accompanying script files `tunnel.sh` and `tunnel_sub.sh` (or `tunnel_sub.bat` and `tunnel.bat`
for Windows) need to be installed on the local *Mathematica* front end machine. They need to be
placed in the `FrontEnd` sub-directory of the *Mathematica* user-specific base directory.
To determine the *Mathematica* user-specific base directory evaluate the *Mathematica* expression
`$UserBaseDirectory` in a *Mathematica* session. E.g., under Windows launch cmd.exe and run:

    C:\>"C:\Program Files\Wolfram Research\Mathematica\10.1\math.exe"
    Mathematica 10.1.0 for Microsoft Windows (64-bit)
    Copyright 1988-2015 Wolfram Research, Inc.

    In[1]:= $UserBaseDirectory
    Out[1]= C:\Users\sakra\AppData\Roaming\Mathematica

`$UserBaseDirectory` usually evaluates to `C:\Users\user_name\AppData\Roaming\Mathematica` under
Windows, to `~/Library/Mathematica` under OS X and to `~/.Mathematica` under Linux.

Under Linux and OS X make sure to check that the executable bit of the copied scripts `tunnel.sh`
and `tunnel_sub.sh` is set.

Setup
-----

Tunnel requires setting up third party software on both the local front end machine and on the
remote kernel machine.

### Linux

Install OpenSSH client on the local front end machine:

    sudo apt-get install openssh-client

Install and start OpenSSH server on the remote kernel machine:

    sudo apt-get install openssh-server

To make OpenSSH work, additional configuration may be required depending on the Linux distribution
used.

### OS X

OpenSSH is installed under OS X out-of-the-box. On a remote OS X kernel machine, start the OpenSSH
server by enabling Remote Login in the Sharing panel of the System Preferences application.

### Windows

Install [PuTTY][putty] on the local front end machine.

On the remote kernel machine an SSH server needs to be installed. Tunnel has been tested with the
following third party SSH servers:

  * [Bitvise SSH Server][winsshd]
  * [Cygwin][cygwin] OpenSSH is a heavy weight solution that you should only consider, if you are
    comfortable with a POSIX shell environment.
  * [freeSSHd][freesshd]

Configuration
-------------

### Remote controller kernels

To set up launching of a remote *Mathematica* controller kernel with Tunnel in the *Mathematica*
front end, choose the menu command `Kernel Configuration Options...` from the `Evaluation` menu and
create a new kernel configuration. In the kernel configuration dialog activate the
{'fraction_non_alphanumeric': 0.0782296418518878, 'fraction_numerical': 0.00951179268174318, 'mean_word_length': 4.440337909186906, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 5, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4238960', 'n_tokens_mistral': 2937, 'n_tokens_neox': 2769, 'n_words': 1316}