.. highlight:: none

Frequently Asked Questions
--------------------------

What is the System Security Services Daemon?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

SSSD is a system daemon. Its primary function is to provide access to
identity and authentication remote resource through a common framework
that can provide caching and offline support to the system. It provides
PAM and NSS modules as well as a D-Bus interface interface for extended
user information.

An excellent write-up on SSSD was created by Marko Myllynen and
submitted to LWN.net: `SSSD: System Security Services
Daemon <http://lwn.net/Articles/457415/>`__

What platforms run SSSD?
^^^^^^^^^^^^^^^^^^^^^^^^

We are currently aware of the following GNU/Linux distributions shipping
some version of SSSD.

-  `Fedora Project <http://fedoraproject.org>`__ - This is the
   platform used by the original developers
-  `Red Hat Enterprise Linux <http://www.redhat.com>`__
-  `CentOS <http://www.centos.org>`__
-  `openSUSE <http://www.opensuse.org>`__
-  `Debian <http://www.debian.org>`__
-  `Ubuntu <http://www.ubuntu.com>`__
-  `Gentoo <http://www.gentoo.org>`__
-  `Mandriva <http://www.mandriva.org>`__
-  `Arch Linux <http://www.archlinux.org>`__ via
   `AUR <http://aur.archlinux.org/packages.php?K=sssd>`__

In theory, SSSD should compile and run (hopefully without modification)
on any modern GNU/Linux distribution. Non-Linux platforms such as the BSD
distributions are not yet fully supported, though some work is ongoing
to port SSSD to
`FreeBSD <http://portsmon.freebsd.org/portoverview.py?category=security&portname=sssd>`__

If you know of any other distributions shipping SSSD, please `tell
us <mailto:sssd-devel@lists.fedorahosted.org>`__!

What branches are maintained upstream at a given time?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

In general, the SSSD upstream supports at least one stable branch and
one LTM branch at the same time. The branches designated as LTM
(long-term maintenance) are supported for longer time than other
releases with fixes for important bugs and security patches.

The regular releases are more frequent than LTM releases and are intended
for users who like to use the latest functionality. The LTM releases are
targeted at users who prefer to run very stable codebase and don't need
the latest features.

An LTM release is maintained until the next LTM release comes out. After
that, the LTM released is declared as end-of-life, but may still receive
critical security fixes for up to one year to allow users to easily
migrate to the next LTM release.

For more detailed information on our releases, see our
`Releases <https://docs.pagure.org/SSSD.sssd/users/releases.html>`__ page.

Features
~~~~~~~~

.. FIXME: Any of the links referred on this section have already
          been migrated to pagure. Thus, this section, for now,
          has been commented out!

.. How do I configure SSSD to talk to an Active Directory server?
.. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
..
.. Our fantastic user community has contributed and maintains a wiki page
.. dedicated to this goal: `Configuring sssd to authenticate with a Windows
.. 2008 or later Domain
.. Server <link here>`__
..
.. Please be aware of `a possible slowdown when using referrals with Active
.. Directory <link here>`__

When should I enable enumeration in SSSD? or Why is enumeration disabled by default?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

"Enumeration" is SSSD's term for "reading in and displaying all the
values of a particular map (users, groups, etc.)". We disable this by
default in the SSSD in order to minimize the load on the servers with
which SSSD must communicate. In most operations, listing the complete set
of users or groups will never be necessary. Applications will generally
request information about specific users or groups.

