With the two-process ZMQ model, the frontend does not block input during execution. This means that actions can be taken by the frontend while the Kernel is executing, or even after it crashes. The most basic such command is via ‘Ctrl-.’, which restarts the kernel. This can be done in the middle of a blocking execution. The frontend can also know, via a heartbeat mechanism, that the kernel has died. This means that the frontend can safely restart the kernel.

Multiple Consoles¶

Since the Kernel listens on the network, multiple frontends can connect to it. These do not have to all be qt frontends - any IPython frontend can connect and run code. When you start ipython qtconsole, there will be an output line, like:

[IPKernelApp] To connect another client to this kernel, use: [IPKernelApp] --existing kernel-12345.json

Other frontends can connect to your kernel, and share in the execution. This is great for collaboration. The --existing flag means connect to a kernel that already exists. Starting other consoles with that flag will not try to start their own kernel, but rather connect to yours. kernel-12345.json is a small JSON file with the ip, port, and authentication information necessary to connect to your kernel. By default, this file will be in your default profile’s security directory. If it is somewhere else, the output line will print the full path of the connection file, rather than just its filename.

If you need to find the connection info to send, and don’t know where your connection file lives, there are a couple of ways to get it. If you are already running an IPython console connected to the kernel, you can use the %connect_info magic to display the information necessary to connect another frontend to the kernel.

In [2]: % connect_info { "stdin_port":50255, "ip":"127.0.0.1", "hb_port":50256, "key":"70be6f0f-1564-4218-8cda-31be40a4d6aa", "shell_port":50253, "iopub_port":50254 } Paste the above JSON into a file, and connect with: $> ipython <app> --existing <file> or, if you are local, you can connect with just: $> ipython <app> --existing kernel-12345.json or even just: $> ipython <app> --existing if this is the most recent IPython session you have started.

Otherwise, you can find a connection file by name (and optionally profile) with IPython.lib.kernel.find_connection_file() :

$> python -c "from IPython.lib.kernel import find_connection_file;\ print find_connection_file('kernel-12345.json')" /home/you/.ipython/profile_default/security/kernel-12345.json

And if you are using a particular IPython profile:

$> python -c "from IPython.lib.kernel import find_connection_file;\ print find_connection_file('kernel-12345.json', profile='foo')" /home/you/.ipython/profile_foo/security/kernel-12345.json

You can even launch a standalone kernel, and connect and disconnect Qt Consoles from various machines. This lets you keep the same running IPython session on your work machine (with matplotlib plots and everything), logging in from home, cafés, etc.:

$> ipython kernel [IPKernelApp] To connect another client to this kernel, use: [IPKernelApp] --existing kernel-12345.json

This is actually exactly the same as the subprocess launched by the qtconsole, so all the information about connecting to a standalone kernel is identical to that of connecting to the kernel attached to a running console.

Security¶ Warning Since the ZMQ code currently has no encryption, listening on an external-facing IP is dangerous. You are giving any computer that can see you on the network the ability to connect to your kernel, and view your traffic. Read the rest of this section before listening on external ports or running an IPython kernel on a shared machine. By default (for security reasons), the kernel only listens on localhost, so you can only connect multiple frontends to the kernel from your local machine. You can specify to listen on an external interface by specifying the ip argument: $> ipython qtconsole --ip=192.168.1.123 If you specify the ip as 0.0.0.0 or ‘*’, that means all interfaces, so any computer that can see yours on the network can connect to the kernel. Messages are not encrypted, so users with access to the ports your kernel is using will be able to see any output of the kernel. They will NOT be able to issue shell commands as you due to message signatures, which are enabled by default as of IPython 0.12. Warning If you disable message signatures, then any user with access to the ports your kernel is listening on can issue arbitrary code as you. DO NOT disable message signatures unless you have a lot of trust in your environment. The one security feature IPython does provide is protection from unauthorized execution. IPython’s messaging system will sign messages with HMAC digests using a shared-key. The key is never sent over the network, it is only used to generate a unique hash for each message, based on its content. When IPython receives a message, it will check that the digest matches, and discard the message. You can use any file that only you have access to to generate this key, but the default is just to generate a new UUID. You can generate a random private key with: # generate 1024b of random data, and store in a file only you can read: # (assumes IPYTHONDIR is defined, otherwise use your IPython directory) $> python -c "import os; print os.urandom(128).encode('base64')" > $IPYTHONDIR/sessionkey $> chmod 600 $IPYTHONDIR/sessionkey The contents of this file will be stored in the JSON connection file, so that file contains everything you need to connect to and use a kernel. To use this generated key, simply specify the Session.keyfile configurable in ipython_config.py or at the command-line, as in: # instruct IPython to sign messages with that key, instead of a new UUID $> ipython qtconsole --Session.keyfile=$IPYTHONDIR/sessionkey

SSH Tunnels¶ Sometimes you want to connect to machines across the internet, or just across a LAN that either doesn’t permit open ports or you don’t trust the other machines on the network. To do this, you can use SSH tunnels. SSH tunnels are a way to securely forward ports on your local machine to ports on another machine, to which you have SSH access. In simple cases, IPython’s tools can forward ports over ssh by simply adding the --ssh=remote argument to the usual --existing... set of flags for connecting to a running kernel, after copying the JSON connection file (or its contents) to the second computer. Warning Using SSH tunnels does not increase localhost security. In fact, when tunneling from one machine to another both machines have open ports on localhost available for connections to the kernel. There are two primary models for using SSH tunnels with IPython. The first is to have the Kernel listen only on localhost, and connect to it from another machine on the same LAN. First, let’s start a kernel on machine worker, listening only on loopback: [email protected] $> ipython kernel [IPKernelApp] To connect another client to this kernel, use: [IPKernelApp] --existing kernel-12345.json In this case, the IP that you would connect to would still be 127.0.0.1, but you want to specify the additional --ssh argument with the hostname of the kernel (in this example, it’s ‘worker’): [email protected] $> ipython qtconsole --ssh=worker --existing /path/to/kernel-12345.json Which will write a new connection file with the forwarded ports, so you can reuse them: [IPythonQtConsoleApp] To connect another client via this tunnel, use: [IPythonQtConsoleApp] --existing kernel-12345-ssh.json Note again that this opens ports on the client machine that point to your kernel. Note the ssh argument is simply passed to openssh, so it can be fully specified user@host:port but it will also respect your aliases, etc. in .ssh/config if you have any. The second pattern is for connecting to a machine behind a firewall across the internet (or otherwise wide network). This time, we have a machine login that you have ssh access to, which can see kernel, but client is on another network. The important difference now is that client can see login, but not worker. So we need to forward ports from client to worker via login. This means that the kernel must be started listening on external interfaces, so that its ports are visible to login : [email protected] $> ipython kernel --ip=0.0.0.0 [IPKernelApp] To connect another client to this kernel, use: [IPKernelApp] --existing kernel-12345.json Which we can connect to from the client with: [email protected] $> ipython qtconsole --ssh=login --ip=192.168.1.123 --existing /path/to/kernel-12345.json Note The IP here is the address of worker as seen from login, and need only be specified if the kernel used the ambiguous 0.0.0.0 (all interfaces) address. If it had used 192.168.1.123 to start with, it would not be needed.