'\" t
.\"     Title: sssd-ipa
.\"    Author: The SSSD upstream - http://fedorahosted.org/sssd
.\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
.\"      Date: 03/04/2013
.\"    Manual: File Formats and Conventions
.\"    Source: SSSD
.\"  Language: English
.\"
.TH "SSSD\-IPA" "5" "03/04/2013" "SSSD" "File Formats and Conventions"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
sssd-ipa \- the configuration file for SSSD
.SH "DESCRIPTION"
.PP
This manual page describes the configuration of the IPA provider for
\fBsssd\fR(8)\&. For a detailed syntax reference, refer to the
\(lqFILE FORMAT\(rq
section of the
\fBsssd.conf\fR(5)
manual page\&.
.PP
The IPA provider is a back end used to connect to an IPA server\&. (Refer to the freeipa\&.org web site for information about IPA servers\&.) This provider requires that the machine be joined to the IPA domain; configuration is almost entirely self\-discovered and obtained directly from the server\&.
.PP
The IPA provider accepts the same options used by the
\fBsssd-ldap\fR(5)
identity provider and the
\fBsssd-krb5\fR(5)
authentication provider with some exceptions described below\&.
.PP
However, it is neither necessary nor recommended to set these options\&. IPA provider can also be used as an access and chpass provider\&. As an access provider it uses HBAC (host\-based access control) rules\&. Please refer to freeipa\&.org for more information about HBAC\&. No configuration of access provider is required on the client side\&.
.SH "CONFIGURATION OPTIONS"
.PP
Refer to the section
\(lqDOMAIN SECTIONS\(rq
of the
\fBsssd.conf\fR(5)
manual page for details on the configuration of an SSSD domain\&.
.PP
ipa_domain (string)
.RS 4
Specifies the name of the IPA domain\&. This is optional\&. If not provided, the configuration domain name is used\&.
.RE
.PP
ipa_server (string)
.RS 4
The comma\-separated list of IP addresses or hostnames of the IPA servers to which SSSD should connect in the order of preference\&. For more information on failover and server redundancy, see the
\(lqFAILOVER\(rq
section\&. This is optional if autodiscovery is enabled\&. For more information on service discovery, refer to the the
\(lqSERVICE DISCOVERY\(rq
section\&.
.RE
.PP
ipa_hostname (string)
.RS 4
Optional\&. May be set on machines where the hostname(5) does not reflect the fully qualified name used in the IPA domain to identify this host\&.
.RE
.PP
ipa_dyndns_update (boolean)
.RS 4
Optional\&. This option tells SSSD to automatically update the DNS server built into FreeIPA v2 with the IP address of this client\&.
.sp
NOTE: On older systems (such as RHEL 5), for this behavior to work reliably, the default Kerberos realm must be set properly in /etc/krb5\&.conf
.sp
Default: false
.RE
.PP
ipa_dyndns_iface (string)
.RS 4
Optional\&. Applicable only when ipa_dyndns_update is true\&. Choose the interface whose IP address should be used for dynamic DNS updates\&.
.sp
Default: Use the IP address of the IPA LDAP connection
.RE
.PP
ipa_hbac_search_base (string)
.RS 4
Optional\&. Use the given string as search base for HBAC related objects\&.
.sp
Default: Use base DN
.RE
.PP
ipa_host_search_base (string)
.RS 4
Optional\&. Use the given string as search base for host objects\&.
.sp
See
\(lqldap_search_base\(rq
for information about configuring multiple search bases\&.
.sp
If filter is given in any of search bases and
\fIipa_hbac_support_srchost\fR
is set to False, the filter will be ignored\&.
.sp
Default: the value of
\fIldap_search_base\fR
.RE
.PP
ipa_selinux_search_base (string)
.RS 4
Optional\&. Use the given string as search base for SELinux user maps\&.
.sp
See
\(lqldap_search_base\(rq
for information about configuring multiple search bases\&.
.sp
Default: the value of
\fIldap_search_base\fR
.RE
.PP
krb5_validate (boolean)
.RS 4
Verify with the help of krb5_keytab that the TGT obtained has not been spoofed\&.
.sp
Default: true
.sp
Note that this default differs from the traditional Kerberos provider back end\&.
.RE
.PP
krb5_realm (string)
.RS 4
The name of the Kerberos realm\&. This is optional and defaults to the value of
\(lqipa_domain\(rq\&.
.sp
The name of the Kerberos realm has a special meaning in IPA \- it is converted into the base DN to use for performing LDAP operations\&.
.RE
.PP
krb5_canonicalize (boolean)
.RS 4
Specifies if the host and user principal should be canonicalized when connecting to IPA LDAP and also for AS requests\&. This feature is available with MIT Kerberos >= 1\&.7
.sp
Default: true
.RE
.PP
ipa_hbac_refresh (integer)
.RS 4
The amount of time between lookups of the HBAC rules against the IPA server\&. This will reduce the latency and load on the IPA server if there are many access\-control requests made in a short period\&.
.sp
Default: 5 (seconds)
.RE
.PP
ipa_hbac_treat_deny_as (string)
.RS 4
This option specifies how to treat the deprecated DENY\-type HBAC rules\&. As of FreeIPA v2\&.1, DENY rules are no longer supported on the server\&. All users of FreeIPA will need to migrate their rules to use only the ALLOW rules\&. The client will support two modes of operation during this transition period:
.sp

\fIDENY_ALL\fR: If any HBAC DENY rules are detected, all users will be denied access\&.
.sp

\fIIGNORE\fR: SSSD will ignore any DENY rules\&. Be very careful with this option, as it may result in opening unintended access\&.
.sp
Default: DENY_ALL
.RE
.PP
ipa_hbac_support_srchost (boolean)
.RS 4
If this is set to false, then srchost as given to SSSD by PAM will be ignored\&.
.sp
Note that if set to
\fIFalse\fR, this option casuses filters given in
\fIipa_host_search_base\fR
to be ignored;
.sp
Default: false
.RE
.PP
ipa_automount_location (string)
.RS 4
The automounter location this IPA client will be using
.sp
Default: The location named "default"
.RE
.PP
ipa_netgroup_member_of (string)
.RS 4
The LDAP attribute that lists netgroup\*(Aqs memberships\&.
.sp
Default: memberOf
.RE
.PP
ipa_netgroup_member_user (string)
.RS 4
The LDAP attribute that lists system users and groups that are direct members of the netgroup\&.
.sp
Default: memberUser
.RE
.PP
ipa_netgroup_member_host (string)
.RS 4
The LDAP attribute that lists hosts and host groups that are direct members of the netgroup\&.
.sp
Default: memberHost
.RE
.PP
ipa_netgroup_member_ext_host (string)
.RS 4
The LDAP attribute that lists FQDNs of hosts and host groups that are members of the netgroup\&.
.sp
Default: externalHost
.RE
.PP
ipa_netgroup_domain (string)
.RS 4
The LDAP attribute that contains NIS domain name of the netgroup\&.
.sp
Default: nisDomainName
.RE
.PP
ipa_host_object_class (string)
.RS 4
The object class of a host entry in LDAP\&.
.sp
Default: ipaHost
.RE
.PP
ipa_host_fqdn (string)
.RS 4
The LDAP attribute that contains FQDN of the host\&.
.sp
Default: fqdn
.RE
.PP
ipa_selinux_usermap_object_class (string)
.RS 4
The object class of a host entry in LDAP\&.
.sp
Default: ipaHost
.RE
.PP
ipa_selinux_usermap_name (string)
.RS 4
The LDAP attribute that contains the name of SELinux usermap\&.
.sp
Default: cn
.RE
.PP
ipa_selinux_usermap_member_user (string)
.RS 4
The LDAP attribute that contains all users / groups this rule match against\&.
.sp
Default: memberUser
.RE
.PP
ipa_selinux_usermap_member_host (string)
.RS 4
The LDAP attribute that contains all hosts / hostgroups this rule match against\&.
.sp
Default: memberHost
.RE
.PP
ipa_selinux_usermap_see_also (string)
.RS 4
The LDAP attribute that contains DN of HBAC rule which can be used for matching instead of memberUser and memberHost
.sp
Default: seeAlso
.RE
.PP
ipa_selinux_usermap_selinux_user (string)
.RS 4
The LDAP attribute that contains SELinux user string itself\&.
.sp
Default: ipaSELinuxUser
.RE
.PP
ipa_selinux_usermap_enabled (string)
.RS 4
The LDAP attribute that contains whether or not is user map enabled for usage\&.
.sp
Default: ipaEnabledFlag
.RE
.PP
ipa_selinux_usermap_user_category (string)
.RS 4
The LDAP attribute that contains user category such as \*(Aqall\*(Aq\&.
.sp
Default: userCategory
.RE
.PP
ipa_selinux_usermap_host_category (string)
.RS 4
The LDAP attribute that contains host category such as \*(Aqall\*(Aq\&.
.sp
Default: hostCategory
.RE
.PP
ipa_selinux_usermap_uuid (string)
.RS 4
The LDAP attribute that contains unique ID of the user map\&.
.sp
Default: ipaUniqueID
.RE
.PP
ipa_host_ssh_public_key (string)
.RS 4
The LDAP attribute that contains the host\*(Aqs SSH public keys\&.
.sp
Default: ipaSshPubKey
.RE
.SH "FAILOVER"
.PP
The failover feature allows back ends to automatically switch to a different server if the primary server fails\&.
.SS "Failover Syntax"
.PP
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\&.
.SS "The Failover Mechanism"
.PP
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 service\&.
.PP
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\&.
.PP
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\&.
.SH "SERVICE DISCOVERY"
.PP
The service discovery feature allows back ends to automatically find the appropriate servers to connect to using a special DNS query\&.
.SS "Configuration"
.PP
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,
\(lq_srv_\(rq, 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\&.
.SS "The domain name"
.PP
Please refer to the
\(lqdns_discovery_domain\(rq
parameter in the
\fBsssd.conf\fR(5)
manual page for more details\&.
.SS "The protocol"
.PP
The queries usually specify _tcp as the protocol\&. Exceptions are documented in respective option description\&.
.SS "See Also"
.PP
For more information on the service discovery mechanism, refer to RFC 2782\&.
.SH "EXAMPLE"
.PP
The following example assumes that SSSD is correctly configured and example\&.com is one of the domains in the
\fI[sssd]\fR
section\&. This examples shows only the ipa provider\-specific options\&.
.PP

.sp
.if n \{\
.RS 4
.\}
.nf
    [domain/example\&.com]
    id_provider = ipa
    ipa_server = ipaserver\&.example\&.com
    ipa_hostname = myhost\&.example\&.com
.fi
.if n \{\
.RE
.\}
.sp
.SH "SEE ALSO"
.PP

\fBsssd.conf\fR(5),
\fBsssd-ldap\fR(5),
\fBsssd-krb5\fR(5),
\fBsssd\fR(8)
.SH "AUTHORS"
.PP
\fBThe SSSD upstream \- http://fedorahosted\&.org/sssd\fR