「JupyterHub」の版間の差分

2023年8月20日 (日) 18:18時点における版

JupyterHubは、Jupyterノートブックのためのマルチユーザーウェブサーバーです。4つのサブシステムから構成されています。

メインハブプロセス
Authenticators はユーザーを認証します。
Spawners は接続された各ユーザーのシングルユーザーサーバーを起動し、監視します。
HTTP プロキシ受信したリクエストをハブまたは適切なシングルユーザーサーバーにルーティングします。

詳しくは JupyterHub ドキュメントの technical overview を参照してください。

インストール

jupyterhub^AUR パッケージをインストールします。ほとんどの場合、jupyter-notebook パッケージもインストールする必要があります（より高度な spawners は必要ない場合もあります）。また、jupyterlab パッケージをインストールすると、JupyterLab インターフェイスを利用できるようになります。

起動

jupyterhub.service を開始/有効化します。デフォルトの設定では、ブラウザで 127.0.0.1:8000 にアクセスしてハブにアクセスできます。

設定

JupyterHub の設定ファイルは /etc/jupyterhub/jupyterhub_config.py に置かれています。これは、設定オブジェクト c を変更する Python スクリプトです。パッケージが提供する設定ファイルには、利用可能な設定オプションとそのデフォルト値が表示されます。

設定中の相対パスは、ハブが実行される作業ディレクトリから解決されます。パッケージが提供する systemd サービスは作業ディレクトリとして /etc/jupyterhub を使用します。これは、例えばデフォルトのデータベース URL c.JupyterHub.db_url = 'sqlite:///jupyterhub.sqlite' がファイル /etc/jupyterhub/jupyterhub.sqlite に対応することを意味しています。

全ての設定オプションはコマンドライン上で上書きすることができます。例えば、設定ファイルの設定 c.Application.show_config = True は、代わりにコマンドラインフラグ --Application.show_config=True で設定することが可能です。提供される systemd サービスはコマンドラインを使用して c.JupyterHub.pid_file と c.ConfigurableHTTPProxy.pid_file をランタイムのディレクトリに明示的に設定するので、設定ファイルにそれらの値があっても無視されることに注意しましょう。

Authenticators

Authenticators はハブと単一ユーザーサーバへのアクセスを制御します。Authenticators セクションのドキュメントには、Authenticators の動作方法やカスタム Authenticator の作成方法についての詳細が含まれています。Authenticators のwikiページには、Authenticators のリストがあり、その中にはAURパッケージを持つものもあり、以下で説明されています。

ユーザーのステータスは、cookie secretによって暗号化されたクッキーに保存されていることに注意してください。異なる Authenticator に切り替える場合、または選択した Authenticator の設定を変更して許可されるユーザーのリストが変更される可能性がある場合は、cookie secretを変更する必要があります。これにより、現在のすべてのユーザーがログアウトされ、新しい設定で再認証を行う必要があります。これは、cookie secretファイルを削除してハブを再起動することで実行でき、新しいシークレットが自動的に生成されます。デフォルトの設定では、cookie secretは/etc/jupyterhub/jupyterhub_cookie_secretに保存されています。

PAM Authenticator

PAM Authenticator は、PAM を使用してローカルユーザーがハブにログインできるようにします。これは JupyterHub に含まれており、デフォルトの Authenticator です。これを使用するには、ハブがユーザーパスワードのハッシュバージョンを含む /etc/shadow の読み取り権限を持っている必要があります。デフォルトでは、/etc/shadow は root が所有し、ファイル権限は -rw------ ですので、root としてハブを実行するとこの要件が満たされます。一部の情報源は、/etc/shadow からすべての権限を削除して、侵害されたデーモンによって読み取られないようにし、アクセスが必要なプロセスに DAC_OVERRIDE ケイパビリティを付与することを推奨しています。もしあなたの /etc/shadow がこのように設定されている場合、この機能を JupyterHub に付与するためのドロップインファイルを作成してください：

/etc/systemd/system/jupyterhub.service.d/override.conf

[Service]
CapabilityBoundingSet=CAP_DAC_OVERRIDE

