diff options
Diffstat (limited to '')
| -rw-r--r-- | src/man/sssd-kcm.8.xml | 327 |
1 files changed, 327 insertions, 0 deletions
diff --git a/src/man/sssd-kcm.8.xml b/src/man/sssd-kcm.8.xml new file mode 100644 index 0000000..846ae69 --- /dev/null +++ b/src/man/sssd-kcm.8.xml @@ -0,0 +1,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> |