jupyterhub-staticsystemdspawner 0.1.0__tar.gz

jupyterhub_staticsystemdspawner-0.1.0/.github/workflows/pypi-publish.yml

@@ -0,0 +1,72 @@
+name: Build and publish Python package to PyPI or TestPyPI
+
+on: [push]
+
+jobs:
+  build-wheels-and-sdist:
+    name: Build wheels and sdist
+    runs-on: ubuntu-latest
+    steps:
+      - name: Fetch sources
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Set up Python 3.13
+        uses: actions/setup-python@v7
+        with:
+          python-version: '3.13'
+
+      - name: Build a binary wheel and a source tarball
+        run: pipx run build --sdist --wheel --outdir dist/ .
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: cibuilds
+          path: |
+            dist/*.tar.gz
+            dist/*.whl
+
+  publish-to-testpypi:
+    needs: [build-wheels-and-sdist]
+    name: Upload build to TestPyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/jupyterhub-staticsystemdspawner
+    permissions:
+      id-token: write
+    steps:
+      - name: Downloads build wheels and sdist
+        uses: actions/download-artifact@v8
+        with:
+          pattern: cibuilds
+          path: dist
+          merge-multiple: true
+
+      - name: Publish package to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  build-and-publish-to-pypi:
+    if: startsWith(github.ref, 'refs/tags/')
+    needs: [build-wheels-and-sdist]
+    name: Upload release to PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/jupyterhub-staticsystemdspawner
+    permissions:
+      id-token: write
+    steps:
+      - name: Downloads build wheels and sdist
+        uses: actions/download-artifact@v8
+        with:
+          pattern: cibuilds
+          path: dist
+          merge-multiple: true
+
+      - name: Publish package to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

jupyterhub_staticsystemdspawner-0.1.0/.gitignore

@@ -0,0 +1,89 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+env/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*,cover
+.hypothesis/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# IPython Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# dotenv
+.env
+
+# virtualenv
+venv/
+ENV/
+
+# Spyder project settings
+.spyderproject
+
+# Rope project settings
+.ropeproject

jupyterhub_staticsystemdspawner-0.1.0/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## v0.1
+
+- Initial Release

jupyterhub_staticsystemdspawner-0.1.0/LICENSE

@@ -0,0 +1,30 @@
+BSD 3-Clause License
+
+Copyright (c) 2017-2024, Project Jupyter Contributors
+              2024-2026, Jörg Behrmann
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of the copyright holder nor the names of its
+  contributors may be used to endorse or promote products derived from
+  this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

jupyterhub_staticsystemdspawner-0.1.0/PKG-INFO

@@ -0,0 +1,363 @@
+Metadata-Version: 2.4
+Name: jupyterhub-staticsystemdspawner
+Version: 0.1.0
+Summary: JupyterHub Spawner using systemd unit files
+Author-email: Jörg Behrmann <behrmann@physik.fu-berlin.de>
+License-Expression: BSD-3-Clause
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: jupyterhub>=0.9
+Requires-Dist: tornado>=5.0
+Dynamic: license-file
+
+# staticsystemdspawner
+
+The **staticsystemdspawner** enables JupyterHub to spawn single-user notebook
+servers using the [systemd](https://www.freedesktop.org/wiki/Software/systemd/)
+service manager, that is available on all current major Linux distributions.
+
+This project is a friendly fork of [systemdspawner](https://github.com/jupyterhub/systemdspawner).
+
+## How is this different from systemdspawner?
+
+systemdspawner uses `systemd-run` to start transient units that are constructed
+on the fly by systemdspawner itself. This makes it necessary for JupyterHub to
+be able to use `systemd-run`.
+
+staticsystemdspawner instead uses pre-generated unit files that only need to be
+started, which makes the scope of what to allow JupyterHub to do smaller and
+also allows to customise the units to a much greater degree without the need to
+pipe all systemd options through the spawner.
+
+## Features
+
+The features of staticsystemdspawner are broadly similar to those of
+systemdspawner, but very open-ended. If you can think of it, you can probably
+hack it up without having to touch the code of systemdspawner.
+
+You can use everything in the systemd suite, which gets you all sorts of
+sandboxing and resource control options, see the man pages
+- `man systemd.service`,
+- `man systemd.exec`, and
+- `man systemd.resource-control`
+for details and `man systemd.directives` if need an index.
+
+## Requirements
+
+### Systemd
+
+staticsystemdspawner requires you to use a Linux Distro that ships with at least
+systemd v252, which shipped by default in Debian bookworm (released in 2023),
+but is also available in Debian bullseye (released in 2021) via Debian
+backports. It might also work with systemd v247 available in Debian bullseye,
+but this has not been tested, we recommend using at least version v252.
+
+Consult `systemctl --version` for your version information.
+
+### Polkit
+
+To control unit lifecycle staticsystemdspawner uses polkit. A version larger
+than polkit 105 is needed. These are available in Debian starting with Debian
+bookworm or from the experimental repositories before that.
+
+### Local unit files for all users
+
+You will have to add local unit files for all users.
+
+### Linux Distro compatibility
+
+Anything with a recent systemd (v252 or newer) and polkit (newer than 105),
+should work, i.e. all Debian versions starting with Debian bookworm, all Ubuntu
+versions starting with Ubuntu 24.04 LTS and all versions of RHEL and its
+derivatives starting with RHEL9 should work out of the box
+
+## Installation
+
+You cannot install it from PyPI yet, but need to install it from git
+
+```bash
+pip install git+https://<url to the repo>
+```
+
+You can enable it for your jupyterhub with the following lines in your
+`jupyterhub_config.py` file
+
+```python
+c.JupyterHub.spawner_class = 'staticsystemdspawner.StaticSystemdSpawner'
+```
+
+Note that to confirm systemdspawner has been installed in the correct jupyterhub
+environment, a newly generated config file should list `staticsystemdspawner` as one of the
+available spawner classes in the comments above the configuration line.
+
+The Hub itself can be run as an unprivileged user
+```ini
+# jupyterhub.service
+[Unit]
+Description=Jupyterhub
+After=network.target postgresql.service jupyterhub-httpproxy.service
+Wants=network.target postgresql.service
+PartOf=jupyterhub.target
+
+[Service]
+User=jupyter
+Environment="PATH=/opt/jupyter/hubenv/bin:/usr/bin:/usr/local/bin:/bin"
+ConfigurationDirectory=jupyterhub
+RuntimeDirectory=jupyterhub
+StateDirectory=jupyterhub
+
+LoadCredentialEncrypted=jupyterhub.dbpassword
+LoadCredentialEncrypted=jupyterhub.authcred
+LoadCredentialEncrypted=jupyterhub.cookiesecret
+LoadCredentialEncrypted=jupyterhub.proxy.authtoken
+
+ExecStart=/opt/jupyter/hubenv/bin/jupyterhub --config ${CONFIGURATION_DIRECTORY}/jupyterhub_config.py
+
+PrivateTmp=yes
+NoNewPrivileges=yes
+ProtectSystem=strict
+ProtectHome=yes
+WorkingDirectory=/var/lib/jupyterhub
+```
+and it is recommended to start it as a part of a target, e.g.
+```ini
+[Unit]
+Description=JupyterHub API services
+Wants=jupyterhub.service jupyterhub-httpproxy.service nginx.service
+
+[Install]
+WantedBy=multi-user.target
+```
+assuming the existence of a separate `jupyterhub-httpproxy.service` and running the Hub behind Nginx as a proxy.
+
+### Aside: Running the configurable http proxy as dynamic user
+
+```ini
+# jupyterhub-httpproxy.service
+[Unit]
+Description=JupyterHub HTTP proxy
+After=network-online.target
+PartOf=jupyterhub.target
+
+[Service]
+User=jupyterproxy
+DynamicUser=yes
+
+LoadCredentialEncrypted=jupyterhub.proxy.authtoken
+ExecStart=/opt/jupyter/configurable-http-proxy-wrapper \
+        --ip 127.0.0.1 \
+        --port 8000 \
+        --api-ip 127.0.0.1 \
+        --api-port 8001 \
+        --host-routing \
+        --default-target=http://127.0.0.1:8081 \
+        --error-target=http://127.0.0.1:8081/hub/error
+
+SuccessExitStatus=0 2
+
+PrivateTmp=yes
+ProtectSystem=strict
+ProtectHome=yes
+```
+
+### Polkit
+
+To authorize JupyterHub to start and stop units a polkit rule is used.
+```js
+polkit.addRule(function(action, subject) {
+    if (action.id == "org.freedesktop.systemd1.manage-units") {
+        polkit.log("action=" + action);
+        polkit.log("subject=" + subject);
+        if (action.lookup("unit").match(/^jupyterhub-singleuser-[a-z][a-z0-9]{0,30}.service$/) ||
+            action.lookup("unit").match(/^jupyterhub-singleuser-[a-z][a-z0-9]{0,30}@[a-zA-Z0-9_\\]+.service$/)) {
+            var verb = action.lookup("verb");
+            if ((verb == "start" || verb == "stop" || verb == "reset-failed") && subject.user == "jupyter") {
+                return polkit.Result.YES;
+            }
+        }
+    }
+});
+```
+
+If you have a sufficiently new polkit (124 or newer) you could also add
+additional checks using `subject.system_unit == "jupyterhub.service"` to check
+whether the this is being called from the context of `jupyterhub.service` and
+`subject.no_new_privileges == true` that the `NoNewPrivileges=` setting on the
+Hub is set.
+
+### Unit files
+
+This package ships with a script `jupyter-staticsystemdspawner-unitgenerator`
+that can be used to generate unit files for users. These are meant as examples
+and should be changed to fit the needs of your deployment.
+
+They use a wrapper script (`jupyter-singleuser-wrapper`) for environment setup,
+since JupyterHub usually reads its configuration from environment files. Since
+the hub is running as an unprivileged users and so are the singleuser servers,
+systemd credentials are used to pass information from the hub to the singleuser
+servers. This wrapper script will therefore be needed to start the singleuser
+servers.
+
+An example for such a file:
+```ini
+[Unit]
+Description=Jupyterhub Single-User Server for user foobar
+
+[Service]
+Type=simple
+User=foobar
+
+Environment="PATH=/opt/jupyter/hubenv/bin:/usr/bin:/usr/local/bin"
+
+LoadCredential=spawnerconf:/run/jupyterhub/spawnerconf/foobar/default
+ExecStart=/opt/jupyter/hubenv/bin/jupyter-singleuser-wrapper
+
+WorkingDirectory=/home/foobar
+StateDirectory=jupyterhub-foobar
+
+# ensure that one singleuser server going over the memory limit
+# does not kill all the user's servers
+OOMPolicy=continue
+# use the jupyterhub PAM module for session setup (see below)
+PAMName=jupyterhub
+```
+
+If you want to configure settings for all singleuser servers, it is recommend to use drop in configuration and make use of the dash namespacing of units, e.g.
+```ini
+# jupyterhub-singleuser-.service.d/30-hardening.conf
+[Service]
+PrivateTmp=yes
+PrivateDevices=yes
+ProtectSystem=strict
+ProtectKernelTunables=yes
+ProtectControlGroups=yes
+ReadWritePaths=/home/%j
+NoNewPrivileges=yes
+```
+
+If you want to configure resource constraints, it is recommend to do that via a
+slice unit and configuring `Slice=` for the singleuser unit. For an alternative
+approach using PAM see below.
+
+### PAM config
+
+When using the `PAMName` service setting an existing PAM module needs to be
+provided that will do session setup. This setting is independent of the used
+authenticator.
+
+Using a PAM module one can register JupyterHub singleuser sessions with `loginctl`.
+
+The following example is adapted from the `login` PAM module.
+```
+#
+# The PAM configuration file for the JupyterHub systemd-spawner service
+#
+# SELinux needs to be the first session rule. This ensures that any
+# lingering context has been cleared. Without this it is possible
+# that a module could execute code in the wrong domain.
+# When the module is present, "required" would be sufficient (When SELinux
+# is disabled, this returns success.)
+session [success=ok ignore=ignore module_unknown=ignore default=bad] pam_selinux.so close
+
+# Sets the loginuid process attribute
+session    required     pam_loginuid.so
+
+# SELinux needs to intervene at login time to ensure that the process
+# starts in the proper default security context. Only sessions which are
+# intended to run in the user's context should be run after this.
+# pam_selinux.so changes the SELinux context of the used TTY and configures
+# SELinux in order to transition to the user context with the next execve()
+# call.
+session [success=ok ignore=ignore module_unknown=ignore default=bad] pam_selinux.so open
+# When the module is present, "required" would be sufficient (When SELinux
+# is disabled, this returns success.)
+
+# This module parses environment configuration file(s)
+# and also allows you to use an extended config
+# file /etc/security/pam_env.conf.
+#
+# parsing /etc/environment needs "readenv=1"
+session       required   pam_env.so readenv=1
+# locale variables are also kept into /etc/default/locale in etch
+# reading this file *in addition to /etc/environment* does not hurt
+session       required   pam_env.so readenv=1 envfile=/etc/default/locale
+
+# Sets up user limits according to /etc/security/limits.conf
+# (Replaces the use of /etc/limits in old login)
+session    required   pam_limits.so
+
+# Prints the last login info upon successful login
+# (Replaces the `LASTLOG_ENAB' option from login.defs)
+session    optional   pam_lastlog.so
+
+# Create a new session keyring.
+session    optional   pam_keyinit.so force revoke
+
+# Standard Un*x account and session
+@include common-session
+```
+
+When using such a setup the resource constraints for a user can be configured on
+their user slice, e.g.
+```ini
+# user-123456.slice
+[Slice]
+TasksMax=33%
+CPUQuota=400%
+MemoryHigh=16G
+MemoryMax=17G
+```
+
+## Configuration
+
+For the most part configuration besides setting the spawner class should not be
+required.
+
+### `default_server_unit_name_template`
+
+The name for the unit that is started by the spawner. It defaults to
+`jupyterhub-singleuser-{USERNAME}.service` and the username is interpolated by
+the spawner. Since the user is identified by the last part of the name after the
+last dash and before the `.service` extension, names not following this format
+will probably not work as exptected.
+
+### `named_server_unit_name_template`
+
+The name for the unit that is started by the spawner. It defaults to
+`jupyterhub-singleuser-{USERNAME}@.service` and the username is interpolated by
+the spawner. Since the user is identified by the last part of the name after the
+last dash and before the @, names not following this format will probably not
+work as exptected.
+
+The unit instance passed in will be the name of the named server escaped with
+`systemd-escape`, i.e. to get the unescaped name you will have to use the `%I`
+specifier in the unit file.
+
+### `unit_generator`
+
+The name of a template unit started when a user unit does not exist. It can be
+used to generate them. Defaults to `None`, which means unit files will have to
+be generated for all users beforehand.
+
+## Getting help
+
+We encourage you to ask questions in the repository.
+
+## License
+
+We use a shared copyright model that enables all contributors to maintain the
+copyright on their contributions.
+
+All code is licensed under the terms of the revised BSD license.
+
+## Resources
+
+### JupyterHub and systemdspawner
+
+- [Documentation for JupyterHub](http://jupyterhub.readthedocs.io/en/latest/) | [PDF (latest)](https://media.readthedocs.org/pdf/jupyterhub/latest/jupyterhub.pdf) | [PDF (stable)](https://media.readthedocs.org/pdf/jupyterhub/stable/jupyterhub.pdf)
+- [Documentation for JupyterHub's REST API](http://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter/jupyterhub/master/docs/rest-api.yml#/default)
+
+### Jupyter
+
+- [Documentation for Project Jupyter](http://jupyter.readthedocs.io/en/latest/index.html) | [PDF](https://media.readthedocs.org/pdf/jupyter/latest/jupyter.pdf)
+- [Project Jupyter website](https://jupyter.org)