JupyterHubのソースを表示

[[Category:科学]]
[[Category:サーバー]]
[[en:JupyterHub]]
[https://jupyterhub.readthedocs.io/ JupyterHub]は、[[Jupyter]]ノートブックのためのマルチユーザーウェブサーバーです。4つのサブシステムから構成されています。

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

詳しくは JupyterHub ドキュメントの [https://jupyterhub.readthedocs.io/en/stable/reference/technical-overview.html technical overview] を参照してください。

== インストール ==

{{AUR|jupyterhub}} パッケージを[[インストール]]します。ほとんどの場合、{{Pkg|jupyter-notebook}} パッケージもインストールする必要があります（より高度な [[#Spawners|spawners]] は必要ない場合もあります）。また、{{Pkg|jupyterlab}} パッケージをインストールすると、[https://jupyterlab.readthedocs.io/ JupyterLab] インターフェイスを利用できるようになります。

== 起動 ==

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

== 設定 ==

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

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

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

== Authenticators ==

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

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

=== PAM Authenticator ===

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

{{hc|/etc/systemd/system/jupyterhub.service.d/override.conf|2=
[Service]
CapabilityBoundingSet=CAP_DAC_OVERRIDE
}}

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

 # python -m pamela -a testuser

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

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

JupyterHub を非 root ユーザーとして実行する場合、そのユーザーに shadow ファイルの読み取り権限を付与する必要があります。[https://jupyterhub.readthedocs.io/en/stable/reference/config-sudo.html#enable-pam-for-non-root JupyterHub のドキュメントで推奨されている方法]は、{{ic|shadow}} グループを作成し、このグループに shadow ファイルを読み取り可能にし、JupyterHub ユーザーをこのグループに追加することです。

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

グループを作成し、shadow ファイルの権限を変更し、ユーザー {{ic|jupyterhub}} をグループに追加することは、次の4つのコマンドで実行できます：
{{bc|1=
# groupadd shadow
# chgrp shadow /etc/shadow
# chmod g+r /etc/shadow
# usermod -aG shadow jupyterhub
}}

== Spawners（スポーナー） ==

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

=== LocalProcessSpawner ===

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

=== SudoSpawner ===

[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]] で作成します。

{{hc|1=# visudo -f /etc/sudoers.d/jupyterhub-sudospawner|2=
# 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 が動作しなくなります。これを許可するためには、{{ic|NoNewPrivileges}} サービスオプション（およびそれを暗黙的に設定する他のオプション、サービスオプションのリストについては {{man|5|systemd.exec}} を参照）をオフにする必要があります。{{ic|jupyterhub}} ユーザーを使用してハブを実行するための[[ドロップインファイル]]を作成してください。

{{hc|/etc/systemd/system/jupyterhub.service.d/override.conf|2=
[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 ユーザーとして実行していた場合、ユーザーデータベースと [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}

PAMAuthenticator を使用している場合、[[#PAM authentication as non-root user|非 root ユーザーとして動作するようにシステムを設定]]する必要があります。

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

{{hc|1=/etc/jupyterhub/jupyterhub_config.py|2=c.JupyterHub.spawner_class='sudospawner.SudoSpawner'}}

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

 # usermod -aG jupyterhub-users <username>

=== systemdspawner ===

[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'}}

[https://github.com/jupyterhub/systemdspawner/blob/master/README.md#root-access systemdspawner の readme] によれば、現在、それを使用するには JupyterHub を root として実行する必要があります。

== サービス ==

[https://jupyterhub.readthedocs.io/en/stable/getting-started/services-basics.html JupyterHub サービス] は、API を通じて Hub と対話するプロセスとして定義されています。サービスは、hub によって実行されるか、スタンドアロンのプロセスとして実行することができます。

=== Idle culler（アイドルカラー） ===

[https://github.com/jupyterhub/jupyterhub-idle-culler idle culler] サービスは、アイドル状態のシングルユーザーサーバーを自動的にシャットダウンするために使用できます。使用するには、{{AUR|jupyterhub-idle-culler}} パッケージをインストールしてください。hub を通じてサービスを実行するには、{{ic|c.JupyterHub.services}} 設定変数にサービスの説明を追加してください：

{{hc|1=/etc/jupyterhub/jupyterhub_config.py|2=
import sys
c.JupyterHub.services = [
    {
        'name': 'idle-culler',
        'admin': True,
        'command': [
            sys.executable,
            '-m', 'jupyterhub_idle_culler',
            '--timeout=3600'
        ],
    }
]
}}

コマンドラインオプションの説明や、サービスをスタンドアロンのプロセスとして実行する方法の詳細については、サービスのドキュメントまたは {{ic|python -m jupyterhub_idle_culler --help}} の出力を参照してください。

== ヒントとコツ ==

=== ルートユーザーとしての実行 ===

デフォルトでは、メインの hub プロセスはルートユーザーとして実行されます（個々のユーザーサーバーは、spawner によって設定された対応するローカルユーザーとして実行されます）。非ルートユーザーとして実行するには、[[#SudoSpawner|SudoSpawner]] を使用する必要があります（上記の他の spawners はルートとしての実行が必要です）。PAM 認証を使用している場合は、非ルートユーザー用に[[#非 root ユーザーとしての PAM 認証|それを設定する]]必要もあります。

=== リバースプロキシの使用 ===

リバースプロキシは、外部のリクエストを JupyterHub インスタンスにリダイレクトするために使用できます。これは、1台のマシンから複数のサイトを提供したい場合や、既存のサーバーを使用して[[SSL]] を処理したい場合に便利です。JupyterHub のドキュメントの [https://jupyterhub.readthedocs.io/en/stable/reference/config-proxy.html リバースプロキシの使用] セクションには、リバースプロキシとして[[nginx]] または[[Apache HTTP Server|Apache]] を使用するためのサンプル設定があります。

{{Note|これは JupyterHub のプロキシコンポーネントを置き換えるものではありません。これは、メインの hub またはシングルユーザーサーバーのどちらかにリクエストをルーティングするためのものです。むしろ、リバースプロキシは外部のリクエストを JupyterHub のプロキシに渡します。}}

=== 他のウェブサービスをプロキシする ===

Jupyter Server Proxy 拡張機能を使用すると、Code Server や RStudio などの他のウェブサービスを JupyterHub の隣に実行し、それらに対して認証付きのウェブアクセスを提供できます。使用するには、{{AUR|python-jupyter-server-proxy}} をインストールし、{{ic|/etc/jupyter/jupyter_notebook_config.py}} ファイルで設定します。例えば、{{AUR|code-server}} をプロキシする場合:

{{hc|1=/etc/jupyter/jupyter_notebook_config.py|2=
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'
    }
  }
}
}}

Jupyter Server Proxy の設定に関する詳細は、[https://jupyter-server-proxy.readthedocs.io/en/latest/ ドキュメント]を参照してください。