hazza/jupyterhub
1
0
Fork 0
mirror of https://github.com/jupyterhub/jupyterhub.git synced 2025-10-17 15:03:02 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'main' into busayo-ojo

Browse Source
This commit is contained in:
Min RK
2022-11-24 10:04:08 +01:00
committed by GitHub
parent 51c1ea1f7f d04c0c28c0
commit 8b471624ee
108 changed files with 1416 additions and 1163 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
docs/source/getting-started/authenticators-users-basics.md
View File

@@ -1,6 +1,6 @@
# Authentication and User Basics
The default Authenticator uses [PAM][] to authenticate system users with
The default Authenticator uses [PAM][] (Pluggable Authentication Module) to authenticate system users with
their username and password. With the default Authenticator, any user
with an account and password on the system will be allowed to login.
@@ -25,7 +25,7 @@ If this configuration value is not set, then **all authenticated users will be a
```{note}
As of JupyterHub 2.0, the full permissions of `admin_users`
should not be required.
Instead, you can assign [roles](https://jupyterhub.readthedocs.io/en/stable/rbac/roles.html#define-role-target) to users or groups
Instead, you can assign [roles](define-role-target) to users or groups
with only the scopes they require.
```
@@ -42,7 +42,7 @@ c.Authenticator.admin_users = {'mal', 'zoe'}
Users in the admin set are automatically added to the user `allowed_users` set,
if they are not already present.
Each authenticator may have different ways of determining whether a user is an
Each Authenticator may have different ways of determining whether a user is an
administrator. By default, JupyterHub uses the PAMAuthenticator which provides the
`admin_groups` option and can set administrator status based on a user
group. For example, we can let any user in the `wheel` group be an admin:
@@ -76,7 +76,7 @@ fresh.
## Use LocalAuthenticator to create system users
The `LocalAuthenticator` is a special kind of authenticator that has
The `LocalAuthenticator` is a special kind of Authenticator that has
the ability to manage users on the local system. When you try to add a
new user to the Hub, a `LocalAuthenticator` will check if the user
already exists. If you set the configuration value, `create_system_users`,
@@ -118,8 +118,8 @@ with any provider, is also available.
## Use DummyAuthenticator for testing
The `DummyAuthenticator` is a simple authenticator that
allows for any username/password unless a global password has been set. If
The `DummyAuthenticator` is a simple Authenticator that
allows for any username or password unless a global password has been set. If
set, it will allow for any username as long as the correct password is provided.
To set a global password, add this to the config file:

10
docs/source/getting-started/config-basics.md
View File