Enumerating all entries has a negative impact in load on the server and
performance on the client (as we have to save all of the complex
relationships between users and the groups to which they belong in the
local cache). So because of this, we ship with enumerations disabled
(the same behavior as the Samba project's winbind).

You should only enable enumerations (and the resultant performance
issues) if you have applications or scripts in your environment that
absolutely must be able to retrieve the complete lists. In these cases,
enumeration can be enabled by setting ::

    [domain/<domainname>]
    enumerate = true
    ...

in your ``sssd.conf`` file.

Why does SSSD (1.7.0 and later) ignore source host[group] rules in HBAC?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

There are two serious problems with the srchost feature. In order to do
srchost processing, SSSD needs to trust the value passed to it by PAM
for the ``pam_data->srchost`` field. Unfortunately, the PAM
specification does not specify the format that this field must take.
Different login programs provide different values for this field (such
as IP address, short hostname or FQDN) and yet others simply pass a
value provided by the remote host. As a result, SSSD has no way of
verifying whether the remote client is actually who they say they are.

The second issue is that support of srchost rules requires significantly
more processing and bigger LDAP lookups, as every client is now required
to retrieve the complete list of hosts and hostgroups from the FreeIPA
server, where otherwise it would only need to download the specification
for the current host (and any groups that contain it). Eliminating the
srchost rules results in at least one order of magnitude performance
increase (more in slow LDAP environments).

So the combination of unreliability and slow performance resulted in our
making the decision to opt to disable the srchost rules by default
(treating them as "allow connection from any source"). It is possible to
re-enable these rules with ``ipa_hbac_support_srchost = True`` in
``sssd.conf``. However, note that recent IPA server releases do not
support this feature on the server side either.

What LDAP schema should I use?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The LDAP schema defines the set of default attribute names retrieved on
the server as well as meaning of some of the attributes, notably
membership attributes. The two most widely used schemas are rfc2307 and
rfc2307bis with rfc2307 being the default. When using the rfc2307
schema, group members are listed by name in the ``memberUid`` attribute.
When using the rfc2307bis schema, group members are listed by DN and
stored in the ``member`` (or sometimes ``uniqueMember``) attribute.

How do I configure caching of sudo rules or autofs maps?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The SSSD manual pages only contain reference documentation on the
options provided. However, two blog posts are available that describe
how to configure
`sudo <https://jhrozek.wordpress.com/2012/03/31/access-your-remote-sudo-rules-offline-with-sssd/>`__
and
`autofs <https://jhrozek.wordpress.com/2012/05/01/how-to-cache-automounter-maps-using-sssd/>`__
caching in a more tutorial-like form.

Why do some users appear as group members even if they are not?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Starting with SSSD 1.9.0, we took a different approach in how we store
group members for performance reasons. While this new approach provides
a notable performance boost, there are some situations when a user might
be removed from a nested group but still show up as a member of a parent
group.

When group information is requested, the SSSD doesn't download all the
information about all members, but rather just downloads the list of
user names and stores this list in the cache along with the group
object. The list of members is returned from cache until the group
object expires and is refreshed during an identity lookup such as
invoking getent group from shell or calling getgrnam from a C program.

On the other hand, the membership information is always refreshed during
a login, so that access control always operates on the most recent set
of data in order to avoid unauthorized access or denial of access.

Troubleshooting
~~~~~~~~~~~~~~~

Basics of Troubleshooting
^^^^^^^^^^^^^^^^^^^^^^^^^

When something is not working right, your first step should be to enable
debug logging. You can do this in any section in the ``sssd.conf`` file
by setting ``debug_level = N`` where N is a bitmask of log levels to
display. At the time of this writing (SSSD 1.7.0), the usage of each of
these levels is still a bit inconsistent, but we are standardizing on
the following levels: ::

    debug_level (integer)
        Bit mask that indicates which debug levels will be visible. 0x0010
        is the default value as well as the lowest allowed value, 0xFFF0 is
        the most verbose mode. This setting overrides the settings from
        config file.

        Currently supported debug levels:

        0x0010: Fatal failures. Anything that would prevent SSSD from
        starting up or causes it to cease running.

        0x0020: Critical failures. An error that doesn't kill the SSSD, but
        one that indicates that at least one major feature is not going to
        work properly.

        0x0040: Serious failures. An error announcing that a particular
        request or operation has failed.

        0x0080: Minor failures. These are the errors that would percolate
        down to cause the operation failure of 2.

        0x0100: Configuration settings.
        0x0200: Function data.

        0x0400: Trace messages for operation functions.

        0x1000: Trace messages for internal control functions.

        0x2000: Contents of function-internal variables that may be
        interesting.

        0x4000: Extremely low-level tracing information.

For backwards-compatibility, the log levels zero through nine map to the
above by including the specified level and lower.

Common Issues
^^^^^^^^^^^^^

I don't see any groups when I run 'id username'
'''''''''''''''''''''''''''''''''''''''''''''''

I don't see any group members when running 'getent group groupname'
'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''

This may be due to an incorrect ``ldap_schema`` setting in the
``[domain/DOMAINNAME]`` section of sssd.conf.

SSSD supports three LDAP schema types: RFC 2307, RFC 2307bis and IPA
(the last being an extension of RFC 2307bis including memberOf
backlinks).

By default, SSSD will use the more common RFC 2307 schema. The
difference between RFC 2307 and RFC 2307bis is the way which group
membership is stored in the LDAP server. In an RFC 2307 server, group
members are stored as the multi-valued attribute ``memberuid`` which
contains the *name* of the users that are members. In an RFC2307bis
server, group members are stored as the multi-valued attribute
``member`` (or sometimes ``uniqueMember``) which contains the *DN* of
the user or group that is a member of this group. RFC2307bis allows
nested groups to be maintained as well.

So the first thing to try when you hit this situation is to try setting
``ldap_schema = rfc2307bis``, deleting
``/var/lib/sss/db/cache_DOMAINNAME.ldb`` and restarting SSSD. If that
still doesn't work, add ``ldap_group_member = uniqueMember``, delete the
cache and restart once more. If that still doesn't work, it's time to
`file a bug <https://pagure.io/SSSD/sssd/new_issue>`__.

The recent glibc versions (Fedora 17 and later) also include a new NSS
database ``initgroups``, which defaults to ``files`` only. In order for
initgroups to function correctly, you can either append the ``sss``
module in the same way as ``passwd`` and ``group`` databases or comment
out the ``initgroups`` line completely. If your system configuration was
generated by authconfig, the ``initgroups`` line is commented out by
authconfig.

Authentication fails against LDAP
'''''''''''''''''''''''''''''''''

SSSD is stricter than pam\_ldap. In order to perform an authentication,
SSSD requires that the communication channel be encrypted. This means
that if ``sssd.conf`` has ``ldap_uri = ldap://<server>``, it will
attempt to encrypt the communication channel with TLS (transport layer
security). If ``sssd.conf`` has ``ldap_uri = ldaps://<server>``, then
SSL will be used instead of TLS. This requires that the LDAP server

#. Supports TLS or SSL
#. Has TLS access enabled on the standard LDAP port (389) (or alternate
   port, if specified in the ``ldap_uri`` or has SSL access enabled on
   the standard LDAPS port (or alternate port).
#. Has a valid certificate trust

The first two of these requirements must be handled by the LDAP server
administrator. Check with them that this is supported. If it is not,
tell them to add it! (Or find out if there are alternate, secure
authentication providers such as Kerberos available).

This last requirement is the cause of most issues with authenticating
against LDAP. If the client does not have proper trust of the LDAP
server certificate, it will be unable to validate the connection, and
SSSD will refuse to send the password. This is done because the LDAP
protocol requires that the password is sent plaintext to the LDAP
server. If the communication channel is not encrypted, it is trivial for
any computer on the network(s) between the client and server to sniff
the users' passwords. pam\_ldap allowed such authentications to occur,
but it was an inexcusable security breach.

If the certificate is not trusted, a syslog message is written,
indicating that TLS encryption could not be started, as well as any
additional information provided by the openldap libraries.

The first step to resolving this is to contact your LDAP server
administrator to acquire a copy of the public CA certificate for the
certificate authority used to sign the LDAP server certificate. This
should be placed on the filesystem and a directive should be added to
``sssd.conf`` to locate it: ``ldap_tls_cacert = /path/to/cacert``

If the LDAP server is self-signed (or for testing purposes while
awaiting a response from the server administrator), the config option
``ldap_tls_reqcert = never`` can be added to the ``sssd.conf``, which
will tell SSSD to blindly trust the certificate provided by the LDAP
server. **This is a security risk**. It is possible for an attacker to
run a man-in-the-middle attack if your clients are not properly
validating certificates against a CA. Do not set this option in
production.

If the logs aren't helping, you can verify your configuration by taking
the following steps: Verify that the services work when not called by
SSSD.

Using a LDAP server IP of 10.1.0.7 and a base of dc=example,dc=com, you
could search using a simple anonymous bind and with mandatory TLS to
confirm LDAP server connectivity using ldapsearch: ::

    ldapsearch -x -ZZ -H ldap://10.1.0.7 -b dc=example,dc=com

If this fails with ::

    ldap_start_tls: Connect error (-11) additional info: TLS error -8179:Unknown code ___f 13

most likely you do not have a correct CA certificate available in the
correct location.

One other common certificate issue is with servers that have multiple
hostnames. When connecting with SSL or TLS, the hostname used to connect
must include the fully-qualified domain name specified by the
certificate subject or subjectAltName. In most cases, this means that
specifying an LDAP URI with a numeric IP address will fail to work with
SSL/TLS.

Connection to LDAP servers on non-standard ports fail
'''''''''''''''''''''''''''''''''''''''''''''''''''''

On systems running SELinux in enforcing mode (such as Fedora, Red Hat
Enterprise Linux and CentOS), you need to modify your client machine's
SELinux policy to allow contacting that port. For example, if you are
communicating with an LDAP server running on port 1389, you would need
to run the command (as root): ::

    semanage port -a -t ldap_port_t -p tcp 1389

This tells the SELinux policy that port 1389 is defined as an LDAP port
(to which SSSD has access to talk). This would need to be done on each
of your client machines (or coordinated with some tool like puppet).

Referral chasing seems to be slowing down the SSSD
''''''''''''''''''''''''''''''''''''''''''''''''''

There can be a performance penalty if the SSSD performs a large number
of referral chasing operations. You can tell a referral rebind operation
from the logs: ::

    [sssd[be[EXAMPLE]]] [sdap_rebind_proc] (7): Successfully bind to [ldap://example.com/DC=example,DC=com].

Unless your environment requires the use of referrals, you can try
setting the ``ldap_referrals`` options to ``false`` and restarting the
SSSD. Some users have reported improved performance after turning the
referral chasing off especially in the case of Microsoft Active
Directory.

Troubleshooting
^^^^^^^^^^^^^^^

There are dedicated pages that describe `how to troubleshoot problems
<https://docs.pagure.org/SSSD.sssd/users/troubleshooting.html>`__ and
`how to submit a detailed bug report
<https://docs.pagure.org/SSSD.sssd/users/reporting_bugs.html>`__.

Getting help
^^^^^^^^^^^^

SSSD has a dedicated `user support mailing
list <https://lists.fedorahosted.org/archives/list/sssd-users@lists.fedorahosted.org/>`__.

SSSD development discussions occur either on the `SSSD development
list <https://lists.fedorahosted.org/archives/list/sssd-devel@lists.fedorahosted.org/>`__
or on the `#sssd IRC channel <irc://irc.freenode.net/sssd>`__ on
`freenode <http://freenode.net/>`__.

Tracking bugs and enhancement requests
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

If you think you have found a bug or would like to file an enhancement
request, create a `new issue
<https://pagure.io/SSSD/sssd/new_issue>`__.
Logging into the issue tracker requires a Fedora Account System login.
To create one, use the `FAS interface
<https://admin.fedoraproject.org/accounts/>`__.