1 """nodoctest
2 """
3
4
5
6
7
8
9
10
11 """
12 Notebook control object
13
14 This is used for configuring and starting the SAGE notebook server.
15 """
16
17 import time, os, shutil, signal, tempfile
18
19 import notebook as _notebook
20
21 import run_notebook
22
24 r"""
25 Start the SAGE Notebook server.
26
27 INPUT:
28 directory -- directory that contains the SAGE notebook files;
29 The default is .sage/sage_notebook, in your home directory.
30 port -- (default: 8000), port to serve the notebook on
31 address -- (default: 'localhost'), address of network interface to listen on;
32 give '' to listen on all interfaces.
33 port_tries -- (default: 0), number of additional ports to try if the
34 first one doesn't work (*not* implemented)
35 secure -- (default: False) if True use https so all
36 communication, e.g., logins and passwords,
37 between web browsers and the SAGE notebook is
38 encrypted (via GNU TLS). *Highly recommended!*
39 require_login -- (default: True) if True login is required else web user is
40 automatically logged in as user admin
41 reset -- (default: False) if True allows you to set the
42 admin password. Use this if you forget your
43 admin password.
44 accounts -- (default: False) if True, any visitor to the website
45 will be able to create a new account. If False,
46 only the admin can create accounts (currently, this
47 can only be done by running with accounts=True for
48 a few minutes, or on the command line with, e.g.,
49 nb = load('./sage/sage_notebook/nb.sobj')
50 nb.set_accounts(True)
51 nb.add_user("username", "password", "email@place", "user")
52 nb.save()
53 open_viewer -- (default: True) whether to pop up a web browser.
54 You can override the default browser by setting
55 the SAGE_BROWSER environment variable, e.g., by putting
56 export SAGE_BROWSER="firefox"
57 in the file .bashrc in your home directory.
58 timeout -- (default: 0) seconds until idle worksheet sessions
59 automatically timeout, i.e., the corresponding
60 Sage session terminates. 0 means 'never timeout'.
61 server_pool -- list; The server_pool option specifies that worksheet processes run
62 as a separate user (chosen from the list in the server_pool -- see below).
63
64 \begin{verbatim}
65
66 NOTE: If you have problems with the server certificate hostname not
67 matching, do \code{notebook.setup()}.
68
69 EXAMPLES:
70
71 1. I just want to run the SAGE notebook. Type
72
73 notebook()
74
75 2. I want to run the SAGE notebook server on a remote machine
76 and be the only person allowed to log in. Type
77
78 notebook(address='', secure=True)
79
80 the first time you do this you'll be prompted to set
81 an administrator password. Use this to login.
82 NOTE: You may have to run notebook.setup() again and change
83 the hostname.
84
85 3. I just want to run the server locally on my laptop at a coffee
86 shop with no wifi and do not want to be bothered with having to log in,
87 and I am *absolutely certain* I am the only
88 user logged into my laptop so I do not have to worry about
89 somebody else using the notebook on localhost and deleting my
90 files. Use
91
92 notebook(require_login=False)
93
94 4. I want to create a SAGE notebook server that is open to anybody
95 in the world to create new accounts, etc. To run the SAGE
96 notebook publically (1) at a minimu run it from a chroot jail
97 (see the SAGE install guide), and (2) use a command like
98
99 notebook(address='', server_pool=['sage1@localhost'], ulimit='-v 500000', accounts=True)
100
101 The server_pool option specifies that worksheet processes run
102 as a separate user. The ulimit option restricts the memory
103 available to each worksheet processes to 500MB. See help on
104 the accounts option above.
105
106 Be sure to make that the sage_notebook/nb.sobj and contents
107 of sage_notebook/backups is chmod og-rwx, i.e., only readable
108 by the notebook process, since otherwise any user can read
109 nb.sobj, which contains user email addresses and account
110 information (password are stored hashed, so less worries there).
111
112
113 INPUT: (more advanced)
114
115 NOTE: The values of these two properties default to what they were
116 last time the notebook command was called.
117
118 server_pool -- (default: None), if given, should be a list like
119 ['sage1@localhost', 'sage2@localhost'], where
120 you have setup ssh keys so that typing
121 ssh sage1@localhost
122 logs in without requiring a password, e.g., by typing
123 as the notebook server user
124 cd; ssh-keygen -t rsa
125 then put ~/.ssh/id_rsa.pub as the file .ssh/authorized_keys2.
126 Note -- you have to get the permissions of files
127 and directories just right -- do a web search
128 for more details.
129
130 ulimit -- (default: None -- leave as is), if given and server_pool is also given,
131 the worksheet processes are run with these constraints.
132 See the ulimit documentation. Common options include:
133 -f The maximum size of files created by the shell
134 -t The maximum amount of cpu time in seconds.
135 -u The maximum number of processes available to a single user.
136 -v The maximum amount of virtual memory available to the process.
137 Values are in 1024-byte increments, except for `-t', which is in seconds.
138 Example: ulimit="-v 400000 -t 30"
139
140 \end{verbatim}
141 """
144
145 notebook = run_notebook.notebook_twisted
146 setup = run_notebook.notebook_setup
147
148 notebook = NotebookObject()
149
150
152 """
153 Exactly the same as notebook(...) but with secure=False.
154 """
155 kwds['secure'] = False
156 notebook(*args, **kwds)
157
158
159 -def test_notebook(admin_passwd, secure=False, directory=None, port=8050, address='localhost', verbose=False):
160 """
161 This function is used to test notebook server functions.
162
163 EXAMPLE:
164 sage: from sage.server.notebook.notebook_object import test_notebook
165 sage: passwd = str(randint(1,1<<128))
166 sage: nb = test_notebook(passwd, address='localhost', port=8060)
167 sage: import urllib
168 sage: h = urllib.urlopen('https://localhost:8060')
169 sage: homepage = h.read()
170 sage: h.close()
171 sage: 'html' in homepage
172 True
173 sage: nb.dispose()
174 """
175 import socket, pexpect
176
177 if directory is None:
178 directory = tmp_dir = tempfile.mkdtemp()
179 else:
180 tmp_dir = None
181
182 if not os.path.exists(directory):
183 os.makedirs(directory)
184
185 nb = _notebook.load_notebook(directory)
186 nb.set_accounts(True)
187 nb.add_user('admin', admin_passwd, '')
188 nb.set_accounts(False)
189 nb.save()
190
191 p = notebook(directory=directory, accounts=True, secure=secure, port=port, address=address, open_viewer=False, fork=True, quiet=True)
192 p.expect("Starting factory")
193 def dispose():
194 try:
195 p.send('\x03')
196 except pexpect.EOF:
197 pass
198 p.close(force=True)
199 shutil.rmtree(nb.directory())
200 p.dispose = dispose
201 if verbose:
202 print "Notebook started."
203 return p
204