@@ -1,6 +1,6 @@
# Configuration Basics
The section contains basic information about configuring settings for a JupyterHub
This section contains basic information about configuring settings for a JupyterHub
deployment. The [Technical Reference](../reference/index)
documentation provides additional details.
@@ -49,7 +49,7 @@ that Jupyter uses.
## Configure using command line options
To display all command line options that are available for configuration:
To display all command line options that are available for configuration run the following command:
```bash
jupyterhub --help-all
@@ -77,11 +77,11 @@ jupyterhub --Spawner.notebook_dir='~/assignments'
## Configure for various deployment environments
The default authentication and process spawning mechanisms can be replaced, and
specific [authenticators](./authenticators-users-basics) and
[spawners](./spawners-basics) can be set in the configuration file.
specific [authenticators](authenticators-users-basics) and
[spawners](spawners-basics) can be set in the configuration file.
This enables JupyterHub to be used with a variety of authentication methods or
process control and deployment environments. [Some examples](../reference/config-examples),
meant as illustration, are:
meant as illustrations, are:
- Using GitHub OAuth instead of PAM with [OAuthenticator](https://github.com/jupyterhub/oauthenticator)
- Spawning single-user servers with Docker, using the [DockerSpawner](https://github.com/jupyterhub/dockerspawner)

2
docs/source/getting-started/institutional-faq.md
View File

@@ -78,7 +78,7 @@ gives administrators more control over their setup and hardware.
Because JupyterHub is an open-source, community-driven tool, it can be extended and
modified to fit an institution's needs. It plays nicely with the open source data science
stack, and can serve a variety of computing enviroments, user interfaces, and
stack, and can serve a variety of computing environments, user interfaces, and
computational hardware. It can also be deployed anywhere - on enterprise cloud infrastructure, on
High-Performance-Computing machines, on local hardware, or even on a single laptop, which
is not possible with most other tools for shared interactive computing.

6
docs/source/getting-started/networking-basics.md
View File

@@ -41,9 +41,9 @@ port.
## Set the Proxy's REST API communication URL (optional)
By default, this REST API listens on port 8001 of `localhost` only.
The Hub service talks to the proxy via a REST API on a secondary port. The
API URL can be configured separately to override the default settings.
By default, the proxy's REST API listens on port 8081 of `localhost` only.
The Hub service talks to the proxy via a REST API on a secondary port.
The REST API URL (hostname and port) can be configured separately and override the default settings.
### Set api_url

51
docs/source/getting-started/security-basics.rst
View File

@@ -5,17 +5,17 @@ Security settings
You should not run JupyterHub without SSL encryption on a public network.
Security is the most important aspect of configuring Jupyter. Three
configuration settings are the main aspects of security configuration:
Security is the most important aspect of configuring Jupyter.
Three (3) configuration settings are the main aspects of security configuration:
1. :ref:`SSL encryption <ssl-encryption>` (to enable HTTPS)
2. :ref:`Cookie secret <cookie-secret>` (a key for encrypting browser cookies)
3. Proxy :ref:`authentication token <authentication-token>` (used for the Hub and
other services to authenticate to the Proxy)
The Hub hashes all secrets (e.g., auth tokens) before storing them in its
The Hub hashes all secrets (e.g. auth tokens) before storing them in its
database. A loss of control over read-access to the database should have
minimal impact on your deployment; if your database has been compromised, it
minimal impact on your deployment. If your database has been compromised, it
is still a good idea to revoke existing tokens.
.. _ssl-encryption:
@@ -72,13 +72,13 @@ would be the needed configuration:
If SSL termination happens outside of the Hub
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In certain cases, for example if the hub is running behind a reverse proxy, and
In certain cases, for example, if the hub is running behind a reverse proxy, and
`SSL termination is being provided by NGINX <https://www.nginx.com/resources/admin-guide/nginx-ssl-termination/>`_,
it is reasonable to run the hub without SSL.
To achieve this, simply omit the configuration settings
``c.JupyterHub.ssl_key`` and ``c.JupyterHub.ssl_cert``
(setting them to ``None`` does not have the same effect, and is an error).
To achieve this, remove ``c.JupyterHub.ssl_key`` and ``c.JupyterHub.ssl_cert``
from your configuration (setting them to ``None`` or an empty string does not
have the same effect, and will result in an error).
.. _authentication-token:
@@ -92,7 +92,7 @@ use an auth token.
The value of this token should be a random string (for example, generated by
``openssl rand -hex 32``). You can store it in the configuration file or an
environment variable
environment variable.
Generating and storing token in the configuration file
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -118,8 +118,8 @@ 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
If you do not set the Proxy authentication token, the Hub will generate a random
key itself. This 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).
@@ -128,7 +128,7 @@ automatically (this is the default configuration).
Cookie secret
-------------
The cookie secret is an encryption key, used to encrypt the browser cookies
The cookie secret is an encryption key, used to encrypt the browser cookies,
which are used for authentication. Three common methods are described for
generating and configuring the cookie secret.
@@ -136,8 +136,8 @@ 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:
stored in a ``jupyterhub_cookie_secret`` file. Below, is an example command to generate the
``jupyterhub_cookie_secret`` file:
.. code-block:: bash
@@ -155,7 +155,7 @@ The location of the ``jupyterhub_cookie_secret`` file can be specified in the
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
``group`` or ``other``, otherwise 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
@@ -176,8 +176,8 @@ 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:
You can also set the cookie secret, as a binary string,
in the configuration file (``jupyterhub_config.py``) itself:
.. code-block:: python
@@ -198,7 +198,7 @@ jupyterhub-hub-login
~~~~~~~~~~~~~~~~~~~~
This is the login token used when visiting Hub-served pages that are
protected by authentication such as the main home, the spawn form, etc.
protected by authentication, such as the main home, the spawn form, etc.
If this cookie is set, then the user is logged in.
Resetting the Hub cookie secret effectively revokes this cookie.
@@ -209,7 +209,7 @@ jupyterhub-user-<username>
~~~~~~~~~~~~~~~~~~~~~~~~~~
This is the cookie used for authenticating with a single-user server.
It is set by the single-user server after OAuth with the Hub.
It is set by the single-user server, after OAuth with the Hub.
Effectively the same as ``jupyterhub-hub-login``, but for the
single-user server instead of the Hub. It contains an OAuth access token,
@@ -218,14 +218,13 @@ which is checked with the Hub to authenticate the browser.
Each OAuth access token is associated with a session id (see ``jupyterhub-session-id`` section
below).
To avoid hitting the Hub on every request, the authentication response
is cached. And to avoid a stale cache the cache key is comprised of both
the token and session id.
To avoid hitting the Hub on every request, the authentication response is cached.
The cache key is comprised of both the token and session id, to avoid a stale cache.
Resetting the Hub cookie secret effectively revokes this cookie.
This cookie is restricted to the path ``/user/<username>``, so that
only the user’s server receives it.
This cookie is restricted to the path ``/user/<username>``,
to ensure that only the user’s server receives it.
jupyterhub-session-id
~~~~~~~~~~~~~~~~~~~~~
@@ -235,7 +234,7 @@ shared by the Hub and single-user servers.
Its sole purpose is to coordinate the logout of the multiple OAuth cookies.
This cookie is set to ``/`` so all endpoints can receive it, or clear it, etc.
This cookie is set to ``/`` so all endpoints can receive it, clear it, etc.
jupyterhub-user-<username>-oauth-state
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -245,7 +244,7 @@ It is only set while OAuth between the single-user server and the Hub
is processing.
If you use your browser development tools, you should see this cookie
for a very brief moment before your are logged in,
for a very brief moment before you are logged in,
with an expiration date shorter than ``jupyterhub-hub-login`` or
``jupyterhub-user-<username>``.

