AppSuite:Grizzly

Grizzly based backend

Up to OX App Suite we were limited to AJP based communication between the HTTP server and the OX backend server. Starting with the release 7.0.1 of OX App Suite we offer a second HTTP based connector for the communication between the HTTP server and the backend. This new connector is based on Oracle's Project Grizzly - a NIO and Web framework.

Packages

Next we'll show some information on the packages needed to install a Grizzly based backend and some more in depth information about the package dependencies of open-xchange to open-xchange-ajp and open-xchange-grizzly and possible conflicts between those packages.

HttpService as packaging dependency

The open-xchange package depends on a virtual package called open-xchange-httpservice. This service is provided by both, the old open-xchange-ajp and the new open-xchange-grizzly packages. Only one of these two packages can be installed at a time because they block each other.

Install on OX App Suite

Debian GNU/Linux 11.0

Add the following entry to /etc/apt/sources.list.d/open-xchange.list if not already present:

deb https://software.open-xchange.com/products/appsuite/stable/backend/DebianBullseye/ /
# if you have a valid maintenance subscription, please uncomment the 
# following and add the ldb account data to the url so that the most recent
# packages get installed
# deb https://[CUSTOMERID:PASSWORD]@software.open-xchange.com/products/appsuite/stable/backend/updates/DebianBullseye/ /

and run

$ apt-get update
$ apt-get install open-xchange-grizzly

Debian GNU/Linux 12.0

Add the following entry to /etc/apt/sources.list.d/open-xchange.list if not already present:

deb https://software.open-xchange.com/products/appsuite/stable/backend/DebianBookworm/ /
# if you have a valid maintenance subscription, please uncomment the 
# following and add the ldb account data to the url so that the most recent
# packages get installed
# deb https://[CUSTOMERID:PASSWORD]@software.open-xchange.com/products/appsuite/stable/backend/updates/DebianBookworm/ /

and run

$ apt-get update
$ apt-get install open-xchange-grizzly

Cluster setup

This picture shows our default cluster setup. It consists of a proxying balancer (in our case Apache) and a cluster of multiple OX App Suite backends. The balancer receives HTTP and/or HTTPS requests and decides which requests should be handled by itself and which should be forwarded to be handled by one of the OX App Suite backends. That's where the AJP or HTTP connector is used.

Configuration

As request logically pass the balancer first, we'll start looking at how to configure this part of our setup before configuring the Grizzly based OX App Suite backends.

Apache configuration

Now as the Open-Xchange Server has been set up and the database is running, we have to configure the Apache webserver and the mod_proxy_http module to access the groupware frontend.

$ a2enmod proxy proxy_http proxy_balancer expires deflate headers rewrite mime setenvif 

Configure the mod_proxy_http module by creating a new Apache configuration file.

$ vim /etc/apache2/conf.d/proxy_http.conf