PAM Authenticator は Python パッケージ pamela に依存しています。基本的なトラブルシューティングはコマンドラインでテストすることができます。ユーザー testuser として認証を試みるには、次のコマンドを実行してください：

# python -m pamela -a testuser

(JupyterHub を非 root ユーザーとして実行する場合は、root の代わりにそのユーザーとしてコマンドを実行してください)。認証が成功すると、出力は表示されません。失敗するとエラーメッセージが表示されます。

非 root ユーザーとしての PAM 認証

JupyterHub を非 root ユーザーとして実行する場合、そのユーザーに shadow ファイルの読み取り権限を付与する必要があります。JupyterHub のドキュメントで推奨されている方法は、shadow グループを作成し、このグループに shadow ファイルを読み取り可能にし、JupyterHub ユーザーをこのグループに追加することです。

警告: これにより、/etc/shadow 内のハッシュ化されたパスワードへの読み取り専用アクセスが JupyterHub ユーザーとしてコードを実行する全てのユーザーに許可されます。各単一ユーザーサーバーは自分のアカウントで実行されるため、それらのサーバーで実行されるコードはアクセス権を持っていないことに注意してください。また、JupyterHub のセキュリティエクスプロイトが root として JupyterHub を実行していた場合、同じハッシュ化されたパスワードへのアクセスが許可されることも注意してください。

グループを作成し、shadow ファイルの権限を変更し、ユーザー jupyterhub をグループに追加することは、次の4つのコマンドで実行できます：

# groupadd shadow
# chgrp shadow /etc/shadow
# chmod g+r /etc/shadow
# usermod -aG shadow jupyterhub

Spawners（スポーナー）

Spawners は、各ユーザーのノートブックサーバーを起動し、監視する責任があります。documentation には、Spawners の動作やカスタムスポーナーの作成方法についての詳しい情報が含まれています。wiki page には、いくつかの Spawners のリストがあり、その中には AUR パッケージがあるものも含まれ、以下で説明されています。

LocalProcessSpawner

これは JupyterHub に含まれるデフォルトのスポーナーです。各シングルユーザーサーバーを、それぞれのユーザーアカウントでローカルプロセスとして実行します（これは、各 JupyterHub ユーザーがローカルのユーザーアカウントに対応している必要があることを意味します）。また、異なるユーザーアカウントでプロセスを起動できるように、JupyterHub を root として実行する必要があります。このスポーナーを動作させるためには、jupyter-notebook パッケージがインストールされている必要があります。

SudoSpawner

SudoSpawner は、sudo で作成された中間プロセスを使用して、シングルユーザーサーバーを起動します。これにより、JupyterHub プロセスを非 root ユーザーとして実行することができます。使用するには、jupyterhub-sudospawner^AUR パッケージをインストールしてください。

それを使用するために、システムユーザーアカウントを作成してください（以下では、アカウントが jupyterhub という名前であると仮定しています）と、ハブにアクセスできるユーザーを定義するグループを作成します（ここでは、jupyterhub-users と呼ばれると仮定しています）。まず、jupyterhub ユーザーがパスワードなしでサーバーを起動できるように、sudo を設定する必要があります。drop-in sudo 設定ファイルを visudo で作成します。

# visudo -f /etc/sudoers.d/jupyterhub-sudospawner

# The command the hub is allowed to run.
Cmnd_Alias SUDOSPAWNER_CMD = /usr/bin/sudospawner

# Allow the jupyterhub user to run this command on behalf of anybody
# in the jupyterhub-users group.
jupyterhub ALL=(%jupyterhub-users) NOPASSWD:SUDOSPAWNER_CMD

デフォルトのサービスファイルは、ハブを root として実行します。また、サービスの機能を制限するためのさまざまな強化オプションを適用します。この強化により、sudo が動作しなくなります。これを許可するためには、NoNewPrivileges サービスオプション（およびそれを暗黙的に設定する他のオプション、サービスオプションのリストについては systemd.exec(5) を参照）をオフにする必要があります。jupyterhub ユーザーを使用してハブを実行するためのドロップインファイルを作成してください。

