mirror of
https://github.com/jupyterhub/the-littlest-jupyterhub.git
synced 2025-12-18 21:54:05 +08:00
adopt myst
run rst2myst, with minimal manual formatting fixes
This commit is contained in:
Min RK
246
docs/topic/tljh-config.md
Normal file
246
docs/topic/tljh-config.md
Normal file
@@ -0,0 +1,246 @@
|
||||
(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:
|
||||
|
||||
1. From inside a terminal in JupyterHub while logged in as an admin user.
|
||||
This method is recommended.
|
||||
2. 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.
|
||||
|
||||
(tljh-set)=
|
||||
|
||||
## 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:
|
||||
|
||||
```bash
|
||||
sudo tljh-config set <property-path> <value>
|
||||
```
|
||||
|
||||
where:
|
||||
|
||||
1. `<property-path>` is a dot-separated path to the property you want
|
||||
to set.
|
||||
2. `<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:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
(tljh-base-url)=
|
||||
|
||||
### Base URL
|
||||
|
||||
> Use `base_url` to determine the base URL used by JupyterHub. This parameter will
|
||||
> be passed straight to `c.JupyterHub.base_url`.
|
||||
|
||||
(tljh-set-auth)=
|
||||
|
||||
### 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.
|
||||
|
||||
(tljh-set-ports)=
|
||||
|
||||
### 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.
|
||||
>
|
||||
> ```bash
|
||||
> sudo tljh-config set http.port 8080
|
||||
> sudo tljh-config set https.port 8443
|
||||
> sudo tljh-config reload proxy
|
||||
> ```
|
||||
|
||||
(tljh-set-user-lists)=
|
||||
|
||||
### User Lists
|
||||
|
||||
- `users.allowed` takes in usernames to whitelist
|
||||
|
||||
- `users.banned` takes in usernames to blacklist
|
||||
|
||||
- `users.admin` takes in usernames to designate as admins
|
||||
|
||||
```bash
|
||||
sudo 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
|
||||
```
|
||||
|
||||
(tljh-set-user-limits)=
|
||||
|
||||
### 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 to `None` disables memory limits.
|
||||
|
||||
```bash
|
||||
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 to `None` disables CPU limits.
|
||||
|
||||
```bash
|
||||
sudo tljh-config set limits.cpu 2
|
||||
```
|
||||
|
||||
(tljh-set-user-env)=
|
||||
|
||||
### User Environment
|
||||
|
||||
> `user_environment.default_app` Set default application users are
|
||||
> launched into. Currently can be set to the following values
|
||||
> `jupyterlab` or `nteract`
|
||||
>
|
||||
> ```bash
|
||||
> sudo tljh-config set user_environment.default_app jupyterlab
|
||||
> ```
|
||||
|
||||
(tljh-set-extra-user-groups)=
|
||||
|
||||
## 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:
|
||||
|
||||
```bash
|
||||
tljh-config set users.extra_user_groups.group1 user1
|
||||
```
|
||||
|
||||
- `tljh-config add-item`, if multiple users are to be added to
|
||||
the group:
|
||||
|
||||
```bash
|
||||
tljh-config add-item users.extra_user_groups.group1 user1
|
||||
tljh-config add-item users.extra_user_groups.group1 user2
|
||||
```
|
||||
|
||||
(tljh-view-conf)=
|
||||
|
||||
## View current configuration
|
||||
|
||||
To see the current configuration, you can run the following command:
|
||||
|
||||
```bash
|
||||
sudo tljh-config show
|
||||
```
|
||||
|
||||
This will print the current configuration of your TLJH. This is very
|
||||
useful when asking for support!
|
||||
|
||||
(tljh-reload-hub)=
|
||||
|
||||
## Reloading JupyterHub to apply configuration
|
||||
|
||||
After modifying the configuration, you need to reload JupyterHub for
|
||||
it to take effect. You can do so with:
|
||||
|
||||
```bash
|
||||
sudo tljh-config reload
|
||||
```
|
||||
|
||||
This should not affect any running users. The JupyterHub will be
|
||||
restarted and loaded with the new configuration.
|
||||
|
||||
(tljh-edit-yaml)=
|
||||
|
||||
## 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.
|
||||
|
||||
```bash
|
||||
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
|
||||
```
|
||||
|
||||
```bash
|
||||
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
|
||||
```
|
||||
Reference in New Issue
Block a user