Author: pzampino
Date: Fri Apr 11 18:25:56 2025
New Revision: 1925021
URL: http://svn.apache.org/viewvc?rev=1925021&view=rev
Log:
Added KNOX-3130 content - ehcache support for Shiro
Modified:
knox/site/books/knox-2-1-0/user-guide.html
knox/site/index.html
knox/site/issue-management.html
knox/site/licenses.html
knox/site/mailing-lists.html
knox/site/project-info.html
knox/site/team.html
knox/trunk/books/2.1.0/config_ldap_authc_cache.md
Modified: knox/site/books/knox-2-1-0/user-guide.html
URL:
http://svn.apache.org/viewvc/knox/site/books/knox-2-1-0/user-guide.html?rev=1925021&r1=1925020&r2=1925021&view=diff
==============================================================================
--- knox/site/books/knox-2-1-0/user-guide.html (original)
+++ knox/site/books/knox-2-1-0/user-guide.html Fri Apr 11 18:25:56 2025
@@ -3587,7 +3587,7 @@ ldapRealm.userDnTemplate=uid={0},ou=peop
</code></pre>
<h3><a id="LDAP+Authentication+Caching">LDAP Authentication Caching</a> <a
href="#LDAP+Authentication+Caching"><img
src="markbook-section-link.png"/></a></h3>
<p>Knox can be configured to cache LDAP authentication information. Knox
leverages Shiro’s built in caching mechanisms and has been tested with
Shiro’s EhCache cache manager implementation.</p>
-<p>The following provider snippet demonstrates how to configure turning on the
cache using the ShiroProvider. In addition to using
<code>org.apache.knox.gateway.shirorealm.KnoxLdapRealm</code> in the Shiro
configuration, and setting up the cache you <em>must</em> set the flag for
enabling caching authentication to true. Please see the property,
<code>main.ldapRealm.authenticationCachingEnabled</code> below.</p>
+<p>The following provider snippet demonstrates how to configure turning on the
cache using the ShiroProvider. In addition to using
<code>org.apache.knox.gateway.shirorealm.KnoxLdapRealm</code> in the Shiro
configuration, and setting up the cache you <em>must</em> set the flag for
enabling caching authentication to true. Please see the property,
<code>main.ldapRealm.authenticationCachingEnabled</code> below. If caching is
enabled on more than one topology, advanced caching configs with differing
persistence directories have to be provided. The reason for this is separate
topologies manage their own caches in different directories. Two cache has to
be in different places otherwise ehcache won’t be able to lock the
directory and the topology deployment will fail.</p>
<pre><code><provider>
<role>authentication</role>
<name>ShiroProvider</name>
@@ -3669,86 +3669,47 @@ bin/gateway.sh start
<pre><code>curl -i -v -k -u tom:tom-password -X GET
https://localhost:8443/gateway/sandbox/webhdfs/v1?op=GETHOMEDIRECTORY
</code></pre>
<h4><a id="Advanced+Caching+Config">Advanced Caching Config</a> <a
href="#Advanced+Caching+Config"><img src="markbook-section-link.png"/></a></h4>
-<p>By default the EhCache support in Shiro contains a ehcache.xml in its
classpath which is the following</p>
-<pre><code><ehcache name="knox-YOUR_TOPOLOGY_NAME">
+<p>By default the EhCache support in Shiro contains the ehcache.xml in its
classpath which is the following</p>
+<pre><code><config xmlns="http://www.ehcache.org/v3">
- <!-- Sets the path to the directory where cache .data files are created.
+ <persistence directory="${java.io.tmpdir}/shiro-ehcache"/>
- If the path is a Java System Property it is replaced by
- its value in the running VM. The following properties are translated:
+ <cache alias="shiro-activeSessionCache">
+ <key-type
serializer="org.ehcache.impl.serialization.CompactJavaSerializer">
+ java.lang.Object
+ </key-type>
+ <value-type
serializer="org.ehcache.impl.serialization.CompactJavaSerializer">
+ java.lang.Object
+ </value-type>
+
+ <resources>
+ <heap unit="entries">10000</heap>
+ <disk unit="GB">1</disk>
+ </resources>
+ </cache>
+
+ <cache
alias="org.apache.shiro.realm.text.PropertiesRealm-0-accounts">
+ <key-type
serializer="org.ehcache.impl.serialization.CompactJavaSerializer">
+ java.lang.Object
+ </key-type>
+ <value-type
serializer="org.ehcache.impl.serialization.CompactJavaSerializer">
+ java.lang.Object
+ </value-type>
+
+ <resources>
+ <heap unit="entries">1000</heap>
+ <disk unit="GB">1</disk>
+ </resources>
+ </cache>
+
+ <cache-template name="defaultCacheConfiguration">
+ <expiry>
+ <tti unit="seconds">120</tti>
+ </expiry>
+ <heap unit="entries">10000</heap>
+ </cache-template>
- user.home - User's home directory
- user.dir - User's current working directory
- java.io.tmpdir - Default temp file path
- -->
- <diskStore path="java.io.tmpdir/shiro-ehcache"/>
-
-
- <!--Default Cache configuration. These will applied to caches
programmatically created through
- the CacheManager.
-
- The following attributes are required:
-
- maxElementsInMemory - Sets the maximum number of objects that
will be created in memory
- eternal - Sets whether elements are eternal. If
eternal, timeouts are ignored and the
- element is never expired.
- overflowToDisk - Sets whether elements can overflow to
disk when the in-memory cache
- has reached the maxInMemory limit.
-
- The following attributes are optional:
- timeToIdleSeconds - Sets the time to idle for an element
before it expires.
- i.e. The maximum amount of time between
accesses before an element expires
- Is only used if the element is not
eternal.
- Optional attribute. A value of 0 means
that an Element can idle for infinity.
- The default value is 0.
- timeToLiveSeconds - Sets the time to live for an element
before it expires.
- i.e. The maximum time between creation
time and when an element expires.
- Is only used if the element is not
eternal.
- Optional attribute. A value of 0 means
that and Element can live for infinity.
- The default value is 0.
- diskPersistent - Whether the disk store persists between
restarts of the Virtual Machine.
- The default value is false.
- diskExpiryThreadIntervalSeconds- The number of seconds between runs of the
disk expiry thread. The default value
- is 120 seconds.
- memoryStoreEvictionPolicy - Policy would be enforced upon reaching
the maxElementsInMemory limit. Default
- policy is Least Recently Used (specified
as LRU). Other policies available -
- First In First Out (specified as FIFO)
and Less Frequently Used
- (specified as LFU)
- -->
-
- <defaultCache
- maxElementsInMemory="10000"
- eternal="false"
- timeToIdleSeconds="120"
- timeToLiveSeconds="120"
- overflowToDisk="false"
- diskPersistent="false"
- diskExpiryThreadIntervalSeconds="120"
- />
-
- <!-- We want eternal="true" and no timeToIdle or timeToLive
settings because Shiro manages session
- expirations explicitly. If we set it to false and then set
corresponding timeToIdle and timeToLive properties,
- ehcache would evict sessions without Shiro's knowledge, which
would cause many problems
- (e.g. "My Shiro session timeout is 30 minutes - why isn't a
session available after 2 minutes?"
- Answer - ehcache expired it due to the timeToIdle property set
to 120 seconds.)
-
- diskPersistent=true since we want an enterprise session management
feature - ability to use sessions after
- even after a JVM restart. -->
- <cache name="shiro-activeSessionCache"
- maxElementsInMemory="10000"
- overflowToDisk="true"
- eternal="true"
- timeToLiveSeconds="0"
- timeToIdleSeconds="0"
- diskPersistent="true"
- diskExpiryThreadIntervalSeconds="600"/>
-
- <cache
name="org.apache.shiro.realm.text.PropertiesRealm-0-accounts"
- maxElementsInMemory="1000"
- eternal="true"
- overflowToDisk="true"/>
-
-</ehcache>
+</config>
</code></pre>
<p>A custom configuration file (ehcache.xml) can be used in place of this in
order to set specific caching configuration.</p>
<p>In order to set the ehcache.xml file to use for a particular topology, set
the following parameter in the configuration for the ShiroProvider:</p>
Modified: knox/site/index.html
URL:
http://svn.apache.org/viewvc/knox/site/index.html?rev=1925021&r1=1925020&r2=1925021&view=diff
==============================================================================
--- knox/site/index.html (original)
+++ knox/site/index.html Fri Apr 11 18:25:56 2025
@@ -1,13 +1,13 @@
<!DOCTYPE html>
<!--
- | Generated by Apache Maven Doxia Site Renderer 1.8.1 from
src/site/markdown/index.md at 2025-04-10
+ | Generated by Apache Maven Doxia Site Renderer 1.8.1 from
src/site/markdown/index.md at 2025-04-11
| Rendered using Apache Maven Fluido Skin 1.7
-->
<html xmlns="http://www.w3.org/1999/xhtml"; xml:lang="en" lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
- <meta name="Date-Revision-yyyymmdd" content="20250410" />
+ <meta name="Date-Revision-yyyymmdd" content="20250411" />
<meta http-equiv="Content-Language" content="en" />
<title>Knox Gateway – Announcing Apache Knox 2.1.0!</title>
<link rel="stylesheet" href="./css/apache-maven-fluido-1.7.min.css" />
@@ -26,7 +26,7 @@
<div id="breadcrumbs">
<ul class="breadcrumb">
- <li id="publishDate">Last Published: 2025-04-10</li>
+ <li id="publishDate">Last Published: 2025-04-11</li>
</ul>
</div>
<div class="row-fluid">
Modified: knox/site/issue-management.html
URL:
http://svn.apache.org/viewvc/knox/site/issue-management.html?rev=1925021&r1=1925020&r2=1925021&view=diff
==============================================================================
--- knox/site/issue-management.html (original)
+++ knox/site/issue-management.html Fri Apr 11 18:25:56 2025
@@ -1,13 +1,13 @@
<!DOCTYPE html>
<!--
- | Generated by Apache Maven Doxia Site Renderer 1.8.1 from
org.apache.maven.plugins:maven-project-info-reports-plugin:3.0.0:issue-management
at 2025-04-10
+ | Generated by Apache Maven Doxia Site Renderer 1.8.1 from
org.apache.maven.plugins:maven-project-info-reports-plugin:3.0.0:issue-management
at 2025-04-11
| Rendered using Apache Maven Fluido Skin 1.7
-->
<html xmlns="http://www.w3.org/1999/xhtml"; xml:lang="en" lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
- <meta name="Date-Revision-yyyymmdd" content="20250410" />
+ <meta name="Date-Revision-yyyymmdd" content="20250411" />
<meta http-equiv="Content-Language" content="en" />
<title>Knox Gateway – Issue Management</title>
<link rel="stylesheet" href="./css/apache-maven-fluido-1.7.min.css" />
@@ -26,7 +26,7 @@
<div id="breadcrumbs">
<ul class="breadcrumb">
- <li id="publishDate">Last Published: 2025-04-10</li>
+ <li id="publishDate">Last Published: 2025-04-11</li>
</ul>
</div>
<div class="row-fluid">
Modified: knox/site/licenses.html
URL:
http://svn.apache.org/viewvc/knox/site/licenses.html?rev=1925021&r1=1925020&r2=1925021&view=diff
==============================================================================
--- knox/site/licenses.html (original)
+++ knox/site/licenses.html Fri Apr 11 18:25:56 2025
@@ -1,13 +1,13 @@
<!DOCTYPE html>
<!--
- | Generated by Apache Maven Doxia Site Renderer 1.8.1 from
org.apache.maven.plugins:maven-project-info-reports-plugin:3.0.0:licenses at
2025-04-10
+ | Generated by Apache Maven Doxia Site Renderer 1.8.1 from
org.apache.maven.plugins:maven-project-info-reports-plugin:3.0.0:licenses at
2025-04-11
| Rendered using Apache Maven Fluido Skin 1.7
-->
<html xmlns="http://www.w3.org/1999/xhtml"; xml:lang="en" lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
- <meta name="Date-Revision-yyyymmdd" content="20250410" />
+ <meta name="Date-Revision-yyyymmdd" content="20250411" />
<meta http-equiv="Content-Language" content="en" />
<title>Knox Gateway – Project Licenses</title>
<link rel="stylesheet" href="./css/apache-maven-fluido-1.7.min.css" />
@@ -26,7 +26,7 @@
<div id="breadcrumbs">
<ul class="breadcrumb">
- <li id="publishDate">Last Published: 2025-04-10</li>
+ <li id="publishDate">Last Published: 2025-04-11</li>
</ul>
</div>
<div class="row-fluid">
Modified: knox/site/mailing-lists.html
URL:
http://svn.apache.org/viewvc/knox/site/mailing-lists.html?rev=1925021&r1=1925020&r2=1925021&view=diff
==============================================================================
--- knox/site/mailing-lists.html (original)
+++ knox/site/mailing-lists.html Fri Apr 11 18:25:56 2025
@@ -1,13 +1,13 @@
<!DOCTYPE html>
<!--
- | Generated by Apache Maven Doxia Site Renderer 1.8.1 from
org.apache.maven.plugins:maven-project-info-reports-plugin:3.0.0:mailing-lists
at 2025-04-10
+ | Generated by Apache Maven Doxia Site Renderer 1.8.1 from
org.apache.maven.plugins:maven-project-info-reports-plugin:3.0.0:mailing-lists
at 2025-04-11
| Rendered using Apache Maven Fluido Skin 1.7
-->
<html xmlns="http://www.w3.org/1999/xhtml"; xml:lang="en" lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
- <meta name="Date-Revision-yyyymmdd" content="20250410" />
+ <meta name="Date-Revision-yyyymmdd" content="20250411" />
<meta http-equiv="Content-Language" content="en" />
<title>Knox Gateway – Project Mailing Lists</title>
<link rel="stylesheet" href="./css/apache-maven-fluido-1.7.min.css" />
@@ -26,7 +26,7 @@
<div id="breadcrumbs">
<ul class="breadcrumb">
- <li id="publishDate">Last Published: 2025-04-10</li>
+ <li id="publishDate">Last Published: 2025-04-11</li>
</ul>
</div>
<div class="row-fluid">
Modified: knox/site/project-info.html
URL:
http://svn.apache.org/viewvc/knox/site/project-info.html?rev=1925021&r1=1925020&r2=1925021&view=diff
==============================================================================
--- knox/site/project-info.html (original)
+++ knox/site/project-info.html Fri Apr 11 18:25:56 2025
@@ -1,13 +1,13 @@
<!DOCTYPE html>
<!--
- | Generated by Apache Maven Doxia Site Renderer 1.8.1 from
org.apache.maven.plugins:maven-site-plugin:3.7.1:CategorySummaryDocumentRenderer
at 2025-04-10
+ | Generated by Apache Maven Doxia Site Renderer 1.8.1 from
org.apache.maven.plugins:maven-site-plugin:3.7.1:CategorySummaryDocumentRenderer
at 2025-04-11
| Rendered using Apache Maven Fluido Skin 1.7
-->
<html xmlns="http://www.w3.org/1999/xhtml"; xml:lang="en" lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
- <meta name="Date-Revision-yyyymmdd" content="20250410" />
+ <meta name="Date-Revision-yyyymmdd" content="20250411" />
<meta http-equiv="Content-Language" content="en" />
<title>Knox Gateway – Project Information</title>
<link rel="stylesheet" href="./css/apache-maven-fluido-1.7.min.css" />
@@ -26,7 +26,7 @@
<div id="breadcrumbs">
<ul class="breadcrumb">
- <li id="publishDate">Last Published: 2025-04-10</li>
+ <li id="publishDate">Last Published: 2025-04-11</li>
</ul>
</div>
<div class="row-fluid">
Modified: knox/site/team.html
URL:
http://svn.apache.org/viewvc/knox/site/team.html?rev=1925021&r1=1925020&r2=1925021&view=diff
==============================================================================
--- knox/site/team.html (original)
+++ knox/site/team.html Fri Apr 11 18:25:56 2025
@@ -1,13 +1,13 @@
<!DOCTYPE html>
<!--
- | Generated by Apache Maven Doxia Site Renderer 1.8.1 from
org.apache.maven.plugins:maven-project-info-reports-plugin:3.0.0:team at
2025-04-10
+ | Generated by Apache Maven Doxia Site Renderer 1.8.1 from
org.apache.maven.plugins:maven-project-info-reports-plugin:3.0.0:team at
2025-04-11
| Rendered using Apache Maven Fluido Skin 1.7
-->
<html xmlns="http://www.w3.org/1999/xhtml"; xml:lang="en" lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
- <meta name="Date-Revision-yyyymmdd" content="20250410" />
+ <meta name="Date-Revision-yyyymmdd" content="20250411" />
<meta http-equiv="Content-Language" content="en" />
<title>Knox Gateway – Project Team</title>
<link rel="stylesheet" href="./css/apache-maven-fluido-1.7.min.css" />
@@ -26,7 +26,7 @@
<div id="breadcrumbs">
<ul class="breadcrumb">
- <li id="publishDate">Last Published: 2025-04-10</li>
+ <li id="publishDate">Last Published: 2025-04-11</li>
</ul>
</div>
<div class="row-fluid">
Modified: knox/trunk/books/2.1.0/config_ldap_authc_cache.md
URL:
http://svn.apache.org/viewvc/knox/trunk/books/2.1.0/config_ldap_authc_cache.md?rev=1925021&r1=1925020&r2=1925021&view=diff
==============================================================================
--- knox/trunk/books/2.1.0/config_ldap_authc_cache.md (original)
+++ knox/trunk/books/2.1.0/config_ldap_authc_cache.md Fri Apr 11 18:25:56 2025
@@ -22,7 +22,7 @@ caching mechanisms and has been tested w
The following provider snippet demonstrates how to configure turning on the
cache using the ShiroProvider. In addition to
using `org.apache.knox.gateway.shirorealm.KnoxLdapRealm` in the Shiro
configuration, and setting up the cache you *must* set
-the flag for enabling caching authentication to true. Please see the property,
`main.ldapRealm.authenticationCachingEnabled` below.
+the flag for enabling caching authentication to true. Please see the property,
`main.ldapRealm.authenticationCachingEnabled` below. If caching is enabled on
more than one topology, advanced caching configs with differing persistence
directories have to be provided. The reason for this is separate topologies
manage their own caches in different directories. Two cache has to be in
different places otherwise ehcache won't be able to lock the directory and the
topology deployment will fail.
<provider>
@@ -116,87 +116,48 @@ and then the following should still retu
#### Advanced Caching Config ####
-By default the EhCache support in Shiro contains a ehcache.xml in its
classpath which is the following
+By default the EhCache support in Shiro contains the ehcache.xml in its
classpath which is the following
- <ehcache name="knox-YOUR_TOPOLOGY_NAME">
+ <config xmlns="http://www.ehcache.org/v3";>
- <!-- Sets the path to the directory where cache .data files are
created.
+ <persistence directory="${java.io.tmpdir}/shiro-ehcache"/>
- If the path is a Java System Property it is replaced by
- its value in the running VM. The following properties are
translated:
+ <cache alias="shiro-activeSessionCache">
+ <key-type
serializer="org.ehcache.impl.serialization.CompactJavaSerializer">
+ java.lang.Object
+ </key-type>
+ <value-type
serializer="org.ehcache.impl.serialization.CompactJavaSerializer">
+ java.lang.Object
+ </value-type>
+
+ <resources>
+ <heap unit="entries">10000</heap>
+ <disk unit="GB">1</disk>
+ </resources>
+ </cache>
+
+ <cache alias="org.apache.shiro.realm.text.PropertiesRealm-0-accounts">
+ <key-type
serializer="org.ehcache.impl.serialization.CompactJavaSerializer">
+ java.lang.Object
+ </key-type>
+ <value-type
serializer="org.ehcache.impl.serialization.CompactJavaSerializer">
+ java.lang.Object
+ </value-type>
+
+ <resources>
+ <heap unit="entries">1000</heap>
+ <disk unit="GB">1</disk>
+ </resources>
+ </cache>
+
+ <cache-template name="defaultCacheConfiguration">
+ <expiry>
+ <tti unit="seconds">120</tti>
+ </expiry>
+ <heap unit="entries">10000</heap>
+ </cache-template>
- user.home - User's home directory
- user.dir - User's current working directory
- java.io.tmpdir - Default temp file path
- -->
- <diskStore path="java.io.tmpdir/shiro-ehcache"/>
-
-
- <!--Default Cache configuration. These will applied to caches
programmatically created through
- the CacheManager.
-
- The following attributes are required:
-
- maxElementsInMemory - Sets the maximum number of objects
that will be created in memory
- eternal - Sets whether elements are eternal. If
eternal, timeouts are ignored and the
- element is never expired.
- overflowToDisk - Sets whether elements can overflow to
disk when the in-memory cache
- has reached the maxInMemory limit.
-
- The following attributes are optional:
- timeToIdleSeconds - Sets the time to idle for an element
before it expires.
- i.e. The maximum amount of time
between accesses before an element expires
- Is only used if the element is not
eternal.
- Optional attribute. A value of 0
means that an Element can idle for infinity.
- The default value is 0.
- timeToLiveSeconds - Sets the time to live for an element
before it expires.
- i.e. The maximum time between
creation time and when an element expires.
- Is only used if the element is not
eternal.
- Optional attribute. A value of 0
means that and Element can live for infinity.
- The default value is 0.
- diskPersistent - Whether the disk store persists
between restarts of the Virtual Machine.
- The default value is false.
- diskExpiryThreadIntervalSeconds- The number of seconds between runs of
the disk expiry thread. The default value
- is 120 seconds.
- memoryStoreEvictionPolicy - Policy would be enforced upon
reaching the maxElementsInMemory limit. Default
- policy is Least Recently Used
(specified as LRU). Other policies available -
- First In First Out (specified as
FIFO) and Less Frequently Used
- (specified as LFU)
- -->
-
- <defaultCache
- maxElementsInMemory="10000"
- eternal="false"
- timeToIdleSeconds="120"
- timeToLiveSeconds="120"
- overflowToDisk="false"
- diskPersistent="false"
- diskExpiryThreadIntervalSeconds="120"
- />
-
- <!-- We want eternal="true" and no timeToIdle or timeToLive settings
because Shiro manages session
- expirations explicitly. If we set it to false and then set
corresponding timeToIdle and timeToLive properties,
- ehcache would evict sessions without Shiro's knowledge, which
would cause many problems
- (e.g. "My Shiro session timeout is 30 minutes - why isn't a
session available after 2 minutes?"
- Answer - ehcache expired it due to the timeToIdle property
set to 120 seconds.)
-
- diskPersistent=true since we want an enterprise session management
feature - ability to use sessions after
- even after a JVM restart. -->
- <cache name="shiro-activeSessionCache"
- maxElementsInMemory="10000"
- overflowToDisk="true"
- eternal="true"
- timeToLiveSeconds="0"
- timeToIdleSeconds="0"
- diskPersistent="true"
- diskExpiryThreadIntervalSeconds="600"/>
-
- <cache name="org.apache.shiro.realm.text.PropertiesRealm-0-accounts"
- maxElementsInMemory="1000"
- eternal="true"
- overflowToDisk="true"/>
-
- </ehcache>
+ </config>
A custom configuration file (ehcache.xml) can be used in place of this in
order to set specific caching configuration.
