docs: add guide to customize which SSL certs to use

docs/guides/howto_behind_proxy.md

@@ -42,30 +42,3 @@ At the shell session scope:
 > $env:QDT_PROXY_HTTP='http://user:password@proxyserver.intra:8765'
 > qdt -vvv
 ```
-
-----
-
-## Defining custom SSL client certificates
-
-Using a proxy for https connections typically requires the local machine to trust the proxy’s root certificate.
-
-> See [Requests official documentation](https://docs.python-requests.org/en/latest/user/advanced/#ca-certificates)
-
-### Using `REQUESTS_CA_BUNDLE` or `CURL_CA_BUNDLE`
-
-Point to a certificat bundle file path (*.pem).
-
-#### Example on Windows PowerShell
-
-Only for the QDT command scope:
-
-```powershell
-$env:REQUESTS_CA_BUNDLE="$env:USERPROFILE\cacerts.pem"; qdt -vvv
-```
-
-At the shell session scope:
-
-```powershell
-> $env:REQUESTS_CA_BUNDLE="$env:USERPROFILE\cacerts.pem"
-> qdt -vvv
-```

docs/guides/howto_use_custom_ssl_certs.md

@@ -0,0 +1,45 @@
+# Defining custom SSL client certificates
+
+Using a [proxy](./howto_behind_proxy.md) for https connections typically requires the local machine to trust the proxy’s root certificate. By default, a bundle of SSL certificates is used, through [certifi](https://pypi.org/project/certifi/) (using Mozilla curated list).
+
+> See [Requests official documentation](https://docs.python-requests.org/en/latest/user/advanced/#ca-certificates)
+
+Here comes how to customize which certificates bundle to use or how to require QDT to use the native system certificates store.
+
+## Using `REQUESTS_CA_BUNDLE` or `CURL_CA_BUNDLE`
+
+Point to a certificat bundle file path (*.pem).
+
+### Example on Windows PowerShell
+
+Only for the QDT command scope:
+
+```powershell
+$env:REQUESTS_CA_BUNDLE="$env:USERPROFILE\cacerts.pem"; qdt -vvv
+```
+
+At the shell session scope:
+
+```powershell
+> $env:REQUESTS_CA_BUNDLE="$env:USERPROFILE\cacerts.pem"
+> qdt -vvv
+```
+
+## Using native system certificates store
+
+If the `QDT_SSL_USE_SYSTEM_STORES` environment variable is set to `True`, HTTPS requests rely on the native system certificates store.
+
+### Example on Windows PowerShell
+
+Only for the QDT command scope:
+
+```powershell
+$env:QDT_SSL_USE_SYSTEM_STORES=true; qdt -vvv
+```
+
+At the shell session scope:
+
+```powershell
+> $env:QDT_SSL_USE_SYSTEM_STORES=true
+> qdt -vvv
+```

docs/index.md

@@ -60,6 +60,7 @@ caption: Guides
 maxdepth: 1
 ---
 guides/howto_behind_proxy
+guides/howto_use_custom_ssl_certs
 guides/howto_qgis_get_plugin_id
 guides/howto_schedule_deployment
 guides/howto_windows_sign_executable

docs/usage/settings.md

@@ -9,7 +9,7 @@ Some options and arguments can be set with environment variables.
 | Variable name                       | Corresponding CLI argument | Default value      |
 | :---------------------------------- | :------------------------: | :----------------: |
 | `QDT_LOGS_LEVEL`                    | `-v`, `--verbose` | `1` (= `logging.WARNING`). Must be an integer. |
-| `QDT_PROXY_HTTP`                    | `--proxy-http` | No proxy. |
+| `QDT_PROXY_HTTP`                    | `--proxy-http` to customize network proxy to use. See also [How to use behind a proxy](../guides/howto_behind_proxy.md). | No proxy. |
 | `QDT_SCENARIO_PATH`                 | `--scenario` in `deploy`   | `scenario.qdt.yml` |
 | `QDT_UPGRADE_CHECK_ONLY`            | `-c`, `--check-only` in `upgrade`   | `False` |
 | `QDT_UPGRADE_DISPLAY_RELEASE_NOTES` | `-n`, `--dont-show-release-notes` in `upgrade`   | `True` |
@@ -24,7 +24,7 @@ Some others parameters can be set using environment variables.
 | `QDT_LOCAL_WORK_DIR` | Local folder where QDT download remote resources (profiles, plugins, etc.) | `~/.cache/qgis-deployment-toolbelt/default/` |
 | `QDT_LOGS_DIR` | Folder where QDT writes the log files, which are automatically rotated. | `~/.cache/qgis-deployment-toolbelt/logs/` |
 | `QDT_QGIS_EXE_PATH` | Path to the QGIS executable to use. Used in shortcuts. | `/usr/bin/qgis` on Linux and MacOS, `%PROGRAMFILES%/QGIS 3.28/bin/qgis-ltr-bin.exe` on Windows. |
-| `QDT_SSL_USE_SYSTEM_STORES` | By default, a bundle of SSL certificates is used, through [certifi](https://pypi.org/project/certifi/). If this environment variable is set to True, QDT tries to uses the system certificates store. Based on [truststore](https://truststore.readthedocs.io/).   | `False` |
+| `QDT_SSL_USE_SYSTEM_STORES` | By default, a bundle of SSL certificates is used, through [certifi](https://pypi.org/project/certifi/). If this environment variable is set to True, QDT tries to uses the system certificates store. Based on [truststore](https://truststore.readthedocs.io/). See also [How to use custom SSL certificates](../guides/howto_use_custom_ssl_certs.md).  | `False` |
 
 ----