JupyterHub¶

Set api_url¶

The URL to access the API, c.configurableHTTPProxy.api_url, is configurable. An example entry to set the proxy's API URL in jupyterhub_config.py is:

c.ConfigurableHTTPProxy.api_url = 'http://10.0.1.4:5432'

proxy_api_ip and proxy_api_port (Deprecated in 0.8)¶

If running the Proxy separate from the Hub, configure the REST API communication IP address and port by adding this to the jupyterhub_config.py file:

# ideally a private network address
c.JupyterHub.proxy_api_ip = '10.0.1.4'
c.JupyterHub.proxy_api_port = 5432

We recommend using the proxy's api_url setting instead of the deprecated settings, proxy_api_ip and proxy_api_port.

Using an SSL certificate¶

This will require you to obtain an official, trusted SSL certificate or create a self-signed certificate. Once you have obtained and installed a key and certificate you need to specify their locations in the jupyterhub_config.py configuration file as follows:

c.JupyterHub.ssl_key = '/path/to/my.key'
c.JupyterHub.ssl_cert = '/path/to/my.cert'

Some cert files also contain the key, in which case only the cert is needed. It is important that these files be put in a secure location on your server, where they are not readable by regular users.

If you are using a chain certificate, see also chained certificate for SSL in the JupyterHub troubleshooting FAQ.

Using letsencrypt¶

It is also possible to use letsencrypt to obtain a free, trusted SSL certificate. If you run letsencrypt using the default options, the needed configuration is (replace mydomain.tld by your fully qualified domain name):

c.JupyterHub.ssl_key = '/etc/letsencrypt/live/{mydomain.tld}/privkey.pem'
c.JupyterHub.ssl_cert = '/etc/letsencrypt/live/{mydomain.tld}/fullchain.pem'

If the fully qualified domain name (FQDN) is example.com, the following would be the needed configuration:

c.JupyterHub.ssl_key = '/etc/letsencrypt/live/example.com/privkey.pem'
c.JupyterHub.ssl_cert = '/etc/letsencrypt/live/example.com/fullchain.pem'

If SSL termination happens outside of the Hub¶

In certain cases, e.g. behind SSL termination in NGINX, allowing no SSL running on the hub may be the desired configuration option.

Generating and storing as a cookie secret file¶

The cookie secret should be 32 random bytes, encoded as hex, and is typically stored in a jupyterhub_cookie_secret file. An example command to generate the jupyterhub_cookie_secret file is:

openssl rand -hex 32 > /srv/jupyterhub/jupyterhub_cookie_secret

In most deployments of JupyterHub, you should point this to a secure location on the file system, such as /srv/jupyterhub/jupyterhub_cookie_secret.

The location of the jupyterhub_cookie_secret file can be specified in the jupyterhub_config.py file as follows:

c.JupyterHub.cookie_secret_file = '/srv/jupyterhub/jupyterhub_cookie_secret'

If the cookie secret file doesn’t exist when the Hub starts, a new cookie secret is generated and stored in the file. The file must not be readable by group or other or the server won’t start. The recommended permissions for the cookie secret file are 600 (owner-only rw).

Generating and storing as an environment variable¶

If you would like to avoid the need for files, the value can be loaded in the Hub process from the JPY_COOKIE_SECRET environment variable, which is a hex-encoded string. You can set it this way:

export JPY_COOKIE_SECRET=`openssl rand -hex 32`

For security reasons, this environment variable should only be visible to the Hub. If you set it dynamically as above, all users will be logged out each time the Hub starts.

Generating and storing as a binary string¶

You can also set the cookie secret in the configuration file itself, jupyterhub_config.py, as a binary string:

c.JupyterHub.cookie_secret = bytes.fromhex('64 CHAR HEX STRING')

Generating and storing token in the configuration file¶

Or you can set the value in the configuration file, jupyterhub_config.py:

c.JupyterHub.proxy_auth_token = '0bc02bede919e99a26de1e2a7a5aadfaf6228de836ec39a05a6c6942831d8fe5'

Generating and storing as an environment variable¶

You can pass this value of the proxy authentication token to the Hub and Proxy using the CONFIGPROXY_AUTH_TOKEN environment variable:

export CONFIGPROXY_AUTH_TOKEN='openssl rand -hex 32'

This environment variable needs to be visible to the Hub and Proxy.

Default if token is not set¶

If you don’t set the Proxy authentication token, the Hub will generate a random key itself, which means that any time you restart the Hub you must also restart the Proxy. If the proxy is a subprocess of the Hub, this should happen automatically (this is the default configuration).

Create an API token¶

To run such an external service, an API token must be created and provided to the service.

As of version 0.6.0, the preferred way of doing this is to first generate an API token:

openssl rand -hex 32

In version 0.8.0, a TOKEN request page for generating an API token is available from the JupyterHub user interface:

Pass environment variable with token to the Hub¶

In the case of cull_idle_servers, it is passed as the environment variable called JUPYTERHUB_API_TOKEN.

Use API tokens for services and tasks that require external access¶

While API tokens are often associated with a specific user, API tokens can be used by services that require external access for activities that may not correspond to a specific human, e.g. adding users during setup for a tutorial or workshop. Add a service and its API token to the JupyterHub configuration file, jupyterhub_config.py:

c.JupyterHub.services = [
    {'name': 'adding-users', 'api_token': 'super-secret-token'},
]

Restart JupyterHub¶

Upon restarting JupyterHub, you should see a message like below in the logs:

Adding API token for <username>

Enable subdomains¶

JupyterHub provides the ability to run single-user servers on their own subdomains. This means the cross-origin protections between servers has the desired effect, and user servers and the Hub are protected from each other. A user's single-user server will be at username.jupyter.mydomain.com. This also requires all user subdomains to point to the same address, which is most easily accomplished with wildcard DNS. Since this spreads the service across multiple domains, you will need wildcard SSL, as well. Unfortunately, for many institutional domains, wildcard DNS and SSL are not available. If you do plan to serve untrusted users, enabling subdomains is highly encouraged, as it resolves the cross-site issues.

Disable user config¶

If subdomains are not available or not desirable, JupyterHub provides a a configuration option Spawner.disable_user_config, which can be set to prevent the user-owned configuration files from being loaded. After implementing this option, PATHs and package installation and PATHs are the other things that the admin must enforce.

Prevent spawners from evaluating shell configuration files¶

For most Spawners, PATH is not something users can influence, but care should be taken to ensure that the Spawner does not evaluate shell configuration files prior to launching the server.

Isolate packages using virtualenv¶

Package isolation is most easily handled by running the single-user server in a virtualenv with disabled system-site-packages. The user should not have permission to install packages into this environment.

It is important to note that the control over the environment only affects the single-user server, and not the environment(s) in which the user's kernel(s) may run. Installing additional packages in the kernel environment does not pose additional risk to the web application's security.

How the Base Authenticator works¶

The base authenticator uses simple username and password authentication.

The base Authenticator has one central method:

Authenticator.authenticate(handler, data)

from tornado import gen
from IPython.utils.traitlets import Dict
from jupyterhub.auth import Authenticator

class DictionaryAuthenticator(Authenticator):

    passwords = Dict(config=True,
        help="""dict of username:password for authentication"""
    )

    @gen.coroutine
    def authenticate(self, handler, data):
        if self.passwords.get(data['username']) == data['password']:
            return data['username']

c.Authenticator.username_map  = {
  'service-name': 'localname'
}

c.Authenticator.username_pattern = r'w.*'

How to write a custom authenticator¶

You can use custom Authenticator subclasses to enable authentication via other mechanisms. One such example is using GitHub OAuth.

Because the username is passed from the Authenticator to the Spawner, a custom Authenticator and Spawner are often used together. For example, the Authenticator methods, pre_spawn_start(user, spawner) and post_spawn_stop(user, spawner), are hooks that can be used to do auth-related startup (e.g. opening PAM sessions) and cleanup (e.g. closing PAM sessions).

See a list of custom Authenticators on the wiki.

If you are interested in writing a custom authenticator, you can read this tutorial.

Authentication state¶

JupyterHub 0.8 adds the ability to persist state related to authentication, such as auth-related tokens. If such state should be persisted, .authenticate() should return a dictionary of the form:

{
  'username': 'name',
  'auth_state': {
    'key': 'value',
  }
}

where username is the username that has been authenticated, and auth_state is any JSON-serializable dictionary.

Because auth_state may contain sensitive information, it is encrypted before being stored in the database. To store auth_state, two conditions must be met:

1. persisting auth state must be enabled explicitly via configuration

   c.Authenticator.enable_auth_state = True
   

2. encryption must be enabled by the presence of JUPYTERHUB_CRYPT_KEY environment variable, which should be a hex-encoded 32-byte key. For example:

   export JUPYTERHUB_CRYPT_KEY=$(openssl rand -hex 32)
   

JupyterHub uses Fernet to encrypt auth_state. To facilitate key-rotation, JUPYTERHUB_CRYPT_KEY may be a semicolon-separated list of encryption keys. If there are multiple keys present, the first key is always used to persist any new auth_state.

class MyAuthenticator(Authenticator):
    @gen.coroutine
    def authenticate(self, handler, data=None):
        username = yield identify_user(handler, data)
        upstream_token = yield token_for_user(username)
        return {
            'name': username,
            'auth_state': {
                'upstream_token': upstream_token,
            },
        }

    @gen.coroutine
    def pre_spawn_start(self, user, spawner):
        """Pass upstream_token to spawner via environment variable"""
        auth_state = yield user.get_auth_state()
        if not auth_state:
            # auth_state not enabled
            return
        spawner.environment['UPSTREAM_TOKEN'] = auth_state['upstream_token']

Spawner.start¶

Spawner.start should start the single-user server for a single user. Information about the user can be retrieved from self.user, an object encapsulating the user's name, authentication, and server info.

The return value of Spawner.start should be the (ip, port) of the running server.

NOTE: When writing coroutines, never yield in between a database change and a commit.

Most Spawner.start functions will look similar to this example:

def start(self):
    self.ip = '127.0.0.1'
    self.port = random_port()
    yield self._actually_start_server_somehow()
    return (self.ip, self.port)

When Spawner.start returns, the single-user server process should actually be running, not just requested. JupyterHub can handle Spawner.start being very slow (such as PBS-style batch queues, or instantiating whole AWS instances) via relaxing the Spawner.start_timeout config value.

Spawner.poll¶

Spawner.poll should check if the spawner is still running. It should return None if it is still running, and an integer exit status, otherwise.

For the local process case, Spawner.poll uses os.kill(PID, 0) to check if the local process is still running.

Spawner.stop¶

Spawner.stop should stop the process. It must be a tornado coroutine, which should return when the process has finished exiting.

Spawner.options_from_form¶

Options from this form will always be a dictionary of lists of strings, e.g.:

