#  -*- text -*-
#
#
#  $Id: 9c8878d6aa455db8b25a95f314abea376d04b71b $

#######################################################################
#
#  = Kerberos Module
#
#  The `krb5` module enables the use of Kerberos 5 for authentication.
#
#  NOTE: This default config presumes you have the MIT Kerberos 5 distribution.
#
#  ## Configuration Settings
#
#  krb5 { ... }::
#
krb5 {
	#
	#  keytab:: Containing the key used by rlm_krb5.
	#
	keytab = /path/to/keytab

	#
	#  service_principal:: Principal that is used by rlm_krb5.
	#
	service_principal = name_of_principle

	#
	#  pool { ... }:: Pool of `krb5` contexts.
	#
	#  This allows us to make the module multithreaded and to avoid expensive
	#  operations like resolving and opening keytabs on every request.
	#  It may also allow TCP connections to the KDC to be cached if that is
	#  supported by the version of libkrb5 used.
	#
	#  NOTE: The context `pool` is only used if the underlying libkrb5 reported
	#  that it was thread safe at compile time.
	#
	pool {
		#
		#  start:: Connections to create during module instantiation.
		#
		#  If the server cannot create specified number of
		#  connections during instantiation it will exit.
		#  Set to `0` to allow the server to start without the
		#  external service being available.
		#
		start = 0

		#
		#  min:: Minimum number of connections to keep open.
		#
		min = 0

		#
		#  max:: Maximum number of connections.
		#
		#  If these connections are all in use and a new one
		#  is requested, the request will NOT get a connection.
		#
		#  Setting `max` to *LESS* than the number of threads means
		#  that some threads may starve, and you will see errors
		#  like _No connections available and at max connection limit_.
		#
		#  Setting `max` to MORE than the number of threads means
		#  that there are more connections than necessary.
		#
		#  If `max` is not specified, then it defaults to the number
		#  of workers configured.
		#
#		max =

		#
		#  spare:: Spare connections to be left idle.
		#
		#  NOTE: Idle connections WILL be closed if `idle_timeout`
		#  is set. This should be less than or equal to `max` above.
		#
		spare = 1

		#
		#  uses:: Number of uses before the connection is closed.
		#
		#  NOTE: A setting of `0` means infinite (no limit).
		#
		uses = 0

		#
		#  lifetime:: The lifetime (in seconds) of the connection.
		#
		#  NOTE: A setting of `0` means infinite (no limit).
		#
		lifetime = 0

		#
		#  idle_timeout:: The idle timeout (in seconds).  A connection which is
		#  unused for this length of time will be closed.
		#
		#  NOTE: A setting of `0` means infinite (no timeout).
		#
		idle_timeout = 0

		#
		#  [NOTE]
		#  ====
		#  All configuration settings are enforced.  If a
		#  connection is closed because of `idle_timeout`,
		#  `uses`, or `lifetime`, then the total number of
		#  connections MAY fall below `min`.  When that
		#  happens, it will open a new connection.  It will
		#  also log a WARNING message.
		#
		#  The solution is to either lower the `min` connections,
		#  or increase lifetime/idle_timeout.
		#  ====
		#
	}
}

#
#  ## Sample
#
#  You can configure the module with the following parameters:
#
#  [source, unlang]
#  ----
#  krb5 {
# 	# Keytab containing the key used by rlm_krb5
# 	keytab = /path/to/keytab
#
# 	# Principal that is used by rlm_krb5
# 	service_principal = radius/some.host.com
#  }
#  ----
#
#  Make sure the keytab is readable by the user that is used to run `radiusd` and
#  that your authorization configuration really uses `krb5` to do the
#  authentication. You will need to add the following to the `authenticate`
#  section of your `radiusd.conf` file:
#
#  [source, unlang]
#  Auth-Type Kerberos {
# 	krb5
#  }
#  ----
#
