1 files changed, 39 insertions, 0 deletions
diff --git a/doc/html/_sources/plugindev/hostrealm.txt b/doc/html/_sources/plugindev/hostrealm.txt
new file mode 100644
index 000000000000..4d488ef7bddc
--- /dev/null
+++ b/doc/html/_sources/plugindev/hostrealm.txt
@@ -0,0 +1,39 @@
+.. _hostrealm_plugin:
+
+Host-to-realm interface (hostrealm)
+===================================
+
+The host-to-realm interface was first introduced in release 1.12.  It
+allows modules to control the local mapping of hostnames to realm
+names as well as the default realm.  For a detailed description of the
+hostrealm interface, see the header file
+``<krb5/hostrealm_plugin.h>``.
+
+Although the mapping methods in the hostrealm interface return a list
+of one or more realms, only the first realm in the list is currently
+used by callers.  Callers may begin using later responses in the
+future.
+
+Any mapping method may return KRB5_PLUGIN_NO_HANDLE to defer
+processing to a later module.
+
+A module can create and destroy per-library-context state objects
+using the **init** and **fini** methods.  If the module does not need
+any state, it does not need to implement these methods.
+
+The optional **host_realm** method allows a module to determine
+authoritative realm mappings for a hostname.  The first authoritative
+mapping is used in preference to KDC referrals when getting service
+credentials.
+
+The optional **fallback_realm** method allows a module to determine
+fallback mappings for a hostname.  The first fallback mapping is tried
+if there is no authoritative mapping for a realm, and KDC referrals
+failed to produce a successful result.
+
+The optional **default_realm** method allows a module to determine the
+local default realm.
+
+If a module implements any of the above methods, it must also
+implement **free_list** to ensure that memory is allocated and
+deallocated consistently.