{
  'integer': ['5'],
  'text': ['some text'],
  'select': ['a', 'b'],
}

When formdata arrives, it is passed through Spawner.options_from_form(formdata), which is a method to turn the form data into the correct structure. This method must return a dictionary, and is meant to interpret the lists-of-strings into the correct types. For example, the options_from_form for the above form would look like:

def options_from_form(self, formdata):
    options = {}
    options['integer'] = int(formdata['integer'][0]) # single integer value
    options['text'] = formdata['text'][0] # single string value
    options['select'] = formdata['select'] # list already correct
    options['notinform'] = 'extra info' # not in the form at all
    return options

which would return:

{
  'integer': 5,
  'text': 'some text',
  'select': ['a', 'b'],
  'notinform': 'extra info',
}

When Spawner.start is called, this dictionary is accessible as self.user_options.

Memory Limits & Guarantees¶

c.Spawner.mem_limit: A limit specifies the maximum amount of memory that may be allocated, though there is no promise that the maximum amount will be available. In supported spawners, you can set c.Spawner.mem_limit to limit the total amount of memory that a single-user notebook server can allocate. Attempting to use more memory than this limit will cause errors. The single-user notebook server can discover its own memory limit by looking at the environment variable MEM_LIMIT, which is specified in absolute bytes.

c.Spawner.mem_guarantee: Sometimes, a guarantee of a minumum amount of memory is desirable. In this case, you can set c.Spawner.mem_guarantee to to provide a guarantee that at minimum this much memory will always be available for the single-user notebook server to use. The environment variable MEM_GUARANTEE will also be set in the single-user notebook server.

The spawner's underlying system or cluster is responsible for enforcing these limits and providing these guarantees. If these values are set to None, no limits or guarantees are provided, and no environment values are set.

CPU Limits & Guarantees¶

c.Spawner.cpu_limit: In supported spawners, you can set c.Spawner.cpu_limit to limit the total number of cpu-cores that a single-user notebook server can use. These can be fractional - 0.5 means 50% of one CPU core, 4.0 is 4 cpu-cores, etc. This value is also set in the single-user notebook server's environment variable CPU_LIMIT. The limit does not claim that you will be able to use all the CPU up to your limit as other higher priority applications might be taking up CPU.

c.Spawner.cpu_guarantee: You can set c.Spawner.cpu_guarantee to provide a guarantee for CPU usage. The environment variable CPU_GUARANTEE will be set in the single-user notebook server when a guarantee is being provided.

The spawner's underlying system or cluster is responsible for enforcing these limits and providing these guarantees. If these values are set to None, no limits or guarantees are provided, and no environment values are set.

Flask Example¶

For example, you have a Flask service that returns information about a user. JupyterHub's HubAuth class can be used to authenticate requests to the Flask service. See the service-whoami-flask example in the JupyterHub GitHub repo for more details.

from functools import wraps
import json
import os
from urllib.parse import quote

from flask import Flask, redirect, request, Response

from jupyterhub.services.auth import HubAuth

prefix = os.environ.get('JUPYTERHUB_SERVICE_PREFIX', '/')

auth = HubAuth(
    api_token=os.environ['JUPYTERHUB_API_TOKEN'],
    cookie_cache_max_age=60,
)

app = Flask(__name__)


def authenticated(f):
    """Decorator for authenticating with the Hub"""
    @wraps(f)
    def decorated(*args, **kwargs):
        cookie = request.cookies.get(auth.cookie_name)
        token = request.headers.get(auth.auth_header_name)
        if cookie:
            user = auth.user_for_cookie(cookie)
        elif token:
            user = auth.user_for_token(token)
        else:
            user = None
        if user:
            return f(user, *args, **kwargs)
        else:
            # redirect to login url on failed auth
            return redirect(auth.login_url + '?next=%s' % quote(request.path))
    return decorated


@app.route(prefix)
@authenticated
def whoami(user):
    return Response(
        json.dumps(user, indent=1, sort_keys=True),
        mimetype='application/json',
        )

Authenticating tornado services with JupyterHub¶

Since most Jupyter services are written with tornado, we include a mixin class, HubAuthenticated, for quickly authenticating your own tornado services with JupyterHub.

Tornado's @web.authenticated method calls a Handler's .get_current_user method to identify the user. Mixing in HubAuthenticated defines get_current_user to use HubAuth. If you want to configure the HubAuth instance beyond the default, you'll want to define an initialize method, such as:

class MyHandler(HubAuthenticated, web.RequestHandler):
    hub_users = {'inara', 'mal'}

    def initialize(self, hub_auth):
        self.hub_auth = hub_auth

    @web.authenticated
    def get(self):
        ...

The HubAuth will automatically load the desired configuration from the Service environment variables.

If you want to limit user access, you can whitelist users through either the .hub_users attribute or .hub_groups. These are sets that check against the username and user group list, respectively. If a user matches neither the user list nor the group list, they will not be allowed access. If both are left undefined, then any user will be allowed.

Implementing your own Authentication with JupyterHub¶

If you don't want to use the reference implementation (e.g. you find the implementation a poor fit for your Flask app), you can implement authentication via the Hub yourself. We recommend looking at the HubAuth class implementation for reference, and taking note of the following process:

1. retrieve the cookie jupyterhub-services from the request.

2. Make an API request GET /hub/api/authorizations/cookie/jupyterhub-services/cookie-value, where cookie-value is the url-encoded value of the jupyterhub-services cookie. This request must be authenticated with a Hub API token in the Authorization header. For example, with requests:

   r = requests.get(
       '/'.join((["http://127.0.0.1:8081/hub/api",
                  "authorizations/cookie/jupyterhub-services",
                  quote(encrypted_cookie, safe=''),
       ]),
       headers = {
           'Authorization' : 'token %s' % api_token,
       },
   )
   r.raise_for_status()
   user = r.json()
   

3. On success, the reply will be a JSON model describing the user:

   {
     "name": "inara",
     "groups": ["serenity", "guild"],
   
   }
   

An example of using an Externally-Managed Service and authentication is in [nbviewer README]_ section on securing the notebook viewer, and an example of its configuration is found here. nbviewer can also be run as a Hub-Managed Service as described [nbviewer README]_ section on securing the notebook viewer.

Purely external proxies¶

Probably most custom proxies will be externally managed, such as Kubernetes ingress-based implementations. In this case, you do not need to define start and stop. To disable the methods, you can define should_start = False at the class level:

class MyProxy(Proxy):
    should_start = False

Adding a route¶

When adding a route, JupyterHub may pass a JSON-serializable dict as a data argument that should be attacked to the proxy route. When that route is retrieved, the data argument should be returned as well. If your proxy implementation doesn't support storing data attached to routes, then your Python wrapper may have to handle storing the data piece itself, e.g in a simple file or database.

@gen.coroutine
def add_route(self, routespec, target, data):
    """Proxy `routespec` to `target`.

    Store `data` associated with the routespec
    for retrieval later.
    """

Adding a route for a user looks like this:

proxy.add_route('/user/pgeorgiou/', 'http://127.0.0.1:1227',
                {'user': 'pgeorgiou'})

Removing routes¶

delete_route() is given a routespec to delete. If there is no such route, delete_route should still succeed, but a warning may be issued.

@gen.coroutine
def delete_route(self, routespec):
    """Delete the route"""

Retrieving routes¶

For retrieval, you only need to implement a single method that retrieves all routes. The return value for this function should be a dictionary, keyed by routespect, of dicts whose keys are the same three arguments passed to add_route (routespec, target, data)

@gen.coroutine
def get_all_routes(self):
    """Return all routes, keyed by routespec""""

{
  '/proxy/path/': {
    'routespec': '/proxy/path/',
    'target': 'http://...',
    'data': {},
  },
}

{
  '/user/pgeorgiou/': {
    'routespec': '/user/pgeorgiou/',
    'target': 'http://127.0.0.1:1227',
    'data': {
      'user': 'pgeourgiou',
      'last_activity': '2017-10-03T10:33:49.570Z',
    },
  },
}

Use requests¶

Using the popular Python requests library, here's example code to make an API request for the users of a JupyterHub deployment. An API GET request is made, and the request sends an API token for authorization. The response contains information about the users:

import requests

api_url = 'http://127.0.0.1:8081/hub/api'

r = requests.get(api_url + '/users',
    headers={
             'Authorization': 'token %s' % token,
            }
    )

r.raise_for_status()
users = r.json()

This example provides a slightly more complicated request, yet the process is very similar:

import requests

api_url = 'http://127.0.0.1:8081/hub/api'

data = {'name': 'mygroup', 'users': ['user1', 'user2']}

r = requests.post(api_url + '/groups/formgrade-data301/users',
    headers={
             'Authorization': 'token %s' % token,
            },
    json=data
)
r.raise_for_status()
r.json()

The same API token can also authorize access to the Jupyter Notebook REST API provided by notebook servers managed by JupyterHub if one of the following is true:

1. The token is for the same user as the owner of the notebook
2. The token is tied to an admin user or service and c.JupyterHub.admin_access is set to True

Some caveats for using named-servers¶

The named-server capabilities are not fully implemented for JupyterHub as yet. While it's possible to start/stop a server via the API, the UI on the JupyterHub control-panel has not been implemented, and so it may not be obvious to those viewing the panel that a named-server may be running for a given user.

For named-servers via the API to work, the spawner used to spawn these servers will need to be able to handle the case of multiple servers per user and ensure uniqueness of names, particularly if servers are spawned via docker containers or kubernetes pods.

Backup JupyterHub database¶

To prevent unintended loss of data or configuration information, you should back up the JupyterHub database (the default SQLite database or a RDBMS database using PostgreSQL, MySQL, or others supported by SQLAlchemy):

• If using the default SQLite database, back up the jupyterhub.sqlite database.
• If using an RDBMS database such as PostgreSQL, MySQL, or other supported by SQLAlchemy, back up the JupyterHub database.

Losing the Hub database is often not a big deal. Information that resides only in the Hub database includes:

• active login tokens (user cookies, service tokens)
• users added via GitHub UI, instead of config files
• info about running servers

If the following conditions are true, you should be fine clearing the Hub database and starting over:

• users specified in config file
• user servers are stopped during upgrade
• don't mind causing users to login again after upgrade

Backup JupyterHub configuration file¶

Additionally, backing up your configuration file, jupyterhub_config.py, to a secure location.

Shutdown JupyterHub¶

Prior to shutting down JupyterHub, you should notify the Hub users of the scheduled downtime. This gives users the opportunity to finish any outstanding work in process.

Next, shutdown the JupyterHub service.

Upgrade JupyterHub¶

Follow directions that correspond to your package manager, pip or conda, for the new JupyterHub release. These directions will guide you to the specific command. In general, pip install -U jupyterhub or conda upgrade jupyterhub

Upgrade JupyterHub databases¶

To run the upgrade process for JupyterHub databases, enter:

jupyterhub upgrade-db

nginx¶

The nginx server config file is fairly standard fare except for the two location blocks within the HUB.DOMAIN.TLD config file:

# top-level http config for websocket headers
# If Upgrade is defined, Connection = upgrade
# If Upgrade is empty, Connection = close
map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

# HTTP server to redirect all 80 traffic to SSL/HTTPS
server {
    listen 80;
    server_name HUB.DOMAIN.TLD;

    # Tell all requests to port 80 to be 302 redirected to HTTPS
    return 302 https://$host$request_uri;
}

# HTTPS server to handle JupyterHub
server {
    listen 443;
    ssl on;

    server_name HUB.DOMAIN.TLD;

    ssl_certificate /etc/letsencrypt/live/HUB.DOMAIN.TLD/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/HUB.DOMAIN.TLD/privkey.pem;

    ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
    ssl_prefer_server_ciphers on;
    ssl_dhparam /etc/ssl/certs/dhparam.pem;
    ssl_ciphers 'ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:DHE-DSS-AES128-GCM-SHA256:kEDH+AESGCM:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA:ECDHE-ECDSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA:DHE-DSS-AES128-SHA256:DHE-RSA-AES256-SHA256:DHE-DSS-AES256-SHA:DHE-RSA-AES256-SHA:AES128-GCM-SHA256:AES256-GCM-SHA384:AES128-SHA256:AES256-SHA256:AES128-SHA:AES256-SHA:AES:CAMELLIA:DES-CBC3-SHA:!aNULL:!eNULL:!EXPORT:!DES:!RC4:!MD5:!PSK:!aECDH:!EDH-DSS-DES-CBC3-SHA:!EDH-RSA-DES-CBC3-SHA:!KRB5-DES-CBC3-SHA';
    ssl_session_timeout 1d;
    ssl_session_cache shared:SSL:50m;
    ssl_stapling on;
    ssl_stapling_verify on;
    add_header Strict-Transport-Security max-age=15768000;

    # Managing literal requests to the JupyterHub front end
    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

        # websocket headers
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
    }

    # Managing requests to verify letsencrypt host
    location ~ /.well-known {
        allow all;
    }
}