<IfModule mod_proxy_http.c>
   ProxyRequests Off
   ProxyStatus On
   # When enabled, this option will pass the Host: line from the incoming request to the proxied host.
   ProxyPreserveHost On
   # Please note that the servlet path to the soap API has changed:
   <Location /webservices>
       # restrict access to the soap provisioning API
       Order Deny,Allow
       Deny from all
       Allow from 127.0.0.1
       # you might add more ip addresses / networks here
       # Allow from 192.168 10 172.16
   </Location>
 
   # The old path is kept for compatibility reasons
   <Location /servlet/axis2/services>
       Order Deny,Allow
       Deny from all
       Allow from 127.0.0.1
   </Location>
   
   # Enable the balancer manager mentioned in
   # https://oxpedia.org/wiki/index.php?title=AppSuite:Running_a_cluster#Updating_a_Cluster
   <IfModule mod_status.c>
     <Location /balancer-manager>
       SetHandler balancer-manager
       Order Deny,Allow
       Deny from all
       Allow from 127.0.0.1
     </Location>
   </IfModule>
   
   <Proxy balancer://oxcluster>
       Order deny,allow
       Allow from all
       # multiple server setups need to have the hostname inserted instead localhost
       BalancerMember http://localhost:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 route=APP1
       # Enable and maybe add additional hosts running OX here
       # BalancerMember http://oxhost2:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 route=APP2
      ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=On
      SetEnv proxy-initial-not-pooled
      SetEnv proxy-sendchunked
   </Proxy>
   
   # The standalone documentconverter(s) within your setup (if installed)
   # Make sure to restrict access to backends only
   # See: http://httpd.apache.org/docs/$YOUR_VERSION/mod/mod_authz_host.html#allow for more infos
   #<Proxy balancer://oxcluster_docs>
   #    Order Deny,Allow
   #    Deny from all
   #    Allow from backend1IP
   #    BalancerMember http://converter_host:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=APP3
   #    ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=On
   #	   SetEnv proxy-initial-not-pooled
   #    SetEnv proxy-sendchunked
   #</Proxy>
   # Define another Proxy Container with different timeout for the sync clients. Microsoft recommends a minimum value of 15 minutes.
   # Setting the value lower than the one defined as com.openexchange.usm.eas.ping.max_heartbeat in eas.properties will lead to connection
   # timeouts for clients.  See http://support.microsoft.com/?kbid=905013 for additional information.
   #
   # NOTE for Apache versions < 2.4:
   # When using a single node system or using BalancerMembers that are assigned to other balancers please add a second hostname for that
   # BalancerMember's IP so Apache can treat it as additional BalancerMember with a different timeout.
   #
   # Example from /etc/hosts: 127.0.0.1	localhost localhost_sync
   #
   # Alternatively select one or more hosts of your cluster to be restricted to handle only eas/usm requests
   <Proxy balancer://{{{syncProxyName}}}>
      Order deny,allow
      Allow from all
      # multiple server setups need to have the hostname inserted instead localhost
      BalancerMember http://localhost_sync:8009 timeout=1900 smax=0 ttl=60 retry=60 loadfactor=50 route=APP1
      # Enable and maybe add additional hosts running OX here
      # BalancerMember http://oxhost2:8009 timeout=1900  smax=0 ttl=60 retry=60 loadfactor=50 route=APP2
      ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=On
      SetEnv proxy-initial-not-pooled
      SetEnv proxy-sendchunked
   </Proxy>
   
   # When specifying additional mappings via the ProxyPass directive be aware that the first matching rule wins. Overlapping urls of
   # mappings have to be ordered from longest URL to shortest URL.
   # 
   # Example:
   #   ProxyPass /ajax      balancer://oxcluster_with_100s_timeout/ajax
   #   ProxyPass /ajax/test balancer://oxcluster_with_200s_timeout/ajax/test
   #
   # Requests to /ajax/test would have a timeout of 100s instead of 200s 
   #   
   # See:
   # - http://httpd.apache.org/docs/current/mod/mod_proxy.html#proxypass Ordering ProxyPass Directives
   # - http://httpd.apache.org/docs/current/mod/mod_proxy.html#workers Worker Sharing
   ProxyPass /ajax balancer://oxcluster/ajax
   ProxyPass /appsuite/api balancer://oxcluster/ajax
   ProxyPass /drive balancer://oxcluster/drive
   ProxyPass /infostore balancer://oxcluster/infostore
   ProxyPass /realtime balancer://oxcluster/realtime
   ProxyPass /servlet balancer://oxcluster/servlet
   ProxyPass /webservices balancer://oxcluster/webservices

   #ProxyPass /documentconverterws balancer://oxcluster_docs/documentconverterws
 
   ProxyPass /usm-json balancer://oxcluster/usm-json
   ProxyPass /Microsoft-Server-ActiveSync balancer://oxcluster/Microsoft-Server-ActiveSync

</IfModule>

Modify the default website settings to display the Open-Xchange GUI

$ vim /etc/apache2/sites-enabled/000-default

<VirtualHost *:80>
       ServerAdmin webmaster@localhost

       DocumentRoot /var/www/
       <Directory /var/www/>
               Options -Indexes +FollowSymLinks +MultiViews
               AllowOverride None
               Order allow,deny
               allow from all
               RedirectMatch ^/$ /appsuite/
       </Directory>

       <Directory /var/www//appsuite>
               Options None +SymLinksIfOwnerMatch
               AllowOverride Indexes FileInfo
       </Directory>
</VirtualHost>

If you want to secure your Apache setup via HTTPS (which is highly recommended) or if you have proxies in front of your Apache please follow the instructions at:

• Grizzly configuration in general, and specifically:
• X-FORWARDED-PROTO Header
• X-FORWARDED-FOR Header

to properly instruct the backend about the security status of the connection and the remote IP used to contact the backend.

Grizzly configuration

/opt/open-xchange/etc/server.conf

