From e0ebd322dd31e6a3f3dba4e8144986247317ef8f Mon Sep 17 00:00:00 2001 From: Carla Schroder Date: Wed, 25 May 2022 21:57:01 -0700 Subject: [PATCH] some small corrections to accounts_and_groups.md, administrivia.md (#776) --- kanidm_book/src/accounts_and_groups.md | 40 ++++++++++++++------------ kanidm_book/src/administrivia.md | 26 ++++++++++------- 2 files changed, 37 insertions(+), 29 deletions(-) diff --git a/kanidm_book/src/accounts_and_groups.md b/kanidm_book/src/accounts_and_groups.md index 4568d56b8..14812442f 100644 --- a/kanidm_book/src/accounts_and_groups.md +++ b/kanidm_book/src/accounts_and_groups.md @@ -1,20 +1,22 @@ # Accounts and groups -Accounts and Groups are the primary reason for Kanidm to exist. Kanidm is optimised as a repository -for these data. As a result, they have many concepts and important details to understand. +Accounts and Groups are the primary reasons for Kanidm to exist. Kanidm is optimised as a repository +for these data. As a result, there are many concepts and important details to understand. ## Default Accounts and Groups -Kanidm ships with a number of default accounts and groups. This is to give you the best out of -box experience possible, as well as supplying best practice examples related to modern IDM -systems. +Kanidm ships with a number of default accounts and groups. This is to give you the best +out-of-box experience possible, as well as supplying best practice examples related to modern +Identity Management (IDM) systems. -The system admin account (the account you recovered in the setup) has limited privileges - only to -manage high-privilege accounts and services. This is to help separate system administration -from identity administration actions. An idm_admin is also provided that is only for management +The system administrator account has limited privileges (see +[Recovering the Initial idm_admin Account](#recovering-the-initial-idm_admin-account)) to learn +how to access the inbuilt admin account). +It manages only high-privilege accounts and services. This is to help separate system administration +from identity administration actions. An idm_admin user is also provided that is only for management of accounts and groups. -Both admin and idm_admin should *NOT* be used for daily activities - they exist for initial +Both the admin and the idm_admin user should *NOT* be used for daily activities - they exist for initial system configuration, and for disaster recovery scenarios. You should delegate permissions as required to named user accounts instead. @@ -24,7 +26,7 @@ and sensitive data), group management, and more. ## Recovering the Initial idm_admin Account -By default the idm_admin has no password, and can not be accessed. You should recover it with the +By default the idm_admin user has no password, and can not be accessed. You should recover it with the admin (system admin) account. We recommend the use of "reset_credential" as it provides a high strength, random, machine only password. @@ -33,7 +35,7 @@ strength, random, machine only password. ## Creating Accounts -We can now use the idm_admin to create initial groups and accounts. +You can now use the idm_admin user to create initial groups and accounts. kanidm group create demo_group --name idm_admin kanidm account create demo_user "Demonstration User" --name idm_admin @@ -42,7 +44,7 @@ We can now use the idm_admin to create initial groups and accounts. kanidm account get demo_user --name idm_admin You can also use anonymous to view users and groups - note that you won't see as many fields due -to the different anonymous access profile limits! +to the different anonymous access profile limits. kanidm account get demo_user --name anonymous @@ -56,10 +58,10 @@ default permissions. These can be viewed with: ## Resetting Account Credentials -Members of the `idm_account_manage_priv` group have the rights to manage other users +Members of the `idm_account_manage_priv` group have the rights to manage other users' accounts security and login aspects. This includes resetting account credentials. -We can perform a password reset on the demo_user for example as idm_admin, who is +You can perform a password reset on the demo_user, for example as the idm_admin user, who is a default member of this group. kanidm account credential set_password demo_user --name idm_admin @@ -70,7 +72,7 @@ a default member of this group. Kanidm supports groups being members of groups, allowing nested groups. These nesting relationships are shown through the "memberof" attribute on groups and accounts. -Kanidm makes all group-membership determinations by inspecting an entries "memberof" attribute. +Kanidm makes all group membership determinations by inspecting an entry's "memberof" attribute. An example can be easily shown with: @@ -83,7 +85,7 @@ An example can be easily shown with: ## Account Validity -Kanidm supports accounts that are only able to be authenticated between specific datetime +Kanidm supports accounts that are only able to be authenticated between specific date and time windows. This takes the form of a "valid from" attribute that defines the earliest start date where authentication can succeed, and an expiry date where the account will no longer allow authentication. @@ -110,7 +112,7 @@ To unset or remove these values the following can be used: kanidm account validity begin_from demo_user any|clear --name idm_admin kanidm account validity expire_at demo_user never|clear --name idm_admin -To "lock" an account, you can set the expire_at value to the past or unix epoch. Even in the situation +To "lock" an account, you can set the expire_at value to the past, or unix epoch. Even in the situation where the "valid from" is *after* the expire_at, the expire_at will be respected. kanidm account validity expire_at demo_user 1970-01-01T00:00:00+00:00 --name idm_admin @@ -165,7 +167,7 @@ Generally, membership of a "privilege" group that ships with Kanidm, such as: * idm_schema_manage_priv * many more ... -Indirectly grants you membership to "idm_high_privilege". If you are a member of +...indirectly grants you membership to "idm_high_privilege". If you are a member of this group, the standard "account" and "people" rights groups are NOT able to alter, read or manage these accounts. To manage these accounts higher rights are required, such as those held by the admin account are required. @@ -187,4 +189,4 @@ system administration rights in the directory, and by extension, over all networ resources that trust Kanidm. All groups that are flagged as "idm_high_privilege" should be audited and -monitored to ensure that they are not altered. +monitored to ensure that they are not altered. \ No newline at end of file diff --git a/kanidm_book/src/administrivia.md b/kanidm_book/src/administrivia.md index 4ada08d23..5e3270684 100644 --- a/kanidm_book/src/administrivia.md +++ b/kanidm_book/src/administrivia.md @@ -1,13 +1,17 @@ # Administration Tasks -There are a number of tasks that you may wish to perform as an administrator of a service like Kanidm. +This chapter describes some of the routine administration tasks for running +a Kanidm server, such as making backups and restoring from backups, testing +server configuration, reindexing, verifying data consistency, and renaming +your domain. # Backup and Restore -With any idm software, it's important you have the capability to restore in case of a disaster - be -that physical damage or mistake. Kanidm supports backup and restore of the database with two methods. +With any Identity Management (IDM) software, it's important you have the capability to restore in +case of a disaster - be that physical damage or a mistake. Kanidm supports backup +and restore of the database with three methods. -## Method 1 +## Method 1 (Preferred) Method 1 involves taking a backup of the database entry content, which is then re-indexed on restore. This is the preferred method. @@ -46,7 +50,8 @@ This is a simple backup of the data volume. Automatic backups can be generated online by a `kanidmd server` instance by including the `[online_backup]` section in the `server.toml`. This allows you to run regular backups, defined by a cron schedule, and maintain -the number of backup versions to keep. An example is located in [examples/server.toml](../../examples/server.toml). +the number of backup versions to keep. An example is located in +[examples/server.toml](https://github.com/kanidm/kanidm/blob/master/examples/server.toml). # Configuration Test @@ -69,7 +74,8 @@ Please note the server will sometimes reindex on startup as a result of the proj changing its internal schema definitions. This is normal and expected - you may never need to start a reindex yourself as a result! -You'll likely notice a need to reindex if you add indexes to schema and you see a message in your logs such as: +You'll likely notice a need to reindex if you add indexes to schema and you see a message in +your logs such as: Index EQUALITY name not found Index {type} {attribute} not found @@ -97,7 +103,7 @@ queries more efficient . It is recommended that you vacuum after a reindex is pe when you wish to reclaim space in the database file. Vacuum is also able to change the pagesize of the database. After changing `db_fs_type` (which affects -pagesize) in server.toml, you must run a vacuum for this to take effect. +pagesize) in server.toml, you must run a vacuum for this to take effect: docker stop docker run --rm -i -t -v kanidmd:/data \ @@ -133,10 +139,10 @@ name, merging, or other needs which may prompt this needing to be changed. > the domain name unless REQUIRED and have a plan on how to manage these issues. > **WARNING:** This operation can take an extensive amount of time as ALL accounts and groups -> in the domain MUST have their SPN's regenerated. This WILL also cause a large delay in -> replication once the system is restarted. +> in the domain MUST have their Security Principal Names (SPNs) regenerated. This WILL also cause +> a large delay in replication once the system is restarted. -You should take a backup before proceeding with this operation. +You should make a backup before proceeding with this operation. When you have a created a migration plan and strategy on handling the invalidation of webauthn, you can then rename the domain.