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 ===

The PAM authenticator uses [[PAM]] to allow local users to log in to the hub. It is included with JupyterHub and is the default authenticator. Using it requires the hub to have read permissions to {{ic|/etc/shadow}} (which contains hashed versions of user passwords) in order to authenticate users. By default {{ic|/etc/shadow}} is owned by root and has [[Users and groups#Permissions and ownership|file permissions]] of {{ic|-rw------}}, so running the hub as root will meet this requirement. [[Fedora:Features/LowerProcessCapabilities|Some sources]] advocate removing all permissions from {{ic|/etc/shadow}} so it cannot be read by compromised daemons, and granting processes which require access the {{ic|DAC_OVERRIDE}} [[capabilities|capability]]. If your {{ic|/etc/shadow}} is set up like this, create a [[drop-in file]] for the service to grant this capability to JupyterHub:

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

The PAM authenticator relies on the Python package [https://github.com/minrk/pamela pamela]. For basic troubleshooting this can be tested on the commandline. To attempt authentication as user {{ic|testuser}}, run the following command:

 # python -m pamela -a testuser

(If you run JupyterHub as a non-root user, run the command as that user instead of root). If the authentication succeeds, no output will be printed. If it failed an error message will be printed.

==== PAM authentication as non-root user ====

If you run JupyterHub as a non-root user, you will need to give that user read permissions to the shadow file. The [https://jupyterhub.readthedocs.io/en/stable/reference/config-sudo.html#enable-pam-for-non-root method recommended by the JupyterHub documentation] is to create a {{ic|shadow}} group, make the shadow file readable by this group, and add the JupyterHub user to this group.

{{Warning|This allows read-only access to the hashed passwords in {{ic|/etc/shadow}} to anybody running code as the JupyterHub user. Note that each single-user server is run under their own account and so code executed in those servers will not have access. Also note that a security exploit in JupyterHub would allow the same access to the hashed passwords if JupyterHub was being run as root.}}

Creating the group, modifying the shadow file permissions and adding the user {{ic|jupyterhub}} to the group can be accomplished with the following four commands:

{{bc|1=
# groupadd shadow
# chgrp shadow /etc/shadow
# chmod g+r /etc/shadow
# usermod -aG shadow jupyterhub
}}

== 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.

=== LocalProcessSpawner ===

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.

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=
# 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
}}

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

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:

 # 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]].

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

To give a user access to the hub, add them to the {{ic|jupyterhub-users}} group:

 # usermod -aG jupyterhub-users <username>

=== 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:

{{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.

== Services ==

A [https://jupyterhub.readthedocs.io/en/stable/getting-started/services-basics.html 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 [https://github.com/jupyterhub/jupyterhub-idle-culler idle culler] service can be used to automatically shut down idle single-user servers. To use it, install the {{AUR|jupyterhub-idle-culler}} package. To run the service through the hub, add a service description to the {{ic|c.JupyterHub.services}} configuration variable:

{{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'
        ],
    }
]
}}

See the service documentation or the output of {{ic|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|SudoSpawner]] (the other spawners listed above require running as root). If you are using the PAM authenticator, you will also need to [[#PAM authentication as non-root user|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 [https://jupyterhub.readthedocs.io/en/stable/reference/config-proxy.html using a reverse proxy] section of the JupyterHub documentation has example configuration for using either [[nginx]] or [[Apache HTTP Server|Apache]] as a reverse proxy.

{{Note|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 {{AUR|python-jupyter-server-proxy}} and configure it with the {{ic|/etc/jupyter/jupyter_notebook_config.py}} file. For instance, to proxy {{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'
    }
  }
}
}}

See the [https://jupyter-server-proxy.readthedocs.io/en/latest/ documentation] for more details about configuring the Jupyter Server Proxy.