diff --git a/docs/howto/auth/ldap.rst b/docs/howto/auth/ldap.rst new file mode 100644 index 0000000..cece4ff --- /dev/null +++ b/docs/howto/auth/ldap.rst @@ -0,0 +1,46 @@ +.. _howto/auth/ldap: + +============================= +Using LDAP for authentication +============================= + +`LDAP `_ +is an open and widely-used protocol for authentication. + +The `LDAPAuthenticator's documentation `_ +lists the various configuration options you can set for LDAPAuthenticator. You can set them +in TLJH with the following pattern: + +.. code-block:: bash + + sudo -E tljh-config set auth.. + +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' + +Enabling the authenticator +========================== + +For LDAPAuthenticator, the fully qualified name is ``ldapauthenticator.LDAPAuthenticator``. +This is the same name that the `documentation asks `_ +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 + + sudo -E tljh-config reload + +Try logging in a separate incognito window to check if your configuration works. This +lets you preserve your terminal in case there were errors. If there are +errors, :ref:`troubleshooting/logs` should help you debug them. diff --git a/docs/howto/resource-estimation.rst b/docs/howto/resource-estimation.rst index 5fe3953..cc21d46 100644 --- a/docs/howto/resource-estimation.rst +++ b/docs/howto/resource-estimation.rst @@ -40,9 +40,16 @@ Maximum memory allowed per user Depending on what kinda work your users are doing, they will use different amounts of memory. The easiest way to determine this is to run through a typical user -workflow yourself, and measure how much memory is used. Add 20-40% headroom for -users to 'play around', and that should be the maximum memory allowed per user. -The system will prevent users from using more memory than this. +workflow yourself, and measure how much memory is used. + +For example, you can begin running a Jupyter Notebook session on your JupyterHub, then open a +terminal on the JupyterHub and use ``top`` to track how much memory you use +as you go through the material. A good rule of thumb is to take the maximum amount of memory you used during +your session, and add 20-40% headroom for users to 'play around'. This is the +maximum amount of memory that should be given to each user. + +If users use *more* than this alloted amount of memory, their kernel will restart (and all +their progress in the current session will be lost). CPU === @@ -56,7 +63,7 @@ stop, unlike with RAM. Server CPU Recommended = (Maximum concurrent users \times Maximum CPU usage per user) + 0.2 The ``0.2`` is overhead for TLJH and related services. **Server CPU Recommended** -is the amount of CPU the server you aquire should have. We recommend using +is the amount of CPU the server you acquire should have. We recommend using the same process used to estimate Memory required for estimating CPU required. Disk space diff --git a/docs/index.rst b/docs/index.rst index 9f68ce7..e5947a7 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -3,13 +3,13 @@ The Littlest JupyterHub ======================= A simple `JupyterHub `_ distribution for -a small (0-50) number of users on a single server. +a small (0-100) number of users on a single server. Development Status ================== This project is currently in **alpha** state. Most things work, but we might -still make breaking changes that have no clear upgrade pathway. We are targetting +still make breaking changes that have no clear upgrade pathway. We are targeting a v0.1 release sometime in mid-August 2018. Follow `this milestone `_ to see progress towards the release! @@ -61,13 +61,18 @@ How-To guides answer the question 'How do I...?' for a lot of topics. howto/notebook-interfaces howto/resource-estimation +Authentication +^^^^^^^^^^^^^^ + We have a special set of How-To Guides on using various forms of authentication -with your JupyterHub. +with your JupyterHub. For more information on Authentication, see +:ref:`topic/authenticator-configuration` .. toctree:: :titlesonly: howto/auth/dummy + howto/auth/ldap Topic Guides ============ diff --git a/docs/topic/authenticator-configuration.rst b/docs/topic/authenticator-configuration.rst index 1b3f176..7c9d96f 100644 --- a/docs/topic/authenticator-configuration.rst +++ b/docs/topic/authenticator-configuration.rst @@ -24,6 +24,12 @@ example. Configuring the authenticator ============================= +Some authenticators have unique configuration options. This section covers a +few common ones. + +LDAPAuthenticator +^^^^^^^^^^^^^^^^^ + LDAPAuthenticator's `documentation `_ lists the various configuration options you can set for LDAPAuthenticator. You can set them in TLJH with the following pattern: @@ -36,7 +42,7 @@ When the documentation asks you to set ``LDAPAuthenticator.server_address`` to s 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,7 +51,9 @@ 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. We'll use the LDAPAuthenticator as an example, though the process +is similar for the other authenticators. .. code-block:: bash @@ -70,4 +78,3 @@ Once enabled, you need to reload JupyterHub for the config to take effect. Try logging in a separate incognito window to check if your configuration works. This lets you preserve your terminal in case there were errors. If there are errors, :ref:`troubleshooting/logs` should help you debug them. - diff --git a/docs/topic/security.rst b/docs/topic/security.rst index 424b61d..e91e858 100644 --- a/docs/topic/security.rst +++ b/docs/topic/security.rst @@ -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,7 +47,13 @@ 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 & archive their home directories as needed. For example, the +following command deletes the user ``yuvi``. + +.. code-block:: + userdel yuvi + +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. @@ -62,6 +68,5 @@ feature of systemd. HTTPS ===== -The Littlest JupyterHub does not currently support HTTPS. Follow `this issue -`_ 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`. diff --git a/docs/topic/tljh-config.rst b/docs/topic/tljh-config.rst index 3e22e5f..bfb137a 100644 --- a/docs/topic/tljh-config.rst +++ b/docs/topic/tljh-config.rst @@ -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. \ No newline at end of file +YAML by hand in a terminal text editor is a large source of errors. diff --git a/docs/tutorials/nbgitpuller.rst b/docs/tutorials/nbgitpuller.rst index 2545c69..def52b9 100644 --- a/docs/tutorials/nbgitpuller.rst +++ b/docs/tutorials/nbgitpuller.rst @@ -7,12 +7,12 @@ Distributing materials to users with nbgitpuller Goal ==== -A very common educational need when using JupyterHub for education is to easily +A very common need when using JupyterHub is to easily distribute study materials / lab notebooks to students. Students should be able to: -1. Easily get latest version of materials, including any updates the instructor +1. Easily get the latest version of materials, including any updates the instructor has made to materials the student already has a copy of. 2. Be confident they won't lose any of their work. If an instructor has modified something the student has also modified, the student's modification should @@ -108,4 +108,10 @@ Step 2: Users click on the nbgitpuller link #. Users will now be redirected to the notebook specified in the URL! This workflow lets users land directly in the notebook you specified -without having to understand much about git or the JupyterHub interface. \ No newline at end of file +without having to understand much about git or the JupyterHub interface. + +Advanced: hand-crafting an nbgitpuller link +=========================================== + +For information on hand-crafting an ``nbgitpuller`` link, see +`the nbgitpuller README `_.