19
docs/source/getting-started/services-basics.md
View File

@@ -24,7 +24,7 @@ Hub via the REST API.
## API Token basics
### Create an API token
### Step 1: Generate an API token
To run such an external service, an API token must be created and
provided to the service.
@@ -43,12 +43,12 @@ generating an API token is available from the JupyterHub user interface:
![API TOKEN success page](../images/token-request-success.png)
### Pass environment variable with token to the Hub
### Step 2: 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
### Step 3: 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
@@ -62,12 +62,12 @@ c.JupyterHub.services = [
]
```
### Restart JupyterHub
### Step 4: Restart JupyterHub
Upon restarting JupyterHub, you should see a message like below in the
logs:
```
```none
Adding API token for <username>
```
@@ -78,16 +78,15 @@ single-user servers, and only cookies can be used for authentication.
0.8 supports using JupyterHub API tokens to authenticate to single-user
servers.
## Configure the idle culler to run as a Hub-Managed Service
## How to configure the idle culler to run as a Hub-Managed Service
Install the idle culler:
### Step 1: Install the idle culler:
```
pip install jupyterhub-idle-culler
```
In `jupyterhub_config.py`, add the following dictionary for the
`idle-culler` Service to the `c.JupyterHub.services` list:
### Step 2: In `jupyterhub_config.py`, add the following dictionary for the `idle-culler` Service to the `c.JupyterHub.services` list:
```python
c.JupyterHub.services = [
@@ -127,7 +126,7 @@ It now needs the scopes:
- `admin:servers` to start/stop servers
```
## Run `cull-idle` manually as a standalone script
## How to run `cull-idle` manually as a standalone script
Now you can run your script by providing it
the API token and it will authenticate through the REST API to

8
docs/source/getting-started/spawners-basics.md
View File

@@ -1,12 +1,12 @@
# Spawners and single-user notebook servers
Since the single-user server is an instance of `jupyter notebook`, an entire separate
multi-process application, there are many aspects of that server that can be configured, and a lot
A Spawner starts each single-user notebook server. Since the single-user server is an instance of `jupyter notebook`, an entire separate
multi-process application, many aspects of that server can be configured and there are a lot
of ways to express that configuration.
At the JupyterHub level, you can set some values on the Spawner. The simplest of these is
`Spawner.notebook_dir`, which lets you set the root directory for a user's server. This root
notebook directory is the highest level directory users will be able to access in the notebook
notebook directory is the highest-level directory users will be able to access in the notebook
dashboard. In this example, the root notebook directory is set to `~/notebooks`, where `~` is
expanded to the user's home directory.
@@ -20,7 +20,7 @@ You can also specify extra command line arguments to the notebook server with:
c.Spawner.args = ['--debug', '--profile=PHYS131']
```
This could be used to set the users default page for the single user server:
This could be used to set the user's default page for the single-user server:
```python
c.Spawner.args = ['--NotebookApp.default_url=/notebooks/Welcome.ipynb']