1SSSD-KCM(8)              File Formats and Conventions              SSSD-KCM(8)
2
3
4

NAME

6       sssd-kcm - SSSD Kerberos Cache Manager
7

DESCRIPTION

9       This manual page describes the configuration of the SSSD Kerberos Cache
10       Manager (KCM). KCM is a process that stores, tracks and manages
11       Kerberos credential caches. It originates in the Heimdal Kerberos
12       project, although the MIT Kerberos library also provides client side
13       (more details on that below) support for the KCM credential cache.
14
15       In a setup where Kerberos caches are managed by KCM, the Kerberos
16       library (typically used through an application, like e.g., kinit(1), is
17       a “"KCM client"” and the KCM daemon is being referred to as a “"KCM
18       server"”. The client and server communicate over a UNIX socket.
19
20       The KCM server keeps track of each credential caches's owner and
21       performs access check control based on the UID and GID of the KCM
22       client. The root user has access to all credential caches.
23
24       The KCM credential cache has several interesting properties:
25
26       •   since the process runs in userspace, it is subject to UID
27           namespacing, unlike the kernel keyring
28
29       •   unlike the kernel keyring-based cache, which is shared between all
30           containers, the KCM server is a separate process whose entry point
31           is a UNIX socket
32
33       •   the SSSD implementation stores the ccaches in a database, typically
34           located at /var/lib/sss/secrets allowing the ccaches to survive KCM
35           server restarts or machine reboots.
36
37       This allows the system to use a collection-aware credential cache, yet
38       share the credential cache between some or no containers by
39       bind-mounting the socket.
40
41       The KCM default client idle timeout is 5 minutes, this allows more time
42       for user interaction with command line tools such as kinit.
43

USING THE KCM CREDENTIAL CACHE

45       In order to use KCM credential cache, it must be selected as the
46       default credential type in krb5.conf(5), The credentials cache name
47       must be only “KCM:” without any template expansions. For example:
48
49           [libdefaults]
50               default_ccache_name = KCM:
51
52
53       Next, make sure the Kerberos client libraries and the KCM server must
54       agree on the UNIX socket path. By default, both use the same path
55       /var/run/.heim_org.h5l.kcm-socket. To configure the Kerberos library,
56       change its “kcm_socket” option which is described in the krb5.conf(5)
57       manual page.
58
59       Finally, make sure the SSSD KCM server can be contacted. The KCM
60       service is typically socket-activated by systemd(1). Unlike other SSSD
61       services, it cannot be started by adding the “kcm” string to the
62       “service” directive.
63
64           systemctl start sssd-kcm.socket
65           systemctl enable sssd-kcm.socket
66
67
68       Please note your distribution may already configure the units for you.
69

THE CREDENTIAL CACHE STORAGE

71       The credential caches are stored in a database, much like SSSD caches
72       user or group entries. The database is typically located at
73       “/var/lib/sss/secrets”.
74

OBTAINING DEBUG LOGS

76       The sssd-kcm service is typically socket-activated systemd(1). To
77       generate debug logs, add the following either to the
78       /etc/sssd/sssd.conf file directly or as a configuration snippet to
79       /etc/sssd/conf.d/ directory:
80
81           [kcm]
82           debug_level = 10
83
84
85       Then, restart the sssd-kcm service:
86
87           systemctl restart sssd-kcm.service
88
89
90       Finally, run whatever use-case doesn't work for you. The KCM logs will
91       be generated at /var/log/sssd/sssd_kcm.log. It is recommended to
92       disable the debug logs when you no longer need the debugging to be
93       enabled as the sssd-kcm service can generate quite a large amount of
94       debugging information.
95
96       Please note that configuration snippets are, at the moment, only
97       processed if the main configuration file at /etc/sssd/sssd.conf exists
98       at all.
99

RENEWALS

101       The sssd-kcm service can be configured to attempt TGT renewal for
102       renewable TGTs stored in the KCM ccache. Renewals are only attempted
103       when half of the ticket lifetime has been reached. KCM Renewals are
104       configured when the following options are set in the [kcm] section:
105
106           tgt_renewal = true
107           krb5_renew_interval = 60m
108
109
110       SSSD can also inherit krb5 options for renewals from an existing
111       domain.
112
113           tgt_renewal = true
114           tgt_renewal_inherit = domain-name
115
116
117       The following krb5 options can be configured in the [kcm] section to
118       control renewal behavior, these options are described in detail below
119
120           krb5_renew_interval
121           krb5_renewable_lifetime
122           krb5_lifetime
123           krb5_validate
124           krb5_canonicalize
125           krb5_auth_timeout
126
127
128

CONFIGURATION OPTIONS

130       The KCM service is configured in the “kcm” section of the sssd.conf
131       file. Please note that because the KCM service is typically
132       socket-activated, it is enough to just restart the “sssd-kcm” service
133       after changing options in the “kcm” section of sssd.conf:
134
135           systemctl restart sssd-kcm.service
136
137
138       The KCM service is configured in the “kcm” For a detailed syntax
139       reference, refer to the “FILE FORMAT” section of the sssd.conf(5)
140       manual page.
141
142       The generic SSSD service options such as “debug_level” or “fd_limit”
143       are accepted by the kcm service. Please refer to the sssd.conf(5)
144       manual page for a complete list. In addition, there are some
145       KCM-specific options as well.
146
147       socket_path (string)
148           The socket the KCM service will listen on.
149
150           Default: /var/run/.heim_org.h5l.kcm-socket
151
152           Note: on platforms where systemd is supported, the socket path is
153           overwritten by the one defined in the sssd-kcm.socket unit file.
154
155       max_ccaches (integer)
156           How many credential caches does the KCM database allow for all
157           users.
158
159           Default: 0 (unlimited, only the per-UID quota is enforced)
160
161       max_uid_ccaches (integer)
162           How many credential caches does the KCM database allow per UID.
163           This is equivalent to “with how many principals you can kinit”.
164
165           Default: 64
166
167       max_ccache_size (integer)
168           How big can a credential cache be per ccache. Each service ticket
169           accounts into this quota.
170
171           Default: 65536
172
173       tgt_renewal (bool)
174           Enables TGT renewals functionality.
175
176           Default: False (Automatic renewals disabled)
177
178       tgt_renewal_inherit (string)
179           Domain to inherit krb5_* options from, for use with TGT renewals.
180
181           Default: NULL
182
183       krb5_auth_timeout (integer)
184           Timeout in seconds after an online authentication request or change
185           password request is aborted. If possible, the authentication
186           request is continued offline.
187
188           Default: 6
189
190       krb5_validate (boolean)
191           Verify with the help of krb5_keytab that the TGT obtained has not
192           been spoofed. The keytab is checked for entries sequentially, and
193           the first entry with a matching realm is used for validation. If no
194           entry matches the realm, the last entry in the keytab is used. This
195           process can be used to validate environments using cross-realm
196           trust by placing the appropriate keytab entry as the last entry or
197           the only entry in the keytab file.
198
199           Default: false (IPA and AD provider: true)
200
201           Please note that the ticket validation is the first step when
202           checking the PAC (see 'pac_check' in the sssd.conf(5) manual page
203           for details). If ticket validation is disabled the PAC checks will
204           be skipped as well.
205
206       krb5_renewable_lifetime (string)
207           Request a renewable ticket with a total lifetime, given as an
208           integer immediately followed by a time unit:
209
210           s for seconds
211
212           m for minutes
213
214           h for hours
215
216           d for days.
217
218           If there is no unit given, s is assumed.
219
220           NOTE: It is not possible to mix units. To set the renewable
221           lifetime to one and a half hours, use '90m' instead of '1h30m'.
222
223           Default: not set, i.e. the TGT is not renewable
224
225       krb5_lifetime (string)
226           Request ticket with a lifetime, given as an integer immediately
227           followed by a time unit:
228
229           s for seconds
230
231           m for minutes
232
233           h for hours
234
235           d for days.
236
237           If there is no unit given s is assumed.
238
239           NOTE: It is not possible to mix units. To set the lifetime to one
240           and a half hours please use '90m' instead of '1h30m'.
241
242           Default: not set, i.e. the default ticket lifetime configured on
243           the KDC.
244
245       krb5_renew_interval (string)
246           The time in seconds between two checks if the TGT should be
247           renewed. TGTs are renewed if about half of their lifetime is
248           exceeded, given as an integer immediately followed by a time unit:
249
250           s for seconds
251
252           m for minutes
253
254           h for hours
255
256           d for days.
257
258           If there is no unit given, s is assumed.
259
260           NOTE: It is not possible to mix units. To set the renewable
261           lifetime to one and a half hours, use '90m' instead of '1h30m'.
262
263           If this option is not set or is 0 the automatic renewal is
264           disabled.
265
266           Default: not set
267
268       krb5_canonicalize (boolean)
269           Specifies if the host and user principal should be canonicalized.
270           This feature is available with MIT Kerberos 1.7 and later versions.
271
272           Default: false
273

SEE ALSO

275       sssd(8), sssd.conf(5),
276

AUTHORS

278       The SSSD upstream - https://github.com/SSSD/sssd/
279
280
281
282SSSD                              11/15/2023                       SSSD-KCM(8)
Impressum