If nginx is not running on port 443, substitute $http_host for $host on the lines setting the Host header.

nginx will now be the front facing element of JupyterHub on 443 which means it is also free to bind other servers, like NO_HUB.DOMAIN.TLD to the same port on the same machine and network interface. In fact, one can simply use the same server blocks as above for NO_HUB and simply add line for the root directory of the site as well as the applicable location call:

server {
    listen 80;
    server_name NO_HUB.DOMAIN.TLD;

    # Tell all requests to port 80 to be 302 redirected to HTTPS
    return 302 https://$host$request_uri;
}

server {
    listen 443;
    ssl on;

    # INSERT OTHER SSL PARAMETERS HERE AS ABOVE
    # SSL cert may differ

    # Set the appropriate root directory
    root /var/www/html

    # Set URI handling
    location / {
        try_files $uri $uri/ =404;
    }

    # Managing requests to verify letsencrypt host
    location ~ /.well-known {
        allow all;
    }

}

Now restart nginx, restart the JupyterHub, and enjoy accessing https://HUB.DOMAIN.TLD while serving other content securely on https://NO_HUB.DOMAIN.TLD.

Apache¶

As with nginx above, you can use Apache as the reverse proxy. First, we will need to enable the apache modules that we are going to need:

a2enmod ssl rewrite proxy proxy_http proxy_wstunnel

Our Apache configuration is equivalent to the nginx configuration above:

• Redirect HTTP to HTTPS
• Good SSL Configuration
• Support for websockets on any proxied URL
• JupyterHub is running locally at http://127.0.0.1:8000

# redirect HTTP to HTTPS
Listen 80
<VirtualHost HUB.DOMAIN.TLD:80>
  ServerName HUB.DOMAIN.TLD
  Redirect / https://HUB.DOMAIN.TLD/
</VirtualHost>

Listen 443
<VirtualHost HUB.DOMAIN.TLD:443>

  ServerName HUB.DOMAIN.TLD

  # configure SSL
  SSLEngine on
  SSLCertificateFile /etc/letsencrypt/live/HUB.DOMAIN.TLD/fullchain.pem
  SSLCertificateKeyFile /etc/letsencrypt/live/HUB.DOMAIN.TLD/privkey.pem
  SSLProtocol All -SSLv2 -SSLv3
  SSLOpenSSLConfCmd DHParameters /etc/ssl/certs/dhparam.pem
  SSLCipherSuite EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH

  # Use RewriteEngine to handle websocket connection upgrades
  RewriteEngine On
  RewriteCond %{HTTP:Connection} Upgrade [NC]
  RewriteCond %{HTTP:Upgrade} websocket [NC]
  RewriteRule /(.*) ws://127.0.0.1:8000/$1 [P,L]

  <Location "/">
    # preserve Host header to avoid cross-origin problems
    ProxyPreserveHost on
    # proxy to JupyterHub
    ProxyPass         http://127.0.0.1:8000/
    ProxyPassReverse  http://127.0.0.1:8000/
  </Location>
</VirtualHost>

JupyterHub¶

class jupyterhub.app.JupyterHub(**kwargs)¶

An Application for starting a Multi-User Jupyter Notebook server.

config c.JupyterHub.active_server_limit = Int(0)

Maximum number of concurrent servers that can be active at a time.

Setting this can limit the total resources your users can consume.

An active server is any server that’s not fully stopped. It is considered active from the time it has been requested until the time that it has completely stopped.

If this many user servers are active, users will not be able to launch new servers until a server is shutdown. Spawn requests will be rejected with a 429 error asking them to try again.

If set to 0, no limit is enforced.

config c.JupyterHub.admin_access = Bool(False)

Grant admin users permission to access single-user servers.

Users should be properly informed if this is enabled.

config c.JupyterHub.admin_users = Set()

DEPRECATED since version 0.7.2, use Authenticator.admin_users instead.

config c.JupyterHub.allow_named_servers = Bool(False)

Allow named single-user servers per user

config c.JupyterHub.answer_yes = Bool(False)

Answer yes to any questions (e.g. confirm overwrite)

config c.JupyterHub.api_tokens = Dict()

PENDING DEPRECATION: consider using service_tokens

Dict of token:username to be loaded into the database.

Allows ahead-of-time generation of API tokens for use by externally managed services, which authenticate as JupyterHub users.

Consider using service_tokens for general services that talk to the JupyterHub API.

config c.JupyterHub.authenticator_class = Type(<class 'jupyterhub.auth.PAMAuthenticator'>)

Class for authenticating users.

This should be a class with the following form:

• constructor takes one kwarg: config, the IPython config object.
• is a tornado.gen.coroutine
• returns username on success, None on failure
• takes two arguments: (handler, data), where handler is the calling web.RequestHandler, and data is the POST form data from the login page.

config c.JupyterHub.base_url = URLPrefix('/')

The base URL of the entire application

config c.JupyterHub.cleanup_proxy = Bool(True)

Whether to shutdown the proxy when the Hub shuts down.

Disable if you want to be able to teardown the Hub while leaving the proxy running.

Only valid if the proxy was starting by the Hub process.

If both this and cleanup_servers are False, sending SIGINT to the Hub will only shutdown the Hub, leaving everything else running.

The Hub should be able to resume from database state.

config c.JupyterHub.cleanup_servers = Bool(True)

Whether to shutdown single-user servers when the Hub shuts down.

Disable if you want to be able to teardown the Hub while leaving the single-user servers running.

If both this and cleanup_proxy are False, sending SIGINT to the Hub will only shutdown the Hub, leaving everything else running.

The Hub should be able to resume from database state.

config c.JupyterHub.concurrent_spawn_limit = Int(100)

Maximum number of concurrent users that can be spawning at a time.

Spawning lots of servers at the same time can cause performance problems for the Hub or the underlying spawning system. Set this limit to prevent bursts of logins from attempting to spawn too many servers at the same time.

This does not limit the number of total running servers. See active_server_limit for that.

If more than this many users attempt to spawn at a time, their requests will be rejected with a 429 error asking them to try again. Users will have to wait for some of the spawning services to finish starting before they can start their own.

If set to 0, no limit is enforced.

config c.JupyterHub.config_file = Unicode('jupyterhub_config.py')

The config file to load

config c.JupyterHub.confirm_no_ssl = Bool(False)

DEPRECATED: does nothing

config c.JupyterHub.cookie_max_age_days = Float(14)

Number of days for a login cookie to be valid. Default is two weeks.

config c.JupyterHub.cookie_secret = Bytes(b'')

The cookie secret to use to encrypt cookies.

Loaded from the JPY_COOKIE_SECRET env variable by default.

Should be exactly 256 bits (32 bytes).

config c.JupyterHub.cookie_secret_file = Unicode('jupyterhub_cookie_secret')

File in which to store the cookie secret.

config c.JupyterHub.data_files_path = Unicode('')

The location of jupyterhub data files (e.g. /usr/local/share/jupyter/hub)

config c.JupyterHub.db_kwargs = Dict()

Include any kwargs to pass to the database connection. See sqlalchemy.create_engine for details.

config c.JupyterHub.db_url = Unicode('sqlite:///jupyterhub.sqlite')

url for the database. e.g. sqlite:///jupyterhub.sqlite

config c.JupyterHub.debug_db = Bool(False)

log all database transactions. This has A LOT of output

config c.JupyterHub.debug_proxy = Bool(False)

DEPRECATED since version 0.8: Use ConfigurableHTTPProxy.debug

config c.JupyterHub.extra_log_file = Unicode('')

Send JupyterHub’s logs to this file.

This will only include the logs of the Hub itself, not the logs of the proxy or any single-user servers.

config c.JupyterHub.extra_log_handlers = List()

Extra log handlers to set on JupyterHub logger

config c.JupyterHub.generate_config = Bool(False)

Generate default config file

config c.JupyterHub.hub_connect_ip = Unicode('')

The ip or hostname for proxies and spawners to use for connecting to the Hub.

Use when the bind address (hub_ip) is 0.0.0.0 or otherwise different from the connect address.

Default: when hub_ip is 0.0.0.0, use socket.gethostname(), otherwise use hub_ip.

New in version 0.8.

config c.JupyterHub.hub_connect_port = Int(0)

The port for proxies & spawners to connect to the hub on.

Used alongside hub_connect_ip

New in version 0.8.

config c.JupyterHub.hub_ip = Unicode('127.0.0.1')

The ip address for the Hub process to bind to.

See hub_connect_ip for cases where the bind and connect address should differ.

config c.JupyterHub.hub_port = Int(8081)

The port for the Hub process

config c.JupyterHub.ip = Unicode('')

The public facing ip of the whole application (the proxy)

config c.JupyterHub.jinja_environment_options = Dict()

