1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
|
<?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, unlike 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
</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
</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>
|
