[Grizzly Config] One Pager

1. Introduction

1.1. Project/Component Working Name:

Grizzly Configuration

1.2. Name(s) and e-mail address of Document Author(s)/Supplier:

The individuals who contributed to this document are:

Name: Jeanfrancois.Arcand@Sun.COM, Oleksiy.Stashok@Sun.COM, Dhiru.Pandey@Sun.COM, Justin.Lee@Sun.com

1.3. Date of This Document:

06/30/08 12/08/08

2. Project Summary

2.1. Project Description:

Grizzly configuration specifies the schema of the element (or file in case of standalone) used by Grizzly to configure the network services (transport, protocol and listeners)

2.2. Risks and Assumptions:

2.2.1 Coordination is required with both the admin CLI and GUI teams which will complicate scheduling.

3. Problem Summary

3.1. Problem Area:

Previous versions of GlassFish application server handled HTML/HTTP requests from within the web container. Modular architecture of V3 requires that this behavior be changed so that these requests can now be handled by the barebone V3 nucleus even before any of the containers have been started. As a result, grizzly configuration which was earlier part of the web container configuration needs to be separated out into its own configuration element.

There may be situations where Grizzly may need to be configured in the absence of GlassFish. The configuration should be able to handle such scenarios as well.

In domain.xml System properties where widely used to tune the performance, so it was very difficult to have a different configuration for a different listeners. Grizzly-config is less dependent on system properties and property elements. Most of the transport related properties from domain.xml, in grizzly-config become XML elements and attributes.

3.2. Justification:

This project provides the necessary infrastructural support for modularity - one of the main features of V3 release. Additionally the configuration schema provides the necessary plug-in points for extensibility in terms of protocol handling.

4. Technical Description:

4.1. Details:

As stated above, Grizzly is now part of the nucleus of GlassFish V3. In earlier versions of GlassFish, Grizzly was configured via the http-service element of domain.xml to field the HTTP traffic. In V3, because of this change, HTTP traffic can be handled by the nucleus and so the configuration of Grizzly needs to be separated out to its own configuration element in domain.xml.

The schema for the Grizzly configuration is described here. The new network-config element would be added to config element of sun-domain.dtd as shown below:

<!ELEMENT config
    (network-config, http-service, iiop-service, admin-service, connector-service?,            
    web-container, ejb-container, mdb-container, jms-service?, log-service,    
    security-service, transaction-service, monitoring-service,                 
    diagnostic-service?, java-config, availability-service?, thread-pools,     
    alert-service?, group-management-service?, management-rules?,              
    system-property*, property*)> 

Any network-specific configuration under http-service in domain.xml will be deprecated and mapped to the new network-config element. However, any HTTP protocol specific configuration will be retained under it. Additionally, Grizzly configuration done in earlier versions of GlassFish using the -D properties will also be deprecated. Backward compatibility in V3 runtime will be maintained to support these by intelligently creating the network-config runtime bean in the admin infrastructure that will read values from these deprecated elements (use defaults where required) and populate the new network-config runtime bean which is then used to bootstrap Grizzly.

The same schema will also be used to configure Grizzly in standalone mode i.e. in the absence of GlassFish. Currently, Grizzly in standalone mode is configured programmatically. The javadoc for the new grizzly classes are attached and should be considered the authoritative documentation. An example grizzly configuration file can be found here. Here is a migrated version of a v3 domain.xml that reflects the proposed changes.

The relevant changed portions are highlighted below:

<network-config>
   <transports>
       <transport name="http"/>
   </transports>
   <protocols>
       <protocol name="http">
           <http default-virtual-server="server" header-buffer-length-bytes="8192">
               <file-cache enabled="false"/>
           </http>
       </protocol>
       <protocol name="http-admin">
           <http default-virtual-server="__asadmin"/>
       </protocol>
       <protocol name="https" security-enabled="true">
           <ssl ssl3-enabled="false" cert-nickname="s1as"/>
       </protocol>
   </protocols>
   <network-listeners>
       <thread-pool thread-pool-id="http-threads" min-thread-pool-size="2" max-thread-pool-size="20"/>
       <network-listener name="http-listener-1" transport="http" protocol="http" address="0.0.0.0" port="8080"/>
       <network-listener name="http-listener-2" transport="http" protocol="https" address="0.0.0.0" port="8181"/>
       <network-listener name="admin-listener" transport="http" protocol="http-admin" address="0.0.0.0" port="4848"/>
   </network-listeners>