Supply extra arguments that will be passed to Jinja environment.

config c.JupyterHub.last_activity_interval = Int(300)

Interval (in seconds) at which to update last-activity timestamps.

config c.JupyterHub.load_groups = Dict()

Dict of ‘group’: [‘usernames’] to load at startup.

This strictly adds groups and users to groups.

Loading one set of groups, then starting JupyterHub again with a different set will not remove users or groups from previous launches. That must be done through the API.

config c.JupyterHub.log_datefmt = Unicode('%Y-%m-%d %H:%M:%S')

The date format used by logging formatters for %(asctime)s

config c.JupyterHub.log_format = Unicode('[%(name)s]%(highlevel)s %(message)s')

The Logging format template

config c.JupyterHub.log_level = Enum(30)

Set the log level by value or name.

config c.JupyterHub.logo_file = Unicode('')

Specify path to a logo image to override the Jupyter logo in the banner.

config c.JupyterHub.pid_file = Unicode('')

File to write PID Useful for daemonizing jupyterhub.

config c.JupyterHub.port = Int(8000)

The public facing port of the proxy

config c.JupyterHub.proxy_api_ip = Unicode('')

DEPRECATED since version 0.8 : Use ConfigurableHTTPProxy.api_url

config c.JupyterHub.proxy_api_port = Int(0)

DEPRECATED since version 0.8 : Use ConfigurableHTTPProxy.api_url

config c.JupyterHub.proxy_auth_token = Unicode('')

DEPRECATED since version 0.8: Use ConfigurableHTTPProxy.auth_token

config c.JupyterHub.proxy_check_interval = Int(30)

Interval (in seconds) at which to check if the proxy is running.

config c.JupyterHub.proxy_class = Type(<class 'jupyterhub.proxy.ConfigurableHTTPProxy'>)

Select the Proxy API implementation.

config c.JupyterHub.proxy_cmd = Command()

DEPRECATED since version 0.8. Use ConfigurableHTTPProxy.command

config c.JupyterHub.reset_db = Bool(False)

Purge and reset the database.

config c.JupyterHub.service_check_interval = Int(60)

Interval (in seconds) at which to check connectivity of services with web endpoints.

config c.JupyterHub.service_tokens = Dict()

Dict of token:servicename to be loaded into the database.

Allows ahead-of-time generation of API tokens for use by externally managed services.

config c.JupyterHub.services = List()

List of service specification dictionaries.

A service

For instance:

services = [
    {
        'name': 'cull_idle',
        'command': ['/path/to/cull_idle_servers.py'],
    },
    {
        'name': 'formgrader',
        'url': 'http://127.0.0.1:1234',
        'api_token': 'super-secret',
        'environment':
    }
]

config c.JupyterHub.spawner_class = Type(<class 'jupyterhub.spawner.LocalProcessSpawner'>)

The class to use for spawning single-user servers.

Should be a subclass of Spawner.

config c.JupyterHub.ssl_cert = Unicode('')

Path to SSL certificate file for the public facing interface of the proxy

When setting this, you should also set ssl_key

config c.JupyterHub.ssl_key = Unicode('')

Path to SSL key file for the public facing interface of the proxy

When setting this, you should also set ssl_cert

config c.JupyterHub.statsd_host = Unicode('')

Host to send statsd metrics to

config c.JupyterHub.statsd_port = Int(8125)

Port on which to send statsd metrics about the hub

config c.JupyterHub.statsd_prefix = Unicode('jupyterhub')

Prefix to use for all metrics sent by jupyterhub to statsd

config c.JupyterHub.subdomain_host = Unicode('')

Run single-user servers on subdomains of this host.

This should be the full https://hub.domain.tld[:port].

Provides additional cross-site protections for javascript served by single-user servers.

Requires <username>.hub.domain.tld to resolve to the same host as hub.domain.tld.

In general, this is most easily achieved with wildcard DNS.

When using SSL (i.e. always) this also requires a wildcard SSL certificate.

config c.JupyterHub.template_paths = List()

Paths to search for jinja templates.

config c.JupyterHub.tornado_settings = Dict()

Extra settings overrides to pass to the tornado application.

config c.JupyterHub.trust_user_provided_tokens = Bool(False)

Trust user-provided tokens (via JupyterHub.service_tokens) to have good entropy.

If you are not inserting additional tokens via configuration file, this flag has no effect.

In JupyterHub 0.8, internally generated tokens do not pass through additional hashing because the hashing is costly and does not increase the entropy of already-good UUIDs.

User-provided tokens, on the other hand, are not trusted to have good entropy by default, and are passed through many rounds of hashing to stretch the entropy of the key (i.e. user-provided tokens are treated as passwords instead of random keys). These keys are more costly to check.

If your inserted tokens are generated by a good-quality mechanism, e.g. openssl rand -hex 32, then you can set this flag to True to reduce the cost of checking authentication tokens.

config c.JupyterHub.upgrade_db = Bool(False)

Upgrade the database automatically on start.

Only safe if database is regularly backed up. Only SQLite databases will be backed up to a local file automatically.

Authenticator¶

class jupyterhub.auth.Authenticator(**kwargs)¶

Base class for implementing an authentication provider for JupyterHub

config c.Authenticator.admin_users = Set()

Set of users that will have admin rights on this JupyterHub.

Admin users have extra privileges:

• Use the admin panel to see list of users logged in
• Add / remove users in some authenticators
• Restart / halt the hub
• Start / stop users’ single-user servers
• Can access each individual users’ single-user server (if configured)

Admin access should be treated the same way root access is.

Defaults to an empty set, in which case no user has admin access.

config c.Authenticator.auto_login = Bool(False)

Automatically begin the login process

rather than starting with a “Login with…” link at /hub/login

To work, .login_url() must give a URL other than the default /hub/login, such as an oauth handler or another automatic login handler, registered with .get_handlers().

New in version 0.8.

config c.Authenticator.enable_auth_state = Bool(False)

Enable persisting auth_state (if available).

auth_state will be encrypted and stored in the Hub’s database. This can include things like authentication tokens, etc. to be passed to Spawners as environment variables.

Encrypting auth_state requires the cryptography package.

Additionally, the JUPYTERHUB_CRYPTO_KEY envirionment variable must contain one (or more, separated by ;) 32B encryption keys. These can be either base64 or hex-encoded.

If encryption is unavailable, auth_state cannot be persisted.

New in JupyterHub 0.8

config c.Authenticator.username_map = Dict()

Dictionary mapping authenticator usernames to JupyterHub users.

Primarily used to normalize OAuth user names to local users.

config c.Authenticator.username_pattern = Unicode('')

Regular expression pattern that all valid usernames must match.

If a username does not match the pattern specified here, authentication will not be attempted.

If not set, allow any username.

config c.Authenticator.whitelist = Set()

Whitelist of usernames that are allowed to log in.

Use this with supported authenticators to restrict which users can log in. This is an additional whitelist that further restricts users, beyond whatever restrictions the authenticator has in place.

If empty, does not perform any additional restriction.

add_user(user)¶

Hook called when a user is added to JupyterHub

This is called:

• When a user first authenticates
• When the hub restarts, for all users.

This method may be a coroutine.

By default, this just adds the user to the whitelist.

Subclasses may do more extensive things, such as adding actual unix users, but they should call super to ensure the whitelist is updated.

Note that this should be idempotent, since it is called whenever the hub restarts for all users.

Parameters:	user (User) – The User wrapper object

config c.Authenticator.admin_users = Set()

Set of users that will have admin rights on this JupyterHub.

Admin users have extra privileges:

• Use the admin panel to see list of users logged in
• Add / remove users in some authenticators
• Restart / halt the hub
• Start / stop users’ single-user servers
• Can access each individual users’ single-user server (if configured)

Admin access should be treated the same way root access is.

Defaults to an empty set, in which case no user has admin access.

authenticate(handler, data)¶

Authenticate a user with login form data

This must be a tornado gen.coroutine. It must return the username on successful authentication, and return None on failed authentication.

Checking the whitelist is handled separately by the caller.

Changed in version 0.8: Allow authenticate to return a dict containing auth_state.

Parameters:	handler (tornado.web.RequestHandler) – the current request handler data (dict) – The formdata of the login form. The default form has ‘username’ and ‘password’ fields.
Returns:	The username of the authenticated user, or None if Authentication failed. If the Authenticator has state associated with the user, it can return a dict with the keys ‘name’ and ‘auth_state’, where ‘name’ is the username and ‘auth_state’ is a dictionary of auth state that will be persisted.
Return type:	user (str or dict or None)

config c.Authenticator.auto_login = Bool(False)

Automatically begin the login process

rather than starting with a “Login with…” link at /hub/login

To work, .login_url() must give a URL other than the default /hub/login, such as an oauth handler or another automatic login handler, registered with .get_handlers().

New in version 0.8.

check_whitelist(username)¶

Check if a username is allowed to authenticate based on whitelist configuration

Return True if username is allowed, False otherwise. No whitelist means any username is allowed.

Names are normalized before being checked against the whitelist.

delete_user(user)¶

Hook called when a user is deleted

Removes the user from the whitelist. Subclasses should call super to ensure the whitelist is updated.

Parameters:	user (User) – The User wrapper object

config c.Authenticator.enable_auth_state = Bool(False)

Enable persisting auth_state (if available).

auth_state will be encrypted and stored in the Hub’s database. This can include things like authentication tokens, etc. to be passed to Spawners as environment variables.

Encrypting auth_state requires the cryptography package.

Additionally, the JUPYTERHUB_CRYPTO_KEY envirionment variable must contain one (or more, separated by ;) 32B encryption keys. These can be either base64 or hex-encoded.

If encryption is unavailable, auth_state cannot be persisted.

New in JupyterHub 0.8

get_authenticated_user(handler, data)¶

Authenticate the user who is attempting to log in

Returns user dict if successful, None otherwise.

This calls authenticate, which should be overridden in subclasses, normalizes the username if any normalization should be done, and then validates the name in the whitelist.

This is the outer API for authenticating a user. Subclasses should not override this method.

The various stages can be overridden separately:

• authenticate turns formdata into a username
• normalize_username normalizes the username
• check_whitelist checks against the user whitelist

Changed in version 0.8: return dict instead of username

get_handlers(app)¶

Return any custom handlers the authenticator needs to register

Used in conjugation with login_url and logout_url.

Parameters:	app (JupyterHub Application) – the application object, in case it needs to be accessed for info.
Returns:	list of ('/url', Handler) tuples passed to tornado. The Hub prefix is added to any URLs.
Return type:	handlers (list)

login_url(base_url)¶

Override this when registering a custom login handler

Generally used by authenticators that do not use simple form-based authentication.

The subclass overriding this is responsible for making sure there is a handler available to handle the URL returned from this method, using the get_handlers method.

