Adding kanidm client config docs and notes ref #2248 (#2333)

book/src/client_tools.md

@@ -15,6 +15,9 @@ verify_hostnames = true|false
 ca_path = "/path/to/ca.pem"
 ```
 
+The full configuration reference is in the
+[definition of `KanidmClientConfig`](https://kanidm.github.io/kanidm/master/rustdoc/kanidm_client/struct.KanidmClientConfig.html).
+
 Once configured, you can test this with:
 
 ```bash

book/src/installing_client_tools.md

@@ -120,7 +120,7 @@ alias kanidm="docker run ..."
 
 The tools are available as a cargo download if you have a rust tool chain available. To install rust
 you should follow the documentation for [rustup](https://rustup.rs/). These will be installed into
-your home directory. To update these, re-run the install command.
+your home directory. To update these, re-run the install command. You will likely need to install additional development libraries, specified in the [Developer Guide](DEVELOPER_README.html).
 
 ```bash
 cargo install kanidm_tools

libs/client/src/lib.rs

@@ -72,10 +72,32 @@ pub enum ClientError {
 }
 
 #[derive(Debug, Deserialize, Serialize)]
+/// This struct is what Kanidm uses for parsing the client configuration at runtime.
+///
+/// # Configuration file inheritance
+///
+/// The configuration files are loaded in order, with the last one loaded overriding the previous one.
+///
+/// 1. The "system" config is loaded from in [kanidm_proto::constants::DEFAULT_CLIENT_CONFIG_PATH].
+/// 2. Then a per-user configuration, from [kanidm_proto::constants::DEFAULT_CLIENT_CONFIG_PATH_HOME] is loaded.
+/// 3. All of these may be overridden by setting environment variables.
+///
 pub struct KanidmClientConfig {
+    /// The URL of the server, ie `https://example.com`.
+    ///
+    /// Environment variable is `KANIDM_URL`. Yeah, we know.
     pub uri: Option<String>,
-    pub verify_ca: Option<bool>,
+    /// Whether to verify the TLS certificate of the server matches the hostname you connect to, defaults to `true`.
+    ///
+    /// Environment variable is slightly inverted - `KANIDM_SKIP_HOSTNAME_VERIFICATION`.
     pub verify_hostnames: Option<bool>,
+    /// Whether to verify the Certificate Authority details of the server's TLS certificate, defaults to `true`.
+    ///
+    /// Environment variable is slightly inverted - `KANIDM_SKIP_HOSTNAME_VERIFICATION`.
+    pub verify_ca: Option<bool>,
+    /// Optionally you can specify the path of a CA certificate to use for verifying the server, if you're not using one trusted by your system certificate store.
+    ///
+    /// Environment variable is `KANIDM_CA_PATH`.
     pub ca_path: Option<String>,
 }
 
@@ -261,7 +283,6 @@ impl KanidmClientBuilder {
         })
     }
 
-    #[allow(clippy::result_unit_err)]
     pub fn read_options_from_optional_config<P: AsRef<Path> + std::fmt::Debug>(
         self,
         config_path: P,

unix_integration/src/daemon.rs

@@ -468,6 +468,7 @@ async fn main() -> ExitCode {
                 .help("Allow running as root. Don't use this in production as it is risky!")
                 .short('r')
                 .long("skip-root-check")
+                .env("KANIDM_SKIP_ROOT_CHECK")
                 .action(ArgAction::SetTrue),
         )
         .arg(
@@ -475,6 +476,7 @@ async fn main() -> ExitCode {
                 .help("Show extra debug information")
                 .short('d')
                 .long("debug")
+                .env("KANIDM_DEBUG")
                 .action(ArgAction::SetTrue),
         )
         .arg(