From ccac483c50a205329bf506dde055d791a694d4f1 Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Tue, 31 Jul 2018 09:38:25 -0700 Subject: [PATCH 1/5] small updates to the docs --- docs/howto/auth/ldap.rst | 46 ++++++++++++++++++++++ docs/howto/resource-estimation.rst | 15 +++++-- docs/index.rst | 11 ++++-- docs/topic/authenticator-configuration.rst | 13 ++++-- docs/topic/security.rst | 19 +++++---- docs/topic/tljh-config.rst | 8 ++-- docs/tutorials/nbgitpuller.rst | 12 ++++-- 7 files changed, 100 insertions(+), 24 deletions(-) create mode 100644 docs/howto/auth/ldap.rst 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 `_. From 6f67a4762f0140f75a8303d88cadb1ac0b14375d Mon Sep 17 00:00:00 2001 From: yuvipanda Date: Thu, 2 Aug 2018 12:03:18 -0700 Subject: [PATCH 2/5] Clarify command for deleting unix system users --- docs/topic/security.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/topic/security.rst b/docs/topic/security.rst index e91e858..b59d911 100644 --- a/docs/topic/security.rst +++ b/docs/topic/security.rst @@ -48,14 +48,14 @@ When you delete users from the JupyterHub admin console, their unix user account 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. For example, the -following command deletes the user ``yuvi``. +following command deletes the unix user associated with the JupyterHub user ``yuvipanda``. .. code-block:: - userdel yuvi + 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. +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`` ================= From f154e0d93674ba3104c94b86ec164da07092f34c Mon Sep 17 00:00:00 2001 From: yuvipanda Date: Thu, 2 Aug 2018 12:25:03 -0700 Subject: [PATCH 3/5] Clarify generic authenticator setup documentation --- docs/topic/authenticator-configuration.rst | 64 +++++++++++++--------- 1 file changed, 38 insertions(+), 26 deletions(-) diff --git a/docs/topic/authenticator-configuration.rst b/docs/topic/authenticator-configuration.rst index 7c9d96f..af50c0a 100644 --- a/docs/topic/authenticator-configuration.rst +++ b/docs/topic/authenticator-configuration.rst @@ -18,28 +18,32 @@ 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 +================================ -Some authenticators have unique configuration options. This section covers a -few common ones. +JupyterHub authenticators are customized by setting *traitlet properties*. In the authenticator's +documentation, you will find these are usually represented as: -LDAPAuthenticator -^^^^^^^^^^^^^^^^^ +.. code-block:: -LDAPAuthenticator's `documentation `_ -lists the various configuration options you can set for LDAPAuthenticator. You can set them -in TLJH with the following pattern: + c.. = + +You can set these with ``tljh-config`` with: .. code-block:: bash - sudo -E tljh-config set auth.. + 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: +Example +------- + +LDAPAuthenticator's `documentation `_ +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 @@ -52,23 +56,19 @@ Enabling the authenticator ========================== 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. +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 -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 @@ -78,3 +78,15 @@ 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. + +Example +------- + +From the `documentation `_ 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 From 92205d799054da904e9d7f288c4a14cfd0bf8b8f Mon Sep 17 00:00:00 2001 From: yuvipanda Date: Thu, 2 Aug 2018 12:25:57 -0700 Subject: [PATCH 4/5] Remove LDAP specific auth howto document This needs a lot more work before it is useful, so we remove it for now. --- docs/howto/auth/ldap.rst | 46 ---------------------------------------- docs/index.rst | 1 - 2 files changed, 47 deletions(-) delete mode 100644 docs/howto/auth/ldap.rst diff --git a/docs/howto/auth/ldap.rst b/docs/howto/auth/ldap.rst deleted file mode 100644 index cece4ff..0000000 --- a/docs/howto/auth/ldap.rst +++ /dev/null @@ -1,46 +0,0 @@ -.. _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/index.rst b/docs/index.rst index e5947a7..9ddfc53 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -72,7 +72,6 @@ with your JupyterHub. For more information on Authentication, see :titlesonly: howto/auth/dummy - howto/auth/ldap Topic Guides ============ From 6c3c437a85a487b4bf06261290b6684e94aacbf4 Mon Sep 17 00:00:00 2001 From: yuvipanda Date: Thu, 2 Aug 2018 12:30:51 -0700 Subject: [PATCH 5/5] Use appropriate heading underline style --- docs/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.rst b/docs/index.rst index 9ddfc53..824f75a 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -62,7 +62,7 @@ How-To guides answer the question 'How do I...?' for a lot of topics. howto/resource-estimation Authentication -^^^^^^^^^^^^^^ +-------------- We have a special set of How-To Guides on using various forms of authentication with your JupyterHub. For more information on Authentication, see