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

    importssh_ipykernel.managessh_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 forthe remote kernelin 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