'\" t
.\"     Title: sssd_krb5_locator_plugin
.\"    Author: The SSSD upstream - https://github.com/SSSD/sssd/
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 02/10/2021
.\"    Manual: SSSD Manual pages
.\"    Source: SSSD
.\"  Language: English
.\"
.TH "SSSD_KRB5_LOCATOR_PL" "8" "02/10/2021" "SSSD" "SSSD Manual pages"
.\" -----------------------------------------------------------------
.\" * 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_krb5_locator_plugin \- Kerberos locator plugin
.SH "DESCRIPTION"
.PP
The Kerberos locator plugin
\fBsssd_krb5_locator_plugin\fR
is used by libkrb5 to find KDCs for a given Kerberos realm\&. SSSD provides such a plugin to guide all Kerberos clients on a system to a single KDC\&. In general it should not matter to which KDC a client process is talking to\&. But there are cases, e\&.g\&. after a password change, where not all KDCs are in the same state because the new data has to be replicated first\&. To avoid unexpected authentication failures and maybe even account lockings it would be good to talk to a single KDC as long as possible\&.
.PP
libkrb5 will search the locator plugin in the libkrb5 sub\-directory of the Kerberos plugin directory, see plugin_base_dir in
\fBkrb5.conf\fR(5)
for details\&. The plugin can only be disabled by removing the plugin file\&. There is no option in the Kerberos configuration to disable it\&. But the SSSD_KRB5_LOCATOR_DISABLE environment variable can be used to disable the plugin for individual commands\&. Alternatively the SSSD option krb5_use_kdcinfo=False can be used to not generate the data needed by the plugin\&. With this the plugin is still called but will provide no data to the caller so that libkrb5 can fall back to other methods defined in krb5\&.conf\&.
.PP
The plugin reads the information about the KDCs of a given realm from a file called
kdcinfo\&.REALM\&. The file should contain one or more DNS names or IP addresses either in dotted\-decimal IPv4 notation or the hexadecimal IPv6 notation\&. An optional port number can be added to the end separated with a colon, the IPv6 address has to be enclosed in squared brackets in this case as usual\&. Valid entries are:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
kdc\&.example\&.com
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
kdc\&.example\&.com:321
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
1\&.2\&.3\&.4
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
5\&.6\&.7\&.8:99
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
2001:db8:85a3::8a2e:370:7334
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
[2001:db8:85a3::8a2e:370:7334]:321
.RE
.sp
SSSD\*(Aqs krb5 auth\-provider which is used by the IPA and AD providers as well adds the address of the current KDC or domain controller SSSD is using to this file\&.
.PP
In environments with read\-only and read\-write KDCs where clients are expected to use the read\-only instances for the general operations and only the read\-write KDC for config changes like password changes a
kpasswdinfo\&.REALM
is used as well to identify read\-write KDCs\&. If this file exists for the given realm the content will be used by the plugin to reply to requests for a kpasswd or kadmin server or for the MIT Kerberos specific master KDC\&. If the address contains a port number the default KDC port 88 will be used for the latter\&.
.SH "NOTES"
.PP
Not all Kerberos implementations support the use of plugins\&. If
\fBsssd_krb5_locator_plugin\fR
is not available on your system you have to edit /etc/krb5\&.conf to reflect your Kerberos setup\&.
.PP
If the environment variable SSSD_KRB5_LOCATOR_DEBUG is set to any value debug messages will be sent to stderr\&.
.PP
If the environment variable SSSD_KRB5_LOCATOR_DISABLE is set to any value the plugin is disabled and will just return KRB5_PLUGIN_NO_HANDLE to the caller\&.
.PP
If the environment variable SSSD_KRB5_LOCATOR_IGNORE_DNS_FAILURES is set to any value plugin will try to resolve all DNS names in kdcinfo file\&. By default plugin returns KRB5_PLUGIN_NO_HANDLE to the caller immediately on first DNS resolving failure\&.
.SH "SEE ALSO"
.PP
\fBsssd\fR(8),
\fBsssd.conf\fR(5),
\fBsssd-ldap\fR(5),
\fBsssd-krb5\fR(5),
\fBsssd-simple\fR(5),
\fBsssd-ipa\fR(5),
\fBsssd-ad\fR(5),
\fBsssd-files\fR(5),
\fBsssd-sudo\fR(5),
\fBsssd-session-recording\fR(5),
\fBsss_cache\fR(8),
\fBsss_debuglevel\fR(8),
\fBsss_obfuscate\fR(8),
\fBsss_seed\fR(8),
\fBsssd_krb5_locator_plugin\fR(8),
\fBsss_ssh_authorizedkeys\fR(8), \fBsss_ssh_knownhostsproxy\fR(8),
\fBsssd-ifp\fR(5),
\fBpam_sss\fR(8)\&.
\fBsss_rpcidmapd\fR(5)
\fBsssd-systemtap\fR(5)
.SH "AUTHORS"
.PP
\fBThe SSSD upstream \- https://github\&.com/SSSD/sssd/\fR