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 / Unset a configuration property#
TLJH’s configuration is organized in a nested tree structure. You can set a particular property with the following command:
sudo 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:
sudo tljh-config set auth.DummyAuthenticator.password mypassword
This can only set string and numerical properties, not lists.
To unset a configuration property you can use the following command:
sudo tljh-config unset <property-path>
Unsetting a configuration property removes the property from the configuration
file. If what you want is only to change the property’s value, you should use
set
and overwrite it with the desired value.
Some of the existing <property-path>
are listed below by categories:
Base URL#
Use base_url
to determine the base URL used by JupyterHub. This parameter will
be passed straight to c.JupyterHub.base_url
.
Authentication#
Use auth.type
to determine authenticator to use. All parameters
in the config under auth.{auth.type}
will be passed straight to the
authenticators themselves.
Ports#
Use http.port
and https.port
to set the ports that TLJH will listen on,
which are 80 and 443 by default. However, if you change these, note that
TLJH does a lot of other things to the system (with user accounts and sudo
rules primarily) that might break security assumptions your other
applications have, so use with extreme caution.
sudo tljh-config set http.port 8080
sudo tljh-config set https.port 8443
sudo tljh-config reload proxy
(tljh-set-listen-address)
Listen address#
Use http.address
and https.address
to set the addresses that TLJH will listen on,
which is an empty address by default (it means it listens on all interfaces by default).
sudo tljh-config set http.address 127.0.0.1
sudo tljh-config set https.address 127.0.0.1
sudo tljh-config reload proxy
User Lists#
users.allowed
takes in usernames to allowusers.banned
takes in usernames to banusers.admin
takes in usernames to designate as adminssudo tljh-config add-item users.allowed good-user_1 sudo tljh-config add-item users.allowed good-user_2 sudo tljh-config add-item users.banned bad-user_6 sudo tljh-config add-item users.admin admin-user_0 sudo tljh-config remove-item users.allowed good-user_2
User Server Limits#
limits.memory
Specifies the maximum memory that can be used by each individual user. By default there is no memory limit. The limit can be specified as an absolute byte value. You can use the suffixes K, M, G or T to mean Kilobyte, Megabyte, Gigabyte or Terabyte respectively. Setting it toNone
disables memory limits.sudo tljh-config set limits.memory 4G
Even if you want individual users to use as much memory as possible, it is still good practice to set a memory limit of 80-90% of total physical memory. This prevents one user from being able to single handedly take down the machine accidentally by OOMing it.
limits.cpu
A float representing the total CPU-cores each user can use. By default there is no CPU limit. 1 represents one full CPU, 4 represents 4 full CPUs, 0.5 represents half of one CPU, etc. This value is ultimately converted to a percentage and rounded down to the nearest integer percentage, i.e. 1.5 is converted to 150%, 0.125 is converted to 12%, etc. Setting it toNone
disables CPU limits.sudo tljh-config set limits.cpu 2
User Environment#
user_environment.default_app
Set default application users are launched into.
Currently this can only be set to: classic
and jupyterlab
.
sudo tljh-config set user_environment.default_app jupyterlab
Extra User Groups#
users.extra_user_groups
is a configuration option that can be used
to automatically add a user to a specific group. By default, there are
no extra groups defined.
Users can be “paired” with the desired, existing groups using:
tljh-config set
, if only one user is to be added to the desired group:
tljh-config set users.extra_user_groups.group1 user1
tljh-config add-item
, if multiple users are to be added to the group:
tljh-config add-item users.extra_user_groups.group1 user1
tljh-config add-item users.extra_user_groups.group1 user2
View current configuration#
To see the current configuration, you can run the following command:
sudo 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:
sudo 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/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.
To learn more about the tljh-config
usage, you can use the --help
flag.
The --help
flag can be used either directly, to get information about the
general usage of the command or after a positional argument. For example, using
it after an argument like remove-item
gives information about this specific command.
sudo tljh-config --help
usage: tljh-config [-h] [--config-path CONFIG_PATH] {show,unset,set,add-item,remove-item,reload} ...
positional arguments:
{show,unset,set,add-item,remove-item,reload}
show Show current configuration
unset Unset a configuration property
set Set a configuration property
add-item Add a value to a list for a configuration property
remove-item Remove a value from a list for a configuration property
reload Reload a component to apply configuration change
optional arguments:
-h, --help show this help message and exit
--config-path CONFIG_PATH
Path to TLJH config.yaml file
sudo tljh-config remove-item --help
usage: tljh-config remove-item [-h] key_path value
positional arguments:
key_path Dot separated path to configuration key to remove value from
value Value to remove from key_path
optional arguments:
-h, --help show this help message and exit