</network-config>
<http-service>
    <access-log rotation-interval-in-minutes="15" rotation-suffix="yyyy-MM-dd"/>
    <virtual-server id="server" network-listeners="http-listener-1,http-listener-2"/>
    <virtual-server id="__asadmin" network-listeners="admin-listener"/>
</http-service>

4.2. Bug/RFE Number(s):

4.3. In Scope:

Standalone Grizzly runtime would also use the same configuration schema to bootstrap.

4.4. Out of Scope:

4.5. Interfaces:

Refer to the javadoc for the configuration element specified above in section 4.1.

4.5.1 Exported Interfaces

Disclose all interfaces that this project exports.

• Interface: network-config element described in the javadoc
• Stability: Committed
• Former Stability (if changing):
• Comments:

4.5.2 Imported interfaces

None

4.5.3 Other interfaces (Optional)

None

4.6. Doc Impact:

Product manuals/guides will need to be modified to incorporate changes related to administering and using network (Grizzly) configuration

4.7. Admin/Config Impact:

Admin console and cli would need to support this new configuration schema.

4.8. HA Impact:

No impact.

4.9. I18N/L10N Impact:

I18N/L10N impact would be on the Admin Console/CLI used to configure this element

4.10. Packaging & Delivery:

In GlassFish V3, this will be an element in domain.xml and will be part of the V3 distribution. It will also be part of the standalone Grizzly distribution.

4.11. Security Impact:

For V3 Transport Level Security (TLS) for HTTP protocol would be configured using this. In earlier releases of GlassFish the same information was picked up from a various protocol listener elements which were part of the protocol service elements for e.g. <http-listener> element specified in <http-service> element of domain.xml. To maintain backward compatibility, V3 runtime would also be able to use the TLS related configuration specified in the protocol listener elements which were part of the protocol service elements of the V2 domain.dtd.

4.12. Compatibility Impact

Any network-specific configuration under http-service in domain.xml will be deprecated and mapped to the new network-config element. However, any HTTP protocol specific configuration will be retained under it. Additionally, Grizzly configuration done in earlier versions of GlassFish using the -D properties will also be deprecated. Backward compatibility in V3 runtime will be maintained to support these by intelligently creating the network-config runtime bean in the admin infrastructure that will read values from these deprecated elements (use defaults where required) and populate the new network-config runtime bean which is then used to bootstrap Grizzly.

Below we propose migration map for http-service children elements and attributes. Where http-service elements or attributes have been mapped to corresponding network-config elements or attributes, respectively, their new dotted names are derived from the mappings. Items below marked as "not supported" are not currently used by the system and will be dropped during the migration. A warning will be logged in the process.

1) http-listener

GFv2	GFv3	Comments
ssl	Map to: network-config>protocols>protocol>ssl
id	N/A
address	Map to: network-config>network-listeners>network-listener#address
port	Map to: network-config>network-listeners>network-listener#port
external-port	not supported
family	not supported
blocking-enabled	not supported
acceptor-threads	Map to: network-config>transports>transport#acceptor-threads
security-enabled	Map to: network-config>protocols>protocol#security-enabled
default-virtual-server	Map to: network-config>protocols>protocol>http#default-virtual-server
server-name	Map to: network-config>protocols>protocol>http#server-name
redirect-port	Map to: network-config>protocols>protocol>http#redirect-port
xpowered-by	Map to: network-config>protocols>protocol>http#xpowered-by
enabled	Map to: network-config>network-listeners>network-listener#enabled
		This element will then be removed

2) http-protocol

GFv2	GFv3	Comments
version	Map to: network-config>protocols>protocol>http#version
dns-lookup-enabled	not supported
forced-response-type	Map to: network-config>protocols>protocol>http#forced-response-type
default-response-type	Map to: network-config>protocols>protocol>http#default-response-type
ssl-enabled	not supported
		This element will then be removed

3) http-service

GFv2	GFv3	Comments
http-listener	N/A	will be removed
http-protocol	N/A	will be removed
connection-pool	N/A	will be removed
keep-alive	N/A	will be removed
http-file-cache	N/A	Map to: network-config>protocols>protocol>http>file-cache
		These are being remapped as noted elsewhere and are no longer necessary under the new schema.
		Per anissa, the "accessLoggingEnabled" property will be pushed down to virtual-server#access-logging-enabled