Parameters:	base_url (str) – the base URL of the Hub (e.g. /hub/)
Returns:	The login URL, e.g. ‘/hub/login’
Return type:	str

logout_url(base_url)¶

Override when registering a custom logout handler

The subclass overriding this is responsible for making sure there is a handler available to handle the URL returned from this method, using the get_handlers method.

Parameters:	base_url (str) – the base URL of the Hub (e.g. /hub/)
Returns:	The logout URL, e.g. ‘/hub/logout’
Return type:	str

normalize_username(username)¶

Normalize the given username and return it

Override in subclasses if usernames need different normalization rules.

The default attempts to lowercase the username and apply username_map if it is set.

post_spawn_stop(user, spawner)¶

Hook called after stopping a user container

Can be used to do auth-related cleanup, e.g. closing PAM sessions.

pre_spawn_start(user, spawner)¶

Hook called before spawning a user’s server

Can be used to do auth-related startup, e.g. opening PAM sessions.

config c.Authenticator.username_map = Dict()

Dictionary mapping authenticator usernames to JupyterHub users.

Primarily used to normalize OAuth user names to local users.

config c.Authenticator.username_pattern = Unicode('')

Regular expression pattern that all valid usernames must match.

If a username does not match the pattern specified here, authentication will not be attempted.

If not set, allow any username.

validate_username(username)¶

Validate a normalized username

Return True if username is valid, False otherwise.

config c.Authenticator.whitelist = Set()

Whitelist of usernames that are allowed to log in.

Use this with supported authenticators to restrict which users can log in. This is an additional whitelist that further restricts users, beyond whatever restrictions the authenticator has in place.

If empty, does not perform any additional restriction.

LocalAuthenticator¶

class jupyterhub.auth.LocalAuthenticator(**kwargs)¶

Base class for Authenticators that work with local Linux/UNIX users

Checks for local users, and can attempt to create them if they exist.

config c.LocalAuthenticator.add_user_cmd = Command()

The command to use for creating users as a list of strings

For each element in the list, the string USERNAME will be replaced with the user’s username. The username will also be appended as the final argument.

For Linux, the default value is:

[‘adduser’, ‘-q’, ‘–gecos’, ‘”“’, ‘–disabled-password’]

To specify a custom home directory, set this to:

[‘adduser’, ‘-q’, ‘–gecos’, ‘”“’, ‘–home’, ‘/customhome/USERNAME’, ‘–disabled-password’]

This will run the command:

adduser -q –gecos “” –home /customhome/river –disabled-password river

when the user ‘river’ is created.

config c.LocalAuthenticator.admin_users = Set()

Set of users that will have admin rights on this JupyterHub.

Admin users have extra privileges:

• Use the admin panel to see list of users logged in
• Add / remove users in some authenticators
• Restart / halt the hub
• Start / stop users’ single-user servers
• Can access each individual users’ single-user server (if configured)

Admin access should be treated the same way root access is.

Defaults to an empty set, in which case no user has admin access.

config c.LocalAuthenticator.auto_login = Bool(False)

Automatically begin the login process

rather than starting with a “Login with…” link at /hub/login

To work, .login_url() must give a URL other than the default /hub/login, such as an oauth handler or another automatic login handler, registered with .get_handlers().

New in version 0.8.

config c.LocalAuthenticator.create_system_users = Bool(False)

If set to True, will attempt to create local system users if they do not exist already.

Supports Linux and BSD variants only.

config c.LocalAuthenticator.enable_auth_state = Bool(False)

Enable persisting auth_state (if available).

auth_state will be encrypted and stored in the Hub’s database. This can include things like authentication tokens, etc. to be passed to Spawners as environment variables.

Encrypting auth_state requires the cryptography package.

Additionally, the JUPYTERHUB_CRYPTO_KEY envirionment variable must contain one (or more, separated by ;) 32B encryption keys. These can be either base64 or hex-encoded.

If encryption is unavailable, auth_state cannot be persisted.

New in JupyterHub 0.8

config c.LocalAuthenticator.group_whitelist = Set()

Whitelist all users from this UNIX group.

This makes the username whitelist ineffective.

config c.LocalAuthenticator.username_map = Dict()

Dictionary mapping authenticator usernames to JupyterHub users.

Primarily used to normalize OAuth user names to local users.

config c.LocalAuthenticator.username_pattern = Unicode('')

Regular expression pattern that all valid usernames must match.

If a username does not match the pattern specified here, authentication will not be attempted.

If not set, allow any username.

config c.LocalAuthenticator.whitelist = Set()

Whitelist of usernames that are allowed to log in.

Use this with supported authenticators to restrict which users can log in. This is an additional whitelist that further restricts users, beyond whatever restrictions the authenticator has in place.

If empty, does not perform any additional restriction.

add_system_user(user)¶

Create a new local UNIX user on the system.

Tested to work on FreeBSD and Linux, at least.

add_user(user)¶

Hook called whenever a new user is added

If self.create_system_users, the user will attempt to be created if it doesn’t exist.

config c.LocalAuthenticator.add_user_cmd = Command()

The command to use for creating users as a list of strings

For each element in the list, the string USERNAME will be replaced with the user’s username. The username will also be appended as the final argument.

For Linux, the default value is:

[‘adduser’, ‘-q’, ‘–gecos’, ‘”“’, ‘–disabled-password’]

To specify a custom home directory, set this to:

[‘adduser’, ‘-q’, ‘–gecos’, ‘”“’, ‘–home’, ‘/customhome/USERNAME’, ‘–disabled-password’]

This will run the command:

adduser -q –gecos “” –home /customhome/river –disabled-password river

when the user ‘river’ is created.

check_group_whitelist(username)¶

If group_whitelist is configured, check if authenticating user is part of group.

config c.LocalAuthenticator.create_system_users = Bool(False)

If set to True, will attempt to create local system users if they do not exist already.

Supports Linux and BSD variants only.

config c.LocalAuthenticator.group_whitelist = Set()

Whitelist all users from this UNIX group.

This makes the username whitelist ineffective.

static system_user_exists(user)¶

Check if the user exists on the system

PAMAuthenticator¶

class jupyterhub.auth.PAMAuthenticator(**kwargs)¶

Authenticate local UNIX users with PAM

config c.PAMAuthenticator.add_user_cmd = Command()

The command to use for creating users as a list of strings

For each element in the list, the string USERNAME will be replaced with the user’s username. The username will also be appended as the final argument.

For Linux, the default value is:

[‘adduser’, ‘-q’, ‘–gecos’, ‘”“’, ‘–disabled-password’]

To specify a custom home directory, set this to:

[‘adduser’, ‘-q’, ‘–gecos’, ‘”“’, ‘–home’, ‘/customhome/USERNAME’, ‘–disabled-password’]

This will run the command:

adduser -q –gecos “” –home /customhome/river –disabled-password river

when the user ‘river’ is created.

config c.PAMAuthenticator.admin_users = Set()

Set of users that will have admin rights on this JupyterHub.

Admin users have extra privileges:

• Use the admin panel to see list of users logged in
• Add / remove users in some authenticators
• Restart / halt the hub
• Start / stop users’ single-user servers
• Can access each individual users’ single-user server (if configured)

Admin access should be treated the same way root access is.

Defaults to an empty set, in which case no user has admin access.

config c.PAMAuthenticator.auto_login = Bool(False)

Automatically begin the login process

rather than starting with a “Login with…” link at /hub/login

To work, .login_url() must give a URL other than the default /hub/login, such as an oauth handler or another automatic login handler, registered with .get_handlers().

New in version 0.8.

config c.PAMAuthenticator.create_system_users = Bool(False)

If set to True, will attempt to create local system users if they do not exist already.

Supports Linux and BSD variants only.

config c.PAMAuthenticator.enable_auth_state = Bool(False)

Enable persisting auth_state (if available).

auth_state will be encrypted and stored in the Hub’s database. This can include things like authentication tokens, etc. to be passed to Spawners as environment variables.

Encrypting auth_state requires the cryptography package.

Additionally, the JUPYTERHUB_CRYPTO_KEY envirionment variable must contain one (or more, separated by ;) 32B encryption keys. These can be either base64 or hex-encoded.

If encryption is unavailable, auth_state cannot be persisted.

New in JupyterHub 0.8

config c.PAMAuthenticator.encoding = Unicode('utf8')

The text encoding to use when communicating with PAM

config c.PAMAuthenticator.group_whitelist = Set()

Whitelist all users from this UNIX group.

This makes the username whitelist ineffective.

config c.PAMAuthenticator.open_sessions = Bool(True)

Whether to open a new PAM session when spawners are started.

This may trigger things like mounting shared filsystems, loading credentials, etc. depending on system configuration, but it does not always work.

If any errors are encountered when opening/closing PAM sessions, this is automatically set to False.

config c.PAMAuthenticator.service = Unicode('login')

The name of the PAM service to use for authentication

config c.PAMAuthenticator.username_map = Dict()

Dictionary mapping authenticator usernames to JupyterHub users.

Primarily used to normalize OAuth user names to local users.

config c.PAMAuthenticator.username_pattern = Unicode('')

Regular expression pattern that all valid usernames must match.

If a username does not match the pattern specified here, authentication will not be attempted.

If not set, allow any username.

config c.PAMAuthenticator.whitelist = Set()

Whitelist of usernames that are allowed to log in.

Use this with supported authenticators to restrict which users can log in. This is an additional whitelist that further restricts users, beyond whatever restrictions the authenticator has in place.

If empty, does not perform any additional restriction.

Spawner¶

class jupyterhub.spawner.Spawner(**kwargs)¶

Base class for spawning single-user notebook servers.

Subclass this, and override the following methods:

• load_state
• get_state
• start
• stop
• poll

As JupyterHub supports multiple users, an instance of the Spawner subclass is created for each user. If there are 20 JupyterHub users, there will be 20 instances of the subclass.

config c.Spawner.args = List()

Extra arguments to be passed to the single-user server.

Some spawners allow shell-style expansion here, allowing you to use environment variables here. Most, including the default, do not. Consult the documentation for your spawner to verify!

config c.Spawner.cmd = Command()

The command used for starting the single-user server.

Provide either a string or a list containing the path to the startup script command. Extra arguments, other than this path, should be provided via args.

This is usually set if you want to start the single-user server in a different python environment (with virtualenv/conda) than JupyterHub itself.

Some spawners allow shell-style expansion here, allowing you to use environment variables. Most, including the default, do not. Consult the documentation for your spawner to verify!

config c.Spawner.cpu_guarantee = Float(None)

Minimum number of cpu-cores a single-user notebook server is guaranteed to have available.

If this value is set to 0.5, allows use of 50% of one CPU. If this value is set to 2, allows use of up to 2 CPUs.

Note that this needs to be supported by your spawner for it to work.

config c.Spawner.cpu_limit = Float(None)

Maximum number of cpu-cores a single-user notebook server is allowed to use.

