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/python36 \
                                   --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

History

1.0.0 (2020-05-07)

• Added an extension to send sigint to the reote kernel via ssh (needed for Windows)
• Added Windows support (for OpoenSSH)
• Added a call to a kernel_customize function for sub classes to inject customizations for the kernel

0.1.0 (2019-09-01)

• First release on github

0.9.0 (2019-09-03)

• Restructured pxssh calls
• Rewrote keeping alive routine
• Stabilized error detection (cluster not reachable, VPN cut, ipykernel missing)

0.9.2 (2019-09-20)

• Added code to call ssh_ipykernel as a module to add a kernel
• Added doc strings to all classes and methods

0.9.3 (2019-09-20)

• Fixed argument error for env variables in ssh_ipykernel.manage