From 255f4379bc20399b929b94f786436bd9790d72de Mon Sep 17 00:00:00 2001 From: Greg Hudson Date: Wed, 14 Mar 2012 21:06:01 +0000 Subject: [PATCH] Add plugin configuration documentation In the RST admin guide, add a page for host configuration, and include a subsection on registering, enabling, and disabling plugin modules. For now, do not cover the private KDB and authdata plugin interfaces. git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@25768 dc483132-0cff-0310-8789-dd5450dbe970 --- doc/rst_source/krb_admins/host_config.rst | 104 ++++++++++++++++++++++ doc/rst_source/krb_admins/index.rst | 1 + doc/rst_source/krb_plugindev/index.rst | 4 +- 3 files changed, 107 insertions(+), 2 deletions(-) create mode 100644 doc/rst_source/krb_admins/host_config.rst diff --git a/doc/rst_source/krb_admins/host_config.rst b/doc/rst_source/krb_admins/host_config.rst new file mode 100644 index 000000000..d7e5dac03 --- /dev/null +++ b/doc/rst_source/krb_admins/host_config.rst @@ -0,0 +1,104 @@ +Host configuration +================== + +All hosts running Kerberos software, whether they are clients, +application servers, or KDCs, can be configured using +:ref:`krb5.conf(5)`. Here we describe some of the behavior changes +you might want to make. + + +.. _plugin_config: + +Plugin module configuration +--------------------------- + +Many aspects of Kerberos behavior, such as client preauthentication +and KDC service location, can be modified through the use of plugin +modules. For most of these behaviors, you can use the :ref:`plugins` +section of krb5.conf to register third-party modules, and to switch +off registered or built-in modules. + +A plugin module takes the form of a Unix shared object +(``modname.so``) or Windows DLL (``modname.dll``). If you have +installed a third-party plugin module and want to register it, you do +so using the **module** directive in the appropriate subsection of the +[plugins] section. For example, to register a client +preauthentication plugin for one-time password authentication +installed at ``/path/to/otp.so``, you could write:: + + [plugins] + clpreauth = { + module = /path/to/otp.so + } + +Many of the pluggable behaviors in MIT krb5 contain built-in modules +which can be switched off. You can disable a built-in module (or one +you have registered) using the **disable** directive in the +appropriate subsection of the [plugins] section. For example, to +disable the use of .k5identity files to select credential caches, you +could write:: + + [plugins] + ccselect = { + disable = k5identity + } + +If you want to disable multiple modules, specify the **disable** +directive multiple times, giving one module to disable each time. + +Alternatively, you can explicitly specify which modules you want to be +enabled for that behavior using the **enable_only** directive. For +example, to make :ref:`kadmind(8)` check password quality using only a +module you have registered, and no other mechanism, you could write:: + + [plugins] + pwqual = { + module = /path/to/mymodule.so + enable_only = mymodule + } + +Again, if you want to specify multiple modules, specify the +**enable_only** directive multiple times, giving one module to enable +each time. + +Some Kerberos interfaces use different mechanisms to register plugin +modules. + + +KDC location modules +~~~~~~~~~~~~~~~~~~~~ + +For historical reasons, modules to control how KDC servers are located +are registered simply by placing the shared object or DLL into the +"libkrb5" subdirectory of the krb5 plugin directory, which defaults to +``/usr/local/lib/krb5/plugins``. For example, Samba's winbind krb5 +locator plugin would be registered by placing its shared object in +``/usr/local/lib/krb5/plugins/libkrb5/winbind_krb5_locator.so``. + + +GSSAPI mechanism modules +~~~~~~~~~~~~~~~~~~~~~~~~ + +GSSAPI mechanism module are registered using the file +``/etc/gss/mech``. Each line in this file has the form:: + + oid pathname [options] + +where *oid* is the object identifier of the GSSAPI mechanism to be +registered, *pathname* is a path to the module shared object or DLL, +and *options* (if present) are options provided to the plugin module, +surrounded in square brackets. + + +Configuration profile modules +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A configuration profile module replaces the information source for +:ref:`krb5.conf(5)` itself. To use a profile module, begin krb5.conf +with the line:: + + module PATHNAME:STRING + +where *PATHNAME* is a path to the module shared object or DLL, and +*STRING* is a string to provide to the module. The module will then +take over, and the rest of krb5.conf will be ignored. diff --git a/doc/rst_source/krb_admins/index.rst b/doc/rst_source/krb_admins/index.rst index ff2110707..a714aedaa 100644 --- a/doc/rst_source/krb_admins/index.rst +++ b/doc/rst_source/krb_admins/index.rst @@ -13,6 +13,7 @@ Contents: database.rst conf_ldap.rst appl_servers.rst + host_config.rst backup_host.rst .. toctree:: diff --git a/doc/rst_source/krb_plugindev/index.rst b/doc/rst_source/krb_plugindev/index.rst index 640b67522..e913810bb 100644 --- a/doc/rst_source/krb_plugindev/index.rst +++ b/doc/rst_source/krb_plugindev/index.rst @@ -5,8 +5,8 @@ Kerberos plugin modules allow increased control over MIT krb5 library and server behavior. This guide describes how to create dynamic plugin modules and the currently available pluggable interfaces. -See :ref:`plugins` for information on how to register dynamic plugin -modules and how to enable and disable plugin modules via +See :ref:`plugin_config` for information on how to register dynamic +plugin modules and how to enable and disable modules via :ref:`krb5.conf(5)`. .. TODO: update the above reference when we have a free-form section -- 2.26.2