Red Hat Enterprise Linux 8 Essentials Book now available.
Purchase a copy of Red Hat Enterprise Linux 8 (RHEL 8) Essentials in eBook ($24.99) or Print ($36.99) format
Red Hat Enterprise Linux 8 Essentials Print and eBook (ePub/PDF/Kindle) editions contain 31 chapters and over 250 pages
This section describes how to install SSSD, how to run the service, and how to configure it for each type of supported information provider.
Run the following command to install SSSD and any dependencies, including the SSSD client:
# yum install sssd
SSSD requires very few dependencies and should install very quickly, depending on the speed of your network connection.
18.104.22.168.1. Upgrading from a Previous Version
Upgrading Using RPM Packages
If you are upgrading using RPM packages, the script will run automatically when you upgrade to the new version. This will upgrade the
/etc/sssd/sssd.conf file to the new format, and copy the existing version to
It may be necessary to run the upgrade script manually, either because you built SSSD from source files, or because you are using a platform that does not support the use of RPM packages. The synopsis for the script is as follows:
upgrade_config.py [ -f INFILE ] [ -o OUTFILE ] [ -verbose ] [ --no-backup ]
-f INFILE — the configuration file to upgrade. If not specified, this defaults to
-o OUTFILE — the name of the upgraded configuration file. If not specified, this defaults to
-verbose — produce more verbose output during the upgrade process
--no-backup — do not produce a back-up file. If not specified, this defaults to
22.214.171.124.2. Starting and Stopping SSSD
Before you start SSSD for the first time, you need to configure at least one domain. Refer to Section 8.2.5, “Configuring Domains”
for information on how to configure an SSSD domain.
You can use either the
service command or the
/etc/init.d/sssd script to control SSSD. For example, run the following command to start
# service sssd start
By default, SSSD is configured not to start automatically. There are two ways to change this behavior; if you use the Authentication Configuration tool to configure SSSD, it will reconfigure the default behavior so that SSSD starts when the machine boots. Alternatively, you can use the
chkconfig command, as follows:
# chkconfig sssd on
126.96.36.199. Configuring SSSD
The global configuration of SSSD is stored in the
/etc/sssd/sssd.conf file. This file consists of various sections, each of which contains a number of key/value pairs. Some keys accept multiple values; use commas to separate multiple values for such keys. This configuration file uses data types of string (no quotes required), integer and Boolean (with values of
FALSE). Comments are indicated by either a hash sign (#) or a semicolon (;) in the first column. The following example illustrates some of this syntax:
# Keys with single values
key1 = value
key2 = val2
# Keys with multiple values
key10 = val10,val11
You can use the
--config) parameter on the command line to specify a different configuration file for SSSD.
Refer to the sssd.conf(5) manual page for more information on global SSSD configuration options.
188.8.131.52.1. Configuring NSS
SSSD provides a new NSS module,
sssd_nss, so that you can configure your system to use SSSD to retrieve user information. Edit the
/etc/nsswitch.conf file for your system to use the
sss name database. For example:
passwd: files sss
group: files sss
184.108.40.206.2. Configuring PAM
Use extreme care when changing your PAM configuration. A mistake in the PAM configuration file can lock you out of the system completely. Always back up your configuration files before performing any changes, and keep a session open so that you can revert any changes you make should the need arise.
To enable your system to use SSSD for PAM, you need to edit the default PAM configuration file. On Red Hat Enterprise Linux—based systems, this is the
/etc/pam.d/system-auth file. Edit this file to reflect the following example, and then restart
# This file is auto-generated.
# User changes will be destroyed the next time authconfig is run.
auth required pam_env.so
auth sufficient pam_unix.so nullok try_first_pass
auth requisite pam_succeed_if.so uid >= 500 quiet
auth sufficient pam_sss.so use_first_pass
auth required pam_deny.so
account required pam_unix.so broken_shadow
account sufficient pam_localuser.so
account sufficient pam_succeed_if.so uid < 500 quiet
account [default=bad success=ok user_unknown=ignore] pam_sss.so
account required pam_permit.so
password requisite pam_cracklib.so try_first_pass retry=3
password sufficient pam_unix.so sha512 shadow nullok try_first_pass use_authtok
password sufficient pam_sss.so use_authtok
password required pam_deny.so
session required pam_mkhomedir.so umask=0022 skel=/etc/skel/
session optional pam_keyinit.so revoke
session required pam_limits.so
session [success=1 default=ignore] pam_succeed_if.so service in crond quiet use_uid
session sufficient pam_sss.so
session required pam_unix.so
220.127.116.11.2.1. Using Custom Home Directories with SSSD
If your LDAP users have home directories that are not in
/home, and if your system is configured to create home directories the first time your users log in, then these directories will be created with the wrong permissions. For example, instead of a typical home directory such as
/home/<username>, your users might have home directories that include their locale, such as
/home/<locale>/<username>. If this is true for your system, the following steps need to be taken (preemptively):
Apply the correct SELinux context and permissions from the
directory to the home directory that you use on your system. In the example above, the following command would achieve this result (replace the directory names with those that apply to your system):
# semanage fcontext -a -e /home /home/locale
Ensure the oddjob-mkhomedir package is installed on your system and then re-run the Authentication Configuration tool.
This package provides the
pam_oddjob_mkhomedir.so library, which the Authentication Configuration tool will then use to create your custom home directories. You need to use this library to create your home directories, and not the default
pam_mkhomedir.so library, because the latter cannot create SELinux labels.
The Authentication Configuration tool will automatically use the
pam_oddjob_mkhomedir.so library if it is available. Otherwise, it will default to using
If the preceding steps were not performed before the custom home directories were created, you can use the following commands to correct the permissions and SELinux contexts (again, replace the directory names with those that apply to your system):
# semanage fcontext -a -e /home /home/locale
# restorecon -R -v /home/locale
18.104.22.168.2.2. Using "include" Statements in PAM Configurations
Recent PAM implementations allow you to use
include statements in PAM configurations. For example:
session include system-auth
session optional pam_console.so
In the preceding example, if a
sufficient condition from
system-auth returns PAM_SUCCESS,
pam_console.so will not be executed.
22.214.171.124.3. Configuring Access Control
SSSD provides a rudimentary access control mechanism, offering two solutions based on the value of the
access_provider option in the
[domain/< section in the
126.96.36.199.3.1. The Simple Access Provider
The first of these solutions is known as the Simple Access Provider, and is based on the implementation of access or deny lists of usernames. To enable the Simple Access Provider, you need to set the
access_provider option to
simple, and then add usernames as a comma-separated list to either the
Using the Simple Access Provider
By using the Simple Access Provider, you can continue to support a number of network logins to maintain common network accounts on company or department laptops, but you might want to restrict the use of a particular laptop to one or two users. This means that even if a different user authenticated successfully against the same authentication provider, the Simple Access Provider would prevent that user from gaining access.
The following example demonstrates the use of the Simple Access Provider to grant access to two users. This example assumes that SSSD is correctly configured and
example.com is one of the domains specified in the
[sssd] section, and only shows the Simple Access Provider-specific options.
access_provider = simple
simple_allow_users = user1, user2
The Local ID provider does not support
simple as an access provider.
Access Control Rules
The Simple Access Provider adheres to the following three rules to determine which users should or should not be granted access:
If both lists are empty, access is granted.
simple_allow_users is set, only users from this list are allowed access. This setting supersedes the
simple_deny_users list (which would be redundant).
simple_allow_users list is empty, users are allowed access unless they appear in the
simple_deny_users is a configuration error. If this occurs, SSSD will output an error to the
/var/log/sssd/sssd_default.log log file when loading the back end, but continue to start normally. Future versions of SSSD will output an error and fail to start.
188.8.131.52.3.2. The LDAP Access Provider
The second access control solution uses the LDAP server itself as the access provider (
access_provider=ldap) and the associated filter option (
ldap_access_filter) to specify which users are granted access to the specified host. Note that these two options are codependent; if you use LDAP as your access provider then you must specify a value for the
ldap_access_filter option, otherwise all users will be denied access. If you are not using LDAP as your access provider, then the
ldap_access_filter option has no effect.
Using the LDAP Access Provider
The following example demonstrates the use of the LDAP Access Provider to grant access to members of the "allowedusers" group in LDAP. This example assumes that SSSD is correctly configured and
example.com is one of the domains specified in the
[sssd] section, and only shows the LDAP Access Provider-specific options.
access_provider = ldap
ldap_access_filter = memberOf=cn=allowedusers,ou=Groups,dc=example,dc=com
Offline caching for this feature is limited to determining whether or not the user's last online login attempt was successful. If they were granted access during their last login, they will continue to be granted access while offline, and vice-versa.
Refer to the sssd-ldap manual page for more information about using the LDAP Access Provider.
184.108.40.206.4. Configuring Failover
The failover feature allows back ends to automatically switch to a different server if the primary server fails. These servers are entered as a case-insensitive, comma-separated list in the
[domain/< sections of the
/etc/sssd/sssd.conf file, and listed in order of preference. This list can contain any number of servers.
For example, if you have configured a native LDAP domain, you could specify the following as your
ldap_uri = ldap://ldap0.mydomain.org, ldap://ldap1.mydomain.org, ldap://ldap2.mydomain.org
In this configuration,
ldap://ldap0.mydomain.org functions as the primary server. If this server fails, the SSSD failover mechanism first attempts to connect to
ldap1.mydomain.org, and if that server is unavailable, it then attempts to connect to
If the parameter that specifies which server to connect to for the specific domain (for example,
, …) is not specified, the back end defaults to using
Use service discovery
. Refer to Section 220.127.116.11.4.1, “Using SRV Records with Failover”
for more information on service discovery.
Do not use multiple
ldap_uri parameters to specify your failover servers. The failover servers must be entered as a comma-separated list of values for a single
ldap_uri parameter. If you enter multiple
ldap_uri parameters, SSSD only recognizes the last entry.
Future versions of SSSD will throw an error upon receiving additional
18.104.22.168.4.1. Using SRV Records with Failover
SSSD also supports the use of SRV records in its failover configuration. This means that you can specify a server that is later resolved into a list of specific servers using SRV requests. The
weight attributes of SRV records provide further opportunity for specifying which servers should be contacted first in the event that the primary server fails.
For every service with which you want to use service discovery, you need to add a special DNS record to your DNS server using the following form:
domain TTL priority weight port hostname
A typical configuration would contain multiple such records, each with a different priority (for failover) and different weights (for load balancing).
The client then makes an SRV DNS query to retrieve a list of host names, their priorities, and weights. These queries are of the form _
domain, for example,
_ldap._tcp._redhat.com. The client then sorts this list according to the priorities and weights, and connects to the first server in this sorted list.
For more information on SRV records, refer to RFC 2782
22.214.171.124.4.2. How the Failover Mechanism Works
The failover mechanism distinguishes between machines and services. The back end first tries to resolve the hostname of a given machine; if this resolution attempt fails, the machine is considered offline. No further attempts are made to connect to this machine for any other service. If the resolution attempt succeeds, the back end tries to connect to a service on this machine. If the service connection attempt fails, then only this particular service is considered offline and the back end automatically switches over to the next service. The machine is still considered online and might still be tried for another service.
The failover mechanism does not handle DNS A records with multiple IP addresses; instead it only uses the first address. DNS round-robin cannot be used for failover. Further, providing multiple A records does not provide failover. Only the first A record is used, and if a lookup attempt on the first record fails then the system attempts no further lookups. To find multiple servers with a single request, and thus implementing failover, SSSD relies on SRV resource records, as explained in Section 126.96.36.199.4.1, “Using SRV Records with Failover”
Further connection attempts are made to machines or services marked as offline after a specified period of time; this is currently hard coded to 30 seconds. If there are no more machines to try, the back end as a whole switches to offline mode, and then attempts to reconnect every 30 seconds.