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
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
|
<?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 a database,
typically located at <replaceable>/var/lib/sss/secrets</replaceable>
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>
<para>
The KCM default client idle timeout is 5 minutes, this allows
more time for user interaction with command line tools such as kinit.
</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 a database, much like SSSD
caches user or group entries. The database is typically
located at <quote>/var/lib/sss/secrets</quote>.
</para>
</refsect1>
<refsect1 id='debugging'>
<title>OBTAINING DEBUG LOGS</title>
<para>
The sssd-kcm service is typically socket-activated
<citerefentry>
<refentrytitle>systemd</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>. To generate debug logs, add the following
either to the <filename>/etc/sssd/sssd.conf</filename>
file directly or as a configuration snippet to
<filename>/etc/sssd/conf.d/</filename> directory:
<programlisting>
[kcm]
debug_level = 10
</programlisting>
Then, restart the sssd-kcm service:
<programlisting>
systemctl restart sssd-kcm.service
</programlisting>
Finally, run whatever use-case doesn't work for you. The KCM
logs will be generated at
<filename>/var/log/sssd/sssd_kcm.log</filename>. It is
recommended to disable the debug logs when you no longer need
the debugging to be enabled as the sssd-kcm service can generate
quite a large amount of debugging information.
</para>
<para>
Please note that configuration snippets are, at the moment,
only processed if the main configuration file at
<filename>/etc/sssd/sssd.conf</filename> exists at all.
</para>
</refsect1>
<refsect1 id='renewals' condition="enable_kcm_renewal">
<title>RENEWALS</title>
<para>
The sssd-kcm service can be configured to attempt TGT
renewal for renewable TGTs stored in the KCM ccache.
Renewals are only attempted when half of the ticket
lifetime has been reached. KCM Renewals are configured
when the following options are set in the [kcm] section:
<programlisting>
tgt_renewal = true
krb5_renew_interval = 60m
</programlisting>
</para>
<para>
SSSD can also inherit krb5 options for renewals from an existing
domain.
</para>
<programlisting>
tgt_renewal = true
tgt_renewal_inherit = domain-name
</programlisting>
<para>
The following krb5 options can be configured in the
[kcm] section to control renewal behavior, these
options are described in detail below
<programlisting>
krb5_renew_interval
krb5_renewable_lifetime
krb5_lifetime
krb5_validate
krb5_canonicalize
krb5_auth_timeout
</programlisting>
</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 because
the KCM service is typically socket-activated, it is
enough to just restart the <quote>sssd-kcm</quote> service
after changing options in the <quote>kcm</quote> section
of sssd.conf:
<programlisting>
systemctl restart sssd-kcm.service
</programlisting>
</para>
<para>
The KCM service is configured in the <quote>kcm</quote>
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>
<para>
<phrase condition="have_systemd">
Note: on platforms where systemd is supported, the
socket path is overwritten by the one defined in
the sssd-kcm.socket unit file.
</phrase>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>max_ccaches (integer)</term>
<listitem>
<para>
How many credential caches does the KCM database allow
for all users.
</para>
<para>
Default: 0 (unlimited, only the per-UID quota is enforced)
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>max_uid_ccaches (integer)</term>
<listitem>
<para>
How many credential caches does the KCM database allow
per UID. This is equivalent to <quote>with how many
principals you can kinit</quote>.
</para>
<para>
Default: 64
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>max_ccache_size (integer)</term>
<listitem>
<para>
How big can a credential cache be per ccache. Each
service ticket accounts into this quota.
</para>
<para>
Default: 65536
</para>
</listitem>
</varlistentry>
<varlistentry condition="enable_kcm_renewal">
<term>tgt_renewal (bool)</term>
<listitem>
<para>
Enables TGT renewals functionality.
</para>
<para>
Default: False (Automatic renewals disabled)
</para>
</listitem>
</varlistentry>
<varlistentry condition="enable_kcm_renewal">
<term>tgt_renewal_inherit (string)</term>
<listitem>
<para>
Domain to inherit krb5_* options from, for use with TGT
renewals.
</para>
<para>
Default: NULL
</para>
</listitem>
</varlistentry>
</variablelist>
<xi:include condition="enable_kcm_renewal" xmlns:xi="http://www.w3.org/2001/XInclude" href="include/krb5_options.xml" />
</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>
|