If this value is set to 0.5, allows use of 50% of one CPU. If this value is set to 2, allows use of up to 2 CPUs.

The single-user notebook server will never be scheduled by the kernel to use more cpu-cores than this. There is no guarantee that it can access this many cpu-cores.

This needs to be supported by your spawner for it to work.

config c.Spawner.debug = Bool(False)

Enable debug-logging of the single-user server

config c.Spawner.default_url = Unicode('')

The URL the single-user server should start in.

{username} will be expanded to the user’s username

Example uses:

• You can set notebook_dir to / and default_url to /tree/home/{username} to allow people to navigate the whole filesystem from their notebook server, but still start in their home directory.
• Start with /notebooks instead of /tree if default_url points to a notebook instead of a directory.
• You can set this to /lab to have JupyterLab start by default, rather than Jupyter Notebook.

config c.Spawner.disable_user_config = Bool(False)

Disable per-user configuration of single-user servers.

When starting the user’s single-user server, any config file found in the user’s $HOME directory will be ignored.

Note: a user could circumvent this if the user modifies their Python environment, such as when they have their own conda environments / virtualenvs / containers.

config c.Spawner.env_keep = List()

Whitelist of environment variables for the single-user server to inherit from the JupyterHub process.

This whitelist is used to ensure that sensitive information in the JupyterHub process’s environment (such as CONFIGPROXY_AUTH_TOKEN) is not passed to the single-user server’s process.

config c.Spawner.environment = Dict()

Extra environment variables to set for the single-user server’s process.

Environment variables that end up in the single-user server’s process come from 3 sources:

• This environment configurable
• The JupyterHub process’ environment variables that are whitelisted in env_keep
• Variables to establish contact between the single-user notebook and the hub (such as JUPYTERHUB_API_TOKEN)

The enviornment configurable should be set by JupyterHub administrators to add installation specific environment variables. It is a dict where the key is the name of the environment variable, and the value can be a string or a callable. If it is a callable, it will be called with one parameter (the spawner instance), and should return a string fairly quickly (no blocking operations please!).

Note that the spawner class’ interface is not guaranteed to be exactly same across upgrades, so if you are using the callable take care to verify it continues to work after upgrades!

config c.Spawner.http_timeout = Int(30)

Timeout (in seconds) before giving up on a spawned HTTP server

Once a server has successfully been spawned, this is the amount of time we wait before assuming that the server is unable to accept connections.

config c.Spawner.ip = Unicode('')

The IP address (or hostname) the single-user server should listen on.

The JupyterHub proxy implementation should be able to send packets to this interface.

config c.Spawner.mem_guarantee = ByteSpecification(None)

Minimum number of bytes a single-user notebook server is guaranteed to have available.

Allows the following suffixes:

• K -> Kilobytes
• M -> Megabytes
• G -> Gigabytes
• T -> Terabytes

This needs to be supported by your spawner for it to work.

config c.Spawner.mem_limit = ByteSpecification(None)

Maximum number of bytes a single-user notebook server is allowed to use.

Allows the following suffixes:

• K -> Kilobytes
• M -> Megabytes
• G -> Gigabytes
• T -> Terabytes

If the single user server tries to allocate more memory than this, it will fail. There is no guarantee that the single-user notebook server will be able to allocate this much memory - only that it can not allocate more than this.

This needs to be supported by your spawner for it to work.

config c.Spawner.notebook_dir = Unicode('')

Path to the notebook directory for the single-user server.

The user sees a file listing of this directory when the notebook interface is started. The current interface does not easily allow browsing beyond the subdirectories in this directory’s tree.

~ will be expanded to the home directory of the user, and {username} will be replaced with the name of the user.

Note that this does not prevent users from accessing files outside of this path! They can do so with many other means.

config c.Spawner.options_form = Unicode('')

An HTML form for options a user can specify on launching their server.

The surrounding <form> element and the submit button are already provided.

For example:

Set your key:
<input name="key" val="default_key"></input>
<br>
Choose a letter:
<select name="letter" multiple="true">
  <option value="A">The letter A</option>
  <option value="B">The letter B</option>
</select>

The data from this form submission will be passed on to your spawner in self.user_options

config c.Spawner.poll_interval = Int(30)

Interval (in seconds) on which to poll the spawner for single-user server’s status.

At every poll interval, each spawner’s .poll method is called, which checks if the single-user server is still running. If it isn’t running, then JupyterHub modifies its own state accordingly and removes appropriate routes from the configurable proxy.

config c.Spawner.port = Int(0)

The port for single-user servers to listen on.

Defaults to 0, which uses a randomly allocated port number each time.

If set to a non-zero value, all Spawners will use the same port, which only makes sense if each server is on a different address, e.g. in containers.

New in version 0.7.

config c.Spawner.pre_spawn_hook = Any(None)

An optional hook function that you can implement to do some bootstrapping work before the spawner starts. For example, create a directory for your user or load initial content.

This can be set independent of any concrete spawner implementation.

Example:

from subprocess import check_call
def my_hook(spawner):
    username = spawner.user.name
    check_call(['./examples/bootstrap-script/bootstrap.sh', username])

c.Spawner.pre_spawn_hook = my_hook

config c.Spawner.start_timeout = Int(60)

Timeout (in seconds) before giving up on starting of single-user server.

This is the timeout for start to return, not the timeout for the server to respond. Callers of spawner.start will assume that startup has failed if it takes longer than this. start should return when the server process is started and its location is known.

format_string(s)¶

Render a Python format string

Uses Spawner.template_namespace() to populate format namespace.

Parameters:	s (str) – Python format-string to be formatted.
Returns:	Formatted string, rendered
Return type:	str

get_args()¶

Return the arguments to be passed after self.cmd

Doesn’t expect shell expansion to happen.

get_env()¶

Return the environment dict to use for the Spawner.

This applies things like env_keep, anything defined in Spawner.environment, and adds the API token to the env.

When overriding in subclasses, subclasses must call super().get_env(), extend the returned dict and return it.

Use this to access the env in Spawner.start to allow extension in subclasses.

get_state()¶

Save state of spawner into database.

A black box of extra state for custom spawners. The returned value of this is passed to load_state.

Subclasses should call super().get_state(), augment the state returned from there, and return that state.

Returns:	state – a JSONable dict of state
Return type:	dict

options_from_form(form_data)¶

Interpret HTTP form data

Form data will always arrive as a dict of lists of strings. Override this function to understand single-values, numbers, etc.

This should coerce form data into the structure expected by self.user_options, which must be a dict.

Instances will receive this data on self.user_options, after passing through this function, prior to Spawner.start.

poll()¶

Check if the single-user process is running

Returns:	None if single-user process is running. Integer exit status (0 if unknown), if it is not running.

State transitions, behavior, and return response:

• If the Spawner has not been initialized (neither loaded state, nor called start), it should behave as if it is not running (status=0).
• If the Spawner has not finished starting, it should behave as if it is running (status=None).

Design assumptions about when poll may be called:

• On Hub launch: poll may be called before start when state is loaded on Hub launch. poll should return exit status 0 (unknown) if the Spawner has not been initialized via load_state or start.
• If .start() is async: poll may be called during any yielded portions of the start process. poll should return None when start is yielded, indicating that the start process has not yet completed.

start()¶

Start the single-user server

Returns:	the (ip, port) where the Hub can connect to the server.
Return type:	(str, int)

Changed in version 0.7: Return ip, port instead of setting on self.user.server directly.

stop(now=False)¶

Stop the single-user server

If now is False (default), shutdown the server as gracefully as possible, e.g. starting with SIGINT, then SIGTERM, then SIGKILL. If now is True, terminate the server immediately.

The coroutine should return when the single-user server process is no longer running.

Must be a coroutine.

template_namespace()¶

Return the template namespace for format-string formatting.

Currently used on default_url and notebook_dir.

Subclasses may add items to the available namespace.

The default implementation includes:

{
  'username': user.name,
  'base_url': users_base_url,
}

Returns:	namespace for string formatting.
Return type:	ns (dict)

LocalProcessSpawner¶

class jupyterhub.spawner.LocalProcessSpawner(**kwargs)¶

A Spawner that uses subprocess.Popen to start single-user servers as local processes.

Requires local UNIX users matching the authenticated users to exist. Does not work on Windows.

This is the default spawner for JupyterHub.

config c.LocalProcessSpawner.args = List()

Extra arguments to be passed to the single-user server.

Some spawners allow shell-style expansion here, allowing you to use environment variables here. Most, including the default, do not. Consult the documentation for your spawner to verify!

config c.LocalProcessSpawner.cmd = Command()

The command used for starting the single-user server.

Provide either a string or a list containing the path to the startup script command. Extra arguments, other than this path, should be provided via args.

This is usually set if you want to start the single-user server in a different python environment (with virtualenv/conda) than JupyterHub itself.

Some spawners allow shell-style expansion here, allowing you to use environment variables. Most, including the default, do not. Consult the documentation for your spawner to verify!

config c.LocalProcessSpawner.cpu_guarantee = Float(None)

Minimum number of cpu-cores a single-user notebook server is guaranteed to have available.

If this value is set to 0.5, allows use of 50% of one CPU. If this value is set to 2, allows use of up to 2 CPUs.

Note that this needs to be supported by your spawner for it to work.

config c.LocalProcessSpawner.cpu_limit = Float(None)

Maximum number of cpu-cores a single-user notebook server is allowed to use.

If this value is set to 0.5, allows use of 50% of one CPU. If this value is set to 2, allows use of up to 2 CPUs.

The single-user notebook server will never be scheduled by the kernel to use more cpu-cores than this. There is no guarantee that it can access this many cpu-cores.

This needs to be supported by your spawner for it to work.

config c.LocalProcessSpawner.debug = Bool(False)

Enable debug-logging of the single-user server

config c.LocalProcessSpawner.default_url = Unicode('')

The URL the single-user server should start in.

{username} will be expanded to the user’s username

Example uses:

• You can set notebook_dir to / and default_url to /tree/home/{username} to allow people to navigate the whole filesystem from their notebook server, but still start in their home directory.
• Start with /notebooks instead of /tree if default_url points to a notebook instead of a directory.
• You can set this to /lab to have JupyterLab start by default, rather than Jupyter Notebook.

config c.LocalProcessSpawner.disable_user_config = Bool(False)

Disable per-user configuration of single-user servers.

When starting the user’s single-user server, any config file found in the user’s $HOME directory will be ignored.

Note: a user could circumvent this if the user modifies their Python environment, such as when they have their own conda environments / virtualenvs / containers.

config c.LocalProcessSpawner.env_keep = List()

Whitelist of environment variables for the single-user server to inherit from the JupyterHub process.

This whitelist is used to ensure that sensitive information in the JupyterHub process’s environment (such as CONFIGPROXY_AUTH_TOKEN) is not passed to the single-user server’s process.