4) request-processing

GFv2	GFv3	Comments
thread-count	Map to: network-config>network-listeners>thread-pool#max-thread-pool-size
initial-thread-count	Map to: network-config>network-listeners>thread-pool#min-thread-pool-size
thread-increment	Map to: network-config>network-listeners>thread-pool#thread-increment
header-buffer-length-in-bytes	Map to: network-config>protocols>protocol>http#header-buffer-length-bytes
		remove element

5) connection-pool

GFv2	GFv3
queue-size-in-bytes	Map to: network-config>network-listeners>thread-pool#max-queue-size
max-pending-count	Map to: network-config>transports>transport#max-connections-count
receive-buffer-size-in-bytes		remove since this is duplicated with max-post-size-bytes
send-buffer-size-in-bytes	Map to: network-config>protocols>protocol>http#send-buffer-size
		remove element

6) virtual-server

GFv2	GFv3	Comments
http-listeners	network-listeners	just mapping to http-listener's replacement instead
		per anissa, docRoot, accessLog, and sso-enabled properties will be pushed up to proper attributes

7) keep-alive

GFv2	GFv3	Comments
thread-count	remove
max-connections	Map to: network-config>protocols>protocol>http#max-connections
timeout-in-seconds	Map to: network-config>protocols>protocol>http#timeout
		remove element

8) http-file-cache

GFv2	GFv3	Comments
globally-enabled	remove
file-caching-enabled	Map to: network-config>protocols>protocol>http>file-cache#enabled
max-age-in-seconds	Map to: network-config>protocols>protocol>http>file-cache#max-age
medium-file-size-limit-in-bytes	remove
medium-file-space-in-bytes	Map to: network-config>protocols>protocol>http>file-cache#max-cache-size
small-file-size-limit-in-bytes	remove
small-file-space-in-bytes	remove
file-transmission-enabled	remove
max-files-count	Map to: network-config>protocols>protocol>http>file-cache#max-files-count
hash-init-size	remove
		element moved to http>file-cache

9) thread-pool

GFv2	GFv3	Comments
num-work-queues	not supported	no code uses this
thread-increment	not supported	corba doesn't want it. grizzly doesn't use it any more.
		we can use a common definition if we can clean up this definition. otherwise we'll need to use specific thread pool definitions

10) The following properties will need to be intercepted and mapped accordingly. This will likely mean adding logic to catch these properties when using asadmin set-jvm-property and migrating existing instances in domain.xml to the appropriate xml element.

Note for v2 migrations: if you are using GlassFish v3, all properties start with com.sun.enterprise.web.connector.grizzly instead of com.sun.grizzly

Property	GFv3	Comments
com.sun.grizzly.selector.timeout	Map to: network-config>network-listeners>network-listener>transport#selector-poll-timeout	The time, in milliseconds, a NIO Selector will block waiting for events (users requests). By default it blocks 1000 (1 second). In some environment, increasing the value will reduce the CPU usage, but changes to that value aren't recommended unless you are seeing high CPU, most probably when your server doesn't have enough ram.
com.sun.grizzly.displayConfiguration	Map to: network-config>network-listeners>network-listener>transport#display-configuration	flush Grizzly's internal configuration to the server logs (like number of threads created, how many polled objects, etc.)
v3.grizzly.enableCometSupport	Map to: network-config>network-listeners>network-listener#comet-support-enabled	enable Comet support for all http-listener, including the Admin-gui.
com.sun.grizzly.enableSnoop	Map to: network-config>network-listeners>network-listener>transport#enable-snoop	dump the requests/response information in server.log. Useful for debugging purpose, but significantly reduce performance as the request/response bytes are translated to String.
com.sun.grizzly.readTimeout	Map to: network-config>network-listeners>network-listener>transport#read-timeout	this value currently gets pushed to a static method. this will be changed to be instance specific
com.sun.grizzly.writeTimeout	Map to: network-config>network-listeners>network-listener>transport#write-timeout	this value currently gets pushed to a static method. this will be changed to be instance specific

The following table lists properties currently being processed under the <http-listener> element that will be remapped:

