From 7f1bc490d6f9a154ed13cd0d7bb0b4c1cd21ec4d Mon Sep 17 00:00:00 2001 From: strawberry Date: Sun, 28 Jul 2024 16:46:20 -0400 Subject: [PATCH] docs: update configuration docs for the new `-O` option Signed-off-by: strawberry --- docs/configuration.md | 28 ++++++++++++++++++++++++---- 1 file changed, 24 insertions(+), 4 deletions(-) diff --git a/docs/configuration.md b/docs/configuration.md index 8b3fec8a..cf3ce00b 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -4,15 +4,35 @@ This chapter describes various ways to configure conduwuit. ## Basics -Conduwuit uses a config file for the majority of the settings. Please refer to the -[example config file](./configuration/examples.md#example-configuration) for all of those settings. -The config file to use can either be specified on the command line when running conduwuit by specifying the +conduwuit uses a config file for the majority of the settings, but also supports setting individual config options via commandline. + +Please refer to the [example config file](./configuration/examples.md#example-configuration) for all of those settings. + +The config file to use can be specified on the commandline when running conduwuit by specifying the `-c`, `--config` flag. Alternatively, you can use the environment variable `CONDUWUIT_CONFIG` to specify the config -file to used. +file to used. Conduit's environment variables are supported for backwards compatibility. + +## Option commandline flag + +conduwuit supports setting individual config options in TOML format from the `-O` / `--option` flag. For example, you can set your server name via `-O server_name=\"example.com\"`. + +Note that the config is parsed as TOML, and shells like bash will remove quotes. So unfortunately it is required to escape quotes if the config option takes a string. +This does not apply to options that take booleans or numbers: +- `--option allow_registration=true` works ✅ +- `-O max_request_size=99999999` works ✅ +- `-O server_name=example.com` does not work ❌ +- `--option log=\"debug\"` works ✅ +- `--option server_name='"example.com'"` works ✅ + ## Environment variables All of the settings that are found in the config file can be specified by using environment variables. The environment variable names should be all caps and prefixed with `CONDUWUIT_`. + For example, if the setting you are changing is `max_request_size`, then the environment variable to set is `CONDUWUIT_MAX_REQUEST_SIZE`. + +To modify config options not in the `[global]` context such as `[global.well_known]`, use the `__` suffix split: `CONDUWUIT_WELL_KNOWN__SERVER` + +Conduit's environment variables are supported for backwards compatibility (e.g. `CONDUIT_SERVER_NAME`).