# Configure and Start a Notebook Server

nodoctest 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 with `secure=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 with `accounts=True` and shutting down the server properly (`SIG_INT` or `SIG_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 the `SAGE_BROWSER` environment variable, e.g., by putting

  >       export 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 via `http://localhost:8080/upload` or to fetching `http://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 the `server_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. Use `automatic_login` to control automatic logins instead—`automatic_login=False` corresponds to `require_login=True`.

  EXAMPLES:

  1. I just want to run the Sage notebook. Type:

         notebook()

  2. 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.

  3. 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 of `sage_notebook.sagenb/backups` are chmod `og-rwx`, i.e., only readable by the notebook process, since otherwise any user can read `users.pickle`, which contains user email addresses and account information (passwords are stored hashed, so fewer worries there). You will need to use the `directory` 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 variable `SAGENB_TMPDIR` or `TMPDIR` exists, that directory is used instead. This directory must be shared, so if the machines are separate the server machine must NFS-export `/tmp` or `SAGENB_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 and `server_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` and `ulimit` 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 with `secure=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()