This extract of the server.properties shows the properties that can be applied to the grizzly and ajp backend.

...
# DEFAULT ENCODING FOR INCOMING HTTP REQUESTS
# This value MUST be equal to web server's default encoding
DefaultEncoding=UTF-8
...
# The host for the connector's (ajp, http) network listener. Set to "*" if you
# want to listen on all available interfaces.
#Default value: 127.0.0.1, bind to localhost only.
com.openexchange.connector.networkListenerHost=*

# The default port for the connector's (ajp, http) network listener.
# Default value: 8009.
com.openexchange.connector.networkListenerPort=8009

# Specify the max. number of allowed request parameters for the connector (ajp, http)
# Default value: 30
com.openexchange.connector.maxRequestParameters: 30

# To enable proper load balancing and request routing from {client1, client2 ..
# .} --> balancer --> {backend1, backend2 ...} we have to append a backend route
# to the JSESSIONID cookies separated by a '.'. It's important that this backend
# route is unique for every single backend behind the load balancer.
# The string has to be a sequence of characters excluding semi-colon, comma and
# white space so the JSESSIONID cookie stays in accordance with the cookie
# specification after we append the backendroute to it.
# Default value: OX0 
com.openexchange.server.backendRoute=OX1
...

/opt/open-xchange/etc/grizzly.conf

Next we'll look at the parts of the grizzly.properties that configure only the grizzly backend but not the ajp backend.

# Grizzly.properties
#
# This file configures the grizzly server contained in the package
# open-xchange-grizzly. In your OX setup grizzly is located behind the
# load-balancer and accepts incoming client requests. Communication with the
# load balancer is done via http, e.g via Apache's mod_proxy_http.


### Push technology
################################################################################

# Comet is an umbrella term used to describe a technique allowing web browser to
# receive almost real time updates from the server. The two most common
# approaches are long polling and streaming. Long polling differs from streaming
# in that each update from the server ultimately results in another follow up
# request from the client.
# Default value: true
com.openexchange.http.grizzly.hasCometEnabled=true

# Bi-directional, full-duplex communications channels over a single TCP
# connection.
# Default value: false
com.openexchange.http.grizzly.hasWebSocketsEnabled=true


### JMX
################################################################################

# Do you want to enable grizzly monitoring via JMX? Default value: true.
com.openexchange.http.grizzly.hasJMXEnabled=true

/opt/open-xchange/etc/requestwatcher.conf

And finally the properties to configure the requestwatchers of the http and ajp backends

# Requestwatcher.properties
#
# This file configures the requestwatchers contained in the packages
# open-xchange-grizzly and open-xchange-ajp. The requestwatcher keeps track of
# incoming requests and periodically checks the age of the currently processing
# requests. If a request exceeds the configured maximum age, infos about the
# request and its processing thread are logged either into the configured
# logfiles or syslog depending on your configuration. 


# Enable/disable the requestwatcher.
# Default value: true (enabled).
com.openexchange.requestwatcher.isEnabled: true

# Define the requestwatcher's frequency in milliseconds.
# Default value: 30000.
com.openexchange.requestwatcher.frequency: 30000

# Define the maximum allowed age of requests in milliseconds.
# Default value: 60000. 
com.openexchange.requestwatcher.maxRequestAge: 60000

# Permission to stop & re-init system (works only for the ajp connector)
com.openexchange.requestwatcher.restartPermission: false

Switching from Grizzly to AJP

It's possible to switch from a Grizzly based setup to an AJP based setup if you don't depend on certian realtime features like websockets or comet based communication.

1. Install the ajp backend

Install the open-xchange-ajp package via your package manager. This will inform you about a conflict between the currently installed open-xchange-grizzly and the package you want to install. To solve the conflict you either have to manually remove open-xchange-grizzly before installing open-xchange-ajp or let the package manager handle this conflict automatically for you.

Debian

$ aptitude install open-xchange-ajp

Suse

$ zypper in open-xchange-ajp

RedHat

$ yum install open-xchange-ajp

2. Adapt the module configuration of apache

Adapt the installed apache modules to switch the proxy connector in use from http to ajp

$ a2dismod proxy_http && a2enmod proxy_http

3. Adapt the apache configuration to use the new connector

To make use of apaches new ajp connector for communication with open-xchange-ajp whe have to change it's configuration

Configure the mod_proxy_ajp module by creating a new Apache configuration file.

$ vim /etc/apache2/conf.d/proxy_ajp.conf

