##// END OF EJS Templates
Add pointers to simple nb manager and bookstore.
Kyle Kelley -
Show More
@@ -1,148 +1,160 b''
1 .. _working_remotely:
1 .. _working_remotely:
2
2
3 Running a notebook server
3 Running a notebook server
4 =========================
4 =========================
5
5
6
6
7 The :ref:`IPython notebook <htmlnotebook>` web-application is based on a
7 The :ref:`IPython notebook <htmlnotebook>` web-application is based on a
8 server-client structure. This server uses a :ref:`two-process kernel
8 server-client structure. This server uses a :ref:`two-process kernel
9 architecture <ipythonzmq>` based on ZeroMQ_, as well as Tornado_ for serving
9 architecture <ipythonzmq>` based on ZeroMQ_, as well as Tornado_ for serving
10 HTTP requests. By default, a notebook server runs on http://127.0.0.1:8888/
10 HTTP requests. By default, a notebook server runs on http://127.0.0.1:8888/
11 and is accessible only from `localhost`. This document describes how you can
11 and is accessible only from `localhost`. This document describes how you can
12 :ref:`secure a notebook server <notebook_security>` and how to :ref:`run it on
12 :ref:`secure a notebook server <notebook_security>` and how to :ref:`run it on
13 a public interface <notebook_public_server>`.
13 a public interface <notebook_public_server>`.
14
14
15 .. _ZeroMQ: http://zeromq.org
15 .. _ZeroMQ: http://zeromq.org
16
16
17 .. _Tornado: http://www.tornadoweb.org
17 .. _Tornado: http://www.tornadoweb.org
18
18
19
19
20 .. _notebook_security:
20 .. _notebook_security:
21
21
22 Notebook security
22 Notebook security
23 -----------------
23 -----------------
24
24
25 You can protect your notebook server with a simple single password by
25 You can protect your notebook server with a simple single password by
26 setting the :attr:`NotebookApp.password` configurable. You can prepare a
26 setting the :attr:`NotebookApp.password` configurable. You can prepare a
27 hashed password using the function :func:`IPython.lib.security.passwd`:
27 hashed password using the function :func:`IPython.lib.security.passwd`:
28
28
29 .. sourcecode:: ipython
29 .. sourcecode:: ipython
30
30
31 In [1]: from IPython.lib import passwd
31 In [1]: from IPython.lib import passwd
32 In [2]: passwd()
32 In [2]: passwd()
33 Enter password:
33 Enter password:
34 Verify password:
34 Verify password:
35 Out[2]: 'sha1:67c9e60bb8b6:9ffede0825894254b2e042ea597d771089e11aed'
35 Out[2]: 'sha1:67c9e60bb8b6:9ffede0825894254b2e042ea597d771089e11aed'
36
36
37 .. note::
37 .. note::
38
38
39 :func:`~IPython.lib.security.passwd` can also take the password as a string
39 :func:`~IPython.lib.security.passwd` can also take the password as a string
40 argument. **Do not** pass it as an argument inside an IPython session, as it
40 argument. **Do not** pass it as an argument inside an IPython session, as it
41 will be saved in your input history.
41 will be saved in your input history.
42
42
43 You can then add this to your :file:`ipython_notebook_config.py`, e.g.::
43 You can then add this to your :file:`ipython_notebook_config.py`, e.g.::
44
44
45 # Password to use for web authentication
45 # Password to use for web authentication
46 c = get_config()
46 c = get_config()
47 c.NotebookApp.password =
47 c.NotebookApp.password =
48 u'sha1:67c9e60bb8b6:9ffede0825894254b2e042ea597d771089e11aed'
48 u'sha1:67c9e60bb8b6:9ffede0825894254b2e042ea597d771089e11aed'
49
49
50 When using a password, it is a good idea to also use SSL, so that your
50 When using a password, it is a good idea to also use SSL, so that your
51 password is not sent unencrypted by your browser. You can start the notebook
51 password is not sent unencrypted by your browser. You can start the notebook
52 to communicate via a secure protocol mode using a self-signed certificate with
52 to communicate via a secure protocol mode using a self-signed certificate with
53 the command::
53 the command::
54
54
55 $ ipython notebook --certfile=mycert.pem
55 $ ipython notebook --certfile=mycert.pem
56
56
57 .. note::
57 .. note::
58
58
59 A self-signed certificate can be generated with ``openssl``. For example,
59 A self-signed certificate can be generated with ``openssl``. For example,
60 the following command will create a certificate valid for 365 days with
60 the following command will create a certificate valid for 365 days with
61 both the key and certificate data written to the same file::
61 both the key and certificate data written to the same file::
62
62
63 $ openssl req -x509 -nodes -days 365 -newkey rsa:1024 -keyout mycert.pem -out mycert.pem
63 $ openssl req -x509 -nodes -days 365 -newkey rsa:1024 -keyout mycert.pem -out mycert.pem
64
64
65 Your browser will warn you of a dangerous certificate because it is
65 Your browser will warn you of a dangerous certificate because it is
66 self-signed. If you want to have a fully compliant certificate that will not
66 self-signed. If you want to have a fully compliant certificate that will not
67 raise warnings, it is possible (but rather involved) to obtain one,
67 raise warnings, it is possible (but rather involved) to obtain one,
68 as explained in detail in `this tutorial`__.
68 as explained in detail in `this tutorial`__.
69
69
70 .. __: http://arstechnica.com/security/news/2009/12/how-to-get-set-with-a-secure-sertificate-for-free.ars
70 .. __: http://arstechnica.com/security/news/2009/12/how-to-get-set-with-a-secure-sertificate-for-free.ars
71
71
72 Keep in mind that when you enable SSL support, you will need to access the
72 Keep in mind that when you enable SSL support, you will need to access the
73 notebook server over ``https://``, not over plain ``http://``. The startup
73 notebook server over ``https://``, not over plain ``http://``. The startup
74 message from the server prints this, but it is easy to overlook and think the
74 message from the server prints this, but it is easy to overlook and think the
75 server is for some reason non-responsive.
75 server is for some reason non-responsive.
76
76
77
77
78 .. _notebook_public_server:
78 .. _notebook_public_server:
79
79
80 Running a public notebook server
80 Running a public notebook server
81 --------------------------------
81 --------------------------------
82
82
83 If you want to access your notebook server remotely via a web browser,
83 If you want to access your notebook server remotely via a web browser,
84 you can do the following.
84 you can do the following.
85
85
86 Start by creating a certificate file and a hashed password, as explained
86 Start by creating a certificate file and a hashed password, as explained
87 above. Then create a custom profile for the notebook, with the following
87 above. Then create a custom profile for the notebook, with the following
88 command line, type::
88 command line, type::
89
89
90 $ ipython profile create nbserver
90 $ ipython profile create nbserver
91
91
92 In the profile directory just created, edit the file
92 In the profile directory just created, edit the file
93 ``ipython_notebook_config.py``. By default, the file has all fields
93 ``ipython_notebook_config.py``. By default, the file has all fields
94 commented; the minimum set you need to uncomment and edit is the following::
94 commented; the minimum set you need to uncomment and edit is the following::
95
95
96 c = get_config()
96 c = get_config()
97
97
98 # Kernel config
98 # Kernel config
99 c.IPKernelApp.pylab = 'inline' # if you want plotting support always
99 c.IPKernelApp.pylab = 'inline' # if you want plotting support always
100
100
101 # Notebook config
101 # Notebook config
102 c.NotebookApp.certfile = u'/absolute/path/to/your/certificate/mycert.pem'
102 c.NotebookApp.certfile = u'/absolute/path/to/your/certificate/mycert.pem'
103 c.NotebookApp.ip = '*'
103 c.NotebookApp.ip = '*'
104 c.NotebookApp.open_browser = False
104 c.NotebookApp.open_browser = False
105 c.NotebookApp.password = u'sha1:bcd259ccf...[your hashed password here]'
105 c.NotebookApp.password = u'sha1:bcd259ccf...[your hashed password here]'
106 # It is a good idea to put it on a known, fixed port
106 # It is a good idea to put it on a known, fixed port
107 c.NotebookApp.port = 9999
107 c.NotebookApp.port = 9999
108
108
109 You can then start the notebook and access it later by pointing your browser
109 You can then start the notebook and access it later by pointing your browser
110 to ``https://your.host.com:9999`` with ``ipython notebook
110 to ``https://your.host.com:9999`` with ``ipython notebook
111 --profile=nbserver``.
111 --profile=nbserver``.
112
112
113 Running with a different URL prefix
113 Running with a different URL prefix
114 -----------------------------------
114 -----------------------------------
115
115
116 The notebook dashboard (the landing page with an overview
116 The notebook dashboard (the landing page with an overview
117 of the notebooks in your working directory) typically lives at the URL
117 of the notebooks in your working directory) typically lives at the URL
118 ``http://localhost:8888/``. If you prefer that it lives, together with the
118 ``http://localhost:8888/``. If you prefer that it lives, together with the
119 rest of the notebook, under a sub-directory,
119 rest of the notebook, under a sub-directory,
120 e.g. ``http://localhost:8888/ipython/``, you can do so with
120 e.g. ``http://localhost:8888/ipython/``, you can do so with
121 configuration options like the following (see above for instructions about
121 configuration options like the following (see above for instructions about
122 modifying ``ipython_notebook_config.py``)::
122 modifying ``ipython_notebook_config.py``)::
123
123
124 c.NotebookApp.base_project_url = '/ipython/'
124 c.NotebookApp.base_project_url = '/ipython/'
125 c.NotebookApp.base_kernel_url = '/ipython/'
125 c.NotebookApp.base_kernel_url = '/ipython/'
126 c.NotebookApp.webapp_settings = {'static_url_prefix':'/ipython/static/'}
126 c.NotebookApp.webapp_settings = {'static_url_prefix':'/ipython/static/'}
127
127
128 Using a different notebook store
128 Using a different notebook store
129 --------------------------------
129 --------------------------------
130
130
131 By default, the notebook server stores the notebook documents that it saves as
131 By default, the notebook server stores the notebook documents that it saves as
132 files in the working directory of the notebook server, also known as the
132 files in the working directory of the notebook server, also known as the
133 ``notebook_dir``. This logic is implemented in the
133 ``notebook_dir``. This logic is implemented in the
134 :class:`FileNotebookManager` class. However, the server can be configured to
134 :class:`FileNotebookManager` class. However, the server can be configured to
135 use a different notebook manager class, which can
135 use a different notebook manager class, which can
136 store the notebooks in a different format.
136 store the notebooks in a different format.
137
137
138 The bookstore_ package currently allows users to store notebooks on Rackspace
139 CloudFiles or OpenStack Swift based object stores.
140
141 Writing a notebook manager is as simple as extending the base class
142 :class:`NotebookManager`. The simple_notebook_manager_ provides a great example
143 of an in memory notebook manager, created solely for the purpose of
144 illustrating the notebook manager API.
145
146 .. _bookstore: https://github.com/rgbkrk/bookstore
147
148 .. _simple_notebook_manager: https://github.com/khinsen/simple_notebook_manager
149
138 Known issues
150 Known issues
139 ------------
151 ------------
140
152
141 When behind a proxy, especially if your system or browser is set to autodetect
153 When behind a proxy, especially if your system or browser is set to autodetect
142 the proxy, the notebook web application might fail to connect to the server's
154 the proxy, the notebook web application might fail to connect to the server's
143 websockets, and present you with a warning at startup. In this case, you need
155 websockets, and present you with a warning at startup. In this case, you need
144 to configure your system not to use the proxy for the server's address.
156 to configure your system not to use the proxy for the server's address.
145
157
146 For example, in Firefox, go to the Preferences panel, Advanced section,
158 For example, in Firefox, go to the Preferences panel, Advanced section,
147 Network tab, click 'Settings...', and add the address of the notebook server
159 Network tab, click 'Settings...', and add the address of the notebook server
148 to the 'No proxy for' field.
160 to the 'No proxy for' field.
General Comments 0
You need to be logged in to leave comments. Login now