"Fossies" - the Fresh Open Source Software Archive

Member "sssd-2.4.2/src/man/sssd-kcm.8.xml" (19 Feb 2021, 11111 Bytes) of package /linux/misc/sssd-2.4.2.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) XML source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the latest Fossies "Diffs" side-by-side code changes report for "sssd-kcm.8.xml": 2.4.1_vs_2.4.2.

    1 <?xml version="1.0" encoding="UTF-8"?>
    2 <!DOCTYPE reference PUBLIC "-//OASIS//DTD DocBook V4.4//EN"
    3 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
    4 <reference>
    5 <title>SSSD Manual pages</title>
    6 <refentry>
    7     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="include/upstream.xml" />
    8 
    9     <refmeta>
   10         <refentrytitle>sssd-kcm</refentrytitle>
   11         <manvolnum>8</manvolnum>
   12         <refmiscinfo class="manual">File Formats and Conventions</refmiscinfo>
   13     </refmeta>
   14 
   15     <refnamediv id='name'>
   16         <refname>sssd-kcm</refname>
   17         <refpurpose>SSSD Kerberos Cache Manager</refpurpose>
   18     </refnamediv>
   19 
   20     <refsect1 id='description'>
   21         <title>DESCRIPTION</title>
   22         <para>
   23             This manual page describes the configuration of the SSSD Kerberos
   24             Cache Manager (KCM). KCM is a process that stores, tracks and
   25             manages Kerberos credential caches. It originates in the Heimdal
   26             Kerberos project, although the MIT Kerberos library also provides
   27             client side (more details on that below) support for the KCM
   28             credential cache.
   29         </para>
   30         <para>
   31             In a setup where Kerberos caches are managed by KCM, the
   32             Kerberos library (typically used through an application, like
   33             e.g.,
   34             <citerefentry>
   35                 <refentrytitle>kinit</refentrytitle><manvolnum>1</manvolnum>
   36             </citerefentry>,
   37             is a <quote>"KCM client"</quote> and the KCM daemon
   38             is being referred to as a <quote>"KCM server"</quote>. The client
   39             and server communicate over a UNIX socket.
   40         </para>
   41         <para>
   42             The KCM server keeps track of each credential caches's owner and
   43             performs access check control based on the UID and GID of the
   44             KCM client. The root user has access to all credential caches.
   45         </para>
   46         <para>
   47             The KCM credential cache has several interesting properties:
   48             <itemizedlist>
   49                 <listitem>
   50                     <para>
   51                         since the process runs in userspace, it is subject to UID namespacing, unlike the kernel keyring
   52                     </para>
   53                 </listitem>
   54                 <listitem>
   55                     <para>
   56                         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
   57                     </para>
   58                 </listitem>
   59                 <listitem>
   60                     <para>
   61                         the SSSD implementation stores the ccaches in a database,
   62                         typically located at <replaceable>/var/lib/sss/secrets</replaceable>
   63                         allowing the ccaches to survive KCM server restarts or machine reboots.
   64                     </para>
   65                 </listitem>
   66             </itemizedlist>
   67             This allows the system to use a collection-aware credential
   68             cache, yet share the credential cache between some or no
   69             containers by bind-mounting the socket.
   70         </para>
   71         <para>
   72             The KCM default client idle timeout is 5 minutes, this allows
   73             more time for user interaction with command line tools such as kinit.
   74         </para>
   75     </refsect1>
   76 
   77     <refsect1 id='usage'>
   78         <title>USING THE KCM CREDENTIAL CACHE</title>
   79         <para>
   80             In order to use KCM credential cache, it must be selected as the default
   81             credential type in
   82             <citerefentry>
   83                 <refentrytitle>krb5.conf</refentrytitle><manvolnum>5</manvolnum>
   84             </citerefentry>,
   85             The credentials cache name must be only <quote>KCM:</quote>
   86             without any template expansions.  For example:
   87             <programlisting>
   88 [libdefaults]
   89     default_ccache_name = KCM:
   90             </programlisting>
   91         </para>
   92         <para>
   93             Next, make sure the Kerberos client libraries and the KCM server must agree
   94             on the UNIX socket path. By default, both use the same path
   95             <replaceable>/var/run/.heim_org.h5l.kcm-socket</replaceable>. To configure
   96             the Kerberos library, change its <quote>kcm_socket</quote> option which
   97             is described in the
   98             <citerefentry>
   99                 <refentrytitle>krb5.conf</refentrytitle><manvolnum>5</manvolnum>
  100             </citerefentry>
  101             manual page.
  102         </para>
  103         <para>
  104             Finally, make sure the SSSD KCM server can be contacted.
  105             The KCM service is typically socket-activated by
  106             <citerefentry>
  107                 <refentrytitle>systemd</refentrytitle>
  108                 <manvolnum>1</manvolnum>
  109             </citerefentry>.
  110             Unlike
  111             other SSSD services, it cannot be started by adding the
  112             <quote>kcm</quote> string to the <quote>service</quote>
  113             directive.
  114             <programlisting>
  115 systemctl start sssd-kcm.socket
  116 systemctl enable sssd-kcm.socket
  117             </programlisting>
  118             Please note your distribution may already configure the units
  119             for you.
  120         </para>
  121     </refsect1>
  122 
  123     <refsect1 id='storage'>
  124         <title>THE CREDENTIAL CACHE STORAGE</title>
  125         <para>
  126             The credential caches are stored in a database, much like SSSD
  127             caches user or group entries. The database is typically
  128             located at <quote>/var/lib/sss/secrets</quote>.
  129         </para>
  130     </refsect1>
  131 
  132     <refsect1 id='debugging'>
  133         <title>OBTAINING DEBUG LOGS</title>
  134         <para>
  135             The sssd-kcm service is typically socket-activated
  136             <citerefentry>
  137                 <refentrytitle>systemd</refentrytitle>
  138                 <manvolnum>1</manvolnum>
  139             </citerefentry>. To generate debug logs, add the following
  140             either to the <filename>/etc/sssd/sssd.conf</filename>
  141             file directly or as a configuration snippet to
  142             <filename>/etc/sssd/conf.d/</filename> directory:
  143             <programlisting>
  144 [kcm]
  145 debug_level = 10
  146             </programlisting>
  147             Then, restart the sssd-kcm service:
  148             <programlisting>
  149 systemctl restart sssd-kcm.service
  150             </programlisting>
  151             Finally, run whatever use-case doesn't work for you. The KCM
  152             logs will be generated at
  153             <filename>/var/log/sssd/sssd_kcm.log</filename>. It is
  154             recommended to disable the debug logs when you no longer need
  155             the debugging to be enabled as the sssd-kcm service can generate
  156             quite a large amount of debugging information.
  157         </para>
  158         <para>
  159             Please note that configuration snippets are, at the moment,
  160             only processed if the main configuration file at
  161             <filename>/etc/sssd/sssd.conf</filename> exists at all.
  162         </para>
  163     </refsect1>
  164 
  165     <refsect1 id='options'>
  166         <title>CONFIGURATION OPTIONS</title>
  167         <para>
  168             The KCM service is configured in the <quote>kcm</quote>
  169             section of the sssd.conf file. Please note that because
  170             the KCM service is typically socket-activated, it is
  171             enough to just restart the <quote>sssd-kcm</quote> service
  172             after changing options in the <quote>kcm</quote> section
  173             of sssd.conf:
  174             <programlisting>
  175 systemctl restart sssd-kcm.service
  176             </programlisting>
  177         </para>
  178         <para>
  179             The KCM service is configured in the <quote>kcm</quote>
  180             For a detailed syntax reference, refer to the <quote>FILE FORMAT</quote> section of the
  181             <citerefentry>
  182                 <refentrytitle>sssd.conf</refentrytitle>
  183                 <manvolnum>5</manvolnum>
  184             </citerefentry> manual page.
  185         </para>
  186         <para>
  187             The generic SSSD service options such as
  188             <quote>debug_level</quote> or <quote>fd_limit</quote> are
  189             accepted by the kcm service.  Please refer to the
  190             <citerefentry>
  191                 <refentrytitle>sssd.conf</refentrytitle>
  192                 <manvolnum>5</manvolnum>
  193             </citerefentry> manual page for a complete list. In addition,
  194             there are some KCM-specific options as well.
  195         </para>
  196         <variablelist>
  197             <varlistentry>
  198                 <term>socket_path (string)</term>
  199                 <listitem>
  200                     <para>
  201                         The socket the KCM service will listen on.
  202                     </para>
  203                     <para>
  204                         Default: <replaceable>/var/run/.heim_org.h5l.kcm-socket</replaceable>
  205                     </para>
  206                     <para>
  207                         <phrase condition="have_systemd">
  208                             Note: on platforms where systemd is supported, the
  209                             socket path is overwritten by the one defined in
  210                             the sssd-kcm.socket unit file.
  211                         </phrase>
  212                     </para>
  213                 </listitem>
  214             </varlistentry>
  215             <varlistentry>
  216                 <term>max_ccaches (integer)</term>
  217                 <listitem>
  218                     <para>
  219                         How many credential caches does the KCM database allow
  220                         for all users.
  221                     </para>
  222                     <para>
  223                         Default: 0 (unlimited, only the per-UID quota is enforced)
  224                     </para>
  225                 </listitem>
  226             </varlistentry>
  227             <varlistentry>
  228                 <term>max_uid_ccaches (integer)</term>
  229                 <listitem>
  230                     <para>
  231                         How many credential caches does the KCM database allow
  232                         per UID. This is equivalent to <quote>with how many
  233                         principals you can kinit</quote>.
  234                     </para>
  235                     <para>
  236                         Default: 64
  237                     </para>
  238                 </listitem>
  239             </varlistentry>
  240             <varlistentry>
  241                 <term>max_ccache_size (integer)</term>
  242                 <listitem>
  243                     <para>
  244                         How big can a credential cache be per ccache. Each
  245                         service ticket accounts into this quota.
  246                     </para>
  247                     <para>
  248                         Default: 65536
  249                     </para>
  250                 </listitem>
  251             </varlistentry>
  252         </variablelist>
  253     </refsect1>
  254 
  255     <refsect1 id='see_also'>
  256         <title>SEE ALSO</title>
  257         <para>
  258             <citerefentry>
  259                 <refentrytitle>sssd</refentrytitle><manvolnum>8</manvolnum>
  260             </citerefentry>,
  261             <citerefentry>
  262                 <refentrytitle>sssd.conf</refentrytitle><manvolnum>5</manvolnum>
  263             </citerefentry>,
  264         </para>
  265     </refsect1>
  266 </refentry>
  267 </reference>