diff --git a/docs/guides/admin.rst b/docs/guides/admin.rst deleted file mode 100644 index f3078aa..0000000 --- a/docs/guides/admin.rst +++ /dev/null @@ -1,57 +0,0 @@ -.. _admin_access: - -===================== -Administrative Access -===================== - -In The Littlest JupyterHub, we try to allow users to do as many administrative -tasks as possible within JupyterHub itself. Admin users can: - -1. Have full root access with passwordless ``sudo`` -2. Install system-wide packages with ``apt`` -3. Install ``conda`` / ``pip`` packages for all JupyterHub users -4. Change the amount of RAM / CPU available to each user, and more! - -By default, there are no admin users. You should add some after installation. - -Adding admin users -================== - -Admin users are specified in the `YAML `_ -config file at ``/opt/tljh/config.yaml``. This file is created upon installing -tljh. - -1. Open the ``config.yaml`` file for editing. - - .. code-block:: bash - - sudo nano /opt/tljh/config.yaml - -2. Add usernames that should have admin access. - - .. code-block:: yaml - - users: - admin: - - user1 - - user2 - - Be careful around the syntax - indentation matters, and you should be using - spaces and not tabs. - - When you are done, save the file and exit. In ``nano``, you can do this with - ``Ctrl+X`` key. - -3. When you are sure the format is ok, restart JupyterHub to let the config take - effect. - - .. code-block:: bash - - sudo systemctl restart jupyterhub - -This should give you admin access from JupyterHub! You can verify this by: - -1. Opening a Terminal in your JupyterHub and checking if ``sudo`` works -2. Opening your JupyterHub ``Control Panel`` and checking for the **Admin** tab - -From now on, you can use the JupyterHub to do most configuration changes. diff --git a/docs/howto/admin-users.rst b/docs/howto/admin-users.rst new file mode 100644 index 0000000..4b72fb3 --- /dev/null +++ b/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 ``` +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 + 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 + 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. diff --git a/docs/index.rst b/docs/index.rst index 93c8529..1c8e5b5 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -54,6 +54,7 @@ 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 @@ -74,7 +75,6 @@ Topic guides provide in-depth explanations of specific topics. :titlesonly: topic/requirements - guides/admin topic/security topic/customizing-installer topic/tljh-config diff --git a/docs/topic/customizing-installer.rst b/docs/topic/customizing-installer.rst index 567e596..7a68fe8 100644 --- a/docs/topic/customizing-installer.rst +++ b/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 ===================