From d512954fe6394b39637bc496b6abe1fc1996051b Mon Sep 17 00:00:00 2001 From: James Hodgkinson Date: Sun, 4 Aug 2024 17:27:45 -0700 Subject: [PATCH] Docker-and-docs-fixes (#2954) * removing VOLUME entry from server container * link fixing * link fixing in docs --- book/book.toml | 8 +++----- book/src/SUMMARY.md | 2 +- book/src/accounts/anonymous_account.md | 2 +- book/src/accounts/intro.md | 2 +- book/src/developers/readme.md | 4 ++-- book/src/evaluation_quickstart.md | 8 +++++--- book/src/examples/kubernetes_ingress.md | 24 ++++++++++++++--------- book/src/installing_client_tools.md | 2 +- book/src/integrations/ldap.md | 2 +- book/src/integrations/pam_and_nsswitch.md | 4 ++-- book/src/integrations/sssd.md | 4 ++-- book/src/server_configuration.md | 2 +- book/src/server_updates.md | 2 +- server/Dockerfile | 3 ++- server/lib/src/idm/server.rs | 6 +++--- server/lib/src/server/mod.rs | 2 +- 16 files changed, 42 insertions(+), 35 deletions(-) diff --git a/book/book.toml b/book/book.toml index 81c62eee9..a9d4bf43f 100644 --- a/book/book.toml +++ b/book/book.toml @@ -1,9 +1,5 @@ [book] -authors = [ - "William Brown", - "James Hodgkinson", - "Carla Schroder", -] +authors = ["William Brown", "James Hodgkinson", "Carla Schroder"] language = "en" multilingual = false src = "src" @@ -16,7 +12,9 @@ git-repository-icon = "fa-github" additional-css = ["theme.css"] additional-js = ["mermaid.min.js", "mermaid-init.js"] +# Github-flavoured markdown alerts, install mdbook-alerts [preprocessor.alerts] +# mermaid graph rendering, you need mdbook-mermaid [preprocessor.mermaid] command = "mdbook-mermaid" diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index 746989b93..bd3217826 100644 --- a/book/src/SUMMARY.md +++ b/book/src/SUMMARY.md @@ -71,7 +71,7 @@ # For Developers -- [Developer Guide](developers/readme.md) +- [Developer Guide](./developers/readme.md) - [Developer Ethics](developers/developer_ethics.md) - [Frequently Asked Questions](developers/faq.md) - [Design Documents]() diff --git a/book/src/accounts/anonymous_account.md b/book/src/accounts/anonymous_account.md index 0e7f5a35d..10240d97d 100644 --- a/book/src/accounts/anonymous_account.md +++ b/book/src/accounts/anonymous_account.md @@ -45,6 +45,6 @@ data. ## Disabling the Anonymous Account The anonymous is like any other and can be expired to prevent its use. See the -[account validity section](./people#account-validity) +[account validity section](./people_accounts.md#account-validity) When disabled, this will prevent stateless unix clients from authenticating to Kanidm. diff --git a/book/src/accounts/intro.md b/book/src/accounts/intro.md index 7dfaf8d82..9cae390db 100644 --- a/book/src/accounts/intro.md +++ b/book/src/accounts/intro.md @@ -70,7 +70,7 @@ By default the `admin` and `idm_admin` accounts have no password, and can not be to be "recovered" from the server that is running the kanidmd server. You should have already recovered the admin account during your setup process. If not, refer to the -[server configuration chapter](server_configuration.md#default-admin-account) on how to recover +[server configuration chapter](../server_configuration.md#default-admin-account) on how to recover these accounts. These accounts will be used through the remainder of this document for managing the server. diff --git a/book/src/developers/readme.md b/book/src/developers/readme.md index 989b34966..754565814 100644 --- a/book/src/developers/readme.md +++ b/book/src/developers/readme.md @@ -84,7 +84,7 @@ deployment, will aim to provide a positive experience to all people. It's important before you start trying to write code and contribute that you understand what Kanidm does and its goals. -An important first step is to [install the server](installing_the_server.md) so if you have not done +An important first step is to [install the server](../installing_the_server.md) so if you have not done that yet, go and try that now! 😄 ## Setting up your Machine @@ -390,7 +390,7 @@ cargo run --bin kanidm -- self whoami -H https://localhost:8443 -D admin -C /tmp ``` You may find it easier to modify `~/.config/kanidm` per the -[book client tools section](client_tools.md) for extended administration locally. +[book client tools section](../client_tools.md) for extended administration locally. ### Raw actions diff --git a/book/src/evaluation_quickstart.md b/book/src/evaluation_quickstart.md index 559987d81..e34bb6297 100644 --- a/book/src/evaluation_quickstart.md +++ b/book/src/evaluation_quickstart.md @@ -25,6 +25,8 @@ Create `server.toml`. The important parts are the `domain` and `origin`. For thi ## Start the container +First we create a docker volume to store the data, then we start the container. + ```bash docker volume create kanidmd docker create --name kanidmd \ @@ -107,6 +109,6 @@ You'll probably want to set it up properly, so that other computers can access i Alternatively you might like to try configurig one of these: -- [OAuth2](integrations/oauth2.md) for web services -- [PAM and nsswitch](integrations/pam_and_nsswitch.md) for authentication to Linux systems -- [Replication](repl/readme.md), if one Kanidm instance isn't enough +- [OAuth2](./integrations/oauth2.md) for web services +- [PAM and nsswitch](./integrations/pam_and_nsswitch.md) for authentication to Linux systems +- [Replication](repl/), if one Kanidm instance isn't enough diff --git a/book/src/examples/kubernetes_ingress.md b/book/src/examples/kubernetes_ingress.md index 35bfe6dd1..21a0d8004 100644 --- a/book/src/examples/kubernetes_ingress.md +++ b/book/src/examples/kubernetes_ingress.md @@ -6,7 +6,7 @@ Guard your Kubernetes ingress with Kanidm authentication and authorization. We recommend you have the following before continuing: -- [Kanidm](../installing_the_server.html) +- [Kanidm](../installing_the_server.md) - [Kubernetes v1.23 or above](https://docs.k0sproject.io/v1.23.6+k0s.2/install/) - [Nginx Ingress](https://kubernetes.github.io/ingress-nginx/deploy/) - A fully qualified domain name with an A record pointing to your k8s ingress. @@ -16,14 +16,13 @@ We recommend you have the following before continuing: 1. Create a Kanidm account and group: 1. Create a Kanidm account. Please see the section - [Creating Accounts](../accounts_and_groups.md). - 1. Give the account a password. Please see the section - [Resetting Account Credentials](../accounts_and_groups.md). - 1. Make the account a person. Please see the section - [People Accounts](../accounts_and_groups.md). - 1. Create a Kanidm group. Please see the section [Creating Accounts](../accounts_and_groups.md). - 1. Add the account you created to the group you create. Please see the section - [Creating Accounts](../accounts_and_groups.md). + [Creating Accounts](../accounts/intro.md). + 2. Give the account a password. Please see the section + [Resetting Account Credentials](../accounts/authentication_and_credentials.md). + 3. Make the account a person. Please see the section + [People Accounts](../accounts/people_accounts.md). + 4. Create a Kanidm group. Please see the section [Creating Accounts](../accounts/groups.md). + 5. Add the account you created to the group you create. 2. Create a Kanidm OAuth2 resource: 1. Create the OAuth2 resource for your domain. Please see the section [Create the Kanidm Configuration](../integrations/oauth2.md). @@ -31,9 +30,11 @@ We recommend you have the following before continuing: profile, and email scopes. Please see the section [Create the Kanidm Configuration](../integrations/oauth2.md). 3. Create a `Cookie Secret` to for the placeholder `` in step 4: + ```shell docker run -ti --rm python:3-alpine python -c 'import secrets,base64; print(base64.b64encode(base64.b64encode(secrets.token_bytes(16))).decode("utf-8"));' ``` + 4. Create a file called `k8s.kanidm-nginx-auth-example.yaml` with the block below. Replace every `` (drop the `<>`) with appropriate values: 1. ``: The fully qualified domain name with an A record pointing to your k8s ingress. @@ -223,11 +224,15 @@ We recommend you have the following before continuing: - secretName: -ingress-tls # replace . with - in the hostname ``` + 5. Apply the configuration by running the following command: + ```bash kubectl apply -f k8s.kanidm-nginx-auth-example.yaml ``` + 6. Check your deployment succeeded by running the following commands: + ```bash kubectl -n kanidm-example get all kubectl -n kanidm-example get ingress @@ -246,6 +251,7 @@ We recommend you have the following before continuing: ## Cleaning Up 1. Remove the resources create for this example from k8s: + ```bash kubectl delete namespace kanidm-example ``` diff --git a/book/src/installing_client_tools.md b/book/src/installing_client_tools.md index bc944df14..cb5edbb73 100644 --- a/book/src/installing_client_tools.md +++ b/book/src/installing_client_tools.md @@ -127,7 +127,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. You will likely need to install -additional development libraries, specified in the [Developer Guide](developers/readme.md). +additional development libraries, specified in the [Developer Guide](developers/). ```bash cargo install kanidm_tools diff --git a/book/src/integrations/ldap.md b/book/src/integrations/ldap.md index bfd9876ed..efff7f502 100644 --- a/book/src/integrations/ldap.md +++ b/book/src/integrations/ldap.md @@ -136,7 +136,7 @@ should not grant the same privileges as the accounts standard credentials. ## Service Accounts If you have -[issued api tokens for a service account](../accounts_and_groups.html#using-api-tokens-with-service-accounts) +[issued api tokens for a service account](../accounts/service_accounts.md#using-api-tokens-with-service-accounts) they can be used to gain extended read permissions for those service accounts. Api tokens can also be used to gain extended search permissions with LDAP. To do this you can bind diff --git a/book/src/integrations/pam_and_nsswitch.md b/book/src/integrations/pam_and_nsswitch.md index aa7621210..06a9b938d 100644 --- a/book/src/integrations/pam_and_nsswitch.md +++ b/book/src/integrations/pam_and_nsswitch.md @@ -91,8 +91,8 @@ passwd: compat kanidm group: compat kanidm ``` -You can [create a user](../accounts_and_groups.md#creating-accounts) then -[enable POSIX feature on the user](../posix_accounts.md#enabling-posix-attributes-on-accounts). +You can [create a user](../accounts/intro.md) then +[enable POSIX feature on the user](../accounts/posix_accounts_and_groups.md#enabling-posix-attributes-on-accounts). You can then test that the POSIX extended user is able to be resolved with: diff --git a/book/src/integrations/sssd.md b/book/src/integrations/sssd.md index ee80f4264..397deaccc 100644 --- a/book/src/integrations/sssd.md +++ b/book/src/integrations/sssd.md @@ -1,6 +1,6 @@ # SSSD -[SSSD](https://sssd.io/) is an alternative [PAM and nsswitch](./pam_and_nsswitch) provider that is +[SSSD](https://sssd.io/) is an alternative [PAM and nsswitch](./pam_and_nsswitch.md) provider that is commonly available on Linux. > [!WARNING] @@ -11,7 +11,7 @@ commonly available on Linux. ## Limitations SSSD has many significant limitations compared to Kanidm's native -[PAM and nsswitch](./pam_and_nsswitch) provider. +[PAM and nsswitch](./pam_and_nsswitch.md) provider. ### Performance diff --git a/book/src/server_configuration.md b/book/src/server_configuration.md index f8f5359b1..2905aa4db 100644 --- a/book/src/server_configuration.md +++ b/book/src/server_configuration.md @@ -38,7 +38,7 @@ This example is located in ### Check the configuration is valid You should test your configuration is valid before you proceed. This defaults to using -`-c /data/server.toml`. +`-c /data/server.toml`. The `kanidmd` volume was created in the [evaluation quickstart](evaluation_quickstart.md) ```bash docker run --rm -i -t -v kanidmd:/data \ diff --git a/book/src/server_updates.md b/book/src/server_updates.md index ac614883a..f0811ba23 100644 --- a/book/src/server_updates.md +++ b/book/src/server_updates.md @@ -74,7 +74,7 @@ docker pull kanidm/tools:latest ### Perform a backup -See [backup and restore](backup_restore.md) +See [backup and restore](backup_and_restore.md) ### Update your Instance diff --git a/server/Dockerfile b/server/Dockerfile index 5d996a1e3..ae61225bc 100644 --- a/server/Dockerfile +++ b/server/Dockerfile @@ -76,8 +76,9 @@ COPY --from=builder /usr/src/kanidm/server/web_ui/pkg /pkg COPY --from=builder /usr/src/kanidm/server/core/static /hpkg RUN chmod +x /sbin/kanidmd +WORKDIR /data + EXPOSE 8443 3636 -VOLUME /data ENV RUST_BACKTRACE 1 diff --git a/server/lib/src/idm/server.rs b/server/lib/src/idm/server.rs index 2aa992097..73b516e44 100644 --- a/server/lib/src/idm/server.rs +++ b/server/lib/src/idm/server.rs @@ -173,9 +173,9 @@ impl IdmServer { if valid { Ok(url) } else { - admin_error!("Effective domain is not a descendent of server domain name (rp_id)."); - admin_error!("You must change origin or domain name to be consistent. ed: {:?} - rp_id: {:?}", origin, rp_id); - admin_error!("To change the origin or domain name see: https://kanidm.github.io/kanidm/server_configuration.html"); + admin_error!("Effective domain (ed) is not a descendent of server domain name (rp_id)."); + admin_error!("You must change origin or domain name to be consistent. ded: {:?} - rp_id: {:?}", origin, rp_id); + admin_error!("To change the origin or domain name see: https://kanidm.github.io/kanidm/master/server_configuration.html"); Err(OperationError::InvalidState) } })?; diff --git a/server/lib/src/server/mod.rs b/server/lib/src/server/mod.rs index 4d55e6949..423da840e 100644 --- a/server/lib/src/server/mod.rs +++ b/server/lib/src/server/mod.rs @@ -2000,7 +2000,7 @@ impl<'a> QueryServerWriteTransaction<'a> { mut_d_info.d_name, ); admin_warn!( - "If you think this is an error, see https://kanidm.github.io/kanidm/stable/administrivia.html#rename-the-domain" + "If you think this is an error, see https://kanidm.github.io/kanidm/master/domain_rename.html" ); mut_d_info.d_name = domain_name; }