Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
SSSD-AD(5)		 File Formats and Conventions		    SSSD-AD(5)

       sssd-ad - the configuration file	for SSSD

       This manual page	describes the configuration of the AD provider for
       sssd(8).	For a detailed syntax reference, refer to the "FILE FORMAT"
       section of the sssd.conf(5) manual page.

       The AD provider is a back end used to connect to	an Active Directory
       server. This provider requires that the machine be joined to the	AD
       domain and a keytab is available.

       The AD provider supports	connecting to Active Directory 2008 R2 or
       later. Earlier versions may work, but are unsupported.

       The AD provider is able to provide identity information and
       authentication for entities from	trusted	domains	as well. Currently
       only trusted domains in the same	forest are recognized.

       The AD provider accepts the same	options	used by	the sssd-ldap(5)
       identity	provider and the sssd-krb5(5) authentication provider with
       some exceptions described below.

       However,	it is neither necessary	nor recommended	to set these options.
       The AD provider can also	be used	as an access, chpass and sudo
       provider. No configuration of the access	provider is required on	the
       client side.

       By default, the AD provider will	map UID	and GID	values from the
       objectSID parameter in Active Directory.	For details on this, see the
       "ID MAPPING" section below. If you want to disable ID mapping and
       instead rely on POSIX attributes	defined	in Active Directory, you
       should set

	   ldap_id_mapping = False

       In order	to retrieve users and groups using POSIX attributes from
       trusted domains,	the AD administrator must make sure that the POSIX
       attributes are replicated to the	Global Catalog.

       Users, groups and other entities	served by SSSD are always treated as
       case-insensitive	in the AD provider for compatibility with Active
       Directory's LDAP	implementation.

       Refer to	the section "DOMAIN SECTIONS" of the sssd.conf(5) manual page
       for details on the configuration	of an SSSD domain.

       ad_domain (string)
	   Specifies the name of the Active Directory domain. This is
	   optional. If	not provided, the configuration	domain name is used.

	   For proper operation, this option should be specified as the
	   lower-case version of the long version of the Active	Directory

	   The short domain name (also known as	the NetBIOS or the flat	name)
	   is autodetected by the SSSD.

       ad_server, ad_backup_server (string)
	   The comma-separated list of hostnames of the	AD servers to which
	   SSSD	should connect in order	of preference. For more	information on
	   failover and	server redundancy, see the "FAILOVER" section. This is
	   optional if autodiscovery is	enabled. For more information on
	   service discovery, refer to the "SERVICE DISCOVERY" section.

       ad_hostname (string)
	   Optional. May be set	on machines where the hostname(5) does not
	   reflect the fully qualified name used in the	Active Directory
	   domain to identify this host.

	   This	field is used to determine the host principal in use in	the
	   keytab. It must match the hostname for which	the keytab was issued.

       ad_enable_dns_sites (boolean)
	   Enables DNS sites - location	based service discovery.

	   If true and service discovery (see Service Discovery	paragraph at
	   the bottom of the man page) is enabled, the SSSD will first attempt
	   to discover the Active Directory server to connect to using the
	   Active Directory Site Discovery and fall back to the	DNS SRV
	   records if no AD site is found. The DNS SRV configuration,
	   including the discovery domain, is used during site discovery as

	   Default: true

       ad_access_filter	(boolean)
	   This	option specifies LDAP access control filter that the user must
	   match in order to be	allowed	access.	Please note that the
	   "access_provider" option must be explicitly set to "ad" in order
	   for this option to have an effect.

	   The option also supports specifying different filters per domain or
	   forest. This	extended filter	would consist of:
	   "KEYWORD:NAME:FILTER". The keyword can be either "DOM", "FOREST" or

	   If the keyword equals to "DOM" or is	missing, then "NAME" specifies
	   the domain or subdomain the filter applies to. If the keyword
	   equals to "FOREST", then the	filter equals to all domains from the
	   forest specified by "NAME".

	   Multiple filters can	be separated with the "?"  character,
	   similarly to	how search bases work.

	   The most specific match is always used. For example,	if the option
	   specified filter for	a domain the user is a member of and a global
	   filter, the per-domain filter would be applied. If there are	more
	   matches with	the same specification,	the first one is used.


	       # apply filter on domain	called dom1 only:

	       # apply filter on domain	called dom2 only:

	       # apply filter on forest	called EXAMPLE.COM only:

	   Default: Not	set

       ad_enable_gc (boolean)
	   By default, the SSSD	connects to the	Global Catalog first to
	   retrieve users from trusted domains and uses	the LDAP port to
	   retrieve group memberships or as a fallback.	Disabling this option
	   makes the SSSD only connect to the LDAP port	of the current AD

	   Please note that disabling Global Catalog support does not disable
	   retrieving users from trusted domains. The SSSD would connect to
	   the LDAP port of trusted domains instead. However, Global Catalog
	   must	be used	in order to resolve cross-domain group memberships.

	   Default: true

       dyndns_update (boolean)
	   Optional. This option tells SSSD to automatically update the	Active
	   Directory DNS server	with the IP address of this client. The	update
	   is secured using GSS-TSIG. As a consequence,	the Active Directory
	   administrator only needs to allow secure updates for	the DNS	zone.
	   The IP address of the AD LDAP connection is used for	the updates,
	   if it is not	otherwise specified by using the "dyndns_iface"

	   NOTE: On older systems (such	as RHEL	5), for	this behavior to work
	   reliably, the default Kerberos realm	must be	set properly in

	   Default: true

       dyndns_ttl (integer)
	   The TTL to apply to the client DNS record when updating it. If
	   dyndns_update is false this has no effect. This will	override the
	   TTL serverside if set by an administrator.

	   Default: 3600 (seconds)

       dyndns_iface (string)
	   Optional. Applicable	only when dyndns_update	is true. Choose	the
	   interface whose IP address should be	used for dynamic DNS updates.

	   Default: Use	the IP address of the AD LDAP connection

       dyndns_refresh_interval (integer)
	   How often should the	back end perform periodic DNS update in
	   addition to the automatic update performed when the back end	goes
	   online. This	option is optional and applicable only when
	   dyndns_update is true.

	   Default: 86400 (24 hours)

       dyndns_update_ptr (bool)
	   Whether the PTR record should also be explicitly updated when
	   updating the	client's DNS records. Applicable only when
	   dyndns_update is true.

	   Default: True

       dyndns_force_tcp	(bool)
	   Whether the nsupdate	utility	should default to using	TCP for
	   communicating with the DNS server.

	   Default: False (let nsupdate	choose the protocol)

       override_homedir	(string)
	   Override the	user's home directory. You can either provide an
	   absolute value or a template. In the	template, the following
	   sequences are substituted:

	       login name

	       UID number

	       domain name

	       fully qualified user name (user@domain)

	       The original home directory retrieved from the identity

	       The value of configure option homedir_substring.

	       a literal '%'

	   This	option can also	be set per-domain.


	       override_homedir	= /home/%u

	   Default: Not	set (SSSD will use the value retrieved from LDAP)

       homedir_substring (string)
	   The value of	this option will be used in the	expansion of the
	   override_homedir option if the template contains the	format string
	   %H. An LDAP directory entry can directly contain this template so
	   that	this option can	be used	to expand the home directory path for
	   each	client machine (or operating system). It can be	set per-domain
	   or globally in the [nss] section. A value specified in a domain
	   section will	override one set in the	[nss] section.

	   Default: /home

       krb5_use_enterprise_principal (boolean)
	   Specifies if	the user principal should be treated as	enterprise
	   principal. See section 5 of RFC 6806	for more details about
	   enterprise principals.

	   Default: true

	   Note	that this default differs from the traditional Kerberos
	   provider back end.

       The failover feature allows back	ends to	automatically switch to	a
       different server	if the current server fails.

   Failover Syntax
       The list	of servers is given as a comma-separated list; any number of
       spaces is allowed around	the comma. The servers are listed in order of
       preference. The list can	contain	any number of servers.

       For each	failover-enabled config	option,	two variants exist: primary
       and backup. The idea is that servers in the primary list	are preferred
       and backup servers are only searched if no primary servers can be
       reached.	If a backup server is selected,	a timeout of 31	seconds	is
       set. After this timeout SSSD will periodically try to reconnect to one
       of the primary servers. If it succeeds, it will replace the current
       active (backup) server.

   The Failover	Mechanism
       The failover mechanism distinguishes between a machine and a service.
       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

       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.

       The service discovery feature allows back ends to automatically find
       the appropriate servers to connect to using a special DNS query.	This
       feature is not supported	for backup servers.

       If no servers are specified, the	back end automatically uses service
       discovery to try	to find	a server. Optionally, the user may choose to
       use both	fixed server addresses and service discovery by	inserting a
       special keyword,	"_srv_", in the	list of	servers. The order of
       preference is maintained. This feature is useful	if, for	example, the
       user prefers to use service discovery whenever possible,	and fall back
       to a specific server when no servers can	be discovered using DNS.

   The domain name
       Please refer to the "dns_discovery_domain" parameter in the
       sssd.conf(5) manual page	for more details.

   The protocol
       The queries usually specify _tcp	as the protocol. Exceptions are
       documented in respective	option description.

   See Also
       For more	information on the service discovery mechanism,	refer to RFC

       The ID-mapping feature allows SSSD to act as a client of	Active
       Directory without requiring administrators to extend user attributes to
       support POSIX attributes	for user and group identifiers.

       NOTE: When ID-mapping is	enabled, the uidNumber and gidNumber
       attributes are ignored. This is to avoid	the possibility	of conflicts
       between automatically-assigned and manually-assigned values. If you
       need to use manually-assigned values, ALL values	must be

       Please note that	changing the ID	mapping	related	configuration options
       will cause user and group IDs to	change.	At the moment, SSSD does not
       support changing	IDs, so	the SSSD database must be removed. Because
       cached passwords	are also stored	in the database, removing the database
       should only be performed	while the authentication servers are
       reachable, otherwise users might	get locked out.	In order to cache the
       password, an authentication must	be performed. It is not	sufficient to
       use sss_cache(8)	to remove the database,	rather the process consists

       o   Making sure the remote servers are reachable

       o   Stopping the	SSSD service

       o   Removing the	database

       o   Starting the	SSSD service

       Moreover, as the	change of IDs might necessitate	the adjustment of
       other system properties such as file and	directory ownership, it's
       advisable to plan ahead and test	the ID mapping configuration

   Mapping Algorithm
       Active Directory	provides an objectSID for every	user and group object
       in the directory. This objectSID	can be broken up into components that
       represent the Active Directory domain identity and the relative
       identifier (RID)	of the user or group object.

       The SSSD	ID-mapping algorithm takes a range of available	UIDs and
       divides it into equally-sized component sections	- called "slices"-.
       Each slice represents the space available to an Active Directory

       When a user or group entry for a	particular domain is encountered for
       the first time, the SSSD	allocates one of the available slices for that
       domain. In order	to make	this slice-assignment repeatable on different
       client machines,	we select the slice based on the following algorithm:

       The SID string is passed	through	the murmurhash3	algorithm to convert
       it to a 32-bit hashed value. We then take the modulus of	this value
       with the	total number of	available slices to pick the slice.

       NOTE: It	is possible to encounter collisions in the hash	and subsequent
       modulus.	In these situations, we	will select the	next available slice,
       but it may not be possible to reproduce the same	exact set of slices on
       other machines (since the order that they are encountered will
       determine their slice). In this situation, it is	recommended to either
       switch to using explicit	POSIX attributes in Active Directory
       (disabling ID-mapping) or configure a default domain to guarantee that
       at least	one is always consistent. See "Configuration" for details.

       Minimum configuration (in the "[domain/DOMAINNAME]" section):

	   ldap_id_mapping = True
	   ldap_schema = ad

       The default configuration results in configuring	10,000 slices, each
       capable of holding up to	200,000	IDs, starting from 10,001 and going up
       to 2,000,100,000. This should be	sufficient for most deployments.

       Advanced	Configuration
	   ldap_idmap_range_min	(integer)
	       Specifies the lower bound of the	range of POSIX IDs to use for
	       mapping Active Directory	user and group SIDs.

	       NOTE: This option is different from "min_id" in that "min_id"
	       acts to filter the output of requests to	this domain, whereas
	       this option controls the	range of ID assignment.	This is	a
	       subtle distinction, but the good	general	advice would be	to
	       have "min_id" be	less-than or equal to "ldap_idmap_range_min"

	       Default:	200000

	   ldap_idmap_range_max	(integer)
	       Specifies the upper bound of the	range of POSIX IDs to use for
	       mapping Active Directory	user and group SIDs.

	       NOTE: This option is different from "max_id" in that "max_id"
	       acts to filter the output of requests to	this domain, whereas
	       this option controls the	range of ID assignment.	This is	a
	       subtle distinction, but the good	general	advice would be	to
	       have "max_id" be	greater-than or	equal to

	       Default:	2000200000

	   ldap_idmap_range_size (integer)
	       Specifies the number of IDs available for each slice. If	the
	       range size does not divide evenly into the min and max values,
	       it will create as many complete slices as it can.

	       Default:	200000

	   ldap_idmap_default_domain_sid (string)
	       Specify the domain SID of the default domain. This will
	       guarantee that this domain will always be assigned to slice
	       zero in the ID map, bypassing the murmurhash algorithm
	       described above.

	       Default:	not set

	   ldap_idmap_default_domain (string)
	       Specify the name	of the default domain.

	       Default:	not set

	   ldap_idmap_autorid_compat (boolean)
	       Changes the behavior of the ID-mapping algorithm	to behave more
	       similarly to winbind's "idmap_autorid" algorithm.

	       When this option	is configured, domains will be allocated
	       starting	with slice zero	and increasing monatomically with each
	       additional domain.

	       NOTE: This algorithm is non-deterministic (it depends on	the
	       order that users	and groups are requested). If this mode	is
	       required	for compatibility with machines	running	winbind, it is
	       recommended to also use the "ldap_idmap_default_domain_sid"
	       option to guarantee that	at least one domain is consistently
	       allocated to slice zero.

	       Default:	False

       The following example assumes that SSSD is correctly configured and is one of the domains in the	[sssd] section.	This example
       shows only the AD provider-specific options.

	   id_provider = ad
	   auth_provider = ad
	   access_provider = ad
	   chpass_provider = ad

	   ad_server =
	   ad_hostname =
	   ad_domain =

       The AD access control provider checks if	the account is expired.	It has
       the same	effect as the following	configuration of the LDAP provider:

	   access_provider = ldap
	   ldap_access_order = expire
	   ldap_account_expire_policy =	ad

       However,	unless the "ad"	access control provider	is explicitly
       configured, the default access provider is "permit".

       sssd(8),	sssd.conf(5), sssd-ldap(5), sssd-krb5(5), sssd-simple(5),
       sssd-ipa(5), sssd-ad(5),	sssd-sudo(5), sss_cache(8), sss_debuglevel(8),
       sss_groupadd(8),	sss_groupdel(8), sss_groupshow(8), sss_groupmod(8),
       sss_useradd(8), sss_userdel(8), sss_usermod(8), sss_obfuscate(8),
       sss_seed(8), sssd_krb5_locator_plugin(8), sss_ssh_authorizedkeys(8),
       sss_ssh_knownhostsproxy(8), sssd-ifp(5),	pam_sss(8).

       The SSSD	upstream -

SSSD				  08/28/2020			    SSSD-AD(5)


Want to link to this manual page? Use this URL:

home | help