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