GFv2	GFv3	Comments
bufferSize	add transport->buffer-size
use-nio-direct-bytebuffer	same as transport->byte-buffer-type (HEAP/DIRECT values are supported)
maxKeepAliveRequests	http->max-connections
authPassthroughEnabled	http->auth-pass-through-enabled
compression	http->compression
compressableMimeType	http->compressable-mime-type
noCompressionUserAgents	http->no-compression-user-agents
compressionMinSize	http->compression-min-size
restrictedUserAgents	http->restricted-user-agents
rcmSupport	http->rcm-support-enabled
cometSupport	http->comet-support-enabled
connectionUploadTimeout	http->connection-upload-timeout
disableUploadTimeout	http->upload-timeout-enabled
proxiedProtocols	to be removed/unsupported	will be replaced with port-unification
chunkingDisabled	http->chunking-enabled
chunking-disabled	http->chunking-enabled
crlFile	ssl->crl-file
trustAlgorithm	ssl->trust-algorithm
trustMaxCertLength	ssl->trust-max-cert-length
uriEncoding	http->uri-encoding
jkEnabled	to be removed/unsupported?	Seems we don't need this anymore for grizzly config. (from Alexey)
tcpNoDelay	transport->tcp-no-delay
traceEnabled	http->trace-enabled

The following table lists properties currently being processed under the <virtual-server> element that will be promoted to attributes on the elements rather than properties:

property	attribute	comment
virtual-server#docroot	virtual-server#docroot
virtual-server#accesslog	virtual-server#access-log
virtual-server#sso-enabled	virtual-server#sso-enabled	takes true/false/inherit to interop with the http-service settings
http-service#accessLoggingEnabled	http-service#access-logging-enabled
http-service#accessLogBufferSize	access-log#buffer-size-bytes
http-service#accessLogWriterInterval	access-log#log-writer-interval
http-service#sso-enabled	http-service#sso-enabled

Glassfish admin commands.

1) Update existing commands.

GFv2	GFv3	Comments
create-ssl	Command has type parameter with following possible values: http-listener, iiop-listener, iiop-service. We should add one more possible type value: network-listener. We can still support http-listener type, but instead of adding ssl element under http-listener - it should be added under corresponding network-listener.
delete-ssl	...
create-thread	According to the schema, proposed above, network config requires additional parameters to be added to the command: max-queue-size, classname (optional).
create-http-listener	...
delete-http-listener	...
list-http-listeners	...
create-virtual-server	...
delete-virtual-server	...
list-virtual-servers	...
set		intercept set of old properties and redirect to appropriate command. just give a message and stop? or automatically make the switch? message+stop would be simplest since it could be done with a simple blacklist

2) Add following commands:

Commands	Parameters	Comments
create-transport	name, acceptor-threads, max-connections-count, classname
delete-transport	name
list-transports
create-protocol	name, security-enabled, max-selectors, byte-buffer-type, read-timeout, write-timeout, oob-inline
delete-protocol	name
list-protocols
create-network-listener	name, transport, protocol, thread-pool, host, port
delete-network-listener	name
list-network-listeners
create-protocol-filter	protocol-id, name, classname
delete-protocol-filter	name
list-protocol-filter

GUI Updates

1. Though a network-listener can have different transports defined, exposing that level of detail right now might be more detail than is useful. I'd recommend inferring a standard transport with default values. The admin gui would not change the transport reference, however, should a more advanced user manually edit domain.xml with custom transport definitions/configurations. Without port unification, exposing transports just for http usage seems a little overkill.
2. The HTTP Listener page can probably remain relatively unchanged. Some fields will need to be remapped to different properties, perhaps, but I don't see any conflicting values with the exception of acceptorThreads.

Migration

1. Migrate existing v2 domain.xml files to the new schema. Fold in grizzly properties to appropriate xml structures
2. dotted properties will need to be mapped. There are doubtless scripts out there setting using "asadmin set foo.bar=bob" these so we'll need to handle those appropriately. Do we handle set-jvm-property similarly? Try to align with work done for logging.

4.12.1 Open Issues

1. notes from migration/admin team (rebecca? kedar?)
   1. admin gui impact assessment
2. dotted property name mapping (kedar?)

4.13. Dependencies:

• Admin infrastructure
• Admin GUI
• CLI

5. Reference Documents:

Project Grizzly

6. Schedule:

6.1. Projected Availability:

This page (revision-149) was last changed on 27-Aug-09 06:47 AM, -0700 by Justin Lee.
This page was created on 30-Jun-08 16:33 PM, -0700 by Dhiru.

More info...