zhangyiss/the-littlest-jupyterhub
1
0
Fork 0
mirror of https://github.com/jupyterhub/the-littlest-jupyterhub.git synced 2025-12-18 21:54:05 +08:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #91 from jupyterhub/docs

Browse Source 
small updates to the docs
This commit is contained in:
Yuvi Panda
2018-08-03 10:57:19 -07:00
committed by GitHub
parent be01336b95 6c3c437a85
commit 83c6c41f39
6 changed files with 88 additions and 47 deletions
Download Patch File Download Diff File Expand all files Collapse all files

67
docs/topic/authenticator-configuration.rst
View File

@@ -18,25 +18,35 @@ can be used with TLJH. A number of them ship by default with TLJH:
their password when they log in for the first time. Default authenticator used in TLJH.
We try to have specific how-to guides & tutorials for common authenticators. Since we can not cover
everything, this guide shows you how to use any authenticator you want by using LDAPAuthenticator as an
example.
everything, this guide shows you how to use any authenticator you want with JupyterHub by following
the authenticator's documentation.
Configuring the authenticator
=============================
Setting authenticator properties
================================
JupyterHub authenticators are customized by setting *traitlet properties*. In the authenticator's
documentation, you will find these are usually represented as:
.. code-block::
c.<AuthenticatorName>.<property-name> = <some-value>
You can set these with ``tljh-config`` with:
.. code-block:: bash
sudo -E tljh-config set auth.<AuthenticatorName>.<property-name> <some-value>
Example
-------
LDAPAuthenticator's `documentation <https://github.com/jupyterhub/ldapauthenticator#required-configuration>`_
lists the various configuration options you can set for LDAPAuthenticator. You can set them
in TLJH with the following pattern:
lists the various configuration options you can set for LDAPAuthenticator.
When the documentation asks you to set ``LDAPAuthenticator.server_address``
to some value, you can do that with the following command:
.. code-block:: bash
sudo -E tljh-config set auth.<authenticator-name>.<config-option-name> <config-option-value>
When the documentation asks you to set ``LDAPAuthenticator.server_address`` to some
value, you can do that with the following command:
.. code-block:: bash
sudo -E tljh-config set auth.LDAPAuthenticator.server_address = 'my-ldap-server'
Most authenticators require you set multiple configuration options before you can
@@ -45,22 +55,20 @@ enable them. Read the authenticator's documentation carefully for more informati
Enabling the authenticator
==========================
Once you have configured the authenticator as you want, it should be enabled.
Once you have configured the authenticator as you want, you should then
enable it. Usually, the documentation for the authenticator would ask you to add
something like the following to your ``jupyterhub_config.py`` to enable it:
.. code-block:: python
c.JupyterHub.authenticator_class = 'fully-qualified-authenticator-name'
You can accomplish the same with ``tljh-config``:
.. code-block:: bash
sudo -E tljh-config set auth.type <fully-qualified-authenticator-name>
For LDAPAuthenticator, the fully qualified name is ``ldapauthenticator.LDAPAuthenticator``.
This is the same name that the documentation `asks <https://github.com/jupyterhub/ldapauthenticator#usage>`_
you to set ``c.JupyterHub.authenticator_class`` to.
For LDAPAuthenticator, this would be:
.. code-block:: bash
sudo -E tljh-config set auth.type ldapauthenticator.LDAPAuthenticator
Once enabled, you need to reload JupyterHub for the config to take effect.
.. code-block:: bash
@@ -71,3 +79,14 @@ Try logging in a separate incognito window to check if your configuration works.
lets you preserve your terminal in case there were errors. If there are
errors, :ref:`troubleshooting/logs` should help you debug them.
Example
-------
From the `documentation <https://github.com/jupyterhub/ldapauthenticator#usage>`_ for
LDAPAuthenticator, we see that the fully qualified name is ``ldapauthenticator.LDAPAuthenticator``.
Assuming you have already configured it, the following commands enable LDAPAuthenticator.
.. code-block:: bash
sudo -E tljh-config set auth.type ldapauthenticator.LDAPAuthenticator
sudo -E tljh-config reload

23
docs/topic/security.rst
View File

@@ -10,7 +10,7 @@ information about the security model of The Littlest JupyterHub.
System user accounts
====================
Each JupyterHub user gets their own unix user account created when they
Each JupyterHub user gets their own Unix user account created when they
first start their server. This protects users from each other, gives them a
home directory at a well known location, and allows sharing based on file system
permissions.
@@ -38,8 +38,8 @@ command on the terminal. No password required.
This is a **lot** of power, and they can do pretty much anything they want to
the server - look at other people's work, modify it, break the server in cool &
funky ways, etc. This also means if an admin's credentials are compromised (
easy to guess password, password re-use, etc) the entire JupyterHub is compromised.
funky ways, etc. This also means **if an admin's credentials are compromised (
easy to guess password, password re-use, etc) the entire JupyterHub is compromised.**
Off-boarding users securely
===========================
@@ -47,9 +47,15 @@ Off-boarding users securely
When you delete users from the JupyterHub admin console, their unix user accounts
are **not** removed. This means they might continue to have access to the server
even after you remove them from JupyterHub. Admins should manually remove the user
from the server & archive their home directories as needed. If the user removed
from the server is an admin, extra care must be taken since they could have
modified the system earlier to continue giving them access.
from the server & archive their home directories as needed. For example, the
following command deletes the unix user associated with the JupyterHub user ``yuvipanda``.
.. code-block::
sudo userdel jupyter-yuvipanda
If the user removed from the server is an admin, extra care must be taken
since they could have modified the system earlier to continue giving them
access.
Per-user ``/tmp``
=================
@@ -62,6 +68,5 @@ feature of systemd.
HTTPS
=====
The Littlest JupyterHub does not currently support HTTPS. Follow `this issue
<https://github.com/jupyterhub/the-littlest-jupyterhub/issues/29>`_ for progress
on HTTPS support.
Any internet-facing JupyterHub should use HTTPS to secure its traffic. For
information on how to use HTTPS with your JupyterHub, see :ref:`_howto/https`.

8
docs/topic/tljh-config.rst
View File

@@ -5,7 +5,7 @@ Configuring TLJH with ``tljh-config``
=====================================
``tljh-config`` is the commandline program used to make configuration
changes to TLJH.
changes to TLJH.
Running ``tljh-config``
======================`
@@ -75,7 +75,7 @@ restarted and loaded with the new configuration.
Advanced: ``config.yaml``
=========================
``tljh-config`` is a simple program that modifies the contents of the
``config.yaml`` file located at ``/opt/tljh/config.yaml``. ``tljh-config``
``tljh-config`` is a simple program that modifies the contents of the
``config.yaml`` file located at ``/opt/tljh/config.yaml``. ``tljh-config``
is the recommended method of editing / viewing configuration since editing
YAML by hand in a terminal text editor is a large source of errors.
YAML by hand in a terminal text editor is a large source of errors.