SSH Kernel - an ipykernel over ssh

A remote jupyterkernel via ssh

Free software: MIT license

The ideas are heavily based on remote_ikernel, however ssh_ipykerneladds some important features

jupyter_client's function write_connection_file is used on the remote server to get free ports
Local ports (obtained by jupyter also via write_connection_file) will be ssh forwarded to the remote ports
The ssh connection and the tunnel command will be retried in case of network or similar errors
introduced signal handling with python's signal module

Installation

pip install ssh_ipykernel
jupyter labextension install interrupt-ipykernel-extension

Usage

Usage of ssh_ipykernel

$ python -m ssh_ipykernel -h
usage: __main__.py [--help] [--timeout TIMEOUT] [--env [ENV [ENV ...]]] [-s]
                  --file FILE --host HOST --python PYTHON

optional arguments:
  --help, -h            show this help message and exit
  --timeout TIMEOUT, -t TIMEOUT
                        timeout for remote commands
  --env [ENV [ENV ...]], -e [ENV [ENV ...]]
                        environment variables for the remote kernel in the
                        form: VAR1=value1 VAR2=value2
  -s                    sudo required to start kernel on the remote machine

required arguments:
  --file FILE, -f FILE  jupyter kernel connection file
  --host HOST, -H HOST  remote host
  --python PYTHON, -p PYTHON
                        remote python_path

Creation of kernel specification

from python

import ssh_ipykernel.manage
ssh_ipykernel.manage.add_kernel(
    host="btest",
    display_name="SSH btest:demo(abc)",
    local_python_path="/opt/miniconda/envs/test36/bin/python",
    remote_python_path="/opt/anaconda/envs/python36",
    sudo=False,
    env="VAR1=demo VAR2=abc",
    timeout=10
)

from terminal

python -m ssh_ipykernel.manage --display-name "SSH btest:demo(abc)" \
                               --host btest \
                               --python /opt/anaconda/envs/python38 \
                               --env "VAR1=demo VAR2=abc"

$ python -m ssh_ipykernel.manage --help

usage: manage.py [--help] [--display-name DISPLAY_NAME] [--sudo]
                [--timeout TIMEOUT] [--env [ENV [ENV ...]]] --host HOST
                --python PYTHON

optional arguments:
  --help, -h            show this help message and exit
  --display-name DISPLAY_NAME, -d DISPLAY_NAME
                        kernel display name (default is host name)
  --sudo, -s            sudo required to start kernel on the remote machine
  --timeout TIMEOUT, -t TIMEOUT
                        timeout for remote commands
  --env [ENV [ENV ...]], -e [ENV [ENV ...]]
                        environment variables for the remote kernel in the
                        form: VAR1=value1 VAR2=value2

required arguments:
  --host HOST, -H HOST  remote host
  --python PYTHON, -p PYTHON
                        remote python_path

Checking of kernel specification

$ jupyter-kernelspec list
Available kernels:
  ssh__ssh_btest_demo_abc_         /Users/bernhard/Library/Jupyter/kernels/ssh__ssh_btest_demo_abc_

$ cat /Users/bernhard/Library/Jupyter/kernels/ssh__ssh_btest_demo_abc_/kernel.json
{
  "argv": [
    "/opt/miniconda/envs/test36/bin/python",
    "-m",
    "ssh_ipykernel",
    "--host",
    "btest",
    "--python",
    "/opt/anaconda/envs/python36",
    "--timeout",
    "10",
    "--env",
    "VAR1=demo VAR2=abc",
    "-f",
    "{connection_file}"
  ],
  "display_name": "SSH btest:demo(abc)",
  "language": "python"
}

Add an ssh config entry to ~/.ssh/configfor the remote host:

Host btest
    HostName btest.example.com
    User john
    Port 22
    IdentityFile ~/.ssh/id_rsa
    ServerAliveInterval 30
    ConnectTimeout 5
    ServerAliveCountMax 5760

Credits

The ideas are heavily based on

remote_ikernel

mashroomxl/ssh_ipykernel

SSH Kernel - an ipykernel over ssh

Installation

Usage

Credits