/etc/systemd/system/jupyterhub.service.d/override.conf

[Service]
User=jupyterhub
Group=jupyterhub

# Required for sudo.
NoNewPrivileges=false

# Setting the following would implicitly set NoNewPrivileges.
PrivateDevices=false
ProtectKernelTunables=false
ProtectKernelModules=false
LockPersonality=false
RestrictRealtime=false
RestrictSUIDGID=false
SystemCallFilter=
SystemCallArchitectures=

以前、ハブを root ユーザーとして実行していた場合、ユーザーデータベースと cookie secret ファイルの所有者を変更する必要があります：

# chown jupyterhub:jupyterhub /etc/jupyterhub/{jupyterhub_cookie_secret,jupyterhub.sqlite}

PAMAuthenticator を使用している場合、非 root ユーザーとして動作するようにシステムを設定する必要があります。

最後に、JupyterHub の設定を編集し、spawner クラスを SudoSpawner に変更します：

/etc/jupyterhub/jupyterhub_config.py

c.JupyterHub.spawner_class='sudospawner.SudoSpawner'

ユーザーにハブへのアクセス権を与えるには、そのユーザーを jupyterhub-users グループに追加します：

# usermod -aG jupyterhub-users <username>

systemdspawner

systemdspawner は systemd を使用して、各ユーザーのノートブックを管理します。これにより、リソースの制限の設定、より良いプロセスの分離とサンドボックス化、動的に割り当てられたユーザーなどが可能になります。使用するには、jupyterhub-systemdspawner^AUR パッケージをインストールし、設定ファイルで spawner クラスを設定します：

/etc/jupyterhub/jupyterhub_config.py

c.JupyterHub.spawner_class = 'systemdspawner.SystemdSpawner'

systemdspawner の readme によれば、現在、それを使用するには JupyterHub を root として実行する必要があります。

Services

A JupyterHub service is defined as a process which interacts with the Hub through its API. Services can either be run by the hub or as standalone processes.

Idle culler

The idle culler service can be used to automatically shut down idle single-user servers. To use it, install the jupyterhub-idle-culler^AUR package. To run the service through the hub, add a service description to the c.JupyterHub.services configuration variable:

/etc/jupyterhub/jupyterhub_config.py

import sys
c.JupyterHub.services = [
    {
        'name': 'idle-culler',
        'admin': True,
        'command': [
            sys.executable,
            '-m', 'jupyterhub_idle_culler',
            '--timeout=3600'
        ],
    }
]

See the service documentation or the output of python -m jupyterhub_idle_culler --help for a description of command-line options and details of how to run the service as a standalone process.

Tips and Tricks

Running as non-root user

By default, the main hub process is run as the root user (the individual user servers are run under the corresponding local user as set by the spawner). To run as a non-root user, you need to use the SudoSpawner (the other spawners listed above require running as root). If you are using the PAM authenticator, you will also need to configure it for a non-root user.

Using a reverse proxy

A reverse proxy can be used to redirect external requests to the JupyterHub instance. This can be useful if you want to serve multiple sites from one machine, or use an existing server to handle SSL. The using a reverse proxy section of the JupyterHub documentation has example configuration for using either nginx or Apache as a reverse proxy.

ノート: This does not replace the proxy component of JupyterHub which is responsible for routing requests to either the main hub or the single-user servers. Rather, the reverse proxy passes external requests to the JupyterHub proxy.

Proxy other web services

The Jupyter Server Proxy extension allows you to run other web services such as Code Server or RStudio alongside JupyterHub and provide authenticated web access to them. To use it, install python-jupyter-server-proxy^AUR and configure it with the /etc/jupyter/jupyter_notebook_config.py file. For instance, to proxy code-server^AUR:

/etc/jupyter/jupyter_notebook_config.py

c.ServerProxy.servers = {
  'code-server': {
    'command': [
      'code-server',
        '--auth=none',
        '--disable-telemetry',
        '--disable-update-check',
        '--bind-addr=localhost:{port}',
        '--user-data-dir=.config/Code - OSS/',
        '--extensions-dir=.vscode-oss/extensions/'
    ],
    'timeout': 20,
    'launcher_entry': {
      'title': 'VS Code'
    }
  }
}

