@ -4,13 +4,19 @@ Running a notebook server
=========================
The :doc: `Jupyter notebook <notebook>` web-application is based on a
server-client structure. This server uses a :ref:`two-process kernel
architecture <ipython:ipythonzmq>` based on ZeroMQ_, as well as Tornado_ for serving
HTTP requests. By default, a notebook server runs on http://127.0.0.1:8888/
and is accessible only from `localhost`
:ref: `secure a notebook server <notebook_server_security>` and how to :ref:`run it on
a public interface <notebook_public_server>`.
The :doc: `Jupyter notebook <notebook>` web application is based on a
server-client structure. The notebook server uses a :ref:`two-process kernel
architecture <ipython:ipythonzmq>` based on ZeroMQ_, as well as Tornado_ for
serving HTTP requests.
.. note ::
By default, a notebook server runs locally at 127.0.0.1:8888
and is accessible only from `localhost`
notebook server from the browser using `http://127.0.0.1:8888`
This document describes how you can
:ref: `secure a notebook server <notebook_server_security>` and how to
:ref: `run it on a public interface <notebook_public_server>` .
.. _ZeroMQ: http://zeromq.org
@ -23,56 +29,96 @@ Securing a notebook server
--------------------------
You can protect your notebook server with a simple single password by
setting the :attr: `NotebookApp.password` configurable. You can prepare a
hashed password using the function :func: `notebook.auth.security.passwd` :
configuring the :attr: `NotebookApp.password` setting in
:file: `jupyter_notebook_config.py` .
Prerequisite: A notebook configuration file
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Check to see if you have a notebook configuration file,
:file: `jupyter_notebook_config.py` . The default location for this file
is your Jupyter folder in your home directory, `` ~/.jupyter `` .
If you don't already have one, create a config file for the notebook
using the following command::
$ jupyter notebook --generate-config
Preparing a hashed password
~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can prepare a hashed password using the function
:func: `notebook.auth.security.passwd` :
.. sourcecode :: ipython
In [1]: from notebook.auth import passwd
In [2]: passwd()
Enter password:
Verify password:
Enter password:
Verify password:
Out[2]: 'sha1:67c9e60bb8b6:9ffede0825894254b2e042ea597d771089e11aed'
.. note ::
:func: `~notebook.auth.security.passwd` can also take the password as a string
argument. **Do not** pass it as an argument inside an IPython session, as it
.. caution ::
:func: `~notebook.auth.security.passwd` when called with no arguments
will prompt you to enter and verify your password such as
in the above code snippet. Although the function can also
be passed a string as an argument such as `` passwd('mypassword') `` , please
**do not** pass a string as an argument inside an IPython session, as it
will be saved in your input history.
You can then add this to your :file: `jupyter_notebook_config.py` , e.g.::
Adding hashed password to your notebook configuration file
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can then add the hashed password to your :file: `jupyter_notebook_config.py` .
The default location for this file :file: `jupyter_notebook_config.py` is in
your Jupyter folder in your home directory, `` ~/.jupyter `` , e.g.::
# Password to use for web authentication
# Get notebook configuration and add hashed password
c = get_config()
c.NotebookApp.password =
c.NotebookApp.password =
u'sha1:67c9e60bb8b6:9ffede0825894254b2e042ea597d771089e11aed'
When using a password, it is a good idea to also use SSL, so that your
password is not sent unencrypted by your browser. You can start the notebook
to communicate via a secure protocol mode using a self-signed certificate with
the command::
Using SSL for encrypted communication
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When using a password, it is a good idea to also use SSL with a web certificate,
so that your hashed password is not sent unencrypted by your browser.
$ ipython notebook --certfile=mycert.pem
.. important ::
Web security is rapidly changing and evolving. We provide this document
as a convenience to the user, and recommend that the user keep current on
changes that may impact security, such as new releases of OpenSSL.
The Open Web Application Security Project (`OWASP`_ ) website is a good resource
on general security issues and web practices.
.. note ::
You can start the notebook to communicate via a secure protocol mode by setting
the `` certfile `` option to your self-signed certificate, i.e. `` mycert.pem `` ,
with the command::
$ jupyter notebook --certfile=mycert.pem
A self-signed certificate can be generated with `` openssl `` . For example,
the following command will create a certificate valid for 365 days with
.. tip ::
A self-signed certificate can be generated with `` openssl `` . For example,
the following command will create a certificate valid for 365 days with
both the key and certificate data written to the same file::
$ openssl req -x509 -nodes -days 365 -newkey rsa:1024 -keyout mycert.pem -out mycert.pem
Your browser will warn you of a dangerous certificate because it is
self-signed. If you want to have a fully compliant certificate that will not
raise warnings, it is possible (but rather involved) to obtain one,
as explained in detail in `this tutorial`__ .
When starting the notebook server, your browser may warn that your self-signed
certificate is insecure or unrecognized. If you wish to have a fully
compliant self-signed certificate that will not raise warnings, it is possible
(but rather involved) to create one, as explained in detail in `this tutorial`__ .
.. __: http://arstechnica.com/security/news/2009/12/how-to-get-set-with-a-secure-sertificate-for-free.ars
.. TODO: Find an additional resource that walks the user through this two-process step by step.
Keep in mind that when you enable SSL support, you will need to access the
notebook server over `` https:// `` , not over plain `` http:// `` . The startup
message from the server prints this, but it is easy to overlook and think the
server is for some reason non-responsive.
message from the server prints a reminder in the console, but it is easy to
overlook this detail and think the server is for some reason non-responsive.
**When using SSL, always access the notebook server with ``https://``.**
.. _OWASP: https://www.owasp.org
.. _notebook_public_server:
@ -81,53 +127,68 @@ Running a public notebook server
--------------------------------
If you want to access your notebook server remotely via a web browser,
you can do the following.
you can do so by running a public notebook server. For optimal security
when running a public notebook server, you should first secure the
server with a password and SSL/HTTPS as described in
:ref: `notebook_server_security` .
Start by creating a certificate file and a hashed password, as explained in
:ref: `notebook_server_security` .
Start by creating a certificate file and a hashed password, as explained
above. Then, if you don't already have one, create a config file for the
notebook using the following command line::
If you don't already have one, create a
config file for the notebook using the following command line::
$ jupyter notebook --generate-config
In the `` ~/.jupyter `` directory, edit the notebook config file,
`` jupyter_notebook_config.py `` . By default, the file has all fields
commented; the minimum set you need to uncomment and edit is the following::
In the `` ~/.jupyter `` directory, edit the notebook config file,
`` jupyter_notebook_config.py `` . By default, the notebook config file has
all fields commented out. The minimum set of configuration options that
you should to uncomment and edit in :file: ``jupyter_notebook_config.py` ` is the
following::
# Notebook configuration for public notebook server
c = get_config()
# Notebook confi g
# Set options for certfile, ip, password, and toggle off browser auto-openin g
c.NotebookApp.certfile = u'/absolute/path/to/your/certificate/mycert.pem'
c.NotebookApp.ip = '*'
c.NotebookApp.ip = u'*' # where * is the desired ip address
c.NotebookApp.password = u'sha1:bcd259ccf...<your hashed password here>'
c.NotebookApp.open_browser = False
c.NotebookApp.password = u'sha1:bcd259ccf...[your hashed password here]'
# It is a good idea to put it on a known, fixed port
# It is a good idea to set a known, fixed port for server access
c.NotebookApp.port = 9999
You can then start the notebook and access it later by pointing your browser
to `` https://your.host.com:9999 `` with `` jupyter notebook `` .
You can then start the notebook and access it later by pointing your browser
to `` https://your.host.com:9999 `` after starting the `` jupyter notebook ``
client.
Firewall Setup
`` ` ` ` ` ` ` ` ` ` ` ``
To function correctly, the firewall on the computer running the ipython server must be
configured to allow connections from client machines on the `` c.NotebookApp.port ``
port to allow connections to the web interface. The firewall must also allow
connections from 127.0.0.1 (localhost) on ports from 49152 to 65535.
These ports are used by the server to communicate with the notebook kernels.
The kernel communication ports are chosen randomly by ZeroMQ, and may require
~~~~~~~~~~~~~~
To function correctly, the firewall on the computer running the jupyter
notebook server must be configured to allow connections from client
machines on the access port `` c.NotebookApp.port `` set in
:file: ``jupyter_notebook_config.py` ` port to allow connections to the
web interface. The firewall must also allow connections from
127.0.0.1 (localhost) on ports from 49152 to 65535.
These ports are used by the server to communicate with the notebook kernels.
The kernel communication ports are chosen randomly by ZeroMQ, and may require
multiple connections per kernel, so a large range of ports must be accessible.
Running with a different URL prefix
-----------------------------------
Running the notebook with a customized URL prefix
-------------------------------------------------
The notebook dashboard, which is the landing page with an overview
of the notebooks in your working directory, is typically found and accessed
at the default URL `` http://localhost:8888/ `` .
The notebook dashboard (the landing page with an overview
of the notebooks in your working directory) typically lives at the URL
`` http://localhost:8888/ `` . If you prefer that it lives, together with the
rest of the notebook, under a sub-directory,
e.g. `` http://localhost:8888/ipython/ `` , you can do so with
configuration options like the following (see above for instructions about
modifying `` jupyter_notebook_config.py `` )::
If you prefer to customize the URL prefix for the notebook dashboard, you can
do so through modifying `` jupyter_notebook_config.py `` . For example, if you
prefer that the notebook dashboard be located with a sub-directory that
contains other ipython files, e.g. `` http://localhost:8888/ipython/ `` ,
you can do so with configuration options like the following (see above for
instructions about modifying `` jupyter_notebook_config.py `` )::
c.NotebookApp.base_url = '/ipython/'
c.NotebookApp.webapp_settings = {'static_url_prefix':'/ipython/static/'}
Matthias Bussonnier
11 years ago