<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE reference PUBLIC "-//OASIS//DTD DocBook V4.4//EN"

"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">

<reference>

<title>SSSD Manual pages</title>

<refentry>

<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="include/upstream.xml" />

<refmeta>

<refentrytitle>sssd.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 line comment starts with a hash sign (<quote>#</quote>) or a

semicolon (<quote>;</quote>)

</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='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.

</para>

<para>

Supported services: nss, pam

</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 described the list of domains

in the order you want them to be queried.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term>re_expression (string)</term>

<listitem>

<para>

Regular expression that describes how to parse the string

containing user name and domain into these components.

</para>

<para>

Default: <quote>(?P&lt;name&gt;[^@]+)@?(?P&lt;domain&gt;[^@]*$)</quote>

which translates to "the name is everything up to the

<quote>@</quote> sign, the domain everything after that"

</para>

<para>

PLEASE NOTE: the support for non-unique named

subpatterns is not available on all plattforms

(e.g. RHEL5 and SLES10). Only plattforms with

libpcre version 7 or higher can support non-unique

named subpatterns.

</para>

<para>

PLEASE NOTE ALSO: older version of libpcre only

support the Python syntax (?P&lt;name&gt;) to label

subpatterns.

</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

translate a (name, domain) tuple into a fully qualified

name.

</para>

<para>

Default: <quote>%1$s@%2$s</quote>.

</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>debug_level (integer)</term>

<listitem>

<para>

Sets the debug level for the service. The

value can be in range from 0 (only critical

messages) to 10 (very verbose).

</para>

<para>

Default: 0

</para>

</listitem>

</varlistentry>

<varlistentry>

<term>debug_timestamps (bool)</term>

<listitem>

<para>

Add a timestamp to the debug messages

</para>

<para>

Default: true

</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>command (string)</term>

<listitem>

<para>

By default, the executable

representing this service is called

<command>sssd_${service_name}</command>.

This directive allows to change the executable

name for the service. In the vast majority of

configurations, the default values should suffice.

</para>

<para>

Default: <command>sssd_${service_name}</command>

</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: 0

</para>

</listitem>

</varlistentry>

<varlistentry>

<term>entry_negative_timeout (integer)</term>

<listitem>

<para>

Specifies for how long 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>filter_users, filter_groups (string)</term>

<listitem>

<para>

Exclude certain users from being fetched from the sss

NSS database. This is particulary useful for system

accounts.

</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>

</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

enable offline authentication again.

</para>

<para>

Default: 5

</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>min_id,max_id (integer)</term>

<listitem>

<para>

UID limits for the domain. If a domain contains

entry that is outside these limits, it is ignored

</para>

<para>

Default: 1000 for min_id, 0 (no limit) for max_id

</para>

</listitem>

</varlistentry>

<varlistentry>

<term>timeout (integer)</term>

<listitem>

<para>

Timeout in seconds between heartbeats for this domain.

This is used to ensure that the backend process is

alive and capable of answering requests.

</para>

<para>

Default: 10

</para>

</listitem>

</varlistentry>

<varlistentry>

<term>enumerate (bool)</term>

<listitem>

<para>

Determines if a domain can be enumerated. 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: TRUE

</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>

Default: 600

</para>

</listitem>

</varlistentry>

<varlistentry>

<term>cache_credentials (bool)</term>

<listitem>

<para>

Determines if user credentials are also cached

in the local LDB cache

</para>

<para>

Default: FALSE

</para>

</listitem>

</varlistentry>

<varlistentry>

<term>id_provider (string)</term>

<listitem>

<para>

The Data Provider identity backend to use for this

domain.

</para>

<para>

Supported backends:

</para>

<para>

proxy: Support a legacy NSS provider

</para>

<para>

local: SSSD internal local provider

</para>

<para>

ldap: LDAP provider

</para>

</listitem>

</varlistentry>

<varlistentry>

<term>use_fully_qualified_names (bool)</term>

<listitem>

<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>

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>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.

</para>

<para>

<quote>deny</quote> always deny access.

</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>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>

<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>

</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.

</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>

</variablelist>

</para>

<refsect2 id='local_domain'>

<title>The local domain section</title>

<para>

This section contains settings for domain that stores users and

groups in SSSD native database, that is, a domain that uses

<replaceable>id_provider=local</replaceable>.

</para>

<variablelist>

<title>Section parameters</title>

<varlistentry>

<term>default_shell (string)</term>

<listitem>

<para>

The default shell for users created

with SSSD userspace tools.

</para>

<para>

Default: <filename>/bin/bash</filename>

</para>

</listitem>

</varlistentry>

<varlistentry>

<term>base_directory (string)</term>

<listitem>

<para>

The tools append the login name to

<replaceable>base_directory</replaceable> and

use that as the home directory.

</para>

<para>

Default: <filename>/home</filename>

</para>

</listitem>

</varlistentry>

<varlistentry>

<term>create_homedir (bool)</term>

<listitem>

<para>

Indicate if a home directory should be created by default for new users.

Can be overriden on command line.

</para>

<para>

Default: TRUE

</para>

</listitem>

</varlistentry>

<varlistentry>

<term>remove_homedir (bool)</term>

<listitem>

<para>

Indicate if a home directory should be removed by default for deleted users.

Can be overriden on command line.

</para>

<para>

Default: TRUE

</para>

</listitem>

</varlistentry>

<varlistentry>

<term>homedir_umask (integer)</term>

<listitem>

<para>

Used by

<citerefentry>

<refentrytitle>sss_useradd</refentrytitle>

<manvolnum>8</manvolnum>

</citerefentry> to specify the default permissions on a newly created

home directory.

</para>

<para>

Default: 077

</para>

</listitem>

</varlistentry>

<varlistentry>

<term>skel_dir (string)</term>

<listitem>

<para>

The skeleton directory, which contains files

and directories to be copied in the user's

home directory, when the home directory is

created by

<citerefentry>

<refentrytitle>sss_useradd</refentrytitle>

<manvolnum>8</manvolnum>

</citerefentry>

</para>

<para>

Default: <filename>/etc/skel</filename>

</para>

</listitem>

</varlistentry>

<varlistentry>

<term>mail_dir (string)</term>

<listitem>

<para>

The mail spool directory. This is needed to

manipulate the mailbox when its corresponding

user account is modified or deleted.

If not specified, a default

value is used.

</para>

<para>

Default: <filename>/var/mail</filename>

</para>

</listitem>

</varlistentry>

</variablelist>

</refsect2>

</refsect1>

<refsect1 id='example'>

<title>EXAMPLE</title>

<para>

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_kdcip = kerberos.example.com

krb5_realm = EXAMPLE.COM

cache_credentials = true

min_id = 10000

max_id = 20000

enumerate = true

</programlisting>

</para>

</refsect1>

<refsect1 id='see_also'>

<title>SEE ALSO</title>

<para>

<citerefentry>

<refentrytitle>sssd-ldap</refentrytitle><manvolnum>5</manvolnum>

</citerefentry>,

<citerefentry>

<refentrytitle>sssd-krb5</refentrytitle><manvolnum>5</manvolnum>

</citerefentry>,

<citerefentry>

<refentrytitle>sss_groupadd</refentrytitle><manvolnum>8</manvolnum>

</citerefentry>,

<citerefentry>

<refentrytitle>sss_groupdel</refentrytitle><manvolnum>8</manvolnum>

</citerefentry>,

<citerefentry>

<refentrytitle>sss_groupmod</refentrytitle><manvolnum>8</manvolnum>

</citerefentry>,

<citerefentry>

<refentrytitle>sss_useradd</refentrytitle><manvolnum>8</manvolnum>

</citerefentry>,

<citerefentry>

<refentrytitle>sss_userdel</refentrytitle><manvolnum>8</manvolnum>

</citerefentry>,

<citerefentry>

<refentrytitle>sss_usermod</refentrytitle><manvolnum>8</manvolnum>

</citerefentry>,

<citerefentry>

<refentrytitle>pam_sss</refentrytitle><manvolnum>8</manvolnum>

</citerefentry>.

</para>

</refsect1>

</refentry>

</reference>