diff options
Diffstat (limited to 'src/man/sssd.conf.5.xml')
| -rw-r--r-- | src/man/sssd.conf.5.xml | 4627 |
1 files changed, 4627 insertions, 0 deletions
diff --git a/src/man/sssd.conf.5.xml b/src/man/sssd.conf.5.xml new file mode 100644 index 0000000..e7a8cbd --- /dev/null +++ b/src/man/sssd.conf.5.xml @@ -0,0 +1,4627 @@ +<?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" +[ +<!ENTITY sssd_user_name SYSTEM "sssd_user_name.include"> +]> +<reference> +<title>SSSD Manual pages</title> +<refentry> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="include/upstream.xml" /> + + <refmeta> + <refentrytitle>sssd.conf</refentrytitle> + <manvolnum>5</manvolnum> + <refmiscinfo class="manual">File Formats and Conventions</refmiscinfo> + </refmeta> + + <refnamediv id='name'> + <refname>sssd.conf</refname> + <refpurpose>the configuration file for SSSD</refpurpose> + </refnamediv> + + <refsect1 id='file-format'> + <title>FILE FORMAT</title> + + <para> + The file has an ini-style syntax and consists of sections and + parameters. A section begins with the name of the section in + square brackets and continues until the next section begins. An + example of section with single and multi-valued parameters: + <programlisting> +<replaceable>[section]</replaceable> +<replaceable>key</replaceable> = <replaceable>value</replaceable> +<replaceable>key2</replaceable> = <replaceable>value2,value3</replaceable> + </programlisting> + </para> + + <para> + The data types used are string (no quotes needed), integer + and bool (with values of <quote>TRUE/FALSE</quote>). + </para> + + <para> + A comment line starts with a hash sign (<quote>#</quote>) or a + semicolon (<quote>;</quote>). + Inline comments are not supported. + </para> + + <para> + All sections can have an optional + <replaceable>description</replaceable> parameter. Its function + is only as a label for the section. + </para> + + <para> + <filename>sssd.conf</filename> must be a regular file, owned by + root and only root may read from or write to the file. + </para> + </refsect1> + + <refsect1 id='config-snippets'> + <title>CONFIGURATION SNIPPETS FROM INCLUDE DIRECTORY</title> + + <para> + The configuration file <filename>sssd.conf</filename> will + include configuration snippets using the include directory + <filename>conf.d</filename>. This feature is available if + SSSD was compiled with libini version 1.3.0 or later. + </para> + + <para> + Any file placed in <filename>conf.d</filename> + that ends in <quote><filename>.conf</filename></quote> + and does not begin with a dot (<quote>.</quote>) will + be used together with <filename>sssd.conf</filename> + to configure SSSD. + </para> + + <para> + The configuration snippets from <filename>conf.d</filename> + have higher priority than <filename>sssd.conf</filename> + and will override <filename>sssd.conf</filename> when + conflicts occur. If several snippets are present in + <filename>conf.d</filename>, then they are included in + alphabetical order (based on locale). + Files included later have higher priority. Numerical + prefixes (<filename>01_snippet.conf</filename>, + <filename>02_snippet.conf</filename> etc.) can help + visualize the priority (higher number means higher + priority). + </para> + + <para> + The snippet files require the same owner and permissions + as <filename>sssd.conf</filename>. Which are by default + root:root and 0600. + </para> + </refsect1> + + <refsect1 id='general-options'> + <title>GENERAL OPTIONS</title> + <para> + Following options are usable in more than one configuration + sections. + </para> + <refsect2 id='all-section-options'> + <title>Options usable in all sections</title> + <para> + <variablelist> + <varlistentry> + <term>debug_level (integer)</term> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="include/debug_levels.xml" /> + </varlistentry> + <varlistentry> + <term>debug (integer)</term> + <listitem> + <para> + SSSD 1.14 and later also includes the + <replaceable>debug</replaceable> alias for + <replaceable>debug_level</replaceable> as a + convenience feature. If both are specified, the + value of <replaceable>debug_level</replaceable> + will be used. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>debug_timestamps (bool)</term> + <listitem> + <para> + Add a timestamp to the debug messages. + If journald is enabled for SSSD debug logging this + option is ignored. + </para> + <para> + Default: true + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>debug_microseconds (bool)</term> + <listitem> + <para> + Add microseconds to the timestamp in debug messages. + If journald is enabled for SSSD debug logging this + option is ignored. + </para> + <para> + Default: false + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>debug_backtrace_enabled (bool)</term> + <listitem> + <para> + Enable debug backtrace. + </para> + <para> + In case SSSD is run with debug_level less than 9, + everything is logged to a ring buffer in memory and + flushed to a log file on any error up to + and including `min(0x0040, debug_level)` + (i.e. if debug_level is explicitly set to 0 or 1 then + only those error levels will trigger backtrace, + otherwise up to 2). + </para> + <para> + Feature is only supported for `logger == files` (i.e. + setting doesn't have effect for other logger types). + </para> + <para> + Default: true + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect2> + + <refsect2 id='services-and-domains-section-options'> + <title>Options usable in SERVICE and DOMAIN sections</title> + <para> + <variablelist> + <varlistentry> + <term>timeout (integer)</term> + <listitem> + <para> + Timeout in seconds between heartbeats for this + service. This is used to ensure that the process + is alive and capable of answering requests. Note + that after three missed heartbeats the process + will terminate itself. + </para> + <para> + Default: 10 + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect2> + </refsect1> + + <refsect1 id='special-sections'> + <title>SPECIAL SECTIONS</title> + + <refsect2 id='services'> + <title>The [sssd] section</title> + <para> + Individual pieces of SSSD functionality are provided by special + SSSD services that are started and stopped together with SSSD. + The services are managed by a special service frequently called + <quote>monitor</quote>. The <quote>[sssd]</quote> section is used + to configure the monitor as well as some other important options + like the identity domains. + <variablelist> + <title>Section parameters</title> + <varlistentry> + <term>config_file_version (integer)</term> + <listitem> + <para> + Indicates what is the syntax of the config + file. SSSD 0.6.0 and later use version 2. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>services</term> + <listitem> + <para> + Comma separated list of services that are + started when sssd itself starts. + <phrase condition="have_systemd"> + The services' list is optional on platforms + where systemd is supported, as they will either + be socket or D-Bus activated when needed. + </phrase> + </para> + <para> + Supported services: nss, pam + <phrase condition="with_sudo">, sudo</phrase> + <phrase condition="with_autofs">, autofs</phrase> + <phrase condition="with_ssh">, ssh</phrase> + <phrase condition="with_pac_responder">, pac</phrase> + <phrase condition="with_ifp">, ifp</phrase> + </para> + <para> + <phrase condition="have_systemd"> + By default, all services are disabled and the administrator + must enable the ones allowed to be used by executing: + "systemctl enable sssd-@service@.socket". + </phrase> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>reconnection_retries (integer)</term> + <listitem> + <para> + Number of times services should attempt to + reconnect in the event of a Data Provider + crash or restart before they give up + </para> + <para> + Default: 3 + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>domains</term> + <listitem> + <para> + A domain is a database containing user + information. SSSD can use more domains + at the same time, but at least one + must be configured or SSSD won't start. + This parameter describes the list of domains + in the order you want them to be queried. + A domain name is recommended to contain only + alphanumeric ASCII characters, dashes, dots + and underscores. '/' character is forbidden. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>re_expression (string)</term> + <listitem> + <para> + Default regular expression that describes how to + parse the string containing user name and domain + into these components. + </para> + <para> + Each domain can have an individual regular + expression configured. For some ID providers + there are also default regular expressions. See + DOMAIN SECTIONS for more info on these regular + expressions. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>full_name_format (string)</term> + <listitem> + <para> + A <citerefentry> + <refentrytitle>printf</refentrytitle> + <manvolnum>3</manvolnum> + </citerefentry>-compatible format that describes how to + compose a fully qualified name from user name + and domain name components. + </para> + <para> + The following expansions are supported: + <variablelist> + <varlistentry> + <term>%1$s</term> + <listitem><para>user name</para></listitem> + </varlistentry> + <varlistentry> + <term>%2$s</term> + <listitem> + <para> + domain name as specified in the + SSSD config file. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>%3$s</term> + <listitem> + <para> + domain flat name. Mostly usable + for Active Directory domains, both + directly configured or discovered + via IPA trusts. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + <para> + Each domain can have an individual format string configured. + See DOMAIN SECTIONS for more info on this option. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>monitor_resolv_conf (boolean)</term> + <listitem> + <para> + Controls if SSSD should monitor the state of + resolv.conf to identify when it needs to + update its internal DNS resolver. + </para> + <para> + Default: true + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>try_inotify (boolean)</term> + <listitem> + <para condition="have_inotify"> + By default, SSSD will attempt to use inotify + to monitor configuration files changes and + will fall back to polling every five seconds + if inotify cannot be used. + </para> + <para condition="have_inotify"> + There are some limited situations where it is + preferred that we should skip even trying to + use inotify. In these rare cases, this option + should be set to 'false' + </para> + <para condition="have_inotify"> + Default: true on platforms where inotify is + supported. False on other platforms. + </para> + <para> + Note: this option will have no effect on + platforms where inotify is unavailable. On + these platforms, polling will always be used. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>krb5_rcache_dir (string)</term> + <listitem> + <para> + Directory on the filesystem where SSSD should + store Kerberos replay cache files. + </para> + <para> + This option accepts a special value + __LIBKRB5_DEFAULTS__ that will instruct SSSD + to let libkrb5 decide the appropriate + location for the replay cache. + </para> + <para> + Default: Distribution-specific and specified + at build-time. (__LIBKRB5_DEFAULTS__ if not + configured) + </para> + </listitem> + </varlistentry> + <varlistentry condition="with_non_root_user_support"> + <term>user (string)</term> + <listitem> + <para> + The user to drop the privileges to where + appropriate to avoid running as the + root user. + Currently the only supported value is '&sssd_user_name;'. + </para> + + <para condition="have_systemd"> + This option does not work when running socket-activated + services, as the user set up to run the processes is + set up during compilation time. + + The way to override the systemd unit files is by creating + the appropriate files in /etc/systemd/system/. + + Keep in mind that any change in the socket user, group or + permissions may result in a non-usable SSSD. The same may + occur in case of changes of the user running the NSS + responder. + </para> + + <para> + Default: not set, process will run as root + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>default_domain_suffix (string)</term> + <listitem> + <para> + This string will be used as a default domain + name for all names without a domain name + component. The main use case is environments + where the primary domain is intended for managing host + policies and all users are located in a trusted domain. + The option allows those users + to log in just with their user name without + giving a domain name as well. + </para> + <para> + Please note that if this option is set all + users from the primary domain have to use their + fully qualified name, e.g. user@domain.name, + to log in. Setting this option changes default + of use_fully_qualified_names to True. It is not + allowed to use this option together with + use_fully_qualified_names set to False. + <phrase condition="with_files_provider"> + One exception from this rule are domains with + <quote>id_provider=files</quote> that always try + to match the behaviour of nss_files + and therefore their output is not + qualified even when the default_domain_suffix + option is used. + </phrase> + </para> + <para> + Default: not set + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>override_space (string)</term> + <listitem> + <para> + This parameter will replace spaces (space bar) + with the given character for user and group names. + e.g. (_). User name "john doe" will + be "john_doe" This feature was added to + help compatibility with shell scripts that have + difficulty handling spaces, due to the + default field separator in the shell. + </para> + <para> + Please note it is a configuration error to use + a replacement character that might be used in + user or group names. If a name contains the + replacement character SSSD tries to return the + unmodified name but in general the result of a + lookup is undefined. + </para> + <para> + Default: not set (spaces will not be replaced) + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>certificate_verification (string)</term> + <listitem> + <para> + With this parameter the certificate verification + can be tuned with a comma separated list of + options. Supported options are: + <variablelist> + <varlistentry> + <term>no_ocsp</term> + <listitem> + <para>Disables Online Certificate Status + Protocol (OCSP) checks. This might be + needed if the OCSP servers defined in + the certificate are not reachable from + the client.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>soft_ocsp</term> + <listitem> + <para> If a connection + cannot be established to an OCSP + responder the OCSP check is skipped. + This option should be used to allow + authentication when the system is + offline and the OCSP responder cannot be + reached.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>ocsp_dgst</term> + <listitem> + <para>Digest (hash) function used to + create the certificate ID for the OCSP + request. Allowed values are: + <itemizedlist> + <listitem><para>sha1</para></listitem> + <listitem><para>sha256</para></listitem> + <listitem><para>sha384</para></listitem> + <listitem><para>sha512</para></listitem> + </itemizedlist></para> + <para> + Default: sha1 (to allow compatibility with + RFC5019-compliant responder) + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>no_verification</term> + <listitem> + <para>Disables verification completely. + This option should only be used for + testing.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>partial_chain</term> + <listitem> + <para>Allow verification to succeed even + if a <replaceable>complete</replaceable> + chain cannot be built to a self-signed + trust-anchor, provided it is possible to + construct a chain to a trusted certificate + that might not be self-signed.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>ocsp_default_responder=URL</term> + <listitem> + <para>Sets the OCSP default responder + which should be used instead of the one + mentioned in the certificate. URL must + be replaced with the URL of the OCSP + default responder e.g. + http://example.com:80/ocsp.</para> + </listitem> + </varlistentry> + <varlistentry> + <term> + ocsp_default_responder_signing_cert=NAME</term> + <listitem> + <para>This option is + currently ignored. All needed + certificates must be available in the + PEM file given by + pam_cert_db_path.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>crl_file=/PATH/TO/CRL/FILE</term> + <listitem> + <para>Use the + Certificate Revocation List (CRL) from + the given file during the verification + of the certificate. The CRL must be + given in PEM format, see + <citerefentry> + <refentrytitle>crl</refentrytitle> + <manvolnum>1ssl</manvolnum> + </citerefentry> + for details.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>soft_crl</term> + <listitem> + <para> + If a Certificate Revocation List (CRL) + is expired ignore the CRL checks for the + related certificates. This option should + be used to allow authentication when the + system is offline and the CRL cannot be + renewed.</para> + </listitem> + </varlistentry> + </variablelist> + </para> + <para> + Unknown options are reported but ignored. + </para> + <para> + Default: not set, i.e. do not restrict + certificate verification + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>disable_netlink (boolean)</term> + <listitem> + <para> + SSSD hooks into the netlink interface to + monitor changes to routes, addresses, links + and trigger certain actions. + </para> + <para> + The SSSD state changes caused by netlink + events may be undesirable and can be disabled + by setting this option to 'true' + </para> + <para> + Default: false (netlink changes are detected) + </para> + </listitem> + </varlistentry> + <varlistentry condition="with_files_provider"> + <term>enable_files_domain (boolean)</term> + <listitem> + <para> + When this option is enabled, SSSD + prepends an implicit domain with + <quote>id_provider=files</quote> before + any explicitly configured domains. + </para> + <para> + Default: false + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>domain_resolution_order</term> + <listitem> + <para> + Comma separated list of domains and subdomains + representing the lookup order that will be + followed. + The list doesn't have to include all possible + domains as the missing domains will be looked + up based on the order they're presented in the + <quote>domains</quote> configuration option. + The subdomains which are not listed as part of + <quote>lookup_order</quote> will be looked up + in a random order for each parent domain. + </para> + <para> + Please, note that when this option is set the + output format of all commands is always + fully-qualified even when using short names + for input + <phrase condition="with_files_provider"> + , for all users but the ones managed + by the files provider + </phrase>. + In case the administrator wants the output not + fully-qualified, the full_name_format option + can be used as shown below: + <quote>full_name_format=%1$s</quote> + However, keep in mind that during login, login + applications often canonicalize the username by + calling + <citerefentry> + <refentrytitle>getpwnam</refentrytitle> + <manvolnum>3</manvolnum> + </citerefentry> + which, if a shortname is returned for a + qualified input (while trying to reach a user + which exists in multiple domains) might + re-route the login attempt into the domain + which uses shortnames, making this workaround + totally not recommended in cases where + usernames may overlap between domains. + </para> + <para> + Default: Not set + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>implicit_pac_responder (boolean)</term> + <listitem> + <para> + The PAC responder is enabled automatically for + the IPA and AD provider to evaluate and check + the PAC. If it has to be disabled + set this option to 'false'. + </para> + <para> + Default: true + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>core_dumpable (boolean)</term> + <listitem> + <para> + This option can be used for general system + hardening: setting it to 'false' forbids core + dumps for all SSSD processes to avoid + leaking plain text passwords. See man page + prctl:PR_SET_DUMPABLE for details. + </para> + <para> + Default: true + </para> + </listitem> + </varlistentry> + <varlistentry condition="build_passkey"> + <term>passkey_verification (string)</term> + <listitem> + <para> + With this parameter the passkey verification + can be tuned with a comma separated list of + options. Supported options are: + <variablelist> + <varlistentry> + <term>user_verification (boolean)</term> + <listitem> + <para> Enable or disable the user + verification (i.e. PIN, fingerprint) + during authentication. If enabled, the + PIN will always be requested. + </para> + <para> + The default is that the key settings + decide what to do. In the IPA or + kerberos pre-authentication case, + this value will be overwritten by the + server. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect2> + + </refsect1> + + <refsect1 id='services-sections'> + <title>SERVICES SECTIONS</title> + <para> + Settings that can be used to configure different services + are described in this section. They should reside in the + [<replaceable>$NAME</replaceable>] section, for example, + for NSS service, the section would be <quote>[nss]</quote> + </para> + + <refsect2 id='general'> + <title>General service configuration options</title> + <para> + These options can be used to configure any service. + </para> + <variablelist> + <varlistentry> + <term>reconnection_retries (integer)</term> + <listitem> + <para> + Number of times services should attempt to + reconnect in the event of a Data Provider + crash or restart before they give up + </para> + <para> + Default: 3 + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>fd_limit</term> + <listitem> + <para> + This option specifies the maximum number of file + descriptors that may be opened at one time by this + SSSD process. On systems where SSSD is granted the + CAP_SYS_RESOURCE capability, this will be an + absolute setting. On systems without this + capability, the resulting value will be the lower + value of this or the limits.conf "hard" limit. + </para> + <para> + Default: 8192 (or limits.conf "hard" limit) + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>client_idle_timeout</term> + <listitem> + <para> + This option specifies the number of seconds that + a client of an SSSD process can hold onto a file + descriptor without communicating on it. This value + is limited in order to avoid resource exhaustion + on the system. The timeout can't be shorter than + 10 seconds. If a lower value is configured, it + will be adjusted to 10 seconds. + </para> + <para> + Default: 60, KCM: 300 + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>offline_timeout (integer)</term> + <listitem> + <para> + When SSSD switches to offline mode the amount of + time before it tries to go back online will + increase based upon the time spent disconnected. + By default SSSD uses incremental behaviour to + calculate delay in between retries. + So, the wait time for a given retry will be longer + than the wait time for the previous ones. + After each unsuccessful attempt to go online, + the new interval is recalculated by the following: + </para> + <para> + new_delay = Minimum(old_delay * 2, offline_timeout_max) + random[0...offline_timeout_random_offset] + </para> + <para> + The offline_timeout default value is 60. + The offline_timeout_max default value is 3600. + The offline_timeout_random_offset default value is 30. + The end result is amount of seconds before next retry. + </para> + <para> + Note that the maximum length of each interval + is defined by offline_timeout_max (apart of random part). + </para> + <para> + Default: 60 + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>offline_timeout_max (integer)</term> + <listitem> + <para> + Controls by how much the time between attempts to go + online can be incremented following unsuccessful + attempts to go online. + </para> + <para> + A value of 0 disables the incrementing behaviour. + </para> + <para> + The value of this parameter should be set in correlation + to offline_timeout parameter value. + </para> + <para> + With offline_timeout set to 60 (default value) there is no point + in setting offlinet_timeout_max to less than 120 as it will + saturate instantly. General rule here should be to set + offline_timeout_max to at least 4 times offline_timeout. + </para> + <para> + Although a value between 0 and offline_timeout may be + specified, it has the effect of overriding the + offline_timeout value so is of little use. + </para> + <para> + Default: 3600 + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>offline_timeout_random_offset (integer)</term> + <listitem> + <para> + When SSSD is in offline mode it keeps probing + backend servers in specified time intervals: + </para> + <para> + new_delay = Minimum(old_delay * 2, offline_timeout_max) + random[0...offline_timeout_random_offset] + </para> + <para> + This parameter controls the value of the random offset + used for the above equation. Final random_offset value + will be random number in range: + </para> + <para> + [0 - offline_timeout_random_offset] + </para> + <para> + A value of 0 disables the random offset addition. + </para> + <para> + Default: 30 + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>responder_idle_timeout</term> + <listitem> + <para> + This option specifies the number of seconds that + an SSSD responder process can be up without being + used. This value is limited in order to avoid + resource exhaustion on the system. + The minimum acceptable value for this option is 60 + seconds. + Setting this option to 0 (zero) means that no + timeout will be set up to the responder. + + This option only has effect when SSSD is built with + systemd support and when services are either socket + or D-Bus activated. + </para> + <para> + Default: 300 + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>cache_first</term> + <listitem> + <para> + This option specifies whether the responder should + query all caches before querying the Data Providers. + </para> + <para condition="with_files_provider"> + Default: false + </para> + <para condition="without_files_provider"> + Default: true + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id='NSS'> + <title>NSS configuration options</title> + <para> + These options can be used to configure the + Name Service Switch (NSS) service. + </para> + <variablelist> + <varlistentry> + <term>enum_cache_timeout (integer)</term> + <listitem> + <para> + How many seconds should nss_sss cache enumerations + (requests for info about all users) + </para> + <para> + Default: 120 + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>entry_cache_nowait_percentage (integer)</term> + <listitem> + <para> + The entry cache can be set to automatically update + entries in the background if they are requested + beyond a percentage of the entry_cache_timeout + value for the domain. + </para> + <para> + For example, if the domain's entry_cache_timeout + is set to 30s and entry_cache_nowait_percentage is + set to 50 (percent), entries that come in after 15 + seconds past the last cache update will be + returned immediately, but the SSSD will go and + update the cache on its own, so that future + requests will not need to block waiting for a + cache update. + </para> + <para> + Valid values for this option are 0-99 and + represent a percentage of the entry_cache_timeout + for each domain. For performance reasons, this + percentage will never reduce the nowait timeout to + less than 10 seconds. + (0 disables this feature) + </para> + <para> + Default: 50 + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>entry_negative_timeout (integer)</term> + <listitem> + <para> + Specifies for how many seconds nss_sss should cache + negative cache hits (that is, queries for + invalid database entries, like nonexistent ones) + before asking the back end again. + </para> + <para> + Default: 15 + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>local_negative_timeout (integer)</term> + <listitem> + <para> + Specifies for how many seconds nss_sss should keep + local users and groups in negative cache before + trying to look it up in the back end again. Setting + the option to 0 disables this feature. + </para> + <para> + Default: 14400 (4 hours) + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>filter_users, filter_groups (string)</term> + <listitem> + <para> + Exclude certain users or groups from being fetched + from the sss NSS database. This is particularly + useful for system accounts. This option can also + be set per-domain or include fully-qualified names + to filter only users from the particular domain or + by a user principal name (UPN). + </para> + <para> + NOTE: The filter_groups option doesn't affect + inheritance of nested group members, since + filtering happens after they are propagated for + returning via NSS. E.g. a group having a member + group filtered out will still have the member + users of the latter listed. + </para> + <para> + Default: root + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>filter_users_in_groups (bool)</term> + <listitem> + <para> + If you want filtered user still be group members + set this option to false. + </para> + <para> + Default: true + </para> + </listitem> + </varlistentry> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="include/override_homedir.xml" /> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="include/homedir_substring.xml" /> + <varlistentry> + <term>fallback_homedir (string)</term> + <listitem> + <para> + Set a default template for a user's home directory + if one is not specified explicitly by the domain's + data provider. + </para> + <para> + The available values for this option are the same + as for override_homedir. + </para> + <para> + example: + <programlisting> +fallback_homedir = /home/%u + </programlisting> + </para> + <para> + Default: not set (no substitution for unset home + directories) + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>override_shell (string)</term> + <listitem> + <para> + Override the login shell for all users. This + option supersedes any other shell options if + it takes effect and can be set either in the + [nss] section or per-domain. + </para> + <para> + Default: not set (SSSD will use the value + retrieved from LDAP) + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>allowed_shells (string)</term> + <listitem> + <para> + Restrict user shell to one of the listed values. The order of evaluation is: + </para> + <para> + 1. If the shell is present in + <quote>/etc/shells</quote>, it is used. + </para> + <para> + 2. If the shell is in the allowed_shells list but + not in <quote>/etc/shells</quote>, use the + value of the shell_fallback parameter. + </para> + <para> + 3. If the shell is not in the allowed_shells list and + not in <quote>/etc/shells</quote>, a nologin shell + is used. + </para> + <para> + The wildcard (*) can be used to allow any shell. + </para> + <para> + The (*) is useful if you want to use + shell_fallback in case that user's shell is not + in <quote>/etc/shells</quote> and maintaining list + of all allowed shells in allowed_shells would be + to much overhead. + </para> + <para> + An empty string for shell is passed as-is to libc. + </para> + <para> + The <quote>/etc/shells</quote> is only read on SSSD start up, which means that + a restart of the SSSD is required in case a new shell is installed. + </para> + <para> + Default: Not set. The user shell is automatically used. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>vetoed_shells (string)</term> + <listitem> + <para> + Replace any instance of these shells with the shell_fallback + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>shell_fallback (string)</term> + <listitem> + <para> + The default shell to use if an allowed shell is not + installed on the machine. + </para> + <para> + Default: /bin/sh + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>default_shell</term> + <listitem> + <para> + The default shell to use if the provider does + not return one during lookup. This option can + be specified globally in the [nss] section + or per-domain. + </para> + <para> + Default: not set (Return NULL if no shell is + specified and rely on libc to substitute something + sensible when necessary, usually /bin/sh) + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>get_domains_timeout (int)</term> + <listitem> + <para> + Specifies time in seconds for which the list of + subdomains will be considered valid. + </para> + <para> + Default: 60 + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>memcache_timeout (integer)</term> + <listitem> + <para> + Specifies time in seconds for which records + in the in-memory cache will be valid. Setting this + option to zero will disable the in-memory cache. + </para> + <para> + Default: 300 + </para> + <para> + WARNING: Disabling the in-memory cache will + have significant negative impact on SSSD's + performance and should only be used for + testing. + </para> + <para> + NOTE: If the environment variable + SSS_NSS_USE_MEMCACHE is set to "NO", client + applications will not use the fast in-memory + cache. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>memcache_size_passwd (integer)</term> + <listitem> + <para> + Size (in megabytes) of the data table allocated inside + fast in-memory cache for passwd requests. + Setting the size to 0 will disable the passwd + in-memory cache. + </para> + <para> + Default: 8 + </para> + <para> + WARNING: Disabled or too small in-memory cache can + have significant negative impact on SSSD's + performance. + </para> + <para> + NOTE: If the environment variable + SSS_NSS_USE_MEMCACHE is set to "NO", client + applications will not use the fast in-memory + cache. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>memcache_size_group (integer)</term> + <listitem> + <para> + Size (in megabytes) of the data table allocated inside + fast in-memory cache for group requests. + Setting the size to 0 will disable the group + in-memory cache. + </para> + <para> + Default: 6 + </para> + <para> + WARNING: Disabled or too small in-memory cache can + have significant negative impact on SSSD's + performance. + </para> + <para> + NOTE: If the environment variable + SSS_NSS_USE_MEMCACHE is set to "NO", client + applications will not use the fast in-memory + cache. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>memcache_size_initgroups (integer)</term> + <listitem> + <para> + Size (in megabytes) of the data table allocated inside + fast in-memory cache for initgroups requests. + Setting the size to 0 will disable the initgroups + in-memory cache. + </para> + <para> + Default: 10 + </para> + <para> + WARNING: Disabled or too small in-memory cache can + have significant negative impact on SSSD's + performance. + </para> + <para> + NOTE: If the environment variable + SSS_NSS_USE_MEMCACHE is set to "NO", client + applications will not use the fast in-memory + cache. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>memcache_size_sid (integer)</term> + <listitem> + <para> + Size (in megabytes) of the data table allocated inside + fast in-memory cache for SID related requests. + Only SID-by-ID and ID-by-SID requests are currently + cached in fast in-memory cache. + Setting the size to 0 will disable the SID + in-memory cache. + </para> + <para> + Default: 6 + </para> + <para> + WARNING: Disabled or too small in-memory cache can + have significant negative impact on SSSD's + performance. + </para> + <para> + NOTE: If the environment variable + SSS_NSS_USE_MEMCACHE is set to "NO", client + applications will not use the fast in-memory + cache. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>user_attributes (string)</term> + <listitem> + <para> + Some of the additional NSS responder requests can + return more attributes than just the POSIX ones + defined by the NSS interface. The list of attributes + is controlled by this option. It is handled the same + way as the <quote>user_attributes</quote> option of + the InfoPipe responder (see + <citerefentry> + <refentrytitle>sssd-ifp</refentrytitle> + <manvolnum>5</manvolnum> + </citerefentry> + for details) but with no default values. + </para> + <para> + To make configuration more easy the NSS responder + will check the InfoPipe option if it is not set for + the NSS responder. + </para> + <para> + Default: not set, fallback to InfoPipe option + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>pwfield (string)</term> + <listitem> + <para> + The value that NSS operations that return + users or groups will return for the + <quote>password</quote> field. + </para> + <para> + Default: <quote>*</quote> + </para> + <para> + Note: This option can also be set per-domain which + overwrites the value in [nss] section. + </para> + <para> + Default: <quote>not set</quote> (remote domains), + <phrase condition="with_files_provider"> + <quote>x</quote> (the files domain), + </phrase> + <quote>x</quote> (proxy domain with nss_files + and sssd-shadowutils target) + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + <refsect2 id='PAM'> + <title>PAM configuration options</title> + <para> + These options can be used to configure the + Pluggable Authentication Module (PAM) service. + </para> + <variablelist> + <varlistentry> + <term>offline_credentials_expiration (integer)</term> + <listitem> + <para> + If the authentication provider is offline, how + long should we allow cached logins (in days since + the last successful online login). + </para> + <para> + Default: 0 (No limit) + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>offline_failed_login_attempts (integer)</term> + <listitem> + <para> + If the authentication provider is offline, how + many failed login attempts are allowed. + </para> + <para> + Default: 0 (No limit) + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>offline_failed_login_delay (integer)</term> + <listitem> + <para> + The time in minutes which has to pass after + offline_failed_login_attempts has been reached + before a new login attempt is possible. + </para> + <para> + If set to 0 the user cannot authenticate offline if + offline_failed_login_attempts has been reached. Only + a successful online authentication can enable + offline authentication again. + </para> + <para> + Default: 5 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>pam_verbosity (integer)</term> + <listitem> + <para> + Controls what kind of messages are shown to the user + during authentication. The higher the number to more + messages are displayed. + </para> + <para> + Currently sssd supports the following values: + </para> + <para> + <emphasis>0</emphasis>: do not show any message + </para> + <para> + <emphasis>1</emphasis>: show only important + messages + </para> + <para> + <emphasis>2</emphasis>: show informational messages + </para> + <para> + <emphasis>3</emphasis>: show all messages and debug + information + </para> + <para> + Default: 1 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>pam_response_filter (string)</term> + <listitem> + <para> + A comma separated list of strings which allows to + remove (filter) data sent by the PAM responder to + pam_sss PAM module. There are different kind of + responses sent to pam_sss e.g. messages displayed to + the user or environment variables which should be + set by pam_sss. + </para> + <para> + While messages already can be controlled with the + help of the pam_verbosity option this option allows + to filter out other kind of responses as well. + </para> + <para> + Currently the following filters are supported: + <variablelist> + <varlistentry><term>ENV</term> + <listitem><para>Do not send any environment + variables to any service.</para></listitem> + </varlistentry> + <varlistentry><term>ENV:var_name</term> + <listitem><para>Do not send environment + variable var_name to any + service.</para></listitem> + </varlistentry> + <varlistentry><term>ENV:var_name:service</term> + <listitem><para>Do not send environment + variable var_name to + service.</para></listitem> + </varlistentry> + </variablelist> + </para> + <para> + The list of strings can either be the list of + filters which would set this list of filters and + overwrite the defaults. Or each element of the list + can be prefixed by a '+' or '-' character which + would add the filter to the existing default or + remove it from the defaults, respectively. Please + note that either all list elements must have a '+' + or '-' prefix or none. It is considered as an error + to mix both styles. + </para> + <para> + Default: ENV:KRB5CCNAME:sudo, ENV:KRB5CCNAME:sudo-i + </para> + <para> + Example: -ENV:KRB5CCNAME:sudo-i will remove the + filter from the default list + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>pam_id_timeout (integer)</term> + <listitem> + <para> + For any PAM request while SSSD is online, the SSSD will + attempt to immediately update the cached identity + information for the user in order to ensure that + authentication takes place with the latest information. + </para> + <para> + A complete PAM conversation may perform multiple PAM + requests, such as account management and session + opening. This option controls (on a + per-client-application basis) how long (in seconds) we + can cache the identity information to avoid excessive + round-trips to the identity provider. + </para> + <para> + Default: 5 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>pam_pwd_expiration_warning (integer)</term> + <listitem> + <para> + Display a warning N days before the password expires. + </para> + <para> + Please note that the backend server has to provide + information about the expiration time of the password. + If this information is missing, sssd cannot display a + warning. + </para> + <para> + If zero is set, then this filter is not applied, + i.e. if the expiration warning was received from + backend server, it will automatically be displayed. + </para> + <para> + This setting can be overridden by setting + <emphasis>pwd_expiration_warning</emphasis> + for a particular domain. + </para> + <para> + Default: 0 + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>get_domains_timeout (int)</term> + <listitem> + <para> + Specifies time in seconds for which the list of + subdomains will be considered valid. + </para> + <para> + Default: 60 + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>pam_trusted_users (string)</term> + <listitem> + <para> + Specifies the comma-separated list of UID + values or user names that are allowed to run + PAM conversations against trusted domains. + Users not included in this list can only access + domains marked as public with + <quote>pam_public_domains</quote>. + User names are resolved to UIDs at + startup. + </para> + <para> + Default: All users are considered trusted + by default + </para> + <para> + Please note that UID 0 is always allowed to access + the PAM responder even in case it is not in the + pam_trusted_users list. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>pam_public_domains (string)</term> + <listitem> + <para> + Specifies the comma-separated list of domain names + that are accessible even to untrusted users. + </para> + <para> + Two special values for pam_public_domains option + are defined: + </para> + <para> + all (Untrusted users are allowed to access + all domains in PAM responder.) + </para> + <para> + none (Untrusted users are not allowed to access + any domains PAM in responder.) + </para> + <para> + Default: none + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>pam_account_expired_message (string)</term> + <listitem> + <para> + Allows a custom expiration message to be set, + replacing the default 'Permission denied' + message. + </para> + <para> + Note: Please be aware that message is only + printed for the SSH service unless pam_verbosity + is set to 3 (show all messages and debug + information). + </para> + <para> + example: + <programlisting> +pam_account_expired_message = Account expired, please contact help desk. + </programlisting> + </para> + <para> + Default: none + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>pam_account_locked_message (string)</term> + <listitem> + <para> + Allows a custom lockout message to be set, + replacing the default 'Permission denied' + message. + </para> + <para> + example: + <programlisting> +pam_account_locked_message = Account locked, please contact help desk. + </programlisting> + </para> + <para> + Default: none + </para> + </listitem> + </varlistentry> + <varlistentry condition="build_passkey"> + <term>pam_passkey_auth (bool)</term> + <listitem> + <para> + Enable passkey device based authentication. + </para> + <para> + Default: False + </para> + </listitem> + </varlistentry> + <varlistentry condition="build_passkey"> + <term>passkey_debug_libfido2 (bool)</term> + <listitem> + <para> + Enable libfido2 library debug messages. + </para> + <para> + Default: False + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>pam_cert_auth (bool)</term> + <listitem> + <para> + Enable certificate based Smartcard authentication. + Since this requires additional communication with + the Smartcard which will delay the authentication + process this option is disabled by default. + </para> + <para> + Default: False + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>pam_cert_db_path (string)</term> + <listitem> + <para> + The path to the certificate database. + </para> + <para> + Default: + <itemizedlist> + <listitem><para>/etc/sssd/pki/sssd_auth_ca_db.pem + (path to a file with trusted CA + certificates in PEM format) + </para> + </listitem> + </itemizedlist> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>pam_cert_verification (string)</term> + <listitem> + <para> + With this parameter the PAM certificate verification + can be tuned with a comma separated list of + options that override the + <quote>certificate_verification</quote> value in + <quote>[sssd]</quote> section. + Supported options are the same of + <quote>certificate_verification</quote>. + </para> + <para> + example: + <programlisting> +pam_cert_verification = partial_chain + </programlisting> + </para> + <para> + Default: not set, i.e. use default + <quote>certificate_verification</quote> option defined + in <quote>[sssd]</quote> section. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>p11_child_timeout (integer)</term> + <listitem> + <para> + How many seconds will pam_sss wait for + p11_child to finish. + </para> + <para> + Default: 10 + </para> + </listitem> + </varlistentry> + <varlistentry condition="build_passkey"> + <term>passkey_child_timeout (integer)</term> + <listitem> + <para> + How many seconds will the PAM responder + wait for passkey_child to finish. + </para> + <para> + Default: 15 + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>pam_app_services (string)</term> + <listitem> + <para> + Which PAM services are permitted to contact + domains of type <quote>application</quote> + </para> + <para> + Default: Not set + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>pam_p11_allowed_services (integer)</term> + <listitem> + <para> + A comma-separated list of PAM service names for + which it will be allowed to use Smartcards. + </para> + <para> + It is possible to add another PAM service name to + the default set by using + <quote>+service_name</quote> or to explicitly + remove a PAM service name from the default set by + using <quote>-service_name</quote>. For example, + in order to replace a default PAM service name for + authentication with Smartcards + (e.g. <quote>login</quote>) with a custom PAM + service name (e.g. <quote>my_pam_service</quote>), + you would use the following configuration: + <programlisting> +pam_p11_allowed_services = +my_pam_service, -login + </programlisting> + </para> + <para> + Default: the default set of PAM service names + includes: + <itemizedlist> + <listitem> + <para> + login + </para> + </listitem> + <listitem> + <para> + su + </para> + </listitem> + <listitem> + <para> + su-l + </para> + </listitem> + <listitem> + <para> + gdm-smartcard + </para> + </listitem> + <listitem> + <para> + gdm-password + </para> + </listitem> + <listitem> + <para> + kdm + </para> + </listitem> + <listitem> + <para> + sudo + </para> + </listitem> + <listitem> + <para> + sudo-i + </para> + </listitem> + <listitem> + <para> + gnome-screensaver + </para> + </listitem> + </itemizedlist> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>p11_wait_for_card_timeout (integer)</term> + <listitem> + <para> + If Smartcard authentication is required how many + extra seconds in addition to p11_child_timeout + should the PAM responder wait until a Smartcard is + inserted. + </para> + <para> + Default: 60 + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>p11_uri (string)</term> + <listitem> + <para> + PKCS#11 URI (see RFC-7512 for details) which can be + used to restrict the selection of devices used for + Smartcard authentication. By default SSSD's + p11_child will search for a PKCS#11 slot (reader) + where the 'removable' flags is set and read the + certificates from the inserted token from the first + slot found. If multiple readers are connected + p11_uri can be used to tell p11_child to use a + specific reader. + </para> + <para> + Example: + <programlisting> +p11_uri = pkcs11:slot-description=My%20Smartcard%20Reader + </programlisting> + or + <programlisting> +p11_uri = pkcs11:library-description=OpenSC%20smartcard%20framework;slot-id=2 + </programlisting> + To find suitable URI please check the debug output + of p11_child. As an alternative the GnuTLS utility + 'p11tool' with e.g. the '--list-all' will show + PKCS#11 URIs as well. + </para> + <para> + Default: none + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>pam_initgroups_scheme</term> + <listitem> + <para> + The PAM responder can force an online lookup to get + the current group memberships of the user trying to + log in. This option controls when this should be + done and the following values are allowed: + <variablelist> + <varlistentry><term>always</term> + <listitem><para>Always do an online lookup, + please note that pam_id_timeout still + applies</para></listitem> + </varlistentry> + <varlistentry><term>no_session</term> + <listitem><para>Only do an online + lookup if there is no active session of the + user, i.e. if the user is currently not logged + in</para></listitem> + </varlistentry> + <varlistentry><term>never</term> + <listitem><para>Never force an online lookup, + use the data from the cache as long as they are + not expired</para></listitem> + </varlistentry> + </variablelist> + </para> + <para> + Default: no_session + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>pam_gssapi_services</term> + <listitem> + <para> + Comma separated list of PAM services that are + allowed to try GSSAPI authentication using + pam_sss_gss.so module. + </para> + <para> + To disable GSSAPI authentication, set this option + to <quote>-</quote> (dash). + </para> + <para> + Note: This option can also be set per-domain which + overwrites the value in [pam] section. It can also + be set for trusted domain which overwrites the value + in the domain section. + </para> + <para> + Example: + <programlisting> +pam_gssapi_services = sudo, sudo-i + </programlisting> + </para> + <para> + Default: - (GSSAPI authentication is disabled) + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>pam_gssapi_check_upn</term> + <listitem> + <para> + If True, SSSD will require that the Kerberos user + principal that successfully authenticated through + GSSAPI can be associated with the user who is being + authenticated. Authentication will fail if the check + fails. + </para> + <para> + If False, every user that is able to obtained + required service ticket will be authenticated. + </para> + <para> + Note: This option can also be set per-domain which + overwrites the value in [pam] section. It can also + be set for trusted domain which overwrites the value + in the domain section. + </para> + <para> + Default: True + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>pam_gssapi_indicators_map</term> + <listitem> + <para> + Comma separated list of authentication indicators required + to be present in a Kerberos ticket to access a PAM service + that is allowed to try GSSAPI authentication using + pam_sss_gss.so module. + </para> + <para> + Each element of the list can be either an authentication indicator + name or a pair <quote>service:indicator</quote>. Indicators not + prefixed with the PAM service name will be required to access any + PAM service configured to be used with + <option>pam_gssapi_services</option>. A resulting list of indicators + per PAM service is then checked against indicators in the Kerberos + ticket during authentication by pam_sss_gss.so. Any indicator from the + ticket that matches the resulting list of indicators for the PAM service + would grant access. If none of the indicators in the list match, access + will be denied. If the resulting list of indicators for the PAM service + is empty, the check will not prevent the access. + </para> + <para> + To disable GSSAPI authentication indicator check, set this option + to <quote>-</quote> (dash). To disable the check for a specific PAM + service, add <quote>service:-</quote>. + </para> + <para> + Note: This option can also be set per-domain which + overwrites the value in [pam] section. It can also + be set for trusted domain which overwrites the value + in the domain section. + </para> + <para> + Following authentication indicators are supported by IPA Kerberos deployments: + <itemizedlist> + <listitem> + <para>pkinit -- pre-authentication using X.509 certificates -- whether stored in files or on smart cards.</para> + </listitem> + <listitem> + <para>hardened -- SPAKE pre-authentication or any pre-authentication wrapped in a FAST channel.</para> + </listitem> + <listitem> + <para>radius -- pre-authentication with the help of a RADIUS server.</para> + </listitem> + <listitem> + <para>otp -- pre-authentication using integrated two-factor authentication (2FA or one-time password, OTP) in IPA.</para> + </listitem> + <listitem> + <para>idp -- pre-authentication using external identity provider.</para> + </listitem> + </itemizedlist> + </para> + <para> + Example: to require access to SUDO services only + for users which obtained their Kerberos tickets + with a X.509 certificate pre-authentication + (PKINIT), set + <programlisting> +pam_gssapi_indicators_map = sudo:pkinit, sudo-i:pkinit + </programlisting> + </para> + <para> + Default: not set (use of authentication indicators is not required) + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id='SUDO' condition="with_sudo"> + <title>SUDO configuration options</title> + <para> + These options can be used to configure the sudo service. + The detailed instructions for configuration of + <citerefentry> + <refentrytitle>sudo</refentrytitle> + <manvolnum>8</manvolnum> + </citerefentry> to work with + <citerefentry> + <refentrytitle>sssd</refentrytitle> + <manvolnum>8</manvolnum> + </citerefentry> are in the manual page + <citerefentry> + <refentrytitle>sssd-sudo</refentrytitle> + <manvolnum>5</manvolnum> + </citerefentry>. + </para> + <variablelist> + <varlistentry> + <term>sudo_timed (bool)</term> + <listitem> + <para> + Whether or not to evaluate the sudoNotBefore + and sudoNotAfter attributes that implement + time-dependent sudoers entries. + </para> + <para> + Default: false + </para> + </listitem> + </varlistentry> + </variablelist> + <variablelist> + <varlistentry> + <term>sudo_threshold (integer)</term> + <listitem> + <para> + Maximum number of expired rules that can be + refreshed at once. If number of expired rules + is below threshold, those rules are refreshed + with <quote>rules refresh</quote> mechanism. If + the threshold is exceeded a + <quote>full refresh</quote> of sudo rules is + triggered instead. This threshold number also + applies to IPA sudo command and command group + searches. + </para> + <para> + Default: 50 + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id='AUTOFS' condition="with_autofs"> + <title>AUTOFS configuration options</title> + <para> + These options can be used to configure the autofs service. + </para> + <variablelist> + <varlistentry> + <term>autofs_negative_timeout (integer)</term> + <listitem> + <para> + Specifies for how many seconds should the + autofs responder negative cache hits + (that is, queries for invalid map entries, + like nonexistent ones) before asking the back + end again. + </para> + <para> + Default: 15 + </para> + </listitem> + </varlistentry> + </variablelist> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="include/autofs_restart.xml" /> + </refsect2> + + <refsect2 id='SSH' condition="with_ssh"> + <title>SSH configuration options</title> + <para> + These options can be used to configure the SSH service. + </para> + <variablelist> + <varlistentry> + <term>ssh_hash_known_hosts (bool)</term> + <listitem> + <para> + Whether or not to hash host names and addresses in + the managed known_hosts file. + </para> + <para> + Default: false + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>ssh_known_hosts_timeout (integer)</term> + <listitem> + <para> + How many seconds to keep a host in the managed + known_hosts file after its host keys were requested. + </para> + <para> + Default: 180 + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>ssh_use_certificate_keys (bool)</term> + <listitem> + <para> + If set to true the + <command>sss_ssh_authorizedkeys</command> will + return ssh keys derived from the public key of X.509 + certificates stored in the user entry as well. See + <citerefentry> + <refentrytitle>sss_ssh_authorizedkeys</refentrytitle> + <manvolnum>1</manvolnum> + </citerefentry> for details. + </para> + <para> + Default: true + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>ssh_use_certificate_matching_rules (string)</term> + <listitem> + <para> + By default the ssh responder will use all available + certificate matching rules to filter the + certificates so that ssh keys are only derived from + the matching ones. With this option the used rules + can be restricted with a comma separated list of + mapping and matching rule names. All other rules + will be ignored. + </para> + <para> + There are two special key words 'all_rules' and + 'no_rules' which will enable all or no rules, + respectively. The latter means that no certificates + will be filtered out and ssh keys will be generated + from all valid certificates. + </para> + <para> + If no rules are configured using 'all_rules' will + enable a default rule which enables all + certificates suitable for client authentication. + This is the same behavior as for the PAM responder + if certificate authentication is enabled. + </para> + <para> + A non-existing rule name is considered an error. + If as a result no rule is selected all certificates + will be ignored. + </para> + <para> + Default: not set, equivalent to 'all_rules', + all found rules or the default rule are used + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>ca_db (string)</term> + <listitem> + <para> + Path to a storage of trusted CA certificates. The + option is used to validate user certificates before + deriving public ssh keys from them. + </para> + <para> + Default: + <itemizedlist> + <listitem><para>/etc/sssd/pki/sssd_auth_ca_db.pem + (path to a file with trusted CA + certificates in PEM format) + </para> + </listitem> + </itemizedlist> + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id='PAC_RESPONDER' condition="with_pac_responder"> + <title>PAC responder configuration options</title> + <para> + The PAC responder works together with the authorization data + plugin for MIT Kerberos sssd_pac_plugin.so and a sub-domain + provider. The plugin sends the PAC data during a GSSAPI + authentication to the PAC responder. The sub-domain provider + collects domain SID and ID ranges of the domain the client is + joined to and of remote trusted domains from the local domain + controller. If the PAC is decoded and evaluated some of the + following operations are done: + <itemizedlist> + <listitem><para>If the remote user does not exist in the + cache, it is created. The UID is determined with the help + of the SID, trusted domains will have UPGs and the GID + will have the same value as the UID. The home directory is + set based on the subdomain_homedir parameter. The shell will + be empty by default, i.e. the system defaults are used, but + can be overwritten with the default_shell parameter.</para> + </listitem> + <listitem><para>If there are SIDs of groups from domains + sssd knows about, the user will be added to those groups. + </para></listitem> + </itemizedlist> + </para> + <para> + These options can be used to configure the PAC responder. + </para> + <variablelist> + <varlistentry> + <term>allowed_uids (string)</term> + <listitem> + <para> + Specifies the comma-separated list of UID values or + user names that are allowed to access the PAC + responder. User names are resolved to UIDs at + startup. + </para> + <para> + Default: 0 (only the root user is allowed to access + the PAC responder) + </para> + <para> + Please note that although the UID 0 is used as the + default it will be overwritten with this option. If + you still want to allow the root user to access the + PAC responder, which would be the typical case, you + have to add 0 to the list of allowed UIDs as well. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>pac_lifetime (integer)</term> + <listitem> + <para> + Lifetime of the PAC entry in seconds. As long as the + PAC is valid the PAC data can be used to determine + the group memberships of a user. + </para> + <para> + Default: 300 + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>pac_check (string)</term> + <listitem> + <para> + Apply additional checks on the PAC of the Kerberos + ticket which is available in Active Directory and + FreeIPA domains, if configured. Please note that + Kerberos ticket validation must be enabled to be + able to check the PAC, i.e. the krb5_validate option + must be set to 'True' which is the default for the + IPA and AD provider. If krb5_validate is set to + 'False' the PAC checks will be skipped. + </para> + <para> + The following options can be used alone or in a + comma-separated list: + <variablelist> + <varlistentry> + <term>no_check</term> + <listitem> + <para>The PAC must not be present and even + if it is present no additional checks will be + done.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>pac_present</term> + <listitem> + <para>The PAC must be present in the + service ticket which SSSD will request with + the help of the user's TGT. If the PAC is + not available the authentication will fail. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>check_upn</term> + <listitem> + <para>If the PAC is present check if the + user principal name (UPN) information is + consistent.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>check_upn_allow_missing</term> + <listitem> + <para>This option should be used together + with 'check_upn' and handles the case where + a UPN is set on the server-side but is not + read by SSSD. The typical example is a + FreeIPA domain where 'ldap_user_principal' + is set to a not existing attribute name. + This was typically done to work-around + issues in the handling of enterprise + principals. But this is fixed since quite + some time and FreeIPA can handle enterprise + principals just fine and there is no need + anymore to set 'ldap_user_principal'.</para> + <para>Currently this option is set by + default to avoid regressions in such + environments. A log message will be added + to the system log and SSSD's debug log in + case a UPN is found in the PAC but not in + SSSD's cache. To avoid this log message it + would be best to evaluate if the + 'ldap_user_principal' option can be removed. + If this is not possible, removing + 'check_upn' will skip the test and avoid the + log message.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>upn_dns_info_present</term> + <listitem> + <para>The PAC must contain the UPN-DNS-INFO + buffer, implies 'check_upn'.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>check_upn_dns_info_ex</term> + <listitem> + <para>If the PAC is present and the + extension to the UPN-DNS-INFO buffer is + available check if the information in the + extension is consistent.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>upn_dns_info_ex_present</term> + <listitem> + <para>The PAC must contain the extension of + the UPN-DNS-INFO buffer, implies + 'check_upn_dns_info_ex', + 'upn_dns_info_present' and 'check_upn'. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + <para> + Default: no_check (AD and IPA provider + 'check_upn, check_upn_allow_missing, check_upn_dns_info_ex') + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id='SESSION_RECORDING'> + <title>Session recording configuration options</title> + <para> + Session recording works in conjunction with + <citerefentry> + <refentrytitle>tlog-rec-session</refentrytitle> + <manvolnum>8</manvolnum> + </citerefentry>, a part of tlog package, to log what users see + and type when they log in on a text terminal. + See also + <citerefentry> + <refentrytitle>sssd-session-recording</refentrytitle> + <manvolnum>5</manvolnum> + </citerefentry>. + </para> + <para> + These options can be used to configure session recording. + </para> + <variablelist> + <varlistentry> + <term>scope (string)</term> + <listitem> + <para> + One of the following strings specifying the scope + of session recording: + <variablelist> + <varlistentry> + <term>"none"</term> + <listitem> + <para> + No users are recorded. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>"some"</term> + <listitem> + <para> + Users/groups specified by + <replaceable>users</replaceable> + and + <replaceable>groups</replaceable> + options are recorded. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>"all"</term> + <listitem> + <para> + All users are recorded. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + <para> + Default: "none" + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>users (string)</term> + <listitem> + <para> + A comma-separated list of users which should have + session recording enabled. Matches user names as + returned by NSS. I.e. after the possible space + replacement, case changes, etc. + </para> + <para> + Default: Empty. Matches no users. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>groups (string)</term> + <listitem> + <para> + A comma-separated list of groups, members of which + should have session recording enabled. Matches + group names as returned by NSS. I.e. after the + possible space replacement, case changes, etc. + </para> + <para> + NOTE: using this option (having it set to + anything) has a considerable performance cost, + because each uncached request for a user requires + retrieving and matching the groups the user is + member of. + </para> + <para> + Default: Empty. Matches no groups. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>exclude_users (string)</term> + <listitem> + <para> + A comma-separated list of users to be excluded from + recording, only applicable with 'scope=all'. + </para> + <para> + Default: Empty. No users excluded. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>exclude_groups (string)</term> + <listitem> + <para> + A comma-separated list of groups, members of which + should be excluded from recording. Only applicable + with 'scope=all'. + </para> + <para> + NOTE: using this option (having it set to + anything) has a considerable performance cost, + because each uncached request for a user requires + retrieving and matching the groups the user is + member of. + </para> + <para> + Default: Empty. No groups excluded. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + </refsect1> + + <refsect1 id='domain-sections'> + <title>DOMAIN SECTIONS</title> + <para> + These configuration options can be present in a domain + configuration section, that is, in a section called + <quote>[domain/<replaceable>NAME</replaceable>]</quote> + <variablelist> + <varlistentry> + <term>enabled</term> + <listitem> + <para> + Explicitly enable or disable the domain. If + <quote>true</quote>, the domain is always + <quote>enabled</quote>. If <quote>false</quote>, + the domain is always <quote>disabled</quote>. If + this option is not set, the domain is enabled only + if it is listed in the domains option in the + <quote>[sssd]</quote> section. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>domain_type (string)</term> + <listitem> + <para> + Specifies whether the domain is meant to be used + by POSIX-aware clients such as the Name Service Switch + or by applications that do not need POSIX data to be + present or generated. Only objects from POSIX domains + are available to the operating system interfaces and + utilities. + </para> + <para> + Allowed values for this option are <quote>posix</quote> + and <quote>application</quote>. + </para> + <para> + POSIX domains are reachable by all services. Application + domains are only reachable from the InfoPipe responder (see + <citerefentry> + <refentrytitle>sssd-ifp</refentrytitle> + <manvolnum>5</manvolnum> + </citerefentry>) and the PAM responder. + </para> + <para> + NOTE: The application domains are currently well tested with + <quote>id_provider=ldap</quote> only. + </para> + <para> + For an easy way to configure a non-POSIX domains, please + see the <quote>Application domains</quote> section. + </para> + <para> + Default: posix + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>min_id,max_id (integer)</term> + <listitem> + <para> + UID and GID limits for the domain. If a domain + contains an entry that is outside these limits, it + is ignored. + </para> + <para> + For users, this affects the primary GID limit. The + user will not be returned to NSS if either the + UID or the primary GID is outside the range. For + non-primary group memberships, those that are in + range will be reported as expected. + </para> + <para> + These ID limits affect even saving entries to + cache, not only returning them by name or ID. + </para> + <para> + Default: 1 for min_id, 0 (no limit) for max_id + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>enumerate (bool)</term> + <listitem> + <para> + Determines if a domain can be enumerated, + that is, whether the domain can list all the + users and group it contains. Note that it is + not required to enable enumeration in order + for secondary groups to be displayed. This + parameter can have one of the following values: + </para> + <para> + TRUE = Users and groups are enumerated + </para> + <para> + FALSE = No enumerations for this domain + </para> + <para> + Default: FALSE + </para> + <para> + Enumerating a domain requires SSSD to download + and store ALL user and group entries from the + remote server. + </para> + <para> + Note: Enabling enumeration has a moderate + performance impact on SSSD while enumeration + is running. It may take up to several minutes + after SSSD startup to fully complete enumerations. + During this time, individual requests for + information will go directly to LDAP, though it + may be slow, due to the heavy enumeration + processing. Saving a large number of entries + to cache after the enumeration completes might + also be CPU intensive as the memberships have + to be recomputed. This can lead to the + <quote>sssd_be</quote> process becoming unresponsive + or even restarted by the internal watchdog. + </para> + <para> + While the first enumeration is running, requests + for the complete user or group lists may return + no results until it completes. + </para> + <para> + Further, enabling enumeration may increase the time + necessary to detect network disconnection, as + longer timeouts are required to ensure that + enumeration lookups are completed successfully. + For more information, refer to the man pages for + the specific id_provider in use. + </para> + <para> + For the reasons cited above, enabling enumeration + is not recommended, especially in large + environments. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>subdomain_enumerate (string)</term> + <listitem> + <para> + Whether any of autodetected trusted domains should + be enumerated. The supported values are: + <variablelist> + <varlistentry> + <term>all</term> + <listitem><para>All discovered trusted domains will be enumerated</para></listitem> + </varlistentry> + <varlistentry> + <term>none</term> + <listitem><para>No discovered trusted domains will be enumerated</para></listitem> + </varlistentry> + </variablelist> + Optionally, a list of one or more domain + names can enable enumeration just for these + trusted domains. + </para> + <para> + Default: none + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>entry_cache_timeout (integer)</term> + <listitem> + <para> + How many seconds should nss_sss consider + entries valid before asking the backend again + </para> + <para> + The cache expiration timestamps are stored + as attributes of individual objects in the + cache. Therefore, changing the cache timeout only + has effect for newly added or expired entries. + You should run the + <citerefentry> + <refentrytitle>sss_cache</refentrytitle> + <manvolnum>8</manvolnum> + </citerefentry> + tool in order to force refresh of entries that + have already been cached. + </para> + <para> + Default: 5400 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>entry_cache_user_timeout (integer)</term> + <listitem> + <para> + How many seconds should nss_sss consider + user entries valid before asking the backend again + </para> + <para> + Default: entry_cache_timeout + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>entry_cache_group_timeout (integer)</term> + <listitem> + <para> + How many seconds should nss_sss consider + group entries valid before asking the backend again + </para> + <para> + Default: entry_cache_timeout + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>entry_cache_netgroup_timeout (integer)</term> + <listitem> + <para> + How many seconds should nss_sss consider + netgroup entries valid before asking the backend again + </para> + <para> + Default: entry_cache_timeout + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>entry_cache_service_timeout (integer)</term> + <listitem> + <para> + How many seconds should nss_sss consider + service entries valid before asking the backend again + </para> + <para> + Default: entry_cache_timeout + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>entry_cache_resolver_timeout (integer)</term> + <listitem> + <para> + How many seconds should nss_sss consider + hosts and networks entries valid before asking + the backend again + </para> + <para> + Default: entry_cache_timeout + </para> + </listitem> + </varlistentry> + + <varlistentry condition="with_sudo"> + <term>entry_cache_sudo_timeout (integer)</term> + <listitem> + <para> + How many seconds should sudo consider + rules valid before asking the backend again + </para> + <para> + Default: entry_cache_timeout + </para> + </listitem> + </varlistentry> + + <varlistentry condition="with_autofs"> + <term>entry_cache_autofs_timeout (integer)</term> + <listitem> + <para> + How many seconds should the autofs service + consider automounter maps valid before asking + the backend again + </para> + <para> + Default: entry_cache_timeout + </para> + </listitem> + </varlistentry> + + <varlistentry condition="with_ssh"> + <term>entry_cache_ssh_host_timeout (integer)</term> + <listitem> + <para> + How many seconds to keep a host ssh key after + refresh. IE how long to cache the host key + for. + </para> + <para> + Default: entry_cache_timeout + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>entry_cache_computer_timeout (integer)</term> + <listitem> + <para> + How many seconds to keep the local computer + entry before asking the backend again + </para> + <para> + Default: entry_cache_timeout + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>refresh_expired_interval (integer)</term> + <listitem> + <para> + Specifies how many seconds SSSD has to wait before + triggering a background refresh task which will + refresh all expired or nearly expired records. + </para> + <para> + The background refresh will process users, + groups and netgroups in the cache. For users + who have performed the initgroups (get group + membership for user, typically ran at login) + operation in the past, both the user entry + and the group membership are updated. + </para> + <para> + This option is automatically inherited for all + trusted domains. + </para> + <para> + You can consider setting this value to + 3/4 * entry_cache_timeout. + </para> + <para> + Cache entry will be refreshed by background task + when 2/3 of cache timeout has already passed. + If there are existing cached entries, the background + task will refer to their original cache timeout + values instead of current configuration value. + This may lead to a situation in which background refresh + task appears to not be working. This is done + by design to improve offline mode operation and + reuse of existing valid cache entries. + To make this change instant the user may want to + manually invalidate existing cache. + </para> + <para> + Default: 0 (disabled) + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>cache_credentials (bool)</term> + <listitem> + <para> + Determines if user credentials are also cached + in the local LDB cache. The cached credentials + refer to passwords, which includes the first (long + term) factor of two-factor authentication, not + other authentication mechanisms. Passkey and + Smartcard authentications are expected to work + offline as long as a successful online + authentication is recorded in the cache without + additional configuration. + </para> + <para> + Take a note that while credentials are stored as + a salted SHA512 hash, this still potentially poses + some security risk in case an attacker manages to + get access to a cache file (normally requires + privileged access) and to break a password using + brute force attack. + </para> + <para> + Default: FALSE + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>cache_credentials_minimal_first_factor_length (int)</term> + <listitem> + <para> + If 2-Factor-Authentication (2FA) is used and + credentials should be saved this value determines + the minimal length the first authentication factor + (long term password) must have to be saved as SHA512 + hash into the cache. + </para> + <para> + This should avoid that the short PINs of a PIN based + 2FA scheme are saved in the cache which would make + them easy targets for brute-force attacks. + </para> + <para> + Default: 8 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>account_cache_expiration (integer)</term> + <listitem> + <para> + Number of days entries are left in cache after + last successful login before being removed during + a cleanup of the cache. 0 means keep forever. + The value of this parameter must be greater than or + equal to offline_credentials_expiration. + </para> + <para> + Default: 0 (unlimited) + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>pwd_expiration_warning (integer)</term> + <listitem> + <para> + Display a warning N days before the password expires. + </para> + <para> + If zero is set, then this filter is not applied, + i.e. if the expiration warning was received from + backend server, it will automatically be displayed. + </para> + <para> + Please note that the backend server has to provide + information about the expiration time of the password. + If this information is missing, sssd cannot display a + warning. Also an auth provider has to be configured for + the backend. + </para> + <para> + Default: 7 (Kerberos), 0 (LDAP) + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>id_provider (string)</term> + <listitem> + <para> + The identification provider used for the domain. + Supported ID providers are: + </para> + <para> + <quote>proxy</quote>: Support a legacy NSS provider. + </para> + <para condition="with_files_provider"> + <quote>files</quote>: FILES provider. See + <citerefentry> + <refentrytitle>sssd-files</refentrytitle> + <manvolnum>5</manvolnum> + </citerefentry> for more information on + how to mirror local users and groups into SSSD. + </para> + <para> + <quote>ldap</quote>: LDAP provider. See + <citerefentry> + <refentrytitle>sssd-ldap</refentrytitle> + <manvolnum>5</manvolnum> + </citerefentry> for more information on + configuring LDAP. + </para> + <para> + <quote>ipa</quote>: FreeIPA and Red Hat + Identity Management provider. See + <citerefentry> + <refentrytitle>sssd-ipa</refentrytitle> + <manvolnum>5</manvolnum> + </citerefentry> for more information on + configuring FreeIPA. + </para> + <para> + <quote>ad</quote>: Active Directory provider. See + <citerefentry> + <refentrytitle>sssd-ad</refentrytitle> + <manvolnum>5</manvolnum> + </citerefentry> for more information on + configuring Active Directory. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>use_fully_qualified_names (bool)</term> + <listitem> + <para> + Use the full name and domain (as formatted by + the domain's full_name_format) as the user's login + name reported to NSS. + </para> + <para> + If set to TRUE, all requests to this domain + must use fully qualified names. For example, + if used in LOCAL domain that contains a "test" + user, <command>getent passwd test</command> + wouldn't find the user while <command>getent + passwd test@LOCAL</command> would. + </para> + <para> + NOTE: This option has no effect on netgroup + lookups due to their tendency to include nested + netgroups without qualified names. For netgroups, + all domains will be searched when an unqualified + name is requested. + </para> + <para> + Default: FALSE (TRUE for trusted + domain/sub-domains or if default_domain_suffix + is used) + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>ignore_group_members (bool)</term> + <listitem> + <para> + Do not return group members for group lookups. + </para> + <para> + If set to TRUE, the group membership attribute + is not requested from the ldap server, and + group members are not returned when processing + group lookup calls, such as + <citerefentry> + <refentrytitle>getgrnam</refentrytitle> + <manvolnum>3</manvolnum> + </citerefentry> + or + <citerefentry> + <refentrytitle>getgrgid</refentrytitle> + <manvolnum>3</manvolnum> + </citerefentry>. + As an effect, <quote>getent group + $groupname</quote> would return the requested + group as if it was empty. + </para> + <para> + Enabling this option can also make access + provider checks for group membership + significantly faster, especially for groups + containing many members. + </para> + <para> + This option can be also set per subdomain or + inherited via + <emphasis>subdomain_inherit</emphasis>. + </para> + <para> + Default: FALSE + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>auth_provider (string)</term> + <listitem> + <para> + The authentication provider used for the domain. + Supported auth providers are: + </para> + <para> + <quote>ldap</quote> for native LDAP authentication. See + <citerefentry> + <refentrytitle>sssd-ldap</refentrytitle> + <manvolnum>5</manvolnum> + </citerefentry> for more information on configuring LDAP. + </para> + <para> + <quote>krb5</quote> for Kerberos authentication. See + <citerefentry> + <refentrytitle>sssd-krb5</refentrytitle> + <manvolnum>5</manvolnum> + </citerefentry> for more information on configuring Kerberos. + </para> + <para> + <quote>ipa</quote>: FreeIPA and Red Hat + Identity Management provider. See + <citerefentry> + <refentrytitle>sssd-ipa</refentrytitle> + <manvolnum>5</manvolnum> + </citerefentry> for more information on + configuring FreeIPA. + </para> + <para> + <quote>ad</quote>: Active Directory provider. See + <citerefentry> + <refentrytitle>sssd-ad</refentrytitle> + <manvolnum>5</manvolnum> + </citerefentry> for more information on + configuring Active Directory. + </para> + <para> + <quote>proxy</quote> for relaying authentication to some other PAM target. + </para> + <para> + <quote>none</quote> disables authentication explicitly. + </para> + <para> + Default: <quote>id_provider</quote> is used if it + is set and can handle authentication requests. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>access_provider (string)</term> + <listitem> + <para> + The access control provider used for the domain. + There are two built-in access providers (in + addition to any included in installed backends) + Internal special providers are: + </para> + <para> + <quote>permit</quote> always allow access. It's the only permitted access provider for a local domain. + </para> + <para> + <quote>deny</quote> always deny access. + </para> + <para> + <quote>ldap</quote> for native LDAP authentication. See + <citerefentry> + <refentrytitle>sssd-ldap</refentrytitle> + <manvolnum>5</manvolnum> + </citerefentry> for more information on configuring LDAP. + </para> + <para> + <quote>ipa</quote>: FreeIPA and Red Hat + Identity Management provider. See + <citerefentry> + <refentrytitle>sssd-ipa</refentrytitle> + <manvolnum>5</manvolnum> + </citerefentry> for more information on + configuring FreeIPA. + </para> + <para> + <quote>ad</quote>: Active Directory provider. See + <citerefentry> + <refentrytitle>sssd-ad</refentrytitle> + <manvolnum>5</manvolnum> + </citerefentry> for more information on + configuring Active Directory. + </para> + <para> + <quote>simple</quote> access control based on access + or deny lists. See <citerefentry> + <refentrytitle>sssd-simple</refentrytitle> + <manvolnum>5</manvolnum></citerefentry> for more + information on configuring the simple access module. + </para> + <para> + <quote>krb5</quote>: .k5login based access control. + See <citerefentry> + <refentrytitle>sssd-krb5</refentrytitle> + <manvolnum>5</manvolnum></citerefentry> for more + information on configuring Kerberos. + </para> + <para> + <quote>proxy</quote> for relaying access control to another PAM module. + </para> + <para> + Default: <quote>permit</quote> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>chpass_provider (string)</term> + <listitem> + <para> + The provider which should handle change password + operations for the domain. + Supported change password providers are: + </para> + <para> + <quote>ldap</quote> to change a password stored + in a LDAP server. See + <citerefentry> + <refentrytitle>sssd-ldap</refentrytitle> + <manvolnum>5</manvolnum> + </citerefentry> for more information on configuring LDAP. + </para> + <para> + <quote>krb5</quote> to change the Kerberos + password. See + <citerefentry> + <refentrytitle>sssd-krb5</refentrytitle> + <manvolnum>5</manvolnum> + </citerefentry> for more information on configuring Kerberos. + </para> + <para> + <quote>ipa</quote>: FreeIPA and Red Hat + Identity Management provider. See + <citerefentry> + <refentrytitle>sssd-ipa</refentrytitle> + <manvolnum>5</manvolnum> + </citerefentry> for more information on + configuring FreeIPA. + </para> + <para> + <quote>ad</quote>: Active Directory provider. See + <citerefentry> + <refentrytitle>sssd-ad</refentrytitle> + <manvolnum>5</manvolnum> + </citerefentry> for more information on + configuring Active Directory. + </para> + <para> + <quote>proxy</quote> for relaying password changes + to some other PAM target. + </para> + <para> + <quote>none</quote> disallows password changes explicitly. + </para> + <para> + Default: <quote>auth_provider</quote> is used if it + is set and can handle change password requests. + </para> + </listitem> + </varlistentry> + + <varlistentry condition="with_sudo"> + <term>sudo_provider (string)</term> + <listitem> + <para> + The SUDO provider used for the domain. + Supported SUDO providers are: + </para> + <para> + <quote>ldap</quote> for rules stored in LDAP. See + <citerefentry> + <refentrytitle>sssd-ldap</refentrytitle> + <manvolnum>5</manvolnum> + </citerefentry> for more information on configuring + LDAP. + </para> + <para> + <quote>ipa</quote> the same as <quote>ldap</quote> + but with IPA default settings. + </para> + <para> + <quote>ad</quote> the same as <quote>ldap</quote> + but with AD default settings. + </para> + <para> + <quote>none</quote> disables SUDO explicitly. + </para> + <para> + Default: The value of <quote>id_provider</quote> is + used if it is set. + </para> + <para> + The detailed instructions for configuration of + sudo_provider are in the manual page + <citerefentry> + <refentrytitle>sssd-sudo</refentrytitle> + <manvolnum>5</manvolnum> + </citerefentry>. + There are many configuration options that can be + used to adjust the behavior. Please refer to + "ldap_sudo_*" in + <citerefentry> + <refentrytitle>sssd-ldap</refentrytitle> + <manvolnum>5</manvolnum> + </citerefentry>. + </para> + <para> + <emphasis>NOTE:</emphasis> Sudo rules are + periodically downloaded in the background unless + the sudo provider is explicitly disabled. Set + <emphasis>sudo_provider = None</emphasis> to + disable all sudo-related activity in SSSD if you do + not want to use sudo with SSSD at all. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>selinux_provider (string)</term> + <listitem> + <para> + The provider which should handle loading of selinux + settings. Note that this provider will be called right + after access provider ends. + Supported selinux providers are: + </para> + <para> + <quote>ipa</quote> to load selinux settings + from an IPA server. See + <citerefentry> + <refentrytitle>sssd-ipa</refentrytitle> + <manvolnum>5</manvolnum> + </citerefentry> for more information on configuring IPA. + </para> + <para> + <quote>none</quote> disallows fetching selinux settings explicitly. + </para> + <para> + Default: <quote>id_provider</quote> is used if it + is set and can handle selinux loading requests. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>subdomains_provider (string)</term> + <listitem> + <para> + The provider which should handle fetching of + subdomains. This value should be always the same as + id_provider. + Supported subdomain providers are: + </para> + <para> + <quote>ipa</quote> to load a list of subdomains + from an IPA server. See + <citerefentry> + <refentrytitle>sssd-ipa</refentrytitle> + <manvolnum>5</manvolnum> + </citerefentry> for more information on configuring + IPA. + </para> + <para> + <quote>ad</quote> to load a list of subdomains + from an Active Directory server. See + <citerefentry> + <refentrytitle>sssd-ad</refentrytitle> + <manvolnum>5</manvolnum> + </citerefentry> for more information on configuring + the AD provider. + </para> + <para> + <quote>none</quote> disallows fetching subdomains + explicitly. + </para> + <para> + Default: The value of <quote>id_provider</quote> is + used if it is set. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>session_provider (string)</term> + <listitem> + <para> + The provider which configures and manages user session + related tasks. The only user session task currently + provided is the integration with Fleet Commander, which + works only with IPA. + Supported session providers are: + </para> + <para> + <quote>ipa</quote> to allow performing user session + related tasks. + </para> + <para> + <quote>none</quote> does not perform any kind of user + session related tasks. + </para> + <para> + Default: <quote>id_provider</quote> is used if it + is set and can perform session related tasks. + </para> + <para> + <emphasis>NOTE:</emphasis> In order to have this feature + working as expected SSSD must be running as "root" and + not as the unprivileged user. + </para> + </listitem> + </varlistentry> + + <varlistentry condition="with_autofs"> + <term>autofs_provider (string)</term> + <listitem> + <para> + The autofs provider used for the domain. + Supported autofs providers are: + </para> + <para> + <quote>ldap</quote> to load maps stored in LDAP. See + <citerefentry> + <refentrytitle>sssd-ldap</refentrytitle> + <manvolnum>5</manvolnum> + </citerefentry> for more information on configuring LDAP. + </para> + <para> + <quote>ipa</quote> to load maps stored in an IPA + server. See + <citerefentry> + <refentrytitle>sssd-ipa</refentrytitle> + <manvolnum>5</manvolnum> + </citerefentry> for more information on configuring IPA. + </para> + <para> + <quote>ad</quote> to load maps stored in an AD + server. See + <citerefentry> + <refentrytitle>sssd-ad</refentrytitle> + <manvolnum>5</manvolnum> + </citerefentry> for more information on configuring + the AD provider. + </para> + <para> + <quote>none</quote> disables autofs explicitly. + </para> + <para> + Default: The value of <quote>id_provider</quote> is used if it + is set. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>hostid_provider (string)</term> + <listitem> + <para> + The provider used for retrieving host identity information. + Supported hostid providers are: + </para> + <para> + <quote>ipa</quote> to load host identity stored in an IPA + server. See + <citerefentry> + <refentrytitle>sssd-ipa</refentrytitle> + <manvolnum>5</manvolnum> + </citerefentry> for more information on configuring IPA. + </para> + <para> + <quote>none</quote> disables hostid explicitly. + </para> + <para> + Default: The value of <quote>id_provider</quote> is used if it + is set. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>resolver_provider (string)</term> + <listitem> + <para> + The provider which should handle hosts and networks + lookups. Supported resolver providers are: + </para> + <para> + <quote>proxy</quote> to forward lookups to another + NSS library. See <quote>proxy_resolver_lib_name</quote> + </para> + <para> + <quote>ldap</quote> to fetch hosts and networks stored in LDAP. See + <citerefentry> + <refentrytitle>sssd-ldap</refentrytitle> + <manvolnum>5</manvolnum> + </citerefentry> for more information on configuring LDAP. + </para> + <para> + <quote>ad</quote> to fetch hosts and networks stored in AD. See + <citerefentry> + <refentrytitle>sssd-ad</refentrytitle> + <manvolnum>5</manvolnum> + </citerefentry> for more information on configuring + the AD provider. + </para> + <para> + <quote>none</quote> disallows fetching hosts and networks explicitly. + </para> + <para> + Default: The value of <quote>id_provider</quote> is used if it + is set. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>re_expression (string)</term> + <listitem> + <para> + Regular expression for this domain that describes + how to parse the string containing user name and + domain into these components. + The "domain" can match either the SSSD + configuration domain name, or, in the case + of IPA trust subdomains and Active Directory + domains, the flat (NetBIOS) name of the domain. + </para> + <para> + Default: <quote>^((?P<name>.+)@(?P<domain>[^@]*)|(?P<name>[^@]+))$</quote> + + which allows two different styles for user names: + <itemizedlist> + <listitem> + <para>username</para> + </listitem> + <listitem> + <para>username@domain.name</para> + </listitem> + </itemizedlist> + </para> + <para> + Default for the AD and IPA provider: + <quote>^(((?P<domain>[^\\]+)\\(?P<name>.+))|((?P<name>.+)@(?P<domain>[^@]+))|((?P<name>[^@\\]+)))$</quote> + + which allows three different styles for user names: + <itemizedlist> + <listitem> + <para>username</para> + </listitem> + <listitem> + <para>username@domain.name</para> + </listitem> + <listitem> + <para>domain\username</para> + </listitem> + </itemizedlist> + While the first two correspond to the general + default the third one is introduced to allow easy + integration of users from Windows domains. + </para> + <para> + The default re_expression uses the <quote>@</quote> + character as a separator between the name and the + domain. As a result of this setting the default + does not accept the <quote>@</quote> character in + short names (as it is allowed in Windows group + names). If a user wishes to use short names with + <quote>@</quote> they must create their own + re_expression. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>full_name_format (string)</term> + <listitem> + <para> + A <citerefentry> + <refentrytitle>printf</refentrytitle> + <manvolnum>3</manvolnum> + </citerefentry>-compatible format that describes how to + compose a fully qualified name from user name + and domain name components. + </para> + <para> + The following expansions are supported: + <variablelist> + <varlistentry> + <term>%1$s</term> + <listitem><para>user name</para></listitem> + </varlistentry> + <varlistentry> + <term>%2$s</term> + <listitem> + <para> + domain name as specified in the + SSSD config file. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>%3$s</term> + <listitem> + <para> + domain flat name. Mostly usable + for Active Directory domains, both + directly configured or discovered + via IPA trusts. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + <para> + Default: <quote>%1$s@%2$s</quote>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>lookup_family_order (string)</term> + <listitem> + <para> + Provides the ability to select preferred address family + to use when performing DNS lookups. + </para> + <para> + Supported values: + </para> + <para> + ipv4_first: Try looking up IPv4 address, if that fails, try IPv6 + </para> + <para> + ipv4_only: Only attempt to resolve hostnames to IPv4 addresses. + </para> + <para> + ipv6_first: Try looking up IPv6 address, if that fails, try IPv4 + </para> + <para> + ipv6_only: Only attempt to resolve hostnames to IPv6 addresses. + </para> + <para> + Default: ipv4_first + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>dns_resolver_server_timeout (integer)</term> + <listitem> + <para> + Defines the amount of time (in milliseconds) + SSSD would try to talk to DNS server before + trying next DNS server. + </para> + <para> + The AD provider will use this option for the + CLDAP ping timeouts as well. + </para> + <para> + Please see the section <quote>FAILOVER</quote> + for more information about the service + resolution. + </para> + <para> + Default: 1000 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>dns_resolver_op_timeout (integer)</term> + <listitem> + <para> + Defines the amount of time (in seconds) to + wait to resolve single DNS query + (e.g. resolution of a hostname or an SRV record) + before trying the next hostname or DNS discovery. + </para> + <para> + Please see the section <quote>FAILOVER</quote> + for more information about the service + resolution. + </para> + <para> + Default: 3 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>dns_resolver_timeout (integer)</term> + <listitem> + <para> + Defines the amount of time (in seconds) to + wait for a reply from the internal fail over + service before assuming that the service is + unreachable. If this timeout is reached, the + domain will continue to operate in offline mode. + </para> + <para> + Please see the section <quote>FAILOVER</quote> + for more information about the service + resolution. + </para> + <para> + Default: 6 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>dns_resolver_use_search_list (bool)</term> + <listitem> + <para> + Normally, the DNS resolver searches the domain + list defined in the "search" directive from the + resolv.conf file. This can lead to delays in + environments with improperly configured DNS. + </para> + <para> + If fully qualified domain names (or _srv_) are used + in the SSSD configuration, setting this option + to FALSE can prevent unnecessary DNS lookups in such + environments. + </para> + <para> + Default: TRUE + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>dns_discovery_domain (string)</term> + <listitem> + <para> + If service discovery is used in the back end, specifies + the domain part of the service discovery DNS query. + </para> + <para> + Default: Use the domain part of machine's hostname + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>override_gid (integer)</term> + <listitem> + <para> + Override the primary GID value with the one specified. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>case_sensitive (string)</term> + <listitem> + <para> + Treat user and group names as case sensitive. + Possible option values are: + <variablelist> + <varlistentry> + <term>True</term> + <listitem> + <para> + Case sensitive. This value is invalid + for AD provider. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>False</term> + <listitem> + <para>Case insensitive.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>Preserving</term> + <listitem> + <para> + Same as False (case insensitive), but + does not lowercase names in the result + of NSS operations. Note that name + aliases (and in case of services also + protocol names) are still lowercased in + the output. + </para> + <para> + If you want to set this value for + trusted domain with IPA provider, you + need to set it on both the client and + SSSD on the server. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + <para> + This option can be also set per subdomain or + inherited via + <emphasis>subdomain_inherit</emphasis>. + </para> + <para> + Default: True (False for AD provider) + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>subdomain_inherit (string)</term> + <listitem> + <para> + Specifies a list of configuration parameters that + should be inherited by a subdomain. Please note + that only selected parameters can be inherited. + Currently the following options can be inherited: + </para> + <para> + ldap_search_timeout + </para> + <para> + ldap_network_timeout + </para> + <para> + ldap_opt_timeout + </para> + <para> + ldap_offline_timeout + </para> + <para> + ldap_enumeration_refresh_timeout + </para> + <para> + ldap_enumeration_refresh_offset + </para> + <para> + ldap_purge_cache_timeout + </para> + <para> + ldap_purge_cache_offset + </para> + <para> + ldap_krb5_keytab (the value of krb5_keytab will be + used if ldap_krb5_keytab is not set explicitly) + </para> + <para> + ldap_krb5_ticket_lifetime + </para> + <para> + ldap_enumeration_search_timeout + </para> + <para> + ldap_connection_expire_timeout + </para> + <para> + ldap_connection_expire_offset + </para> + <para> + ldap_connection_idle_timeout + </para> + <para> + ldap_use_tokengroups + </para> + <para> + ldap_user_principal + </para> + <para> + ignore_group_members + </para> + <para> + auto_private_groups + </para> + <para> + case_sensitive + </para> + <para> + Example: + <programlisting> +subdomain_inherit = ldap_purge_cache_timeout + </programlisting> + </para> + <para> + Default: none + </para> + <para> + Note: This option only works with the IPA and + AD provider. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>subdomain_homedir (string)</term> + <listitem> + <para> + Use this homedir as default value for all subdomains + within this domain in IPA AD trust. + See <emphasis>override_homedir</emphasis> + for info about possible values. In addition to those, the + expansion below can only be used with + <emphasis>subdomain_homedir</emphasis>. + <variablelist> + <varlistentry> + <term>%F</term> + <listitem><para>flat (NetBIOS) name of a subdomain.</para></listitem> + </varlistentry> + </variablelist> + </para> + <para> + The value can be overridden by + <emphasis>override_homedir</emphasis> option. + </para> + <para> + Default: <filename>/home/%d/%u</filename> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>realmd_tags (string)</term> + <listitem> + <para> + Various tags stored by the realmd configuration service + for this domain. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>cached_auth_timeout (int)</term> + <listitem> + <para> + Specifies time in seconds since last successful + online authentication for which user will be + authenticated using cached credentials while + SSSD is in the online mode. If the credentials + are incorrect, SSSD falls back to online + authentication. + </para> + <para> + This option's value is inherited by all trusted + domains. At the moment it is not possible to set + a different value per trusted domain. + </para> + <para> + Special value 0 implies that this feature is + disabled. + </para> + <para> + Please note that if <quote>cached_auth_timeout</quote> + is longer than <quote>pam_id_timeout</quote> then the + back end could be called to handle + <quote>initgroups.</quote> + </para> + <para> + Default: 0 + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>local_auth_policy (string)</term> + <listitem> + <para> + Local authentication methods policy. Some backends + (i.e. LDAP, proxy provider) only support a password + based authentication, while others can handle PKINIT + based Smartcard authentication (AD, IPA), + two-factor authentication (IPA), or other methods + against a central instance. By default in such cases + authentication is only performed with the methods + supported by the backend. + </para> + <para> + There are three possible values for this option: + match, only, enable. <quote>match</quote> is + used to match offline and online states for Kerberos + methods. <quote>only</quote> ignores the online methods + and only offer the local ones. enable allows explicitly + defining the methods for local authentication. As an + example, <quote>enable:passkey</quote>, only enables + passkey for local authentication. Multiple enable values + should be comma-separated, such as + <quote>enable:passkey, enable:smartcard</quote> + </para> + <para> + Please note that if local Smartcard authentication + is enabled and a Smartcard is present, Smartcard + authentication will be preferred over the + authentication methods supported by the backend. + I.e. there will be a PIN prompt instead of e.g. a + password prompt. + </para> + <para> + The following configuration example allows local users + to authenticate locally using any enabled method + (i.e. smartcard, passkey). +<programlisting> +[domain/shadowutils] +id_provider = proxy +proxy_lib_name = files +auth_provider = none +local_auth_policy = only +</programlisting> + </para> + <para condition="with_files_provider"> + It is expected that the <quote>files</quote> + provider ignores the local_auth_policy option and + supports Smartcard authentication by default. + </para> + <para> + Default: match + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>auto_private_groups (string)</term> + <listitem> + <para> + This option takes any of three available values: + <variablelist> + <varlistentry> + <term>true</term> + <listitem> + <para> + Create user's private group unconditionally from user's UID number. + The GID number is ignored in this case. + </para> + <para> + NOTE: Because the GID number and the user private group + are inferred from the UID number, it is not supported + to have multiple entries with the same UID or GID number + with this option. In other words, enabling this option + enforces uniqueness across the ID space. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>false</term> + <listitem> + <para> + Always use the user's primary GID number. The GID number must refer + to a group object in the LDAP database. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>hybrid</term> + <listitem> + <para> + A primary group is autogenerated + for user entries whose UID + and GID numbers have the same + value and at the same time the + GID number does not correspond + to a real group object in LDAP. + If the values are the same, but + the primary GID in the user entry + is also used by a group object, + the primary GID of the user resolves + to that group object. + </para> + <para> + If the UID and GID of a user + are different, then the GID + must correspond to a group + entry, otherwise the GID is + simply not resolvable. + </para> + <para> + This feature is useful for + environments that wish to stop + maintaining a separate group + objects for the user private + groups, but also wish to retain + the existing user private groups. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + <para> + For subdomains, the default value is False for + subdomains that use assigned POSIX IDs and True + for subdomains that use automatic ID-mapping. + </para> + <para> + The value of auto_private_groups can either be set per subdomains + in a subsection, for example: +<programlisting> +[domain/forest.domain/sub.domain] +auto_private_groups = false +</programlisting> + or globally for all subdomains in the main domain section + using the subdomain_inherit option: +<programlisting> +[domain/forest.domain] +subdomain_inherit = auto_private_groups +auto_private_groups = false +</programlisting> + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + + <para> + Options valid for proxy domains. + + <variablelist> + <varlistentry> + <term>proxy_pam_target (string)</term> + <listitem> + <para> + The proxy target PAM proxies to. + </para> + <para> + Default: not set by default, you have to take an + existing pam configuration or create a new one and + add the service name here. As an alternative you + can enable local authentication with the + local_auth_policy option. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>proxy_lib_name (string)</term> + <listitem> + <para> + The name of the NSS library to use in proxy + domains. The NSS functions searched for in the + library are in the form of + _nss_$(libName)_$(function), for example + _nss_files_getpwent. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>proxy_resolver_lib_name (string)</term> + <listitem> + <para> + The name of the NSS library to use for hosts and + networks lookups in proxy domains. The NSS + functions searched for in the + library are in the form of + _nss_$(libName)_$(function), for example + _nss_dns_gethostbyname2_r. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>proxy_fast_alias (boolean)</term> + <listitem> + <para> + When a user or group is looked up by name in + the proxy provider, a second lookup by ID is + performed to "canonicalize" the name in case + the requested name was an alias. Setting this + option to true would cause the SSSD to perform + the ID lookup from cache for performance reasons. + </para> + <para> + Default: false + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>proxy_max_children (integer)</term> + <listitem> + <para> + This option specifies the number of pre-forked + proxy children. It is useful for high-load SSSD + environments where sssd may run out of available + child slots, which would cause some issues due to + the requests being queued. + </para> + <para> + Default: 10 + </para> + </listitem> + </varlistentry> + + </variablelist> + </para> + + <refsect2 id='app_domains'> + <title>Application domains</title> + <para> + SSSD, with its D-Bus interface (see + <citerefentry> + <refentrytitle>sssd-ifp</refentrytitle> + <manvolnum>5</manvolnum> + </citerefentry>) is appealing to applications + as a gateway to an LDAP directory where users and groups + are stored. However, contrary to the traditional SSSD + deployment where all users and groups either have POSIX + attributes or those attributes can be inferred from the + Windows SIDs, in many cases the users and groups in the + application support scenario have no POSIX attributes. + Instead of setting a + <quote>[domain/<replaceable>NAME</replaceable>]</quote> + section, the administrator can set up an + <quote>[application/<replaceable>NAME</replaceable>]</quote> + section that internally represents a domain with type + <quote>application</quote> optionally inherits settings + from a tradition SSSD domain. + </para> + <para> + Please note that the application domain must still be + explicitly enabled in the <quote>domains</quote> parameter + so that the lookup order between the application domain + and its POSIX sibling domain is set correctly. + </para> + <variablelist> + <title>Application domain parameters</title> + <varlistentry> + <term>inherit_from (string)</term> + <listitem> + <para> + The SSSD POSIX-type domain the application + domain inherits all settings from. The + application domain can moreover add its own + settings to the application settings that augment + or override the <quote>sibling</quote> + domain settings. + </para> + <para> + Default: Not set + </para> + </listitem> + </varlistentry> + </variablelist> + <para> + The following example illustrates the use of an application + domain. In this setup, the POSIX domain is connected to an LDAP + server and is used by the OS through the NSS responder. In addition, + the application domain also requests the telephoneNumber attribute, + stores it as the phone attribute in the cache and makes the phone + attribute reachable through the D-Bus interface. + </para> +<programlisting> +[sssd] +domains = appdom, posixdom + +[ifp] +user_attributes = +phone + +[domain/posixdom] +id_provider = ldap +ldap_uri = ldap://ldap.example.com +ldap_search_base = dc=example,dc=com + +[application/appdom] +inherit_from = posixdom +ldap_user_extra_attrs = phone:telephoneNumber +</programlisting> + </refsect2> + + </refsect1> + + <refsect1 id='trusted-domains'> + <title>TRUSTED DOMAIN SECTION</title> + <para> + Some options used in the domain section can also be used in the + trusted domain section, that is, in a section called + <quote>[domain/<replaceable>DOMAIN_NAME</replaceable>/<replaceable>TRUSTED_DOMAIN_NAME</replaceable>]</quote>. + Where DOMAIN_NAME is the actual joined-to base domain. Please refer + to examples below for explanation. + Currently supported options in the trusted domain section are: + </para> + <para>ldap_search_base,</para> + <para>ldap_user_search_base,</para> + <para>ldap_group_search_base,</para> + <para>ldap_netgroup_search_base,</para> + <para>ldap_service_search_base,</para> + <para>ldap_sasl_mech,</para> + <para>ad_server,</para> + <para>ad_backup_server,</para> + <para>ad_site,</para> + <para>use_fully_qualified_names</para> + <para>pam_gssapi_services</para> + <para>pam_gssapi_check_upn</para> + <para> + For more details about these options see their individual description + in the manual page. + </para> + </refsect1> + + <refsect1 id='certmap'> + <title>CERTIFICATE MAPPING SECTION</title> + <para> + To allow authentication with Smartcards and certificates SSSD must + be able to map certificates to users. This can be done by adding the + full certificate to the LDAP object of the user or to a local + override. While using the full certificate is required to use the + Smartcard authentication feature of SSH (see + <citerefentry> + <refentrytitle>sss_ssh_authorizedkeys</refentrytitle> + <manvolnum>8</manvolnum> + </citerefentry> + for details) it might be cumbersome or not even possible to do this + for the general case where local services use PAM for + authentication. + </para> + <para> + To make the mapping more flexible mapping and matching rules were + added to SSSD (see + <citerefentry> + <refentrytitle>sss-certmap</refentrytitle> + <manvolnum>5</manvolnum> + </citerefentry> + for details). + </para> + <para> + A mapping and matching rule can be added to the SSSD configuration + in a section on its own with a name like + <quote>[certmap/<replaceable>DOMAIN_NAME</replaceable>/<replaceable>RULE_NAME</replaceable>]</quote>. + In this section the following options are allowed: + </para> + <variablelist> + <varlistentry> + <term>matchrule (string)</term> + <listitem> + <para> + Only certificates from the Smartcard which matches this + rule will be processed, all others are ignored. + </para> + <para> + Default: KRB5:<EKU>clientAuth, i.e. only + certificates which have the Extended Key Usage + <quote>clientAuth</quote> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>maprule (string)</term> + <listitem> + <para> + Defines how the user is found for a given certificate. + </para> + <para> + Default: + <itemizedlist> + <listitem> + <para>LDAP:(userCertificate;binary={cert!bin}) + for LDAP based providers like + <quote>ldap</quote>, <quote>AD</quote> or + <quote>ipa</quote>.</para> + </listitem> + <listitem condition="with_files_provider"> + <para>The RULE_NAME for the <quote>files</quote> + provider which tries to find a user with the + same name.</para> + </listitem> + </itemizedlist> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>domains (string)</term> + <listitem> + <para> + Comma separated list of domain names the rule should be + applied. By default a rule is only valid in the domain + configured in sssd.conf. If the provider supports + subdomains this option can be used to add the rule to + subdomains as well. + </para> + <para> + Default: the configured domain in sssd.conf + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>priority (integer)</term> + <listitem> + <para> + Unsigned integer value defining the priority of the + rule. The higher the number the lower the priority. + <quote>0</quote> stands for the highest priority while + <quote>4294967295</quote> is the lowest. + </para> + <para> + Default: the lowest priority + </para> + </listitem> + </varlistentry> + </variablelist> + <para condition="with_files_provider"> + To make the configuration simple and reduce the amount of + configuration options the <quote>files</quote> provider has some + special properties: + <itemizedlist> + <listitem> + <para> + if maprule is not set the RULE_NAME name is assumed to + be the name of the matching user + </para> + </listitem> + <listitem> + <para> + if a maprule is used both a single user name or a + template like + <quote>{subject_rfc822_name.short_name}</quote> must + be in braces like e.g. <quote>(username)</quote> or + <quote>({subject_rfc822_name.short_name})</quote> + </para> + </listitem> + <listitem> + <para> + the <quote>domains</quote> option is ignored + </para> + </listitem> + </itemizedlist> + </para> + </refsect1> + + <refsect1 id='prompting_configuration'> + <title>PROMPTING CONFIGURATION SECTION</title> + <para> + If a special file + (<filename>/var/lib/sss/pubconf/pam_preauth_available</filename>) + exists SSSD's PAM module pam_sss will ask SSSD to figure out which + authentication methods are available for the user trying to log in. + Based on the results pam_sss will prompt the user for appropriate + credentials. + </para> + <para> + With the growing number of authentication methods and the + possibility that there are multiple ones for a single user the + heuristic used by pam_sss to select the prompting might not be + suitable for all use cases. The following options should provide a + better flexibility here. + </para> + <para> + Each supported authentication method has its own configuration + subsection under <quote>[prompting/...]</quote>. Currently there + are: + <variablelist> + <varlistentry> + <term>[prompting/password]</term> + <listitem> + <para>to configure password prompting, allowed options are: + <variablelist><varlistentry><term>password_prompt</term> + <listitem><para>to change the string of the password + prompt</para></listitem></varlistentry></variablelist> + </para> + </listitem> + </varlistentry> + </variablelist> + <variablelist> + <varlistentry> + <term>[prompting/2fa]</term> + <listitem> + <para>to configure two-factor authentication prompting, + allowed options are: + <variablelist><varlistentry><term>first_prompt</term> + <listitem><para>to change the string of the prompt for + the first factor </para></listitem> + </varlistentry> + <varlistentry><term>second_prompt</term> + <listitem><para>to change the string of the prompt for + the second factor </para></listitem> + </varlistentry> + <varlistentry><term>single_prompt</term> + <listitem><para>boolean value, if True there will be + only a single prompt using the value of first_prompt + where it is expected that both factors are entered as a + single string. Please note that both factors have to be + entered here, even if the second factor is + optional.</para></listitem> + </varlistentry> + </variablelist> + If the second factor is optional and it should be possible + to log in either only with the password or with both factors + two-step prompting has to be used. + </para> + </listitem> + </varlistentry> + </variablelist> + <variablelist> + <varlistentry condition="build_passkey"> + <term>[prompting/passkey]</term> + <listitem> + <para>to configure passkey authentication prompting, + allowed options are: + <variablelist> + <varlistentry> + <term>interactive</term> + <listitem> + <para>boolean value, if True prompt a message and wait + before testing the presence of a passkey device. + Recommended if your device doesn’t have a + tactile trigger. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>interactive_prompt</term> + <listitem> + <para>to change the message of the interactive prompt. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>touch</term> + <listitem> + <para>boolean value, if True prompt a message to + remind the user to touch the device. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>touch_prompt</term> + <listitem> + <para>to change the message of the touch prompt. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + <para> + It is possible to add a subsection for specific PAM services, + e.g. <quote>[prompting/password/sshd]</quote> to individual change + the prompting for this service. + </para> + </refsect1> + + <refsect1 id='example'> + <title>EXAMPLES</title> + <para> + 1. The following example shows a typical SSSD config. It does + not describe configuration of the domains themselves - refer to + documentation on configuring domains for more details. +<programlisting> +[sssd] +domains = LDAP +services = nss, pam +config_file_version = 2 + +[nss] +filter_groups = root +filter_users = root + +[pam] + +[domain/LDAP] +id_provider = ldap +ldap_uri = ldap://ldap.example.com +ldap_search_base = dc=example,dc=com + +auth_provider = krb5 +krb5_server = kerberos.example.com +krb5_realm = EXAMPLE.COM +cache_credentials = true + +min_id = 10000 +max_id = 20000 +enumerate = False +</programlisting> + </para> + <para> + 2. The following example shows configuration of IPA AD trust where + the AD forest consists of two domains in a parent-child structure. + Suppose IPA domain (ipa.com) has trust with AD domain(ad.com). + ad.com has child domain (child.ad.com). To enable shortnames in + the child domain the following configuration should be used. +<programlisting> +[domain/ipa.com/child.ad.com] +use_fully_qualified_names = false +</programlisting> + </para> + <para> + 3. The following example shows the configuration of a certificate + mapping rule. It is valid for the configured domain + <quote>my.domain</quote> and additionally for the subdomains + <quote>your.domain</quote> and uses the full certificate in the + search filter. +<programlisting> +[certmap/my.domain/rule_name] +matchrule = <ISSUER>^CN=My-CA,DC=MY,DC=DOMAIN$ +maprule = (userCertificate;binary={cert!bin}) +domains = my.domain, your.domain +priority = 10 +</programlisting> + </para> + </refsect1> + + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="include/seealso.xml" /> + +</refentry> +</reference> |