diff --git a/docs/howto/admin/systemd.rst b/docs/howto/admin/systemd.rst new file mode 100644 index 0000000..7082262 --- /dev/null +++ b/docs/howto/admin/systemd.rst @@ -0,0 +1,77 @@ +.. _howto/admin/systemd: + +================================ +Customizing ``systemd`` services +================================ + +By default, TLJH configures two ``systemd`` services to run JupyterHub and Traefik. + +These services come with a default set of settings, which are specified in +`jupyterhub.service `_ and +`traefik.service `_. +They look like the following: + +.. code-block:: bash + + [Unit] + Requires=traefik.service + After=traefik.service + + [Service] + User=root + Restart=always + WorkingDirectory=/opt/tljh/state + PrivateTmp=yes + PrivateDevices=yes + ProtectKernelTunables=yes + ProtectKernelModules=yes + Environment=TLJH_INSTALL_PREFIX=/opt/tljh + ExecStart=/opt/tljh/hub/bin/python3 -m jupyterhub.app -f jupyterhub_config.py --upgrade-db + + [Install] + WantedBy=multi-user.target + + +However in some cases, admins might want to have better control on these settings. + +For example when mounting shared volumes over the network using Samba, these namespacing settings might be a bit too strict +and prevent users from accessing the shared volumes. + + +Overriding settings with ``override.conf`` +========================================== + +To override the settings, it is possible to provide a custom ``/etc/systemd/system/jupyterhub.service.d/override.conf`` file +with the following content: + +.. code-block:: bash + + [Service] + PrivateTmp=no + PrivateDevices=no + ProtectKernelTunables=no + ProtectKernelModules=no + +Then make sure to reload the daemon and the ``jupyterhub`` service: + +.. code-block:: bash + + sudo systemctl daemon-reload + sudo systemctl restart jupyterhub + +Checking the status should look like the following: + +.. image:: ../../images/admin/jupyterhub-systemd-status.png + :alt: Checking the status of the JupyterHub systemd service + +To override the ``traefik`` settings, create a new file under ``/etc/systemd/system/traefik.service.d/override.conf`` +and follow the same steps. + + +References +========== + +If you would like to learn more about the ``systemd`` security features, check out these references: + +- `List of systemd settings `_ +- `Mastering systemd: Securing and sandboxing applications and services `_ diff --git a/docs/howto/index.rst b/docs/howto/index.rst index 9f6369a..8339d82 100644 --- a/docs/howto/index.rst +++ b/docs/howto/index.rst @@ -76,6 +76,7 @@ Administration and security admin/nbresuse admin/https admin/enable-extensions + admin/systemd Cloud provider configuration ---------------------------- diff --git a/docs/images/admin/jupyterhub-systemd-status.png b/docs/images/admin/jupyterhub-systemd-status.png new file mode 100644 index 0000000..450767f Binary files /dev/null and b/docs/images/admin/jupyterhub-systemd-status.png differ