1.. _hostrealm_plugin: 2 3Host-to-realm interface (hostrealm) 4=================================== 5 6The host-to-realm interface was first introduced in release 1.12. It 7allows modules to control the local mapping of hostnames to realm 8names as well as the default realm. For a detailed description of the 9hostrealm interface, see the header file 10``<krb5/hostrealm_plugin.h>``. 11 12Although the mapping methods in the hostrealm interface return a list 13of one or more realms, only the first realm in the list is currently 14used by callers. Callers may begin using later responses in the 15future. 16 17Any mapping method may return KRB5_PLUGIN_NO_HANDLE to defer 18processing to a later module. 19 20A module can create and destroy per-library-context state objects 21using the **init** and **fini** methods. If the module does not need 22any state, it does not need to implement these methods. 23 24The optional **host_realm** method allows a module to determine 25authoritative realm mappings for a hostname. The first authoritative 26mapping is used in preference to KDC referrals when getting service 27credentials. 28 29The optional **fallback_realm** method allows a module to determine 30fallback mappings for a hostname. The first fallback mapping is tried 31if there is no authoritative mapping for a realm, and KDC referrals 32failed to produce a successful result. 33 34The optional **default_realm** method allows a module to determine the 35local default realm. 36 37If a module implements any of the above methods, it must also 38implement **free_list** to ensure that memory is allocated and 39deallocated consistently. 40