From 14d42e26c2050c1941874e83761fae69585ddc27 Mon Sep 17 00:00:00 2001 From: Jakub Hrozek Date: Wed, 8 Mar 2017 17:46:09 +0100 Subject: [PATCH 27/36] MAN: Add a manual page for sssd-kcm MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Reviewed-by: Michal Židek Reviewed-by: Simo Sorce --- contrib/sssd.spec.in | 1 + src/man/Makefile.am | 9 ++- src/man/po/po4a.cfg | 1 + src/man/sssd-kcm.8.xml | 193 +++++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 203 insertions(+), 1 deletion(-) create mode 100644 src/man/sssd-kcm.8.xml diff --git a/contrib/sssd.spec.in b/contrib/sssd.spec.in index 52d33b4de281dc1d91a9027ac1c8c878e66fb396..1d4d020415ee28292bb4d88c78de205465d812f1 100644 --- a/contrib/sssd.spec.in +++ b/contrib/sssd.spec.in @@ -1206,6 +1206,7 @@ done %config(noreplace) %{_sysconfdir}/krb5.conf.d/kcm_default_ccache %{_unitdir}/sssd-kcm.socket %{_unitdir}/sssd-kcm.service +%{_mandir}/man8/sssd-kcm.8* %endif %pre common diff --git a/src/man/Makefile.am b/src/man/Makefile.am index 142d6e2743f814294e3d92c8342070b8230bb3e5..3a063614f085691652db32d76315375466e0d3de 100644 --- a/src/man/Makefile.am +++ b/src/man/Makefile.am @@ -27,6 +27,9 @@ endif if BUILD_SECRETS SEC_CONDS = ;with_secrets endif +if BUILD_SECRETS +KCM_CONDS = ;with_kcm +endif if GPO_DEFAULT_ENFORCING GPO_CONDS = ;gpo_default_enforcing else @@ -40,7 +43,7 @@ FILES_CONDS = ;enable_files_domain else FILES_CONDS = ;no_enable_files_domain endif -CONDS = with_false$(SUDO_CONDS)$(AUTOFS_CONDS)$(SSH_CONDS)$(PAC_RESPONDER_CONDS)$(IFP_CONDS)$(GPO_CONDS)$(SEC_CONDS)$(SYSTEMD_CONDS)$(FILES_CONDS) +CONDS = with_false$(SUDO_CONDS)$(AUTOFS_CONDS)$(SSH_CONDS)$(PAC_RESPONDER_CONDS)$(IFP_CONDS)$(GPO_CONDS)$(SEC_CONDS)$(SYSTEMD_CONDS)$(FILES_CONDS)$(KCM_CONDS) #Special Rules: @@ -85,6 +88,10 @@ if BUILD_SECRETS man_MANS += sssd-secrets.5 endif +if BUILD_KCM +man_MANS += sssd-kcm.8 +endif + if BUILD_NFS_IDMAP man_MANS += sss_rpcidmapd.5 endif diff --git a/src/man/po/po4a.cfg b/src/man/po/po4a.cfg index d1f6ac39f841c61ae3d2393fb3402dc21b9cbd69..a02f97e777fa76615e4d5cbcfc788956706d8cd0 100644 --- a/src/man/po/po4a.cfg +++ b/src/man/po/po4a.cfg @@ -31,6 +31,7 @@ [type:docbook] sssctl.8.xml $lang:$(builddir)/$lang/sssctl.8.xml [type:docbook] sssd-files.5.xml $lang:$(builddir)/$lang/sssd-files.5.xml [type:docbook] sssd-secrets.5.xml $lang:$(builddir)/$lang/sssd-secrets.5.xml +[type:docbook] sssd-kcm.8.xml $lang:$(builddir)/$lang/sssd-kcm.8.xml [type:docbook] include/service_discovery.xml $lang:$(builddir)/$lang/include/service_discovery.xml opt:"-k 0" [type:docbook] include/upstream.xml $lang:$(builddir)/$lang/include/upstream.xml opt:"-k 0" [type:docbook] include/failover.xml $lang:$(builddir)/$lang/include/failover.xml opt:"-k 0" diff --git a/src/man/sssd-kcm.8.xml b/src/man/sssd-kcm.8.xml new file mode 100644 index 0000000000000000000000000000000000000000..5dc93838e48723bdb470c0a9c8575bd17c7593e8 --- /dev/null +++ b/src/man/sssd-kcm.8.xml @@ -0,0 +1,193 @@ + + + +SSSD Manual pages + + + + + sssd-kcm + 8 + File Formats and Conventions + + + + sssd-kcm + SSSD Kerberos Cache Manager + + + + DESCRIPTION + + This manual page describes the configuration of the SSSD Kerberos + Cache Manager (KCM). KCM is a process that stores, tracks and + manages Kerberos credential caches. It originates in the Heimdal + Kerberos project, although the MIT Kerberos library also provides + client side (more details on that below) support for the KCM + credential cache. + + + In a setup where Kerberos caches are managed by KCM, the + Kerberos library (typically used through an application, like + e.g., + + kinit1 + , + is a "KCM client" and the KCM daemon + is being referred to as a "KCM server". The client + and server communicate over a UNIX socket. + + + The KCM server keeps track of each credential caches's owner and + performs access check control based on the UID and GID of the + KCM client. The root user has access to all credential caches. + + + The KCM credential cache has several interesting properties: + + + + since the process runs in userspace, it is subject to UID namespacing, ulike the kernel keyring + + + + + unlike the kernel keyring-based cache, which is shared between all containers, the KCM server is a separate process whose entry point is a UNIX socket + + + + + the SSSD implementation stores the ccaches in the SSSD + + sssd-secrets5 + + secrets store, allowing the ccaches to survive KCM server restarts or machine reboots. + + + + This allows the system to use a collection-aware credential + cache, yet share the credential cache between some or no + containers by bind-mounting the socket. + + + + + USING THE KCM CREDENTIAL CACHE + + In order to use KCM credential cache, it must be selected as the default + credential type in + + krb5.conf5 + , + The credentials cache name must be only KCM: + without any template expansions. For example: + +[libdefaults] + default_ccache_name = KCM: + + + + Next, make sure the Kerberos client libraries and the KCM server must agree + on the UNIX socket path. By default, both use the same path + /var/run/.heim_org.h5l.kcm-socket. To configure + the Kerberos library, change its kcm_socket option which + is described in the + + krb5.conf5 + + manual page. + + + Finally, make sure the SSSD KCM server can be contacted. + The KCM service is typically socket-activated by + + systemd + 1 + . + Unlike + other SSSD services, it cannot be started by adding the + kcm string to the service + directive. + +systemctl start sssd-kcm.socket +systemctl enable sssd-kcm.socket +systemctl enable sssd-kcm.service + + Please note your distribution may already configure the units + for you. + + + + + THE CREDENTIAL CACHE STORAGE + + The credential caches are stored in the SSSD secrets service (see + + sssd-secrets5 + + for more details). Therefore it is important that also the sssd-secrets + service is enabled and its socket is started: + +systemctl start sssd-secrets.socket +systemctl enable sssd-secrets.socket +systemctl enable sssd-secrets.service + + Your distribution should already set the dependencies between the services. + + + + + CONFIGURATION OPTIONS + + The KCM service is configured in the kcm + section of the sssd.conf file. Please note that currently, + is it not sufficient to restart the sssd-kcm service, because + the sssd configuration is only parsed and read to an internal + configuration database by the sssd service. Therefore you + must restart the sssd service if you change anything in the + kcm section of sssd.conf. + For a detailed syntax reference, refer to the FILE FORMAT section of the + + sssd.conf + 5 + manual page. + + + The generic SSSD service options such as + debug_level or fd_limit are + accepted by the kcm service. Please refer to the + + sssd.conf + 5 + manual page for a complete list. In addition, + there are some KCM-specific options as well. + + + + socket_path (string) + + + The socket the KCM service will listen on. + + + Default: /var/run/.heim_org.h5l.kcm-socket + + + + + + + + SEE ALSO + + + sssd8 + , + + sssd.conf5 + , + + + + -- 2.9.3