Configure and Start a Notebook Server¶
Configure and Start a Notebook Server
The NotebookObject
is used to configure and launch a Sage
Notebook server.
-
class
sagenb.notebook.notebook_object.
NotebookObject
¶ Start the Sage Notebook server. More details about using these options, as well as tips and tricks, may be available at this Sage wiki page. If a notebook server is already running in the directory, this will open a browser to the running notebook.
INPUT:
directory
– string; directory that contains the Sage notebook files; the default is.sage/sage_notebook.sagenb
, in your home directory.port
– integer (default:8080
), port to serve the notebook on.interface
– string (default:'localhost'
), address of network interface to listen on; give''
to listen on all interfaces.port_tries
– integer (default:0
), number of additional ports to try if the first one doesn’t work (not implemented).secure
– boolean (default:False
) if True use https so all communication, e.g., logins and passwords, between web browsers and the Sage notebook is encrypted via SSL. You must have OpenSSL installed to use this feature, or if you compile Sage yourself, have the OpenSSL development libraries installed. Highly recommended!When
notebook()
is run for first time withsecure=True
, it will generate new keys and store them to.sage/notebook/
. Remove this when you want to generate new keys, for example if an older version of Sage has generated keys that are too short for current browsers.reset
– boolean (default:False
) if True allows you to set the admin password. Use this if you forget your admin password.accounts
– boolean (default:False
) if True, any visitor to the website will be able to create a new account. If False, only the admin can create accounts (currently, this can only be done by running withaccounts=True
and shutting down the server properly (SIG_INT
orSIG_TERM
), or on the command line with, e.g.,from sagenb.notebook.notebook import load_notebook nb = load_notebook("directory_to_run_sage_in") user_manager = nb.user_manager() user_manager.set_accounts(True) user_manager.add_user("username", "password", "email@place", "user") nb.save()
automatic_login
– boolean (default: True) whether to pop up a web browser and automatically log into the server as admin. You can override the default browser by setting theSAGE_BROWSER
environment variable, e.g., by puttingexport SAGE_BROWSER="firefox"
in the file .bashrc in your home directory.
upload
– string (default: None) Full path to a local file (sws, txt, zip) to be uploaded and turned into a worksheet(s). This is equivalent to manually uploading a file viahttp://localhost:8080/upload
or to fetchinghttp://localhost:8080/upload_worksheet?url=file:///...
in a script except that (hopefully) you will already be logged in.Warning
If you are running a server for others to log into, set
automatic_login=False
. Otherwise, all of the worksheets on the entire server will be loaded when the server automatically logs into the admin account.timeout
– integer (default: 0) seconds until idle worksheet sessions automatically timeout, i.e., the corresponding Sage session terminates. 0 means “never timeout”. If your server is running out of memory, setting a timeout can be useful as this will free the memory used by idle sessions.doc_timeout
– integer (default: 600) seconds until idle live documentation worksheet sessions automatically timeout, i.e., the corresponding Sage session terminates. 0 means “never timeout”.server_pool
– list of strings (default: None) list; this option specifies that worksheet processes run as a separate user (chosen from the list in theserver_pool
– see below).
Note
If you have problems with the server certificate hostname not matching, do
notebook.setup()
.Note
The
require_login
option has been removed. Useautomatic_login
to control automatic logins instead—automatic_login=False
corresponds torequire_login=True
.EXAMPLES:
I just want to run the Sage notebook. Type:
notebook()
I want to run the Sage notebook server on a remote machine and be the only person allowed to log in. Type:
notebook(interface='', secure=True)
the first time you do this you’ll be prompted to set an administrator password. Use this to login. NOTE: You may have to run
notebook.setup()
again and change the hostname. ANOTHER NOTE: You must have installed pyOpenSSL in order to use secure mode; see the top-level Sage README file or the “Install from Source Code” section in the Sage manual for more information.I want to create a Sage notebook server that is open to anybody in the world to create new accounts. To run the Sage notebook publicly (1) at a minimum run it from a chroot jail or inside a virtual machine (see this Sage wiki page) and (2) use a command like:
notebook(interface='', server_pool=['sage1@localhost'], ulimit='-v 500000', accounts=True, automatic_login=False)
The server_pool option specifies that worksheet processes run as a separate user. The ulimit option restricts the memory available to each worksheet processes to 500 MB. See help on the
accounts
option above.Be sure that
sage_notebook.sagenb/users.pickle
and the contents ofsage_notebook.sagenb/backups
are chmodog-rwx
, i.e., only readable by the notebook process, since otherwise any user can readusers.pickle
, which contains user email addresses and account information (passwords are stored hashed, so fewer worries there). You will need to use thedirectory
option to accomplish this.
INPUT: (more advanced)
server_pool
– list of strings (initial default: None), if given, should be a list like ['sage1@localhost‘, 'sage2@localhost‘], where you have setup ssh keys so that typing:ssh sage1@localhost
logs in without requiring a password, e.g., by typing
ssh-keygen
as the notebook server user, then putting~/.ssh/id_rsa.pub
as the file.ssh/authorized_keys
. Note: you have to get the permissions of files and directories just right – see this Sage wiki page for more details.Files between the main Sage process and the
server_pool
workers are transferred through/tmp
by default. If the environment variableSAGENB_TMPDIR
orTMPDIR
exists, that directory is used instead. This directory must be shared, so if the machines are separate the server machine must NFS-export/tmp
orSAGENB_TMPDIR
.server
– string (“twistd” (default) or “flask”). The server to use to server content.profile
– True, False, or file prefix (default: False - no profiling), If True, profiling is saved to a randomly-named file like \(sagenb-*-profile*.stats\) in the $DOT_SAGE directory. If a string, that string is used as a prefix for the pstats data file.ulimit
– string (initial default: None – leave as is), if given andserver_pool
is also given, the worksheet processes are run with these constraints. See the ulimit documentation. Common options include:-t
The maximum amount of cpu time in seconds. NOTE: For Sage,-t
is the wall time, not cpu time.-u
The maximum number of processes available to a single user.-v
The maximum amount of virtual memory available to the process.
Values are in 1024-byte increments, except for
-t
, which is in seconds, and-u
which is a positive integer. Example: ulimit=”-v 400000 -t 30”
Note
The values of
server_pool
andulimit
default to what they were last time the notebook command was called.OTHER NOTES:
- If you create a file
$DOT_SAGE/notebook.css
then it will get applied when rendering the notebook HTML. This allows notebook administrators to customize the look of the notebook. Note that by default$DOT_SAGE
is$HOME/.sage
.
-
notebook
(directory=None, port=8080, interface='localhost', port_tries=50, secure=False, reset=False, accounts=None, openid=None, server_pool=None, ulimit='', timeout=None, doc_timeout=None, upload=None, automatic_login=True, start_path='', fork=False, quiet=False, server='twistd', profile=False, subnets=None, require_login=None, open_viewer=None, address=None)¶
-
setup
()¶
-
sagenb.notebook.notebook_object.
inotebook
(*args, **kwds)¶ Exactly the same as
notebook(...)
but withsecure=False
.
-
sagenb.notebook.notebook_object.
test_notebook
(admin_passwd, secure=False, directory=None, port=8050, interface='localhost', verbose=False)¶ This function is used to test notebook server functions.
EXAMPLES:
sage: from sagenb.notebook.notebook_object import test_notebook sage: passwd = str(randint(1,1<<128)) sage: nb = test_notebook(passwd, interface='localhost', port=8060) sage: import urllib sage: h = urllib.urlopen('http://localhost:8060') sage: homepage = h.read() sage: h.close() sage: 'html' in homepage True sage: nb.dispose()