config c.LocalProcessSpawner.environment = Dict()

Extra environment variables to set for the single-user server’s process.

Environment variables that end up in the single-user server’s process come from 3 sources:

• This environment configurable
• The JupyterHub process’ environment variables that are whitelisted in env_keep
• Variables to establish contact between the single-user notebook and the hub (such as JUPYTERHUB_API_TOKEN)

The enviornment configurable should be set by JupyterHub administrators to add installation specific environment variables. It is a dict where the key is the name of the environment variable, and the value can be a string or a callable. If it is a callable, it will be called with one parameter (the spawner instance), and should return a string fairly quickly (no blocking operations please!).

Note that the spawner class’ interface is not guaranteed to be exactly same across upgrades, so if you are using the callable take care to verify it continues to work after upgrades!

config c.LocalProcessSpawner.http_timeout = Int(30)

Timeout (in seconds) before giving up on a spawned HTTP server

Once a server has successfully been spawned, this is the amount of time we wait before assuming that the server is unable to accept connections.

config c.LocalProcessSpawner.interrupt_timeout = Int(10)

Seconds to wait for single-user server process to halt after SIGINT.

If the process has not exited cleanly after this many seconds, a SIGTERM is sent.

config c.LocalProcessSpawner.ip = Unicode('')

The IP address (or hostname) the single-user server should listen on.

The JupyterHub proxy implementation should be able to send packets to this interface.

config c.LocalProcessSpawner.kill_timeout = Int(5)

Seconds to wait for process to halt after SIGKILL before giving up.

If the process does not exit cleanly after this many seconds of SIGKILL, it becomes a zombie process. The hub process will log a warning and then give up.

config c.LocalProcessSpawner.mem_guarantee = ByteSpecification(None)

Minimum number of bytes a single-user notebook server is guaranteed to have available.

Allows the following suffixes:

• K -> Kilobytes
• M -> Megabytes
• G -> Gigabytes
• T -> Terabytes

This needs to be supported by your spawner for it to work.

config c.LocalProcessSpawner.mem_limit = ByteSpecification(None)

Maximum number of bytes a single-user notebook server is allowed to use.

Allows the following suffixes:

• K -> Kilobytes
• M -> Megabytes
• G -> Gigabytes
• T -> Terabytes

If the single user server tries to allocate more memory than this, it will fail. There is no guarantee that the single-user notebook server will be able to allocate this much memory - only that it can not allocate more than this.

This needs to be supported by your spawner for it to work.

config c.LocalProcessSpawner.notebook_dir = Unicode('')

Path to the notebook directory for the single-user server.

The user sees a file listing of this directory when the notebook interface is started. The current interface does not easily allow browsing beyond the subdirectories in this directory’s tree.

~ will be expanded to the home directory of the user, and {username} will be replaced with the name of the user.

Note that this does not prevent users from accessing files outside of this path! They can do so with many other means.

config c.LocalProcessSpawner.options_form = Unicode('')

An HTML form for options a user can specify on launching their server.

The surrounding <form> element and the submit button are already provided.

For example:

Set your key:
<input name="key" val="default_key"></input>
<br>
Choose a letter:
<select name="letter" multiple="true">
  <option value="A">The letter A</option>
  <option value="B">The letter B</option>
</select>

The data from this form submission will be passed on to your spawner in self.user_options

config c.LocalProcessSpawner.poll_interval = Int(30)

Interval (in seconds) on which to poll the spawner for single-user server’s status.

At every poll interval, each spawner’s .poll method is called, which checks if the single-user server is still running. If it isn’t running, then JupyterHub modifies its own state accordingly and removes appropriate routes from the configurable proxy.

config c.LocalProcessSpawner.popen_kwargs = Dict()

Extra keyword arguments to pass to Popen

when spawning single-user servers.

For example:

popen_kwargs = dict(shell=True)

config c.LocalProcessSpawner.port = Int(0)

The port for single-user servers to listen on.

Defaults to 0, which uses a randomly allocated port number each time.

If set to a non-zero value, all Spawners will use the same port, which only makes sense if each server is on a different address, e.g. in containers.

New in version 0.7.

config c.LocalProcessSpawner.pre_spawn_hook = Any(None)

An optional hook function that you can implement to do some bootstrapping work before the spawner starts. For example, create a directory for your user or load initial content.

This can be set independent of any concrete spawner implementation.

Example:

from subprocess import check_call
def my_hook(spawner):
    username = spawner.user.name
    check_call(['./examples/bootstrap-script/bootstrap.sh', username])

c.Spawner.pre_spawn_hook = my_hook

config c.LocalProcessSpawner.start_timeout = Int(60)

Timeout (in seconds) before giving up on starting of single-user server.

This is the timeout for start to return, not the timeout for the server to respond. Callers of spawner.start will assume that startup has failed if it takes longer than this. start should return when the server process is started and its location is known.

config c.LocalProcessSpawner.term_timeout = Int(5)

Seconds to wait for single-user server process to halt after SIGTERM.

If the process does not exit cleanly after this many seconds of SIGTERM, a SIGKILL is sent.

Proxy¶

class jupyterhub.proxy.Proxy(**kwargs)¶

Base class for configurable proxies that JupyterHub can use.

A proxy implementation should subclass this and must define the following methods:

• get_all_routes() return a dictionary of all JupyterHub-related routes
• add_route() adds a route
• delete_route() deletes a route

In addition to these, the following method(s) may need to be implemented:

• start() start the proxy, if it should be launched by the Hub instead of externally managed. If the proxy is externally managed, it should set should_start to False.
• stop() stop the proxy. Only used if start() is also used.

And the following method(s) are optional, but can be provided:

• get_route() gets a single route. There is a default implementation that extracts data from get_all_routes(), but implementations may choose to provide a more efficient implementation of fetching a single route.

config c.Proxy.should_start = Bool(True)

Should the Hub start the proxy

If True, the Hub will start the proxy and stop it. Set to False if the proxy is managed externally, such as by systemd, docker, or another service manager.

add_all_services(service_dict)¶

Update the proxy table from the database.

Used when loading up a new proxy.

add_all_users(user_dict)¶

Update the proxy table from the database.

Used when loading up a new proxy.

add_hub_route(hub)¶

Add the default route for the Hub

add_route(routespec, target, data)¶

Add a route to the proxy.

Subclasses must define this method

Parameters:	routespec (str) – A URL prefix ([host]/path/) for which this route will be matched, e.g. host.name/path/ target (str) – A full URL that will be the target of this route. data (dict) – A JSONable dict that will be associated with this route, and will be returned when retrieving information about this route.

Will raise an appropriate Exception (FIXME: find what?) if the route could not be added.

The proxy implementation should also have a way to associate the fact that a route came from JupyterHub.

add_service(service, client=None)¶

Add a service’s server to the proxy table.

add_user(user, server_name='', client=None)¶

Add a user’s server to the proxy table.

check_routes(user_dict, service_dict, routes=None)¶

Check that all users are properly routed on the proxy.

delete_route(routespec)¶

Delete a route with a given routespec if it exists.

Subclasses must define this method

delete_service(service, client=None)¶

Remove a service’s server from the proxy table.

delete_user(user, server_name='')¶

Remove a user’s server from the proxy table.

get_all_routes()¶

Fetch and return all the routes associated by JupyterHub from the proxy.

Subclasses must define this method

Should return a dictionary of routes, where the keys are routespecs and each value is a dict of the form:

