From 14d42e26c2050c1941874e83761fae69585ddc27 Mon Sep 17 00:00:00 2001
From: Jakub Hrozek <jhrozek@redhat.com>
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 <mzidek@redhat.com>
Reviewed-by: Simo Sorce <simo@redhat.com>
---
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 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE reference PUBLIC "-//OASIS//DTD DocBook V4.4//EN"
+"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+<reference>
+<title>SSSD Manual pages</title>
+<refentry>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="include/upstream.xml" />
+
+ <refmeta>
+ <refentrytitle>sssd-kcm</refentrytitle>
+ <manvolnum>8</manvolnum>
+ <refmiscinfo class="manual">File Formats and Conventions</refmiscinfo>
+ </refmeta>
+
+ <refnamediv id='name'>
+ <refname>sssd-kcm</refname>
+ <refpurpose>SSSD Kerberos Cache Manager</refpurpose>
+ </refnamediv>
+
+ <refsect1 id='description'>
+ <title>DESCRIPTION</title>
+ <para>
+ 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.
+ </para>
+ <para>
+ In a setup where Kerberos caches are managed by KCM, the
+ Kerberos library (typically used through an application, like
+ e.g.,
+ <citerefentry>
+ <refentrytitle>kinit</refentrytitle><manvolnum>1</manvolnum>
+ </citerefentry>,
+ is a <quote>"KCM client"</quote> and the KCM daemon
+ is being referred to as a <quote>"KCM server"</quote>. The client
+ and server communicate over a UNIX socket.
+ </para>
+ <para>
+ 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.
+ </para>
+ <para>
+ The KCM credential cache has several interesting properties:
+ <itemizedlist>
+ <listitem>
+ <para>
+ since the process runs in userspace, it is subject to UID namespacing, ulike the kernel keyring
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ 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
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ the SSSD implementation stores the ccaches in the SSSD
+ <citerefentry>
+ <refentrytitle>sssd-secrets</refentrytitle><manvolnum>5</manvolnum>
+ </citerefentry>
+ secrets store, allowing the ccaches to survive KCM server restarts or machine reboots.
+ </para>
+ </listitem>
+ </itemizedlist>
+ 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.
+ </para>
+ </refsect1>
+
+ <refsect1 id='usage'>
+ <title>USING THE KCM CREDENTIAL CACHE</title>
+ <para>
+ In order to use KCM credential cache, it must be selected as the default
+ credential type in
+ <citerefentry>
+ <refentrytitle>krb5.conf</refentrytitle><manvolnum>5</manvolnum>
+ </citerefentry>,
+ The credentials cache name must be only <quote>KCM:</quote>
+ without any template expansions. For example:
+ <programlisting>
+[libdefaults]
+ default_ccache_name = KCM:
+ </programlisting>
+ </para>
+ <para>
+ 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
+ <replaceable>/var/run/.heim_org.h5l.kcm-socket</replaceable>. To configure
+ the Kerberos library, change its <quote>kcm_socket</quote> option which
+ is described in the
+ <citerefentry>
+ <refentrytitle>krb5.conf</refentrytitle><manvolnum>5</manvolnum>
+ </citerefentry>
+ manual page.
+ </para>
+ <para>
+ Finally, make sure the SSSD KCM server can be contacted.
+ The KCM service is typically socket-activated by
+ <citerefentry>
+ <refentrytitle>systemd</refentrytitle>
+ <manvolnum>1</manvolnum>
+ </citerefentry>.
+ Unlike
+ other SSSD services, it cannot be started by adding the
+ <quote>kcm</quote> string to the <quote>service</quote>
+ directive.
+ <programlisting>
+systemctl start sssd-kcm.socket
+systemctl enable sssd-kcm.socket
+systemctl enable sssd-kcm.service
+ </programlisting>
+ Please note your distribution may already configure the units
+ for you.
+ </para>
+ </refsect1>
+
+ <refsect1 id='storage'>
+ <title>THE CREDENTIAL CACHE STORAGE</title>
+ <para>
+ The credential caches are stored in the SSSD secrets service (see
+ <citerefentry>
+ <refentrytitle>sssd-secrets</refentrytitle><manvolnum>5</manvolnum>
+ </citerefentry>
+ for more details). Therefore it is important that also the sssd-secrets
+ service is enabled and its socket is started:
+ <programlisting>
+systemctl start sssd-secrets.socket
+systemctl enable sssd-secrets.socket
+systemctl enable sssd-secrets.service
+ </programlisting>
+ Your distribution should already set the dependencies between the services.
+ </para>
+ </refsect1>
+
+ <refsect1 id='options'>
+ <title>CONFIGURATION OPTIONS</title>
+ <para>
+ The KCM service is configured in the <quote>kcm</quote>
+ 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
+ <quote>kcm</quote> section of sssd.conf.
+ For a detailed syntax reference, refer to the <quote>FILE FORMAT</quote> section of the
+ <citerefentry>
+ <refentrytitle>sssd.conf</refentrytitle>
+ <manvolnum>5</manvolnum>
+ </citerefentry> manual page.
+ </para>
+ <para>
+ The generic SSSD service options such as
+ <quote>debug_level</quote> or <quote>fd_limit</quote> are
+ accepted by the kcm service. Please refer to the
+ <citerefentry>
+ <refentrytitle>sssd.conf</refentrytitle>
+ <manvolnum>5</manvolnum>
+ </citerefentry> manual page for a complete list. In addition,
+ there are some KCM-specific options as well.
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term>socket_path (string)</term>
+ <listitem>
+ <para>
+ The socket the KCM service will listen on.
+ </para>
+ <para>
+ Default: <replaceable>/var/run/.heim_org.h5l.kcm-socket</replaceable>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+
+ <refsect1 id='see_also'>
+ <title>SEE ALSO</title>
+ <para>
+ <citerefentry>
+ <refentrytitle>sssd</refentrytitle><manvolnum>8</manvolnum>
+ </citerefentry>,
+ <citerefentry>
+ <refentrytitle>sssd.conf</refentrytitle><manvolnum>5</manvolnum>
+ </citerefentry>,
+ </para>
+ </refsect1>
+</refentry>
+</reference>
--
2.9.3