Merge pull request #77 from jupyterhub/config

Add tljh-config command

.circleci/config.yml

@@ -77,6 +77,13 @@ jobs:
                     python3 .circleci/integration-test.py copy . /srv/src
                     python3 .circleci/integration-test.py run 'python3 /srv/src/bootstrap/bootstrap.py'
 
+
+            - run:
+                name: switch to dummyauthenticator
+                command: |
+                    python3 .circleci/integration-test.py run '/opt/tljh/hub/bin/tljh-config set auth.type dummyauthenticator.DummyAuthenticator'
+                    python3 .circleci/integration-test.py run '/opt/tljh/hub/bin/tljh-config reload'
+
             - run:
                 name: print systemd status + logs
                 command: |

docs/howto/admin-users.rst

@@ -0,0 +1,55 @@
+.. _howto/admin-users:
+
+========================
+Add / Remove admin users
+========================
+
+Admin users in TLJH have the following powers:
+
+#. Full root access to the server with passwordless ``sudo``.
+   This lets them do literally whatever they want in the server
+#. Access servers / home directories of all other users
+#. Install new packages for everyone with ``conda``, ``pip`` or ``apt``
+#. Change configuration of TLJH
+
+This is a lot of power, so make sure you know who you are giving it
+to. Admin users should have decent passwords / secure logni mechanisms,
+so attackers can not easily gain control of the system.
+
+Make sure an admin user is present
+==================================
+
+You should make sure an admin user is present when you **install** TLJH
+the very first time. The ``:ref:`--admin <topic/customizing-installer/admin>```
+flag passed to the installer does this. If you had forgotten to do so, the
+easiest way to fix this is to run the installer again.
+
+Adding new admin users
+======================
+
+New admin users can be added by executing the following commands on an
+admin terminal:
+
+.. code-block:: bash
+
+   sudo -E tljh-config add-item users.admin <username>
+   sudo -E tljh-config reload
+
+If the user is already using the JupyterHub, they might have to stop and
+start their server from the control panel to gain new powers.
+
+Removing admin users
+====================
+
+You can remove an existing admin user by executing the following commands in
+an admin terminal:
+
+.. code-block:: bash
+
+   sudo -E tljh-config remove-item users.admin <username>
+   sudo -E tljh-config reload
+
+If the user is already using the JupyterHub, they will continue to have
+some of their admin powers until their server is stopped. Another admin
+can force their server to stop by clicking 'Stop Server' in the admin
+panel.

docs/howto/auth/dummy.rst

@@ -0,0 +1,43 @@
+.. _howto/auth/dummy:
+
+=====================================================
+Authenticate *any* user with a single shared password
+=====================================================
+
+The **Dummy Authenticator** lets *any* user log in with the given password.
+This authenticator is **extremely insecure**, so do not use it if you can
+avoid it.
+
+Enabling the authenticator
+==========================
+
+1. Always use DummyAuthenticator with a password. You can communicate this 
+   password to all your users via an out of band mechanism (like writing on
+   a whiteboard). Once you have selected a password, configure TLJH to use
+   the password by executing the following from an admin console.
+
+.. code-block:: bash
+   
+   sudo -E tljh-config set auth.DummyAuthenticator.password <password>
+
+   Remember to replace ``<password>`` with the password you choose.
+
+2. Enable the authenticator and reload config to apply configuration:
+
+   sudo -E tljh-config set auth.type dummyauthenticator.DummyAuthenticator
+   sudo -E tljh-config reload
+
+Users who are currently logged in will continue to be logged in. When they 
+log out and try to log back in, they will be asked to provide a username and
+password.
+
+Changing the password
+=====================
+
+The password used by DummyAuthenticator can be changed with the following
+commands:
+
+.. code-block:: bash
+
+   tljh-config set auth.DummyAuthenticator.password <new-password>
+   tljh-config reload

docs/index.rst

@@ -54,9 +54,18 @@ How-To guides answer the question 'How do I...?' for a lot of topics.
    :titlesonly:
 
    howto/user-environment
+   howto/admin-users
    howto/notebook-interfaces
    howto/resource-estimation
 
+We have a special set of How-To Guides on using various forms of authentication
+with your JupyterHub.
+
+.. toctree::
+   :titlesonly:
+
+   howto/auth/dummy
+
 Topic Guides
 ============
 
@@ -66,9 +75,9 @@ Topic guides provide in-depth explanations of specific topics.
    :titlesonly:
 
    topic/requirements
-   guides/admin
    topic/security
    topic/customizing-installer
+   topic/tljh-config
 
 
 Troubleshooting

docs/topic/customizing-installer.rst

@@ -13,6 +13,8 @@ is executed as:
 
 This page documents the various options you can pass as commandline parameters to the installer.
 
+.. _topic/customizing-installer/admin:
+
 Adding admin users
 ===================
 

docs/topic/tljh-config.rst

@@ -0,0 +1,81 @@
+.. _topic/tljh-config:
+
+=====================================
+Configuring TLJH with ``tljh-config``
+=====================================
+
+``tljh-config`` is the commandline program used to make configuration
+changes to TLJH. 
+
+Running ``tljh-config``
+======================`
+
+You can run ``tljh-config`` in two ways:
+
+#. From inside a terminal in JupyterHub while logged in as an admin user.
+   This method is **recommended**.
+
+#. By directly calling ``/opt/tljh/hub/bin/tljh-config`` as root when
+   logged in to the server via other means (such as SSH). This is an
+   advanced use case, and not covered much in this guide.
+
+Set a configuration property
+============================
+
+TLJH's configuration is organized in a nested tree structure. You can
+set a particular property with the following command:
+
+.. code-block:: bash
+
+   sudo -E tljh-config set <property-path> <value>
+
+
+where:
+
+#. ``<property-path>`` is a dot-separated path to the property you want
+   to set.
+#. ``<value>`` is the value you want to set the property to.
+
+For example, to set the password for the DummyAuthenticator, you
+need to set the ``auth.DummyAuthenticator.password`` property. You would
+do so with the following:
+
+.. code-block:: bash
+
+   sudo -E tljh-config set auth.DummyAuthenticator.password mypassword
+
+
+This can only set string and numerical properties, not lists.
+
+View current configuration
+==========================
+
+To see the current configuration, you can run the following command:
+
+.. code-block:: bash
+
+   sudo -E tljh-config show
+
+This will print the current configuration of your TLJH. This is very
+useful when asking for support!
+
+Reloading JupyterHub to apply configuration
+===========================================
+
+After modifying the configuration, you need to reload JupyterHub for
+it to take effect. You can do so with:
+
+.. code-block:: bash
+
+   sudo -E tljh-config reload
+
+This should not affect any running users. The JupyterHub will be
+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`` 
+is the recommended method of editing / viewing configuration since editing
+YAML by hand in a terminal text editor is a large source of errors.

integration-tests/requirements.txt

@@ -1,2 +1,3 @@
 pytest
-requests
+pytest-asyncio
+git+https://github.com/yuvipanda/hubtraf.git