[GLASSFISH-19351] [UB]GlassFish Server 3.1 Administration Guide has incorrect steps for mod_jk Created: 15/Nov/12  Updated: 19/Sep/14

Status: Open
Project: glassfish
Component/s: docs
Affects Version/s:
Fix Version/s: 4.1

Type: Bug Priority: Major
Reporter: Ian Evans Assignee: Mike Fitch
Resolution: Unresolved Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified


In To Enable mod_jk:
step 5 creates an http-listener on port 8009 with this asadmin command:

create-http-listener --listenerport 8009 --listeneraddress --defaultvs server listener-name

Then in step 6, another network listener is created on port 8009:

create-network-listener --protocol http-listener-1 \
--listenerport 8009 --jkenabled true jk-connector

Step 5 is unnecessary if you're doing step 6, and results in an unstartable domain, as GlassFish attempts to create two listeners on port 8009.

The instructions should either be to create an http-listener as in step 5, then enable jk on that already-created listener like this:

set configs.config.server-config.network-config.network-listeners.network-listener.<listener name>.jk-enabled=true

or to use step 6, which does it all in one step.

It's also weird to not specify the listener name in step 5, but then to use an example listener name in step 6 ("jk-connector").

Comment by Ian Evans [ 15/Nov/12 ]

Also, step 6 assumes that the user is using a glassfish-jk.properties file in their domain, and not a workers.properties file with Apache httpd:

set server-config.network-config.network-listeners.network-listener.\

This command is unnecessary if you're configuring mod_jk on the Apache httpd side, and also uses an explicit listener name.

Comment by Paul Davies [ 16/Nov/12 ]

The target of the link in the description is the documentation for release 3.1. The corresponding section (To Enable mod_jk) in the documentation for release 3.1.2 has been updated and seems to address the duplication of the instruction to create a network listener in Step 5 and Step 6.

Comment by Ian Evans [ 16/Nov/12 ]

Paul, if you do a Google search for "glassfish mod_jk" you get the 3.1 doc as the very first link, with the title of "Administering mod_jk - Oracle GlassFish Server 3.1 Administration ...". I dug through the search results, and the 3.1.2 page (with the corrected info) is on page 4, with the far less useful title of "Administering Web Applications" (the chapter title, not the section). Links to older versions of the same section for GlassFish 3.0.1 and 2.1.1 appear on page 3 of the results. In between are a lot of blog entries, forum posts, and answer web site entries, all of them with more enticing titles than "Administering Web Applications".

In other words, the latest documentation is not only far down on the list, but maybe the least likely link to be clicked out of all of them. Perhaps this is something that should be addressed by the tools and web teams.

Generated at Tue May 05 00:37:45 UTC 2015 using JIRA 6.2.3#6260-sha1:63ef1d6dac3f4f4d7db4c1effd405ba38ccdc558.