{
  'routespec': the route specification ([host]/path/)
  'target': the target host URL (proto://host) for this route
  'data': the attached data dict for this route (as specified in add_route)
}

get_route(routespec)¶

Return the route info for a given routespec.

Parameters:	routespec (str) – A URI that was used to add this route, e.g. host.tld/path/
Returns:	dict with the following keys: 'routespec': The normalized route specification passed in to add_route ([host]/path/) 'target': The target host for this route (proto://host) 'data': The arbitrary data dict that was passed in by JupyterHub when adding this route. None: if there are no routes matching the given routespec
Return type:	result (dict)

config c.Proxy.should_start = Bool(True)

Should the Hub start the proxy

If True, the Hub will start the proxy and stop it. Set to False if the proxy is managed externally, such as by systemd, docker, or another service manager.

start()¶

Start the proxy.

Will be called during startup if should_start is True.

Subclasses must define this method if the proxy is to be started by the Hub

stop()¶

Stop the proxy.

Will be called during teardown if should_start is True.

Subclasses must define this method if the proxy is to be started by the Hub

validate_routespec(routespec)¶

Validate a routespec

• Checks host value vs host-based routing.
• Ensures trailing slash on path.

ConfigurableHTTPProxy¶

class jupyterhub.proxy.ConfigurableHTTPProxy(**kwargs)¶

Proxy implementation for the default configurable-http-proxy.

This is the default proxy implementation for running the nodejs proxy configurable-http-proxy.

If the proxy should not be run as a subprocess of the Hub, (e.g. in a separate container), set:

c.ConfigurableHTTPProxy.should_start = False

config c.ConfigurableHTTPProxy.api_url = Unicode('http://127.0.0.1:8001')

The ip (or hostname) of the proxy’s API endpoint

config c.ConfigurableHTTPProxy.auth_token = Unicode('')

The Proxy auth token

Loaded from the CONFIGPROXY_AUTH_TOKEN env variable by default.

config c.ConfigurableHTTPProxy.command = Command()

The command to start the proxy

config c.ConfigurableHTTPProxy.debug = Bool(False)

Add debug-level logging to the Proxy.

config c.ConfigurableHTTPProxy.should_start = Bool(True)

Should the Hub start the proxy

If True, the Hub will start the proxy and stop it. Set to False if the proxy is managed externally, such as by systemd, docker, or another service manager.

config c.ConfigurableHTTPProxy.api_url = Unicode('http://127.0.0.1:8001')

The ip (or hostname) of the proxy’s API endpoint

config c.ConfigurableHTTPProxy.auth_token = Unicode('')

The Proxy auth token

Loaded from the CONFIGPROXY_AUTH_TOKEN env variable by default.

config c.ConfigurableHTTPProxy.command = Command()

The command to start the proxy

config c.ConfigurableHTTPProxy.debug = Bool(False)

Add debug-level logging to the Proxy.

UserDict¶

class jupyterhub.user.UserDict(db_factory, settings)¶

Like defaultdict, but for users

Getting by a user id OR an orm.User instance returns a User wrapper around the orm user.

count_active_users()¶

Count the number of user servers that are active/pending/ready

Returns dict with counts of active/pending/ready servers

User¶

class jupyterhub.user.User(orm_user, settings=None, **kwargs)¶

name¶

The user’s name

server¶

The user’s Server data object if running, None otherwise. Has ip, port attributes.

spawner¶

The user’s Spawner instance.

escaped_name¶

My name, escaped for use in URLs, cookies, etc.

Service¶

class jupyterhub.services.service.Service(**kwargs)¶

An object wrapping a service specification for Hub API consumers.

A service has inputs:

• name: str

  the name of the service

• admin: bool(false)

  whether the service should have administrative privileges

• url: str (None)

  The URL where the service is/should be. If specified, the service will be added to the proxy at /services/:name

If a service is to be managed by the Hub, it has a few extra options:

• command: (str/Popen list)

  Command for JupyterHub to spawn the service. Only use this if the service should be a subprocess. If command is not specified, it is assumed to be managed by a

• environment: dict

  Additional environment variables for the service.

• user: str

  The name of a system user to become. If unspecified, run as the same user as the Hub.

kind¶

The name of the kind of service as a string

• ‘managed’ for managed services
• ‘external’ for external services

managed¶

Am I managed by the Hub?

HubAuth¶

class jupyterhub.services.auth.HubAuth(**kwargs)¶

A class for authenticating with JupyterHub

This can be used by any application.

If using tornado, use via HubAuthenticated mixin. If using manually, use the .user_for_cookie(cookie_value) method to identify the user corresponding to a given cookie value.

The following config must be set:

• api_token (token for authenticating with JupyterHub API), fetched from the JUPYTERHUB_API_TOKEN env by default.

The following config MAY be set:

• api_url: the base URL of the Hub’s internal API, fetched from JUPYTERHUB_API_URL by default.
• cookie_cache_max_age: the number of seconds responses from the Hub should be cached.
• login_url (the public /hub/login URL of the Hub).
• cookie_name: the name of the cookie I should be using, if different from the default (unlikely).

config c.HubAuth.api_token = Unicode('')

API key for accessing Hub API.

Generate with jupyterhub token [username] or add to JupyterHub.services config.

config c.HubAuth.api_url = Unicode('http://127.0.0.1:8081/hub/api')

The base API URL of the Hub.

Typically http://hub-ip:hub-port/hub/api

config c.HubAuth.base_url = Unicode('/')

The base URL prefix of this application

e.g. /services/service-name/ or /user/name/

Default: get from JUPYTERHUB_SERVICE_PREFIX

config c.HubAuth.cache_max_age = Int(300)

The maximum time (in seconds) to cache the Hub’s responses for authentication.

A larger value reduces load on the Hub and occasional response lag. A smaller value reduces propagation time of changes on the Hub (rare).

Default: 300 (five minutes)

config c.HubAuth.cookie_name = Unicode('jupyterhub-services')

The name of the cookie I should be looking for

config c.HubAuth.hub_host = Unicode('')

The public host of JupyterHub

Only used if JupyterHub is spreading servers across subdomains.

config c.HubAuth.hub_prefix = Unicode('/hub/')

The URL prefix for the Hub itself.

Typically /hub/

config c.HubAuth.login_url = Unicode('/hub/login')

The login URL to use

Typically /hub/login

config c.HubAuth.api_token = Unicode('')

API key for accessing Hub API.

Generate with jupyterhub token [username] or add to JupyterHub.services config.

config c.HubAuth.api_url = Unicode('http://127.0.0.1:8081/hub/api')

The base API URL of the Hub.

Typically http://hub-ip:hub-port/hub/api

config c.HubAuth.base_url = Unicode('/')

The base URL prefix of this application

e.g. /services/service-name/ or /user/name/

Default: get from JUPYTERHUB_SERVICE_PREFIX

config c.HubAuth.cache_max_age = Int(300)

The maximum time (in seconds) to cache the Hub’s responses for authentication.

A larger value reduces load on the Hub and occasional response lag. A smaller value reduces propagation time of changes on the Hub (rare).

Default: 300 (five minutes)

config c.HubAuth.cookie_name = Unicode('jupyterhub-services')

The name of the cookie I should be looking for

get_token(handler)¶

Get the user token from a request

• in URL parameters: ?token=<token>
• in header: Authorization: token <token>

get_user(handler)¶

Get the Hub user for a given tornado handler.

Checks cookie with the Hub to identify the current user.

Parameters:	handler (tornado.web.RequestHandler) – the current request handler
Returns:	The user model, if a user is identified, None if authentication fails. The ‘name’ field contains the user’s name.
Return type:	user_model (dict)

config c.HubAuth.hub_host = Unicode('')

The public host of JupyterHub

Only used if JupyterHub is spreading servers across subdomains.

config c.HubAuth.hub_prefix = Unicode('/hub/')

The URL prefix for the Hub itself.

Typically /hub/

config c.HubAuth.login_url = Unicode('/hub/login')

The login URL to use

Typically /hub/login

user_for_cookie(encrypted_cookie, use_cache=True)¶

Ask the Hub to identify the user for a given cookie.

Parameters:	encrypted_cookie (str) – the cookie value (not decrypted, the Hub will do that) use_cache (bool) – Specify use_cache=False to skip cached cookie values (default: True)
Returns:	The user model, if a user is identified, None if authentication fails. The ‘name’ field contains the user’s name.
Return type:	user_model (dict)

user_for_token(token, use_cache=True)¶

Ask the Hub to identify the user for a given token.

Parameters:	token (str) – the token use_cache (bool) – Specify use_cache=False to skip cached cookie values (default: True)
Returns:	The user model, if a user is identified, None if authentication fails. The ‘name’ field contains the user’s name.
Return type:	user_model (dict)

HubOAuth¶

class jupyterhub.services.auth.HubOAuth(**kwargs)¶

HubAuth using OAuth for login instead of cookies set by the Hub.

config c.HubOAuth.api_token = Unicode('')

API key for accessing Hub API.

Generate with jupyterhub token [username] or add to JupyterHub.services config.

config c.HubOAuth.api_url = Unicode('http://127.0.0.1:8081/hub/api')

The base API URL of the Hub.

Typically http://hub-ip:hub-port/hub/api

config c.HubOAuth.base_url = Unicode('/')

The base URL prefix of this application

e.g. /services/service-name/ or /user/name/

Default: get from JUPYTERHUB_SERVICE_PREFIX

config c.HubOAuth.cache_max_age = Int(300)

The maximum time (in seconds) to cache the Hub’s responses for authentication.

A larger value reduces load on the Hub and occasional response lag. A smaller value reduces propagation time of changes on the Hub (rare).

Default: 300 (five minutes)

config c.HubOAuth.hub_host = Unicode('')

The public host of JupyterHub

Only used if JupyterHub is spreading servers across subdomains.

config c.HubOAuth.hub_prefix = Unicode('/hub/')

The URL prefix for the Hub itself.

Typically /hub/

config c.HubOAuth.login_url = Unicode('/hub/login')

The login URL to use

Typically /hub/login

config c.HubOAuth.oauth_authorization_url = Unicode('/hub/api/oauth2/authorize')

The URL to redirect to when starting the OAuth process

config c.HubOAuth.oauth_client_id = Unicode('')

The OAuth client ID for this application.

Use JUPYTERHUB_CLIENT_ID by default.

config c.HubOAuth.oauth_redirect_uri = Unicode('')

OAuth redirect URI

Should generally be /base_url/oauth_callback

config c.HubOAuth.oauth_token_url = Unicode('')

The URL for requesting an OAuth token from JupyterHub

clear_cookie(handler)¶

Clear the OAuth cookie

cookie_name¶

Use OAuth client_id for cookie name

because we don’t want to use the same cookie name across OAuth clients.

generate_state(next_url=None, **extra_state)¶

Generate a state string, given a next_url redirect target

Parameters:	(str) (next_url) –
Returns:	state (str)
Return type:	The base64-encoded state string.

get_next_url(b64_state='')¶

Get the next_url for redirection, given an encoded OAuth state

get_state_cookie_name(b64_state='')¶

Get the cookie name for oauth state, given an encoded OAuth state

Cookie name is stored in the state itself because the cookie name is randomized to deal with races between concurrent oauth sequences.

config c.HubOAuth.oauth_authorization_url = Unicode('/hub/api/oauth2/authorize')

The URL to redirect to when starting the OAuth process

config c.HubOAuth.oauth_client_id = Unicode('')

The OAuth client ID for this application.

Use JUPYTERHUB_CLIENT_ID by default.

config c.HubOAuth.oauth_redirect_uri = Unicode('')

OAuth redirect URI

Should generally be /base_url/oauth_callback

config c.HubOAuth.oauth_token_url = Unicode('')

The URL for requesting an OAuth token from JupyterHub

set_cookie(handler, access_token)¶

Set a cookie recording OAuth result

set_state_cookie(handler, next_url=None)¶

Generate an OAuth state and store it in a cookie

Parameters:	(RequestHandler) (handler) – (str) (next_url) –
Returns:	state (str)
Return type:	The OAuth state that has been stored in the cookie (url safe, base64-encoded)

state_cookie_name¶

The cookie name for storing OAuth state

This cookie is only live for the duration of the OAuth handshake.

token_for_code(code)¶

Get token for OAuth temporary code

This is the last step of OAuth login. Should be called in OAuth Callback handler.

Parameters:	code (str) – oauth code for finishing OAuth login
Returns:	JupyterHub API Token
Return type:	token (str)

HubAuthenticated¶

class jupyterhub.services.auth.HubAuthenticated¶

Mixin for tornado handlers that are authenticated with JupyterHub

A handler that mixes this in must have the following attributes/properties:

• .hub_auth: A HubAuth instance
• .hub_users: A set of usernames to allow. If left unspecified or None, username will not be checked.
• .hub_groups: A set of group names to allow. If left unspecified or None, groups will not be checked.

Examples:

class MyHandler(HubAuthenticated, web.RequestHandler):
    hub_users = {'inara', 'mal'}

    def initialize(self, hub_auth):
        self.hub_auth = hub_auth

    @web.authenticated
    def get(self):
        ...

allow_all¶

Property indicating that all successfully identified user or service should be allowed.

check_hub_user(model)¶

Check whether Hub-authenticated user or service should be allowed.

Returns the input if the user should be allowed, None otherwise.

Override if you want to check anything other than the username’s presence in hub_users list.

Parameters:	model (dict) – the user or service model returned from HubAuth
Returns:	The user model if the user should be allowed, None otherwise.
Return type:	user_model (dict)

get_current_user()¶

Tornado’s authentication method

Returns:	The user model, if a user is identified, None if authentication fails.
Return type:	user_model (dict)

get_login_url()¶

Return the Hub’s login URL

hub_auth_class¶

alias of HubAuth

HubOAuthenticated¶

class jupyterhub.services.auth.HubOAuthenticated¶

Simple subclass of HubAuthenticated using OAuth instead of old shared cookies

HubOAuthCallbackHandler¶

class jupyterhub.services.auth.HubOAuthCallbackHandler(application, request, **kwargs)¶

OAuth Callback handler

Finishes the OAuth flow, setting a cookie to record the user’s info.

Should be registered at SERVICE_PREFIX/oauth_callback