Skip to content

Commit

Permalink
GEODE-9426: Update docs for HTTP session management (#6703)
Browse files Browse the repository at this point in the history
  • Loading branch information
@davebarnes97
davebarnes97 committed Jul 19, 2021
1 parent 1caf033 commit 4984b04
Show file tree
Hide file tree
Showing 7 changed files with 110 additions and 91 deletions.
Binary file added geode-docs/images/Apache_Tomcat_Homepage.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
45 changes: 29 additions & 16 deletions geode-docs/tools_modules/http_session_mgmt/quick_start.html.md.erb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,25 +21,32 @@ limitations under the License.

In this section you download, install, and set up the HTTP Session Management modules.

Following the Apache Tomcat convention, this page assumes the CATALINA_HOME environment variable is set to the root directory of the "binary" Tomcat distribution.
For example, if Apache Tomcat is installed in `/usr/bin/apache-tomcat-9.0.50` then

```
CATALINA_HOME=/usr/bin/apache-tomcat-9.0.50
```

## <a id="quick_start__section_6A4A00B6DA404E10A5C29E5E31101445" class="no-quick-link"></a>Quick Start Instructions

1. Download and install one of the application servers.

| Supported Application Server | Version | Download Location |
|------------------------------|-----------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| tc Server | 3.2 | [https://network.pivotal.io/products/pivotal-tcserver](https://network.pivotal.io/products/pivotal-tcserver) |
| Tomcat | 8.5 | [http://tomcat.apache.org/download-80.cgi](http://tomcat.apache.org/download-80.cgi) |
| Tomcat | 9.0 | [https://tomcat.apache.org/download-90.cgi](https://tomcat.apache.org/download-90.cgi) |
| Supported Application Server | Version | Download Location |
|------------------------------|---------|-------------------------|
| tc Server | 3.2 | [https://network.pivotal.io/products/pivotal-tcserver](https://network.pivotal.io/products/pivotal-tcserver) |
| Tomcat | 8.5 | [Tomcat 8 Software Downloads](https://tomcat.apache.org/download-80.cgi) |
| Tomcat | 9.0 | [Tomcat 9 Software Downloads](https://tomcat.apache.org/download-90.cgi) |

The generic HTTP Session Management Module for AppServers is implemented as a servlet filter and should work on any application server platform that supports the Java Servlet 3.1 specification.

2. The HTTP Session Management Modules installation .zip files are located in the `tools/Modules` directory of the product installation directory. Locate the .zip file for the HTTP Session Management Module that you wish to install. Unzip the appropriate HTTP Session Management Module into the specified directory for your application server:

| Supported Application Server | Version | Module | Target Location for Module |
|------------------------------|-----------------------------|----------------------------------------------------------|----------------------------------------------------------------------------------|
| tc Server | 3.2 | HTTP Session Management Module for Pivotal tc Server | `<tc Server root dir>/templates` |
| Tomcat | 8.5 | HTTP Session Management Module for Tomcat | `$CATALINA_HOME` |
| Tomcat | 9.0 | HTTP Session Management Module for Tomcat | `$CATALINA_HOME` |
| Supported Application Server | Version | Module | Target Location for Module |
|------------------------------|----------|------------------------------------------------------|----------------------------------|
| tc Server | 2.9 | Apache_Geode_Modules-SERVER-VERSION-tcServer.zip | `<tc Server root dir>/templates` |
| tc Server | 3.2 | Apache_Geode_Modules-SERVER-VERSION-tcServer30.zip | `<tc Server root dir>/templates` |
| Tomcat | 8.5, 9.0 | Apache_Geode_Modules-SERVER-VERSION-Tomcat.zip | `$CATALINA_HOME` |

3. Complete the appropriate set up instructions for your application server described in the following sections:
- [Additional Quick Start Instructions for tc Server Module](quick_start.html#quick_start__section_EE60463F524A46B7B83CE74C1C3E8E0E)
Expand Down Expand Up @@ -72,22 +79,28 @@ These steps provide a basic starting point for using the Tomcat module. For more
For example, in a peer-to-peer configuration using Tomcat 9, you would add the following entry within the `<server>` element of server.xml:
``` pre
<Listener className="org.apache.geode.modules.session.catalina.
PeerToPeerCacheLifecycleListener"
locator="localhost[10334]" />
<Listener className="org.apache.geode.modules.session.catalina.PeerToPeerCacheLifecycleListener"
locator="localhost[10334]" />
```
and the following entry within the `<context>` tag in the context.xml file:
``` pre
<Manager className="org.apache.geode.modules.session.catalina.
Tomcat9DeltaSessionManager"/>
<Manager className="org.apache.geode.modules.session.catalina.Tomcat9DeltaSessionManager"/>
```
See [Setting Up the HTTP Module for Tomcat](tomcat_setting_up_the_module.html) for additional instructions.
2. Restart the application server.
2. Start the Tomcat application server.
```
$CATALINA_HOME/bin/startup.sh
```
3. Confirm that Tomcat is running by opening a browser and navigating to `localhost:8080`. If you see the Tomcat home page, your installation was successful.
<img src="../../images/Apache_Tomcat_Homepage.png">
## <a id="quick_start__section_1587C3E55F06406EBD4AB13014A406D4" class="no-quick-link"></a>Additional Instructions for AppServers Module
These steps provide a basic starting point for using the AppServers module with WebLogic, WebSphere or JBoss. For more configuration options, see [HTTP Session Management Module for AppServers](session_mgmt_weblogic.html).
Expand Down
9 changes: 6 additions & 3 deletions geode-docs/tools_modules/http_session_mgmt/tc_installing_the_module.html.md.erb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,10 @@ limitations under the License.
This topic describes how to install the HTTP session management module with tc Server templates.

1. If you do not already have tc Server, download and install the product from the [Pivotal tc Server download page](https://network.pivotal.io/products/pivotal-tcserver). These instructions require **tc Server 2.9** or later.
2. The HTTP Session Management Module for tc Server is included in the <%=vars.product_name_long%> installation package. After you install <%=vars.product_name_long%>, you will find the module in the `tools/Modules` directory of the installation.

3. Unzip the module into the Pivotal tc Server `$CATALINA_HOME/templates` directory so that it creates `geode-p2p` and `geode-cs` subdirectories within the tc Server `templates` directory.
2. The HTTP Session Management Module for tc Server is included in the <%=vars.product_name_long%> installation package. After you install <%=vars.product_name_long%>, you will find the module in the `tools/Modules` directory of the installation with a name of the form `Apache_Geode_Modules-SERVER-VERSION-tcServer30.zip` or `Apache_Geode_Modules-SERVER-VERSION-tcServer.zip`. In these names,
- SERVER-VERSION is the <%=vars.product_name_long%> version number.
- `tcServer30` supports tcServer version 3.x.
- `tcserver` supports tcServer version 2.9.

3. Unzip the appropriate module into the Pivotal tc Server `$CATALINA_HOME/templates` directory so that it creates `geode-p2p` and `geode-cs` subdirectories within the tc Server `templates` directory.

31 changes: 15 additions & 16 deletions geode-docs/tools_modules/http_session_mgmt/tomcat_changing_gf_default_cfg.html.md.erb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -36,11 +36,12 @@ On the application server side, the default inactive interval for session expira
``` pre
<Listener
className="org.apache.geode.modules.session.catalina.xxxLifecycleListener"
name="value"
name="value"
property-name="property-value"
property-name="property-value"
...
/>
```
where `property-name` is the name of a property and `property-value` is that property's value.
If the `xxxLifecycleListener` is a `PeerToPeerCacheLifecycleListener`, then a minimal addition to the `server.xml` file is
Expand All @@ -53,21 +54,21 @@ If the `xxxLifecycleListener` is a `PeerToPeerCacheLifecycleListener`, then a mi
/>
```
The list of configurable Tomcat's `server.xml` system properties include any of the properties that can be specified in <%=vars.product_name%>'s `gemfire.properties` file. The following list contains some of the properties that can be configured.
The list of Tomcat's configurable `server.xml` system properties includes any of the properties that can be specified in <%=vars.product_name%>'s `gemfire.properties` file. The following list contains some of the properties that can be configured.
| Parameter | Description | Default |
|-------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------|
| cache-xml-file | name of the cache configuration file | `cache-peer.xml` for peer-to-peer, `cache-client.xml` for client/server |
| Property | Description | Default |
|------------------------------------------|---------------------------------------|----------|
| cache-xml-file | name of the cache configuration file | `cache-peer.xml` for peer-to-peer, `cache-client.xml` for client/server |
| locators (only for peer-to-peer topology) | (required) list of locators (host\[port\]) used by <%=vars.product_name%> members; if a single locator listens on its default port, then set this value to `"localhost[10334]"` | empty string |
| log-file | name of the <%=vars.product_name%> log file | `gemfire_modules.log` |
| statistic-archive-file | name of the <%=vars.product_name%> statistics file | `gemfire_modules.gfs` |
| statistic-sampling-enabled | whether <%=vars.product_name%> statistics sampling is enabled | false |
| log-file | name of the <%=vars.product_name%> log file | `gemfire_modules.log` |
| statistic-archive-file | name of the <%=vars.product_name%> statistics file | `gemfire_modules.gfs` |
| statistic-sampling-enabled | whether <%=vars.product_name%> statistics sampling is enabled | false |
For more information on these properties, along with the full list of properties, see the [Reference](../../reference/book_intro.html#reference).
In addition to the standard <%=vars.product_name%> system properties, the following cache-specific properties can also be configured with the `LifecycleListener`.
| Parameter | Description | Default |
| Property | Description | Default |
|------------------------|-------------------------------------------------------------------------------------------------|--------------|
| criticalHeapPercentage | percentage of heap at which updates to the cache are refused | 0 (disabled) |
| evictionHeapPercentage | percentage of heap at which session eviction begins | 80.0 |
Expand All @@ -82,13 +83,13 @@ To edit <%=vars.product_name%> cache properties such as the name and the charact
``` pre
<Manager
className="org.apache.geode.modules.session.catalina.Tomcat9DeltaSessionManager"
name="value"
name="value"
property-name="property-value"
property-name="property-value"
...
/>
```
In the preceding code snippet, `name` is the property name and `value` is the property value. For example:
where `property-name` is the name of a property and `property-value` is that property's value.
For example, this entry creates a partitioned region by the name of "my\_region".
``` pre
<Manager className="org.apache.geode.modules.session.catalina.
Expand All @@ -98,8 +99,6 @@ In the preceding code snippet, `name` is the property name and `value` is the pr
/>
```
This example creates a partitioned region by the name of "my\_region".
The following parameters are the cache configuration parameters that can be added to Tomcat's `context.xml` file.
<dt>**CommitSessionValve**</dt>
Expand Down
37 changes: 30 additions & 7 deletions geode-docs/tools_modules/http_session_mgmt/tomcat_installing_the_module.html.md.erb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,21 +21,44 @@ limitations under the License.

This topic describes how to install the HTTP session management module for Tomcat.

1. If you do not already have Tomcat installed, download the desired version from the [Apache Website](http://tomcat.apache.org/).
2. The HTTP Session Management Module for Tomcat is included in the <%=vars.product_name%> installation package. After you install <%=vars.product_name_long%>, you will find the module in the `tools/Modules` directory of the installation.
1. If you have not already installed Tomcat, download the desired version from the [Apache Website](http://tomcat.apache.org/) and install it.
2. Following the Apache Tomcat convention, this page assumes the CATALINA_HOME environment variable is set to the root directory of the "binary" Tomcat distribution.
For example, if Apache Tomcat is installed in `/usr/bin/apache-tomcat-9.0.50` then

3. Unzip the module into the `$CATALINA_HOME` directory or wherever you installed the application server.
4. Copy the following jar files to the `lib` directory of your Tomcat server (`$CATALINA_HOME/lib`):
- antlr jar
```
CATALINA_HOME=/usr/bin/apache-tomcat-9.0.50
```
Define $CATALINA_HOME if it is not already defined.

3. For development purposes, you may find it helpful to establish manager-level access to Tomcat. To do so, edit the file `$CATALINA_HOME/conf/tomcat-users.xml`.
Uncomment the following line, and replace the `<must-be-changed>` placeholder with a password of your own choosing:

```
<user username="admin" password="<must-be-changed>" roles="manager-gui"/>
```
This creates an admin/password credential you can use to view system information when following links from the Tomcat home page.

4. The HTTP Session Management Module for Tomcat is included in the <%=vars.product_name%> installation package. After you install <%=vars.product_name_long%>, you will find the module in the `tools/Modules` directory of the installation with a name of the form `Apache_Geode_Modules-SERVER-VERSION-Tomcat.zip`, where SERVER-VERSION is the <%=vars.product_name_long%> version number.
5. Set your current working directory to the `$CATALINA_HOME` directory (or wherever you installed the application server) and unzip the HTTP Session Management Module.
This adds jar files to the `lib` subdirectory and XML files to the `conf` subdirectory.
```
cd $CATALINA_HOME
unzip $GEODE_HOME/tools/Modules/Apache_Geode_Modules-SERVER-VERSION-Tomcat.zip
```
6. Copy the following jar files from the <%=vars.product_name%> `lib` subdirectory to the `lib` subdirectory of your Tomcat server (`$CATALINA_HOME/lib`), adding version numbers to the filenames as needed:
- commons-io jar
- commons-lang jar
- commons-validator jar
- fastutil jar
- geode-commons jar
- geode-common jar
- geode-core jar
- geode-logging jar
- geode-management jar
- geode-membership jar
- geode-serialization jar
- geode-tcp-server jar
- javax.transaction-api jar
- jgroups jar
- log4j-api jar
Expand All @@ -44,4 +67,4 @@ This topic describes how to install the HTTP session management module for Tomca
- micrometer-core jar
- shiro-core jar


Proceed to [Setting Up the HTTP Module for Tomcat](./tomcat_setting_up_the_module.html) to complete your Tomcat configuration.
Loading

0 comments on commit 4984b04

Please sign in to comment.