1Host configuration 2================== 3 4All hosts running Kerberos software, whether they are clients, 5application servers, or KDCs, can be configured using 6:ref:`krb5.conf(5)`. Here we describe some of the behavior changes 7you might want to make. 8 9 10Default realm 11------------- 12 13In the :ref:`libdefaults` section, the **default_realm** realm 14relation sets the default Kerberos realm. For example:: 15 16 [libdefaults] 17 default_realm = ATHENA.MIT.EDU 18 19The default realm affects Kerberos behavior in the following ways: 20 21* When a principal name is parsed from text, the default realm is used 22 if no ``@REALM`` component is specified. 23 24* The default realm affects login authorization as described below. 25 26* For programs which operate on a Kerberos database, the default realm 27 is used to determine which database to operate on, unless the **-r** 28 parameter is given to specify a realm. 29 30* A server program may use the default realm when looking up its key 31 in a :ref:`keytab file <keytab_file>`, if its realm is not 32 determined by :ref:`domain_realm` configuration or by the server 33 program itself. 34 35* If :ref:`kinit(1)` is passed the **-n** flag, it requests anonymous 36 tickets from the default realm. 37 38In some situations, these uses of the default realm might conflict. 39For example, it might be desirable for principal name parsing to use 40one realm by default, but for login authorization to use a second 41realm. In this situation, the first realm can be configured as the 42default realm, and **auth_to_local** relations can be used as 43described below to use the second realm for login authorization. 44 45 46.. _login_authorization: 47 48Login authorization 49------------------- 50 51If a host runs a Kerberos-enabled login service such as OpenSSH with 52GSSAPIAuthentication enabled, login authorization rules determine 53whether a Kerberos principal is allowed to access a local account. 54 55By default, a Kerberos principal is allowed access to an account if 56its realm matches the default realm and its name matches the account 57name. (For historical reasons, access is also granted by default if 58the name has two components and the second component matches the 59default realm; for instance, ``alice/ATHENA.MIT.EDU@ATHENA.MIT.EDU`` 60is granted access to the ``alice`` account if ``ATHENA.MIT.EDU`` is 61the default realm.) 62 63The simplest way to control local access is using :ref:`.k5login(5)` 64files. To use these, place a ``.k5login`` file in the home directory 65of each account listing the principal names which should have login 66access to that account. If it is not desirable to use ``.k5login`` 67files located in account home directories, the **k5login_directory** 68relation in the :ref:`libdefaults` section can specify a directory 69containing one file per account uname. 70 71By default, if a ``.k5login`` file is present, it controls 72authorization both positively and negatively--any principal name 73contained in the file is granted access and any other principal name 74is denied access, even if it would have had access if the ``.k5login`` 75file didn't exist. The **k5login_authoritative** relation in the 76:ref:`libdefaults` section can be set to false to make ``.k5login`` 77files provide positive authorization only. 78 79The **auth_to_local** relation in the :ref:`realms` section for the 80default realm can specify pattern-matching rules to control login 81authorization. For example, the following configuration allows access 82to principals from a different realm than the default realm:: 83 84 [realms] 85 DEFAULT.REALM = { 86 # Allow access to principals from OTHER.REALM. 87 # 88 # [1:$1@$0] matches single-component principal names and creates 89 # a selection string containing the principal name and realm. 90 # 91 # (.*@OTHER\.REALM) matches against the selection string, so that 92 # only principals in OTHER.REALM are matched. 93 # 94 # s/@OTHER\.REALM$// removes the realm name, leaving behind the 95 # principal name as the account name. 96 auth_to_local = RULE:[1:$1@$0](.*@OTHER\.REALM)s/@OTHER\.REALM$// 97 98 # Also allow principals from the default realm. Omit this line 99 # to only allow access to principals in OTHER.REALM. 100 auth_to_local = DEFAULT 101 } 102 103The **auth_to_local_names** subsection of the :ref:`realms` section 104for the default realm can specify explicit mappings from principal 105names to local accounts. The key used in this subsection is the 106principal name without realm, so it is only safe to use in a Kerberos 107environment with a single realm or a tightly controlled set of realms. 108An example use of **auth_to_local_names** might be:: 109 110 [realms] 111 ATHENA.MIT.EDU = { 112 auth_to_local_names = { 113 # Careful, these match principals in any realm! 114 host/example.com = hostaccount 115 fred = localfred 116 } 117 } 118 119Local authorization behavior can also be modified using plugin 120modules; see :ref:`hostrealm_plugin` for details. 121 122 123.. _plugin_config: 124 125Plugin module configuration 126--------------------------- 127 128Many aspects of Kerberos behavior, such as client preauthentication 129and KDC service location, can be modified through the use of plugin 130modules. For most of these behaviors, you can use the :ref:`plugins` 131section of krb5.conf to register third-party modules, and to switch 132off registered or built-in modules. 133 134A plugin module takes the form of a Unix shared object 135(``modname.so``) or Windows DLL (``modname.dll``). If you have 136installed a third-party plugin module and want to register it, you do 137so using the **module** relation in the appropriate subsection of the 138[plugins] section. The value for **module** must give the module name 139and the path to the module, separated by a colon. The module name 140will often be the same as the shared object's name, but in unusual 141cases (such as a shared object which implements multiple modules for 142the same interface) it might not be. For example, to register a 143client preauthentication module named ``mypreauth`` installed at 144``/path/to/mypreauth.so``, you could write:: 145 146 [plugins] 147 clpreauth = { 148 module = mypreauth:/path/to/mypreauth.so 149 } 150 151Many of the pluggable behaviors in MIT krb5 contain built-in modules 152which can be switched off. You can disable a built-in module (or one 153you have registered) using the **disable** directive in the 154appropriate subsection of the [plugins] section. For example, to 155disable the use of .k5identity files to select credential caches, you 156could write:: 157 158 [plugins] 159 ccselect = { 160 disable = k5identity 161 } 162 163If you want to disable multiple modules, specify the **disable** 164directive multiple times, giving one module to disable each time. 165 166Alternatively, you can explicitly specify which modules you want to be 167enabled for that behavior using the **enable_only** directive. For 168example, to make :ref:`kadmind(8)` check password quality using only a 169module you have registered, and no other mechanism, you could write:: 170 171 [plugins] 172 pwqual = { 173 module = mymodule:/path/to/mymodule.so 174 enable_only = mymodule 175 } 176 177Again, if you want to specify multiple modules, specify the 178**enable_only** directive multiple times, giving one module to enable 179each time. 180 181Some Kerberos interfaces use different mechanisms to register plugin 182modules. 183 184 185KDC location modules 186~~~~~~~~~~~~~~~~~~~~ 187 188For historical reasons, modules to control how KDC servers are located 189are registered simply by placing the shared object or DLL into the 190"libkrb5" subdirectory of the krb5 plugin directory, which defaults to 191|libdir|\ ``/krb5/plugins``. For example, Samba's winbind krb5 192locator plugin would be registered by placing its shared object in 193|libdir|\ ``/krb5/plugins/libkrb5/winbind_krb5_locator.so``. 194 195 196.. _gssapi_plugin_config: 197 198GSSAPI mechanism modules 199~~~~~~~~~~~~~~~~~~~~~~~~ 200 201GSSAPI mechanism modules are registered using the file 202|sysconfdir|\ ``/gss/mech`` or configuration files in the 203|sysconfdir|\ ``/gss/mech.d`` directory with a ``.conf`` 204suffix. Each line in these files has the form:: 205 206 name oid pathname [options] <type> 207 208Only the name, oid, and pathname are required. *name* is the 209mechanism name, which may be used for debugging or logging purposes. 210*oid* is the object identifier of the GSSAPI mechanism to be 211registered. *pathname* is a path to the module shared object or DLL. 212*options* (if present) are options provided to the plugin module, 213surrounded in square brackets. *type* (if present) can be used to 214indicate a special type of module. Currently the only special module 215type is "interposer", for a module designed to intercept calls to 216other mechanisms. 217 218If the environment variable **GSS_MECH_CONFIG** is set, its value is 219used as the sole mechanism configuration filename. 220 221 222.. _profile_plugin_config: 223 224Configuration profile modules 225~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 226 227A configuration profile module replaces the information source for 228:ref:`krb5.conf(5)` itself. To use a profile module, begin krb5.conf 229with the line:: 230 231 module PATHNAME:STRING 232 233where *PATHNAME* is a path to the module shared object or DLL, and 234*STRING* is a string to provide to the module. The module will then 235take over, and the rest of krb5.conf will be ignored. 236