See the documentation for more details about configuring the Jupyter Server Proxy.

@@ 62行目: / 62行目: @@
 }}
+== Spawners（スポーナー） ==
-== Spawners ==
-Spawners are responsible for starting and monitoring each user's notebook server. The [https://jupyterhub.readthedocs.io/en/stable/reference/spawners.html spawners section of the documentation] contains more details about how they work and how to write a custom spawner. The [https://github.com/jupyterhub/jupyterhub/wiki/Spawners spawners wiki page] has a list of spawners; some of these have [[AUR]] packages and are described below.
+Spawners は、各ユーザーのノートブックサーバーを起動し、監視する責任があります。[https://jupyterhub.readthedocs.io/en/stable/reference/spawners.html documentation] には、Spawners の動作やカスタムスポーナーの作成方法についての詳しい情報が含まれています。[https://github.com/jupyterhub/jupyterhub/wiki/Spawners wiki page] には、いくつかの Spawners のリストがあり、その中には [[AUR]] パッケージがあるものも含まれ、以下で説明されています。
 === LocalProcessSpawner ===
+これは JupyterHub に含まれるデフォルトのスポーナーです。各シングルユーザーサーバーを、それぞれの[[ユーザーアカウント]]でローカルプロセスとして実行します（これは、各 JupyterHub ユーザーがローカルのユーザーアカウントに対応している必要があることを意味します）。また、異なるユーザーアカウントでプロセスを起動できるように、JupyterHub を root として実行する必要があります。このスポーナーを動作させるためには、{{Pkg|jupyter-notebook}} パッケージがインストールされている必要があります。
-This is the default spawner included with JupyterHub. It runs each single-user server in a separate local process under their [[user account]] (this means each JupyterHub user must correspond to a local user account). It also requires JupyterHub to be run as root so it can spawn the processes under the different user accounts. The {{Pkg|jupyter-notebook}} package must be installed for this spawner to work.
 === SudoSpawner ===
-The [https://github.com/jupyterhub/sudospawner SudoSpawner] uses an intermediate process created with [[sudo]] to spawn the single-user servers. This allows the JupyterHub process to be [[#Running as non-root user|run as a non-root user]]. To use it install the {{AUR|jupyterhub-sudospawner}} package.
+[https://github.com/jupyterhub/sudospawner SudoSpawner] は、[[sudo]] で作成された中間プロセスを使用して、シングルユーザーサーバーを起動します。これにより、JupyterHub プロセスを [[#Running as non-root user|非 root ユーザーとして実行]] することができます。使用するには、{{AUR|jupyterhub-sudospawner}} パッケージをインストールしてください。
+それを使用するために、[[ユーザーとグループ|システムユーザーアカウントを作成]] してください（以下では、アカウントが {{ic|jupyterhub}} という名前であると仮定しています）と、ハブにアクセスできるユーザーを定義するグループを作成します（ここでは、{{ic|jupyterhub-users}} と呼ばれると仮定しています）。まず、{{ic|jupyterhub}} ユーザーがパスワードなしでサーバーを起動できるように、sudo を設定する必要があります。[[sudo#Configure sudo using drop-in files in /etc/sudoers.d|drop-in sudo 設定ファイル]] を [[sudo#Using visudo|visudo]] で作成します。
-To use it, [[Users and groups|create a system user account]] (the following assumes the account is named {{ic|jupyterhub}}) and a group whose membership will define which users can access the hub (here assumed to be called {{ic|jupyterhub-users}}). First, we have to configure sudo to allow the {{ic|jupyterhub}} user to spawn a server without a password. Create a [[sudo#Configure sudo using drop-in files in /etc/sudoers.d|drop-in sudo configuration file]] with [[sudo#Using visudo|visudo]]:
 {{hc|1=# visudo -f /etc/sudoers.d/jupyterhub-sudospawner|2=
@@ 85行目: / 85行目: @@
 }}
+デフォルトのサービスファイルは、ハブを root として実行します。また、サービスの機能を制限するためのさまざまな強化オプションを適用します。この強化により、sudo が動作しなくなります。これを許可するためには、{{ic|NoNewPrivileges}} サービスオプション（およびそれを暗黙的に設定する他のオプション、サービスオプションのリストについては {{man|5|systemd.exec}} を参照）をオフにする必要があります。{{ic|jupyterhub}} ユーザーを使用してハブを実行するための[[ドロップインファイル]]を作成してください。
-The default service file runs the hub as root. It also applies a number of hardening options to the service to restrict its capabilities. This hardening prevents sudo from working; to allow it, the {{ic|NoNewPrivileges}} service option (plus any other options which implicitly set it, see {{man|5|systemd.exec}} for a list of service options) needs to be off. Create a [[drop-in file]] to run the hub using the {{ic|jupyterhub}} user instead:
 {{hc|/etc/systemd/system/jupyterhub.service.d/override.conf|2=
@@ 106行目: / 106行目: @@
 }}
-If you have previously run the hub as the root user, you will need to [[File permissions and attributes#Changing ownership|change the ownership]] of the user database and [https://jupyterhub.readthedocs.io/en/stable/getting-started/security-basics.html#cookie-secret cookie secret] files:
+以前、ハブを root ユーザーとして実行していた場合、ユーザーデータベースと [https://jupyterhub.readthedocs.io/en/stable/getting-started/security-basics.html#cookie-secret cookie secret] ファイルの[[ファイルのパーミッションと属性#所有者の変更|所有者を変更]]する必要があります：
  # chown jupyterhub:jupyterhub /etc/jupyterhub/{jupyterhub_cookie_secret,jupyterhub.sqlite}
-If you are using the PAMAuthenticator, you will need to [[#PAM authentication as non-root user|configure your system to allow it to work as a non-root user]].
+PAMAuthenticator を使用している場合、[[#PAM authentication as non-root user|非 root ユーザーとして動作するようにシステムを設定]]する必要があります。
+最後に、JupyterHub の設定を編集し、spawner クラスを SudoSpawner に変更します：
-Finally, edit the JupyterHub configuration and change the spawner class to SudoSpawner:
 {{hc|1=/etc/jupyterhub/jupyterhub_config.py|2=c.JupyterHub.spawner_class='sudospawner.SudoSpawner'}}
+ユーザーにハブへのアクセス権を与えるには、そのユーザーを {{ic|jupyterhub-users}} グループに追加します：
-To give a user access to the hub, add them to the {{ic|jupyterhub-users}} group:
  # usermod -aG jupyterhub-users <username>
@@ 122行目: / 122行目: @@
 === systemdspawner ===
-The [https://github.com/jupyterhub/systemdspawner systemdspawner] uses [[systemd]] to manage each user's notebook which allows configuring resource limitations, better process isolation and sandboxing, and dynamically allocated users. To use it install the {{AUR|jupyterhub-systemdspawner}} package and set the spawner class in the configuration file:
+[https://github.com/jupyterhub/systemdspawner systemdspawner] は [[systemd]] を使用して、各ユーザーのノートブックを管理します。これにより、リソースの制限の設定、より良いプロセスの分離とサンドボックス化、動的に割り当てられたユーザーなどが可能になります。使用するには、{{AUR|jupyterhub-systemdspawner}} パッケージをインストールし、設定ファイルで spawner クラスを設定します：
 {{hc|1=/etc/jupyterhub/jupyterhub_config.py|2=c.JupyterHub.spawner_class = 'systemdspawner.SystemdSpawner'}}
-Note that as per [https://github.com/jupyterhub/systemdspawner/blob/master/README.md#root-access systemdspawner's readme] using it currently requires JupyterHub to be run as root.
+[https://github.com/jupyterhub/systemdspawner/blob/master/README.md#root-access systemdspawner の readme] によれば、現在、それを使用するには JupyterHub を root として実行する必要があります。
 == Services ==