<IfModule mod_proxy_ajp.c>
   ProxyRequests Off
   ProxyStatus On
   
   # Please note that the servlet path to the soap API has changed:
   <Location /webservices>
       # restrict access to the soap provisioning API
       Order Deny,Allow
       Deny from all
       Allow from 127.0.0.1
       # you might add more ip addresses / networks here
       # Allow from 192.168 10 172.16
   </Location>
 
   # The old path is kept for compatibility reasons
   <Location /servlet/axis2/services>
       Order Deny,Allow
       Deny from all
       Allow from 127.0.0.1
   </Location>
   
   # Enable the balancer manager mentioned in
   # https://oxpedia.org/wiki/index.php?title=AppSuite:Running_a_cluster#Updating_a_Cluster
   <IfModule mod_status.c>
     <Location /balancer-manager>
       SetHandler balancer-manager
       Order Deny,Allow
       Deny from all
       Allow from 127.0.0.1
     </Location>
   </IfModule>
   
   <Proxy balancer://oxcluster>
       Order deny,allow
       Allow from all
       # multiple server setups need to have the hostname inserted instead localhost
       BalancerMember ajp://localhost:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 route=APP1
       # Enable and maybe add additional hosts running OX here
       # BalancerMember ajp://oxhost2:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 route=APP2
      ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=On
      
   </Proxy>
   
   # The standalone documentconverter(s) within your setup (if installed)
   # Make sure to restrict access to backends only
   # See: http://httpd.apache.org/docs/$YOUR_VERSION/mod/mod_authz_host.html#allow for more infos
   #<Proxy balancer://oxcluster_docs>
   #    Order Deny,Allow
   #    Deny from all
   #    Allow from backend1IP
   #    BalancerMember ajp://converter_host:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=APP3
   #    ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=On
   #	   SetEnv proxy-initial-not-pooled
   #    SetEnv proxy-sendchunked
   #</Proxy>
   
   
   # When specifying additional mappings via the ProxyPass directive be aware that the first matching rule wins. Overlapping urls of
   # mappings have to be ordered from longest URL to shortest URL.
   # 
   # Example:
   #   ProxyPass /ajax      balancer://oxcluster_with_100s_timeout/ajax
   #   ProxyPass /ajax/test balancer://oxcluster_with_200s_timeout/ajax/test
   #
   # Requests to /ajax/test would have a timeout of 100s instead of 200s 
   #   
   # See:
   # - http://httpd.apache.org/docs/current/mod/mod_proxy.html#proxypass Ordering ProxyPass Directives
   # - http://httpd.apache.org/docs/current/mod/mod_proxy.html#workers Worker Sharing
   ProxyPass /ajax balancer://oxcluster/ajax
   ProxyPass /appsuite/api balancer://oxcluster/ajax
   ProxyPass /drive balancer://oxcluster/drive
   ProxyPass /infostore balancer://oxcluster/infostore
   
   ProxyPass /servlet balancer://oxcluster/servlet
   ProxyPass /webservices balancer://oxcluster/webservices

   #ProxyPass /documentconverterws balancer://oxcluster_docs/documentconverterws
 
   ProxyPass /usm-json balancer://oxcluster/usm-json
   ProxyPass /Microsoft-Server-ActiveSync balancer://oxcluster/Microsoft-Server-ActiveSync

</IfModule>

Modify the default website settings to display the Open-Xchange GUI

$ vim /etc/apache2/sites-enabled/000-default

<VirtualHost *:80>
       ServerAdmin webmaster@localhost

       DocumentRoot /var/www/
       <Directory /var/www/>
               Options -Indexes +FollowSymLinks +MultiViews
               AllowOverride None
               Order allow,deny
               allow from all
               RedirectMatch ^/$ /appsuite/
       </Directory>

       <Directory /var/www//appsuite>
               Options None +SymLinksIfOwnerMatch
               AllowOverride Indexes FileInfo
       </Directory>
</VirtualHost>

If you want to secure your Apache setup via HTTPS (which is highly recommended) or if you have proxies in front of your Apache please follow the instructions at:

• Grizzly configuration in general, and specifically:
• X-FORWARDED-PROTO Header
• X-FORWARDED-FOR Header

to properly instruct the backend about the security status of the connection and the remote IP used to contact the backend.

4.Restart services

$ /etc/init.d/apache2 restart
$ /etc/init.d/open-xchange restart