From 55bd5434340d8688e27e6faee487bb5cc3fcf6b2 Mon Sep 17 00:00:00 2001 From: James Hodgkinson Date: Thu, 26 Oct 2023 11:48:58 +1000 Subject: [PATCH] .deb package build and docs fixes (#2252) * moving docs around a bit * workflow fixes --- .github/workflows/debian_package_kanidm.yml | 8 +- .github/workflows/docker_build_kanidm.yml | 2 +- .github/workflows/docker_build_kanidmd.yml | 2 +- .github/workflows/docker_build_radiusd.yml | 2 +- book/src/SUMMARY.md | 7 +- book/src/integrations/pam_and_nsswitch.md | 343 +----------------- .../integrations/pam_and_nsswitch/fedora.md | 125 +++++++ .../src/integrations/pam_and_nsswitch/suse.md | 66 ++++ .../pam_and_nsswitch/troubleshooting.md | 139 +++++++ 9 files changed, 353 insertions(+), 341 deletions(-) create mode 100644 book/src/integrations/pam_and_nsswitch/fedora.md create mode 100644 book/src/integrations/pam_and_nsswitch/suse.md create mode 100644 book/src/integrations/pam_and_nsswitch/troubleshooting.md diff --git a/.github/workflows/debian_package_kanidm.yml b/.github/workflows/debian_package_kanidm.yml index a70f8a121..6b1a3d672 100644 --- a/.github/workflows/debian_package_kanidm.yml +++ b/.github/workflows/debian_package_kanidm.yml @@ -52,6 +52,10 @@ jobs: path: | target/*.deb upload-to-releases: + permissions: + # https://docs.github.com/en/actions/using-jobs/assigning-permissions-to-jobs + contents: write # allows the action to create a release + name: Upload to releases needs: build-deb-package runs-on: ubuntu-latest @@ -67,7 +71,7 @@ jobs: - uses: "marvinpinto/action-automatic-releases@latest" with: repo_token: "${{ secrets.GITHUB_TOKEN }}" - automatic_release_tag: "latest" + automatic_release_tag: "debs" prerelease: true - title: "Ubuntu Packages" + title: ".deb Packages" files: "*.deb" diff --git a/.github/workflows/docker_build_kanidm.yml b/.github/workflows/docker_build_kanidm.yml index 89a01c4f2..94bff28bb 100644 --- a/.github/workflows/docker_build_kanidm.yml +++ b/.github/workflows/docker_build_kanidm.yml @@ -3,7 +3,7 @@ name: Container - Kanidm # This is always built and uploads an OCI image as a build artifact, but only # pushes to "ghcr.io/kanidm/kanidm:devel" when on "kanidm/kanidm@master". -on: +"on": pull_request: push: diff --git a/.github/workflows/docker_build_kanidmd.yml b/.github/workflows/docker_build_kanidmd.yml index 69e148a70..dd2da1a88 100644 --- a/.github/workflows/docker_build_kanidmd.yml +++ b/.github/workflows/docker_build_kanidmd.yml @@ -3,7 +3,7 @@ name: Container - Kanidmd # This is always built and uploads an OCI image as a build artifact, but only # pushes to "ghcr.io/kanidm/kanidmd:devel" when on "kanidm/kanidm@master". -on: +"on": pull_request: push: diff --git a/.github/workflows/docker_build_radiusd.yml b/.github/workflows/docker_build_radiusd.yml index 6bb7d2593..afa03b747 100644 --- a/.github/workflows/docker_build_radiusd.yml +++ b/.github/workflows/docker_build_radiusd.yml @@ -3,7 +3,7 @@ name: Container - Radiusd # This is always built and uploads an OCI image as a build artifact, but only # pushes to "ghcr.io/kanidm/radius:devel" when on "kanidm/kanidm@master". -on: +"on": pull_request: push: diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index c4118ee05..54baaa702 100644 --- a/book/src/SUMMARY.md +++ b/book/src/SUMMARY.md @@ -33,6 +33,9 @@ - [Service Integrations](integrations/readme.md) - [PAM and nsswitch](integrations/pam_and_nsswitch.md) + - [SUSE / OpenSUSE](integrations/pam_and_nsswitch/suse.md) + - [Fedora](integrations/pam_and_nsswitch/fedora.md) + - [Troubleshooting](integrations/pam_and_nsswitch/troubleshooting.md) - [SSH Key Distribution](integrations/ssh_key_dist.md) - [Oauth2](integrations/oauth2.md) - [LDAP](integrations/ldap.md) @@ -46,13 +49,13 @@ - [FreeIPA](sync/freeipa.md) - [LDAP](sync/ldap.md) -# Support +## Support - [Troubleshooting](troubleshooting.md) - [Frequently Asked Questions](frequently_asked_questions.md) - [Glossary of Technical Terms](glossary.md) -# For Developers +## For Developers - [Developer Guide](DEVELOPER_README.md) - [FAQ](developers/faq.md) diff --git a/book/src/integrations/pam_and_nsswitch.md b/book/src/integrations/pam_and_nsswitch.md index e2f8a22fc..c02281175 100644 --- a/book/src/integrations/pam_and_nsswitch.md +++ b/book/src/integrations/pam_and_nsswitch.md @@ -81,7 +81,7 @@ to `spn`. > system. We recommend that you have a stable ID (like the UUID), and symlinks from the name to the > UUID folder. Automatic support is provided for this via the unixd tasks daemon, as documented > here. - +> > **NOTE:** Ubuntu users please see: > [Why aren't snaps launching with home_alias set?](../frequently_asked_questions.md#why-arent-snaps-launching-with-home_alias-set) @@ -114,13 +114,13 @@ kanidm-unix status If the daemon is working, you should see: -``` +```text working! ``` If it is not working, you will see an error message: -``` +```text [2020-02-14T05:58:10Z ERROR kanidm-unix] Error -> Os { code: 111, kind: ConnectionRefused, message: "Connection refused" } ``` @@ -131,7 +131,7 @@ For more information, see the [Troubleshooting](./pam_and_nsswitch.md#troublesho When the daemon is running you can add the nsswitch libraries to /etc/nsswitch.conf -``` +```text passwd: compat kanidm group: compat kanidm ``` @@ -179,335 +179,10 @@ configuration in a way that will not allow you to authenticate to your machine. cp -a /etc/pam.d /root/pam.d.backup ``` -### SUSE / OpenSUSE +### Configuration Examples -To configure PAM on suse you must modify four files, which control the various stages of -authentication: +Documentation examples for the following Linux distributions are available: -```bash -/etc/pam.d/common-account -/etc/pam.d/common-auth -/etc/pam.d/common-password -/etc/pam.d/common-session -``` - -> **IMPORTANT** By default these files are symlinks to their corresponding `-pc` file, for example -> `common-account -> common-account-pc`. If you directly edit these you are updating the inner -> content of the `-pc` file and it WILL be reset on a future upgrade. To prevent this you must first -> copy the `-pc` files. You can then edit the files safely. - -```bash -cp /etc/pam.d/common-account-pc /etc/pam.d/common-account -cp /etc/pam.d/common-auth-pc /etc/pam.d/common-auth -cp /etc/pam.d/common-password-pc /etc/pam.d/common-password -cp /etc/pam.d/common-session-pc /etc/pam.d/common-session -``` - -The content should look like: - -``` -# /etc/pam.d/common-auth-pc -# Controls authentication to this system (verification of credentials) -auth required pam_env.so -auth [default=1 ignore=ignore success=ok] pam_localuser.so -auth sufficient pam_unix.so nullok try_first_pass -auth requisite pam_succeed_if.so uid >= 1000 quiet_success -auth sufficient pam_kanidm.so ignore_unknown_user -auth required pam_deny.so - -# /etc/pam.d/common-account-pc -# Controls authorisation to this system (who may login) -account [default=1 ignore=ignore success=ok] pam_localuser.so -account sufficient pam_unix.so -account [default=1 ignore=ignore success=ok] pam_succeed_if.so uid >= 1000 quiet_success quiet_fail -account sufficient pam_kanidm.so ignore_unknown_user -account required pam_deny.so - -# /etc/pam.d/common-session-pc -# Controls setup of the user session once a successful authentication and authorisation has -# occurred. -session optional pam_systemd.so -session required pam_limits.so -session optional pam_unix.so try_first_pass -session optional pam_umask.so -session [default=1 ignore=ignore success=ok] pam_succeed_if.so uid >= 1000 quiet_success quiet_fail -session optional pam_kanidm.so -session optional pam_env.so - -# /etc/pam.d/common-password-pc -# Controls flow of what happens when a user invokes the passwd command. Currently does NOT -# interact with kanidm. -password [default=1 ignore=ignore success=ok] pam_localuser.so -password required pam_unix.so use_authtok nullok shadow try_first_pass -password [default=1 ignore=ignore success=ok] pam_succeed_if.so uid >= 1000 quiet_success quiet_fail -password required pam_kanidm.so -``` - -> **WARNING:** Ensure that `pam_mkhomedir` or `pam_oddjobd` are _not_ present in any stage of your -> PAM configuration, as they interfere with the correct operation of the Kanidm tasks daemon. - -### Fedora / CentOS - -> **WARNING:** Kanidm currently has no support for SELinux policy - this may mean you need to run -> the daemon with permissive mode for the `unconfined_service_t` daemon type. To do this run: -> `semanage permissive -a unconfined_service_t`. To undo this run -> `semanage permissive -d unconfined_service_t`. -> -> You may also need to run `audit2allow` for sshd and other types to be able to access the UNIX -> daemon sockets. - -These files are managed by authselect as symlinks. You can either work with authselect, or remove -the symlinks first. - -#### Without authselect - -If you just remove the symlinks: - -Edit the content. - -``` -# /etc/pam.d/password-auth -auth required pam_env.so -auth required pam_faildelay.so delay=2000000 -auth [default=1 ignore=ignore success=ok] pam_usertype.so isregular -auth [default=1 ignore=ignore success=ok] pam_localuser.so -auth sufficient pam_unix.so nullok try_first_pass -auth [default=1 ignore=ignore success=ok] pam_usertype.so isregular -auth sufficient pam_kanidm.so ignore_unknown_user -auth required pam_deny.so - -account sufficient pam_unix.so -account sufficient pam_localuser.so -account sufficient pam_usertype.so issystem -account sufficient pam_kanidm.so ignore_unknown_user -account required pam_permit.so - -password requisite pam_pwquality.so try_first_pass local_users_only -password sufficient pam_unix.so sha512 shadow nullok try_first_pass use_authtok -password sufficient pam_kanidm.so -password required pam_deny.so - -session optional pam_keyinit.so revoke -session required pam_limits.so --session optional pam_systemd.so -session [success=1 default=ignore] pam_succeed_if.so service in crond quiet use_uid -session required pam_unix.so -session optional pam_kanidm.so - -- - -# /etc/pam.d/system-auth -auth required pam_env.so -auth required pam_faildelay.so delay=2000000 -auth sufficient pam_fprintd.so -auth [default=1 ignore=ignore success=ok] pam_usertype.so isregular -auth [default=1 ignore=ignore success=ok] pam_localuser.so -auth sufficient pam_unix.so nullok try_first_pass -auth [default=1 ignore=ignore success=ok] pam_usertype.so isregular -auth sufficient pam_kanidm.so ignore_unknown_user -auth required pam_deny.so - -account sufficient pam_unix.so -account sufficient pam_localuser.so -account sufficient pam_usertype.so issystem -account sufficient pam_kanidm.so ignore_unknown_user -account required pam_permit.so - -password requisite pam_pwquality.so try_first_pass local_users_only -password sufficient pam_unix.so sha512 shadow nullok try_first_pass use_authtok -password sufficient pam_kanidm.so -password required pam_deny.so - -session optional pam_keyinit.so revoke -session required pam_limits.so --session optional pam_systemd.so -session [success=1 default=ignore] pam_succeed_if.so service in crond quiet use_uid -session required pam_unix.so -session optional pam_kanidm.so -``` - -#### With authselect - -To work with authselect: - -You will need to -[create a new profile](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/configuring_authentication_and_authorization_in_rhel/configuring-user-authentication-using-authselect_configuring-authentication-and-authorization-in-rhel#creating-and-deploying-your-own-authselect-profile_configuring-user-authentication-using-authselect). - - - -First run the following command: - -```bash -authselect create-profile kanidm -b sssd -``` - -A new folder, /etc/authselect/custom/kanidm, should be created. Inside that folder, create or -overwrite the following three files: nsswitch.conf, password-auth, system-auth. password-auth and -system-auth should be the same as above. nsswitch should be modified for your use case. A working -example looks like this: - -``` -passwd: compat kanidm sss files systemd -group: compat kanidm sss files systemd -shadow: files -hosts: files dns myhostname -services: sss files -netgroup: sss files -automount: sss files - -aliases: files -ethers: files -gshadow: files -networks: files dns -protocols: files -publickey: files -rpc: files -``` - -Then run: - -```bash -authselect select custom/kanidm -``` - -to update your profile. - -## Troubleshooting - -### Check POSIX-status of Group and Configuration - -If authentication is failing via PAM, make sure that a list of groups is configured in -`/etc/kanidm/unixd`: - -```toml -pam_allowed_login_groups = ["example_group"] -``` - -Check the status of the group with `kanidm group posix show example_group`. If you get something -similar to the following example: - -```bash -> kanidm group posix show example_group -Using cached token for name idm_admin -Error -> Http(500, Some(InvalidAccountState("Missing class: account && posixaccount OR group && posixgroup")), - "b71f137e-39f3-4368-9e58-21d26671ae24") -``` - -POSIX-enable the group with `kanidm group posix set example_group`. You should get a result similar -to this when you search for your group name: - -```bash -> kanidm group posix show example_group -[ spn: example_group@kanidm.example.com, gidnumber: 3443347205 name: example_group, uuid: b71f137e-39f3-4368-9e58-21d26671ae24 ] -``` - -Also, ensure the target user is in the group by running: - -```bash -> kanidm group list_members example_group -``` - -### Increase Logging - -For the unixd daemon, you can increase the logging with: - -```bash -systemctl edit kanidm-unixd.service -``` - -And add the lines: - -``` -[Service] -Environment="RUST_LOG=kanidm=debug" -``` - -Then restart the kanidm-unixd.service. - -The same pattern is true for the kanidm-unixd-tasks.service daemon. - -To debug the pam module interactions add `debug` to the module arguments such as: - -``` -auth sufficient pam_kanidm.so debug -``` - -### Check the Socket Permissions - -Check that the `/var/run/kanidm-unixd/sock` has permissions mode 777, and that non-root readers can -see it with ls or other tools. - -Ensure that `/var/run/kanidm-unixd/task_sock` has permissions mode 700, and that it is owned by the -kanidm unixd process user. - -### Verify that You Can Access the Kanidm Server - -You can check this with the client tools: - -```bash -kanidm self whoami --name anonymous -``` - -### Ensure the Libraries are Correct - -You should have: - -```bash -/usr/lib64/libnss_kanidm.so.2 -/usr/lib64/security/pam_kanidm.so -``` - -The exact path _may_ change depending on your distribution, `pam_unixd.so` should be co-located with -pam_kanidm.so. Look for it with the find command: - -```bash -find /usr/ -name 'pam_unix.so' -``` - -For example, on a Debian machine, it's located in `/usr/lib/x86_64-linux-gnu/security/`. - -### Increase Connection Timeout - -In some high-latency environments, you may need to increase the connection timeout. We set this low -to improve response on LANs, but over the internet this may need to be increased. By increasing the -conn_timeout, you will be able to operate on higher latency links, but some operations may take -longer to complete causing a degree of latency. - -By increasing the cache_timeout, you will need to refresh less often, but it may result in an -account lockout or group change until cache_timeout takes effect. Note that this has security -implications: - -```toml -# /etc/kanidm/unixd -# Seconds -conn_timeout = 8 -# Cache timeout -cache_timeout = 60 -``` - -### Invalidate or Clear the Cache - -You can invalidate the kanidm_unixd cache with: - -```bash -kanidm-unix cache-invalidate -``` - -You can clear (wipe) the cache with: - -```bash -kanidm-unix cache-clear -``` - -There is an important distinction between these two - invalidated cache items may still be yielded -to a client request if the communication to the main Kanidm server is not possible. For example, you -may have your laptop in a park without wifi. - -Clearing the cache, however, completely wipes all local data about all accounts and groups. If you -are relying on this cached (but invalid) data, you may lose access to your accounts until other -communication issues have been resolved. - -### Home directories are not created via SSH - -Ensure that `UsePAM yes` is set in `sshd_config`. Without this the pam session module won't be -triggered which prevents the background task being completed. +* [Fedora](pam_and_nsswitch/fedora.md) +* [SUSE / OpenSUSE](pam_and_nsswitch/suse.md) +* Debian / Ubuntu - when one generates packages [from the repository tools](https://github.com/kanidm/kanidm/tree/master/platform/debian), configuration is modified on install. diff --git a/book/src/integrations/pam_and_nsswitch/fedora.md b/book/src/integrations/pam_and_nsswitch/fedora.md new file mode 100644 index 000000000..c6b4625be --- /dev/null +++ b/book/src/integrations/pam_and_nsswitch/fedora.md @@ -0,0 +1,125 @@ +# Fedora / CentOS + +> **WARNING:** Kanidm currently has no support for SELinux policy - this may mean you need to run +> the daemon with permissive mode for the `unconfined_service_t` daemon type. To do this run: +> `semanage permissive -a unconfined_service_t`. To undo this run +> `semanage permissive -d unconfined_service_t`. +> +> You may also need to run `audit2allow` for sshd and other types to be able to access the UNIX +> daemon sockets. + +These files are managed by authselect as symlinks. You can either work with authselect, or remove +the symlinks first. + +## Without authselect + +If you just remove the symlinks: + +Edit the content. + +```text +# /etc/pam.d/password-auth +auth required pam_env.so +auth required pam_faildelay.so delay=2000000 +auth [default=1 ignore=ignore success=ok] pam_usertype.so isregular +auth [default=1 ignore=ignore success=ok] pam_localuser.so +auth sufficient pam_unix.so nullok try_first_pass +auth [default=1 ignore=ignore success=ok] pam_usertype.so isregular +auth sufficient pam_kanidm.so ignore_unknown_user +auth required pam_deny.so + +account sufficient pam_unix.so +account sufficient pam_localuser.so +account sufficient pam_usertype.so issystem +account sufficient pam_kanidm.so ignore_unknown_user +account required pam_permit.so + +password requisite pam_pwquality.so try_first_pass local_users_only +password sufficient pam_unix.so sha512 shadow nullok try_first_pass use_authtok +password sufficient pam_kanidm.so +password required pam_deny.so + +session optional pam_keyinit.so revoke +session required pam_limits.so +-session optional pam_systemd.so +session [success=1 default=ignore] pam_succeed_if.so service in crond quiet use_uid +session required pam_unix.so +session optional pam_kanidm.so + +- + +# /etc/pam.d/system-auth +auth required pam_env.so +auth required pam_faildelay.so delay=2000000 +auth sufficient pam_fprintd.so +auth [default=1 ignore=ignore success=ok] pam_usertype.so isregular +auth [default=1 ignore=ignore success=ok] pam_localuser.so +auth sufficient pam_unix.so nullok try_first_pass +auth [default=1 ignore=ignore success=ok] pam_usertype.so isregular +auth sufficient pam_kanidm.so ignore_unknown_user +auth required pam_deny.so + +account sufficient pam_unix.so +account sufficient pam_localuser.so +account sufficient pam_usertype.so issystem +account sufficient pam_kanidm.so ignore_unknown_user +account required pam_permit.so + +password requisite pam_pwquality.so try_first_pass local_users_only +password sufficient pam_unix.so sha512 shadow nullok try_first_pass use_authtok +password sufficient pam_kanidm.so +password required pam_deny.so + +session optional pam_keyinit.so revoke +session required pam_limits.so +-session optional pam_systemd.so +session [success=1 default=ignore] pam_succeed_if.so service in crond quiet use_uid +session required pam_unix.so +session optional pam_kanidm.so +``` + +## With authselect + +To work with authselect: + +You will need to +[create a new profile](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/configuring_authentication_and_authorization_in_rhel/configuring-user-authentication-using-authselect_configuring-authentication-and-authorization-in-rhel#creating-and-deploying-your-own-authselect-profile_configuring-user-authentication-using-authselect). + + + +First run the following command: + +```bash +authselect create-profile kanidm -b sssd +``` + +A new folder, /etc/authselect/custom/kanidm, should be created. Inside that folder, create or +overwrite the following three files: nsswitch.conf, password-auth, system-auth. password-auth and +system-auth should be the same as above. nsswitch should be modified for your use case. A working +example looks like this: + +```text +passwd: compat kanidm sss files systemd +group: compat kanidm sss files systemd +shadow: files +hosts: files dns myhostname +services: sss files +netgroup: sss files +automount: sss files + +aliases: files +ethers: files +gshadow: files +networks: files dns +protocols: files +publickey: files +rpc: files +``` + +Then run: + +```bash +authselect select custom/kanidm +``` + +to update your profile. diff --git a/book/src/integrations/pam_and_nsswitch/suse.md b/book/src/integrations/pam_and_nsswitch/suse.md new file mode 100644 index 000000000..b4e720abd --- /dev/null +++ b/book/src/integrations/pam_and_nsswitch/suse.md @@ -0,0 +1,66 @@ +# SUSE / OpenSUSE + +To configure PAM on SUSE you must modify four files, which control the various stages of +authentication: + +```bash +/etc/pam.d/common-account +/etc/pam.d/common-auth +/etc/pam.d/common-password +/etc/pam.d/common-session +``` + +> **IMPORTANT** By default these files are symlinks to their corresponding `-pc` file, for example +> `common-account -> common-account-pc`. If you directly edit these you are updating the inner +> content of the `-pc` file and it WILL be reset on a future upgrade. To prevent this you must first +> copy the `-pc` files. You can then edit the files safely. + +```bash +cp /etc/pam.d/common-account-pc /etc/pam.d/common-account +cp /etc/pam.d/common-auth-pc /etc/pam.d/common-auth +cp /etc/pam.d/common-password-pc /etc/pam.d/common-password +cp /etc/pam.d/common-session-pc /etc/pam.d/common-session +``` + +The content should look like: + +```text +# /etc/pam.d/common-auth-pc +# Controls authentication to this system (verification of credentials) +auth required pam_env.so +auth [default=1 ignore=ignore success=ok] pam_localuser.so +auth sufficient pam_unix.so nullok try_first_pass +auth requisite pam_succeed_if.so uid >= 1000 quiet_success +auth sufficient pam_kanidm.so ignore_unknown_user +auth required pam_deny.so + +# /etc/pam.d/common-account-pc +# Controls authorisation to this system (who may login) +account [default=1 ignore=ignore success=ok] pam_localuser.so +account sufficient pam_unix.so +account [default=1 ignore=ignore success=ok] pam_succeed_if.so uid >= 1000 quiet_success quiet_fail +account sufficient pam_kanidm.so ignore_unknown_user +account required pam_deny.so + +# /etc/pam.d/common-session-pc +# Controls setup of the user session once a successful authentication and authorisation has +# occurred. +session optional pam_systemd.so +session required pam_limits.so +session optional pam_unix.so try_first_pass +session optional pam_umask.so +session [default=1 ignore=ignore success=ok] pam_succeed_if.so uid >= 1000 quiet_success quiet_fail +session optional pam_kanidm.so +session optional pam_env.so + +# /etc/pam.d/common-password-pc +# Controls flow of what happens when a user invokes the passwd command. Currently does NOT +# interact with kanidm. +password [default=1 ignore=ignore success=ok] pam_localuser.so +password required pam_unix.so use_authtok nullok shadow try_first_pass +password [default=1 ignore=ignore success=ok] pam_succeed_if.so uid >= 1000 quiet_success quiet_fail +password required pam_kanidm.so +``` + +> **WARNING:** Ensure that `pam_mkhomedir` or `pam_oddjobd` are _not_ present in any stage of your +> PAM configuration, as they interfere with the correct operation of the Kanidm tasks daemon. diff --git a/book/src/integrations/pam_and_nsswitch/troubleshooting.md b/book/src/integrations/pam_and_nsswitch/troubleshooting.md new file mode 100644 index 000000000..b42434b79 --- /dev/null +++ b/book/src/integrations/pam_and_nsswitch/troubleshooting.md @@ -0,0 +1,139 @@ +# Troubleshooting PAM/nsswitch + +## Check POSIX-status of Group and Configuration + +If authentication is failing via PAM, make sure that a list of groups is configured in +`/etc/kanidm/unixd`: + +```toml +pam_allowed_login_groups = ["example_group"] +``` + +Check the status of the group with `kanidm group posix show example_group`. If you get something +similar to the following example: + +```bash +> kanidm group posix show example_group +Using cached token for name idm_admin +Error -> Http(500, Some(InvalidAccountState("Missing class: account && posixaccount OR group && posixgroup")), + "b71f137e-39f3-4368-9e58-21d26671ae24") +``` + +POSIX-enable the group with `kanidm group posix set example_group`. You should get a result similar +to this when you search for your group name: + +```bash +> kanidm group posix show example_group +[ spn: example_group@kanidm.example.com, gidnumber: 3443347205 name: example_group, uuid: b71f137e-39f3-4368-9e58-21d26671ae24 ] +``` + +Also, ensure the target user is in the group by running: + +```bash +> kanidm group list_members example_group +``` + +## Increase Logging + +For the unixd daemon, you can increase the logging with: + +```bash +systemctl edit kanidm-unixd.service +``` + +And add the lines: + +```ini +[Service] +Environment="RUST_LOG=kanidm=debug" +``` + +Then restart the kanidm-unixd.service. + +The same pattern is true for the kanidm-unixd-tasks.service daemon. + +To debug the pam module interactions add `debug` to the module arguments such as: + +```text +auth sufficient pam_kanidm.so debug +``` + +## Check the Socket Permissions + +Check that the `/var/run/kanidm-unixd/sock` has permissions mode 777, and that non-root readers can +see it with ls or other tools. + +Ensure that `/var/run/kanidm-unixd/task_sock` has permissions mode 700, and that it is owned by the +kanidm unixd process user. + +## Verify that You Can Access the Kanidm Server + +You can check this with the client tools: + +```bash +kanidm self whoami --name anonymous +``` + +## Ensure the Libraries are Correct + +You should have: + +```bash +/usr/lib64/libnss_kanidm.so.2 +/usr/lib64/security/pam_kanidm.so +``` + +The exact path _may_ change depending on your distribution, `pam_unixd.so` should be co-located with +pam_kanidm.so. Look for it with the find command: + +```bash +find /usr/ -name 'pam_unix.so' +``` + +For example, on a Debian machine, it's located in `/usr/lib/x86_64-linux-gnu/security/`. + +## Increase Connection Timeout + +In some high-latency environments, you may need to increase the connection timeout. We set this low +to improve response on LANs, but over the internet this may need to be increased. By increasing the +conn_timeout, you will be able to operate on higher latency links, but some operations may take +longer to complete causing a degree of latency. + +By increasing the cache_timeout, you will need to refresh less often, but it may result in an +account lockout or group change until cache_timeout takes effect. Note that this has security +implications: + +```toml +# /etc/kanidm/unixd +# Seconds +conn_timeout = 8 +# Cache timeout +cache_timeout = 60 +``` + +## Invalidate or Clear the Cache + +You can invalidate the kanidm_unixd cache with: + +```bash +kanidm-unix cache-invalidate +``` + +You can clear (wipe) the cache with: + +```bash +kanidm-unix cache-clear +``` + +There is an important distinction between these two - invalidated cache items may still be yielded +to a client request if the communication to the main Kanidm server is not possible. For example, you +may have your laptop in a park without wifi. + +Clearing the cache, however, completely wipes all local data about all accounts and groups. If you +are relying on this cached (but invalid) data, you may lose access to your accounts until other +communication issues have been resolved. + +## Home directories are not created via SSH + +Ensure that `UsePAM yes` is set in `sshd_config`. Without this the pam session module won't be +triggered which prevents the background task being completed.