Create a JupyterHub Configuration File

In this lab, you will:

• create a JupyterHub configuration file, jupyterhub_config.py

• add an admin user

• explore the JupyterHub admin user interface

JupyterHub configuration file¶

The JupyterHub configuration file, jupyterhub_config.py, contains settings for users, admins, spawners, authenticators, proxies, and hub maintenance. The file uses the traitlets package to add configurable traits or settings.

Generate a JupyterHub configuration file¶

First, make a private directory where JupyterHub configuration and state will live:

sudo mkdir -p /srv/jupyterhub
sudo chmod o-rwx /srv/jupyterhub
sudo chown root:adm /srv/jupyterhub
sudo chmod g+rw /srv/jupyterhub

Now we can actually generate the config file:

sudo /opt/jupyterhub/bin/jupyterhub --generate-config -f /srv/jupyterhub/jupyterhub_config.py

Writing default config to: /srv/jupyterhub/jupyterhub_config.py

Inspect the configuration file¶

As a standard Python script, jupyterhub_config.py can include any valid Python commands. When JupyterHub starts, the configuration file is executed.

At the top of a traitlets-based config file like this one, is generally the line:

c = get_config()  # noqa

where c is the “configuration object,” and each configuration option is represented as:

c.ClassName.trait_name = value

See more in the traitlets documentation

Grant access to JupyterHub¶

By default, nobody has access to JupyterHub, so the first configuration added to a JupyterHub deployment is typically who should have access.

There are a number of ways to grant access, specific to each Authenticator. Since we are currently using the default PAM Authenticator, we have three choices:

1. Authenticator.allow_all defers to the Authenticator, such that any user who can successfully authenticate will be allowed. This is often the right choice for PAM.

   c.Authenticator.allow_all = True

2. Authenticator.allowed_users can be a set of usernames, who will be allowed to access the Hub. Only users in this list will be allowed to login to the Hub.

3. PAMAuthenticator.allowed_groups lets you grant access based on system group membership. This is nice because you can use existing system tools to manage user access to JupyterHub, instead of relying on JupyterHub-specific tools.

c.Authenticator.allowed_groups = {"jupyterhub-users"}

Let’s go with the simplest and most logical version for PAM, which also happens to be the same thing we added on the command-line before:

c.Authenticator.allow_all = True

Now, we want JupyterHub to load this configuration. How do we do that?

Restart JupyterHub¶

For configuration changes to take effect, the hub progress must be restarted.

If the hub is running, stop the hub using Control + C in the terminal.

Run

sudo -D /srv/jupyterhub /opt/jupyterhub/bin/jupyterhub

We’ll do this each time we restart JupyterHub.

Grant some administrative privileges¶

JupyterHub grants permissions through a pattern called Role-Based Access Control (RBAC). Each action a user takes in JupyterHub, be it starting a server or viewing information about other users, is associated with a scope.

A role is a named collection of scopes, and a user (or group or service) can be assigned one or more roles.

There is also a super user role, called an admin. Admin users can do literally anything for anyone (much like root on your computer), so it’s advisable to use limited roles to grant just the permissions folks actually need, and not actually create any admin users.

We’re going to define a “monitor” role, who can see user activity and restart their servers, but not take over everything.

c.JupyterHub.load_roles = [
    {
        "name": "monitor",
        "scopes": [
            "admin-ui",
            "read:users",
            "list:users",
            "servers",
        ],
        "users": ["hardway-watcher"],
    }
]

We can also add a ‘true admin’:

c.Authenticator.admin_users = {"jupyroot"}

Now restart the jupyterhub process for configuration to take effect.

JupyterHub’s admin user interface¶

From the navbar in JupyterHub, access administrative options through the Admin tab.

The JupyterHub admin user interface allows admins to monitor, start, and stop a user’s notebook server.

Key Concepts¶

• JupyterHub has a configuration file, jupyterhub_config.py. It is a Python script.

• A configuration item is represented by the format c.Class.trait = value.

• The JupyterHub configuration file allows specifying which users can access JupyterHub via Authenticator.allow_* config.

• JupyterHub users can be granted permissions via roles.

• The JupyterHub admin user interface allows some users to monitor, start, and stop other users’ servers.

Extend your learning¶

TODO Add an allow list, configure port

Next: Spawning Servers