Difference between revisions of "Zimbra with Apache using mod jk - mod proxy - mod proxy ajp"

(Adding category)
(Update for Zimbra 5.0 (Jetty) and mod_proxy_ajp; major re-organization and cleanup)
Line 1: Line 1:
Note: see also [[Hosting_other_sites_with_Zimbra]], [[ZimbraApache]], and [[Using_Tomcat_with_Apache_(mod_jk)]].
+
These instructions will enable access to Zimbra and other web applications/pages through the same host/port.
  
= Overview =
+
For example, if the Zimbra web interface is running at http://your.domain.com:8080/, and a separate instance of Apache is running at http://your.domain.com/, follow these steps to enable access to the Zimbra web interface through http://your.domain.com/zimbra/.
  
== Confession ==
+
== Disclaimer ==
I am no expert at either Linux, Programming or anything whatsoever. I cannot guarantee that this ''will'' work for you. If it doesn't please don't blame me. If you think I misunderstood something or I am wrong in some place or even all places, please try to improve on this and be helpful to others. The following has worked for me and, I believe, it should work for you, too. However, no guarantees.
+
This procedure is not fully verified, so follow these directions at your own risk.  Particularly, note that using ''mod_proxy'' requires you to '''secure your server first''', according to the Apache documentation. '''Please edit this page''' if something is wrong or incomplete.
  
== Thank-you ==
+
== Methods ==
Firstly, thanks to everyone at the [http://zimbra.com/forums/ Forums] for posting about their problems and efforts in trying to run Zimbra with Apache using mod_jk. And thanks to the original [[Using_Tomcat_with_Apache_(mod_jk)]] entry (a lot has been borrowed from it). This how-to is a result of their efforts.
+
There are two different ways of accomplishing this:
 +
# Creating an HTTP proxy to the Zimbra web interface, using Apache's [http://httpd.apache.org/docs/2.2/mod/mod_proxy.html mod_proxy]. (This method is easier but is generally considered to be less secure.)
 +
# Configuring the Zimbra web interface for the [http://en.wikipedia.org/wiki/Apache_JServ_Protocol Apache JServ Protocol] (AJP), and then using Apache's [http://httpd.apache.org/docs/2.2/mod/mod_proxy_ajp.html mod_proxy_ajp] or [http://en.wikipedia.org/wiki/Mod_jk mod_jk] to access it.
  
== What you want to do? ==
+
== Prerequisites ==
You want to access Zimbra at http://your.domain.com/zimbra/ which is currently accessible at http://your.domain.com:8080/
+
Zimbra and Apache should both be installed.
  
'''Note:''' The port could be 8080 or 6080 or any other. This is the port you have used to configure Zimbra's Web UI. Zimbra asked you a question regarding this when you installed it.
+
If you are installing Apache after installing Zimbra, you may first need to change the specific port numbers that the Zimbra web interface uses. For example, if you originally configured Zimbra to use port 80, you will need to change it to another port (such as 8080) in order for Apache to run on port 80. You can do this with the ''[[zmprov]]'' command.
  
== How to do that? ==
+
These instructions include the commands to use under Ubuntu Linux, which may need to be modified slightly under other distributions.
There are 2 ways:
 
# Use Apache's module called "mod_proxy"
 
# Use Apache's module called "mod_jk"
 
  
== Which way is better? ==
+
== Using an HTTP proxy ==
Honestly, I don't know which one's better. But, I do know that:
+
* Install and enable ''mod_proxy'' in Apache. Under Ubuntu, mod_proxy is installed by default, so just use this command to enable it:
 
+
<pre>sudo a2enmod proxy</pre>
1. If you use "mod_proxy", content from http://your.domain.com:8080/ is '''proxied''' to http://your.domain.com/somefolder/. It takes only a few lines and a few seconds to configure this. All you need to edit is one file: '''httpd.conf '''. The disbenefit of this method is that, you need to secure your Proxy. Securing Proxy implies that you need to explicitly specify access controls. Only those domains & IP Addresses which have been explicitly allowed by you will be able to access this proxied content. So, what would you do if you were on move or your ISP provides a dynamic IP address? If your ISP gives you a dynamic IP address, Dyndns.org would be one way to go. But, IMHO, that's not a good practice at all. You need to have some other way to do this.
 
 
 
FYI, here is the snippet from my httpd.conf for using "mod_proxy":
 
  
 +
* Create a new Apache site for Zimbra.  Under Ubuntu, add these lines to a new file named ''/etc/apache2/sites-available/zimbra'':
 
<pre>
 
<pre>
 
<IfModule mod_proxy.c>
 
<IfModule mod_proxy.c>
 
ProxyRequests On
 
ProxyRequests On
 +
ProxyVia On
  
<Proxy *>
+
<Location "/service">
 
     Order deny,allow
 
     Order deny,allow
 
     Deny from all
 
     Deny from all
 
     Allow from 127.0.0.1
 
     Allow from 127.0.0.1
 
     Allow from 192.168.0.5
 
     Allow from 192.168.0.5
    Allow from localhost
 
 
     Allow from your.domain.com
 
     Allow from your.domain.com
# this list goes on and on
+
    # modify this to your needs, but do not skip this step!
# OR, you can simply comment out this entire access control block
 
# BUT DON'T EVER DO THAT!
 
# You won't if you have ever heard of Distributed Denial of Service attacks!
 
</Proxy>
 
  
<Location "/service">
+
    ProxyPass http://localhost:8080/service
ProxyPass http://192.168.0.5:6080/service
+
    ProxyPassReverse http://localhost:8080/service
ProxyPassReverse http://192.168.0.5:6080/service
 
 
</Location>
 
</Location>
  
 
<Location "/zimbra">
 
<Location "/zimbra">
ProxyPass http://192.168.0.5:6080/zimbra
+
    Order deny,allow
ProxyPassReverse http://192.168.0.5:6080/zimbra
+
    Deny from all
 +
    Allow from 127.0.0.1
 +
    Allow from 192.168.0.5
 +
    Allow from your.domain.com
 +
    # modify this to your needs, but do not skip this step!
 +
 
 +
    ProxyPass http://localhost:8080/zimbra
 +
    ProxyPassReverse http://localhost:8080/zimbra
 
</Location>
 
</Location>
 
ProxyVia On
 
  
 
</IfModule>
 
</IfModule>
 
</pre>
 
</pre>
  
2. If you use "mod_jk". It is cool! If it would not be, I would not be writing this.
+
* Enable the site. Under Ubuntu, use the command:
 +
<pre>sudo a2ensite zimbra</pre>
 +
(Instead of creating a site, you could also add the previous configuration block to either ''apache2.conf'', ''httpd.conf'', or to a new file in ''conf.d/''.)
  
= How To =
+
* Restart Apache.  Under Ubuntu, use the command:
 +
<pre>sudo /etc/init.d/apache2 force-reload</pre>
  
== My setup of Zimbra ==
+
== Using Apache JServ Protocol ==
* CentOS 4.3
+
The application server ([http://tomcat.apache.org/ Tomcat] for Zimbra 4.5 and earlier, or [http://www.mortbay.org/ Jetty] for Zimbra 5.0) will be configured to bind to port 8009, in addition to the other ports that it is currently bound to for the Zimbra web interface.  The application server will serve requests on this port using the [http://en.wikipedia.org/wiki/Apache_JServ_Protocol Apache JServ Protocol (AJP)]. Then Apache will be configured to access Zimbra through this port with AJP, using either [http://httpd.apache.org/docs/2.2/mod/mod_proxy_ajp.html mod_proxy_ajp] or [http://en.wikipedia.org/wiki/Mod_jk mod_jk].
* Zimbra Open Source 4.0.0 RC1 (also, tested this with ZCS 4.0.0 GA, it works and I am using it)
 
* Pentium 4 2.8 GHz Processor, 1 GB Memory
 
  
== Pre-requisites, Assumptions, et al. ==
+
=== Configuring the application server ===
* I am assuming that you already have a fully functional instance of Zimbra running on your system.
+
 
* I had Zimbra running on port 6080. So, I will use 6080 to refer to the port Zimbra runs on.
+
==== For Zimbra 5.0 ====
* I have still not experimented with https, which I will do once I finish writing this How-to and post the results here. But, I am pretty confident that it will work.
+
Edit the file ''/opt/zimbra/jetty/etc/jetty.xml.in'':
'''Confirmed:''' This works with SSL, too. For this your authentication type should be https. The following command should do it:
+
* Search for these lines:
 
<pre>
 
<pre>
su - zimbra
+
    <!-- =========================================================== -->
zmtlsctl https
+
    <!-- Set connectors                                              -->
 +
    <!-- =========================================================== -->
 
</pre>
 
</pre>
 
+
* Below them, add the following:
* I am using http authentication
 
 
 
== How it works ==
 
What does Tomcat or any web server or any server generally do? It binds to some port and waits for requests and when it receives them, it serves them. In this case, too, we are going to do the same. We will bind Tomcat to listen to port 8009 (in addition to other ports for http and https that it will bind to out-of-the-box when Zimbra is installed) and we will ask Apache to send request to this port when it itself receives request for serving Zimbra. So, port 8009 will be their point of communication. The module "mod_jk" allows Apache to communicate via a protocol called "AJP 1.3", which, Tomcat already understands.
 
 
 
Now that both of them know Japanese - (Master mod_jk taught Mr. Apache to speak and understand it) they decide to meet at Miss Tomcat's place!
 
 
 
Here is one representation:
 
 
 
# You want to access Zimbra
 
# You point your browser to http://your.domain.com/zimbra/
 
# This request is sent to port 80 on your.server.com
 
# Apache is listening on port 80 and it tries to serve your request by checking its configuration first
 
# Its configuration says that the content for http://your.domain.com/zimbra/ is being served by some service on port 8009
 
# It also says that port 8009 will understand only AJP 1.3 protocol
 
# Since, Apache has mod_jk.so present in its modules directory it is able to communicate via AJP 1.3
 
# It sends request to port 8009
 
# Tomcat is listening on port 8009
 
# As soon as it receives this request, it fetches the content and serves it on this port 8009
 
# This content is then taken from there and served to you on port 80, which is where you placed request for it
 
 
 
== Prozess! ==
 
 
 
(I am not repeating what the docs already say somewhere - this is just to make it work)
 
 
 
* Download mod_jk from [http://tomcat.apache.org/download-connectors.cgi here]
 
* Uncompress the archive and follow the instructions in the doc directory for installing it. I've found some neat instructions [http://www.howtoforge.com/apache2_tomcat5_mod_jk_p2?s=e539814ef307061b6e1c99dd41e67046& here], have a look at them, it explains how to build your <tt>mod_jk</tt> for debian sarge, other distros should be similiar.
 
* Once "mod_jk" is installed, create a file called '''/etc/httpd/conf/workers.properties''' and dump in the following text:
 
 
 
 
<pre>
 
<pre>
# Zimbra worker
+
    <Call name="addConnector">
worker.list=zimbra
+
      <Arg>
worker.zimbra.type=ajp13
+
        <New id="ajp" class="org.mortbay.jetty.ajp.Ajp13SocketConnector">
worker.zimbra.host=localhost
+
          <Set name="port">8009</Set>
worker.zimbra.port=8009
+
        </New>
worker.zimbra.lbfactor=1
+
      </Arg>
workers.tomcat_home=/opt/zimbra/tomcat
+
    </Call>
workers.java_home=/opt/zimbra/java
 
 
</pre>
 
</pre>
  
* Create a file called '''/etc/httpd/conf.d/tomcat.conf''' and dump in the following text:
 
  
 +
Next, edit the file ''/opt/zimbra/jetty/etc/service.web.xml.in'':
 +
* Search for instances of the ''allowed.ports'' parameter, which will look like this:
 
<pre>
 
<pre>
# Load mod_jk module
+
    <init-param>
# Update this path to match your modules location
+
       <param-name>allowed.ports</param-name>
LoadModule      jk_module       modules/mod_jk.so
+
      <param-value>%%zimbraMailPort%%, %%zimbraMailSSLPort%%, 7070, 7443, 7071</param-value>
# Declare the module for <IfModule directive> (remove this line on Apache 2.x)
+
    </init-param>
# AddModule    mod_jk.c
 
 
 
# Where to find workers.properties
 
# Update this path to match your conf directory location (put workers.properties next to httpd.conf)
 
JkWorkersFile          /etc/httpd/conf/workers.properties
 
 
 
# Where to put jk logs
 
# Update this path to match your logs directory location (put mod_jk.log next to access_log)
 
JkLogFile              /etc/httpd/logs/mod_jk.log
 
# Set the jk log level [debug/error/info]
 
JkLogLevel              info
 
# Select the log format
 
JkLogStampFormat        "[%a %b %d %H:%M:%S %Y] "
 
 
 
# JkOptions indicate to send SSL KEY SIZE,
 
JkOptions      +ForwardKeySize +ForwardURICompat      -ForwardDirectories
 
 
 
# JkRequestLogFormat set the request format
 
JkRequestLogFormat      "%w %V %T"
 
 
 
# Send everything for context /examples to worker named zimbra (ajp13)
 
JkMount        /zimbra        zimbra
 
JkMount        /zimbra/        zimbra
 
JkMount        /zimbra/*      zimbra
 
JkMount        /service        zimbra
 
JkMount        /service/      zimbra
 
JkMount        /service/*      zimbra
 
JkMount        /zimbraAdmin    zimbra
 
JkMount        /zimbraAdmin/  zimbra
 
JkMount        /zimbraAdmin/*  zimbra
 
 
</pre>
 
</pre>
 
+
* If the parameter value contains ''%%zimbraMailPort%%'' and ''%%zimbraMailSSLPort%%'', as above, then add port 8009 to the end of the list, like this:
* Edit '''/opt/zimbra/tomcat/conf/server.xml''' and '''/opt/zimbra/tomcat/conf/server.xml.in''' and add the following:
 
 
 
 
<pre>
 
<pre>
<!-- for mod_jk -->
+
...
<Connector port="8009" acceptCount="1024" enableLookups="false" redirectPort="6443" protocol="AJP/1.3" />
+
      <param-value>%%zimbraMailPort%%, %%zimbraMailSSLPort%%, 7070, 7443, 7071, 8009</param-value>
<!-- for mod_jk -->
+
...
 
</pre>
 
</pre>
 +
* If you wish to enable access to the Zimbra administrative web interface, then also perform the above step on any instance of ''allowed.ports'' in which the value contains ''7071''.
  
'''just before:'''
 
  
 +
Finally, restart the application server.  Under Ubuntu, type:
 
<pre>
 
<pre>
<Engine name="Catalina" defaultHost="localhost">
+
sudo -u zimbra /opt/zimbra/bin/zmcontrol stop
 +
sudo -u zimbra /opt/zimbra/bin/zmcontrol start
 
</pre>
 
</pre>
  
'''Note:''' The port 6443 mentioned above as '''redirectPort="6443"''' is the same that you see in the HTTP section in server.xml file. In my server.xml file it looks like this:
+
==== For Zimbra 4.5 and earlier ====
 
+
Edit the file ''/opt/zimbra/tomcat/conf/server.xml.in'':
 +
* Search for these lines in the file, and note the value of ''redirectPort'':
 
<pre>
 
<pre>
 
<!-- HTTPBEGIN -->
 
<!-- HTTPBEGIN -->
Line 180: Line 121:
 
<!-- HTTPEND -->
 
<!-- HTTPEND -->
 
</pre>
 
</pre>
 
+
* Then find this line:
* Restart Tomcat
+
<pre>
 +
<Engine name="Catalina" defaultHost="localhost">
 +
</pre>
 +
* Just '''before''' this line, add the following:
 
<pre>
 
<pre>
tomcat stop
+
<!-- AJPBEGIN -->
tomcat start
+
<Connector port="8009"
 +
        acceptCount="1024"
 +
        enableLookups="false" redirectPort="6443"
 +
        protocol="AJP/1.3" />
 +
<!-- AJPEND -->
 
</pre>
 
</pre>
 +
where '''6443''' is the same as the value of ''redirectPort'' found above.
  
* Now, if you try to visit http://your.domain.com/zimbra the Zimbra log-in screen should appear. If it does not appear please re-check everything again. Perhaps, some of the paths I mentioned above are not the same on your system. Please change them accordingly.
 
* Once the Zimbra log-in screen appears, try to log-in. Most probably you will get some service error. If you can log-in you are done! You need not read ahead. If you can't log-in, please check that in the files '''/opt/zimbra/apache-tomcat-5.5.15/webapps/service/WEB-INF/web.xml''' and '''/opt/zimbra/apache-tomcat-5.5.15/conf/service.web.xml.in''' you have ports 80 and 443 mentioned in all instances where code such as following appears:
 
  
 +
Next, edit the files ''/opt/zimbra/tomcat/conf/service.web.xml.in'' and ''/opt/zimbra/tomcat/conf/zimbra.web.xml.in'' (and, if you would like to access the Zimbra administrative web interface, ''/opt/zimbra/tomcat/conf/zimbraAdmin.web.xml.in''):
 +
* Search for instances of the ''allowed.ports'' parameter, which will look like this:
 
<pre>
 
<pre>
 
     <init-param>
 
     <init-param>
 
       <param-name>allowed.ports</param-name>
 
       <param-name>allowed.ports</param-name>
       <param-value>80, 443, 6080, 6443, 7070, 7443, 7071</param-value>
+
       <param-value>8080, 8443, 7070, 7443, 7071</param-value>
 
     </init-param>
 
     </init-param>
 
</pre>
 
</pre>
 
+
* For each instance, add ports 80 and 443 to the end of the list, like this:
* Restart Tomcat.
 
* Done!
 
 
 
= If it won't work ... =
 
== What will not work? ==
 
Ok, I must admit I entirely forgot to check zimbraAdmin. To make zimbraAdmin available at http://your.domain.com/zimbraAdmin please edit '''/opt/zimbra/tomcat/webapps/zimbraAdmin/WEB-INF/web.xml''', '''/opt/zimbra/tomcat/conf/zimbraAdmin.web.xml.in''', '''/opt/zimbra/tomcat/webapps/service/WEB-INF/web.xml''' and '''/opt/zimbra/tomcat/conf/service.web.xml.in''' and add port 443 along with 7071 in all instances where 7071 has been solely quoted. E.g. If the block looks like this:
 
 
 
 
<pre>
 
<pre>
    <init-param>
+
...
      <param-name>allowed.ports</param-name>
+
       <param-value>8080, 8443, 7070, 7443, 7071, 80, 443</param-value>
       <param-value>7071</param-value>
+
...
    </init-param>
 
 
</pre>
 
</pre>
  
... change it to:
 
  
 +
Finally, restart the application server.  Under Ubuntu, type:
 
<pre>
 
<pre>
    <init-param>
+
sudo -u zimbra /opt/zimbra/bin/zmcontrol stop
      <param-name>allowed.ports</param-name>
+
sudo -u zimbra /opt/zimbra/bin/zmcontrol start
      <param-value>443, 7071</param-value>
 
    </init-param>
 
 
</pre>
 
</pre>
  
Restart tomcat!
+
=== Configuring Apache ===
  
Now you can also access zimbraAdmin at https://your.domain.com/zimbraAdmin
+
==== Using mod_proxy_ajp ====
 +
* Enable ''mod_proxy_ajp''.  Under Ubuntu, use the command:
 +
<pre>sudo a2enmod proxy_ajp</pre>
 +
* Create a new Apache site for Zimbra.  Under Ubuntu, add these lines to a new file named ''/etc/apache2/sites-available/zimbra'':
 +
<pre>
 +
<IfModule mod_proxy_ajp.c>
 +
ProxyRequests On
 +
ProxyVia On
  
== Changes in 4.0.2 GA ==
+
<Location /service>
 +
Order allow,deny
 +
Allow from all
 +
ProxyPass ajp://localhost:8009/service
 +
ProxyPassReverse ajp://localhost:8009/service
 +
</Location>
  
You will notice that the path to web.xml.in has changed in 4.0.2 (I never upgraded to 4.0.1 so am not sure whether these changes exist in it). Now there are three files:
+
<Location /zimbra>
 +
Order allow,deny
 +
Allow from all
 +
ProxyPass ajp://localhost:8009/zimbra
 +
ProxyPassReverse ajp://localhost:8009/zimbra
 +
</Location>
  
* /opt/zimbra/apache-tomcat-5.5.15/conf/zimbraAdmin.web.xml.in
+
<!-- Uncomment these lines to enable access to the Zimbra administrative web interface
* /opt/zimbra/apache-tomcat-5.5.15/conf/service.web.xml.in
+
<Location /zimbraAdmin>
* /opt/zimbra/apache-tomcat-5.5.15/conf/zimbra.web.xml.in
+
Order allow,deny
 +
Allow from all
 +
ProxyPass ajp://localhost:8009/zimbraAdmin
 +
ProxyPassReverse ajp://localhost:8009/zimbraAdmin
 +
</Location>
 +
-->
  
Please make the changes to these files as per the instructions above.
+
</IfModule>
 +
</pre>
 +
* Enable the site.  Under Ubuntu, use the command:
 +
<pre>sudo a2ensite zimbra</pre>
 +
(Instead of creating a site, you could also add the previous configuration block to either ''apache2.conf'', ''httpd.conf'', or to a new file in ''conf.d/''.)
 +
* Restart Apache.  Under Ubuntu, use the command:
 +
<pre>sudo /etc/init.d/apache2 force-reload</pre>
  
 +
==== Using mod_jk ====
 +
* Install ''mod_jk'' for Apache.  Under Ubuntu, use the command:
 +
<pre>sudo apt-get install libapache2-mod-jk</pre>
 +
* In the Apache configuration directory (''/etc/apache2'' in Ubuntu), create a file named ''workers.properties'' and add the following lines to it:
 +
<pre>
 +
worker.list=zimbra
 +
worker.zimbra.type=ajp13
 +
worker.zimbra.host=localhost
 +
worker.zimbra.port=8009
 +
worker.zimbra.lbfactor=1
 +
</pre>
 +
* Add configuration for ''mod_jk'' to Apache.  Under Ubuntu, create a file named ''/etc/apache2/mods-available/jk.conf'' and add the following lines:
 +
<pre>
 +
# Modify the following two paths, according to your distribution's filesystem layout
 +
JkWorkersFile      /etc/apache2/workers.properties
 +
JkLogFile          /var/log/apache2/jk.log
 +
JkLogLevel          info
 +
JkLogStampFormat    "[%a %b %d %H:%M:%S %Y] "
 +
JkRequestLogFormat  "%w %V %T"
 +
JkOptions          +ForwardKeySize +ForwardURICompat -ForwardDirectories
  
----
+
JkMount            /zimbra        zimbra
 +
JkMount            /zimbra/        zimbra
 +
JkMount            /zimbra/*      zimbra
 +
JkMount            /service        zimbra
 +
JkMount            /service/      zimbra
 +
JkMount            /service/*      zimbra
  
 +
# Add the following lines to enable access to the Zimbra administrative web interface
 +
JkMount            /zimbraAdmin    zimbra
 +
JkMount            /zimbraAdmin/  zimbra
 +
JkMount            /zimbraAdmin/*  zimbra
 +
</pre>
 +
(Alternatively, you can add the previous block to either ''apache2.conf'', ''httpd.conf'', or a new file in ''conf.d/''.)
 +
* Enable ''mod_jk''.  Under Ubuntu, use the command:
 +
<pre>sudo a2enmod jk</pre>
  
''' The only thing that does not work now and is in my attention is the Documents Wiki or Zmwiki. I am working on this currently and will soon report progress.'''
+
== Known Issues ==
 
+
When using the Documents Wiki (zmwiki), the links on the wiki page use the port that Zimbra is configured for (i.e., 8080). Currently, you must copy the link to the address bar in your browser, and change the port number in the address.
Ok, regarding the Wiki, I have filed it as a bug here: http://bugzilla.zimbra.com/show_bug.cgi?id=10432
 
  
If you are interested in redirecting the wiki to be available on ports 80 or 443, this bug must be resolved - so, please vote for it. Thanks! :-)
+
== Credits ==
 +
Thanks to everyone at the [http://zimbra.com/forums/ Forums] for posting about their problems and efforts in trying to run Zimbra with Apache using mod_jk.  Also, thanks to the original [[Using_Tomcat_with_Apache_(mod_jk)]] entry (a lot has been borrowed from it). This how-to is a result of their efforts.
  
(The wiki is available as of now, but the links on the wiki page are all made up of your original port E.g. 8080, So the person who wants to visit those pages, must manually enter the URL in the location bar, excluding the ports.)
+
== See Also ==
 +
*[[Using_Tomcat_with_Apache_(mod_jk)]]
 +
*[[ZimbraApache]]
 +
*[[Hosting_other_sites_with_Zimbra]]
  
 
[[Category:MTA]]
 
[[Category:MTA]]

Revision as of 04:24, 24 December 2007

These instructions will enable access to Zimbra and other web applications/pages through the same host/port.

For example, if the Zimbra web interface is running at http://your.domain.com:8080/, and a separate instance of Apache is running at http://your.domain.com/, follow these steps to enable access to the Zimbra web interface through http://your.domain.com/zimbra/.

Disclaimer

This procedure is not fully verified, so follow these directions at your own risk. Particularly, note that using mod_proxy requires you to secure your server first, according to the Apache documentation. Please edit this page if something is wrong or incomplete.

Methods

There are two different ways of accomplishing this:

  1. Creating an HTTP proxy to the Zimbra web interface, using Apache's mod_proxy. (This method is easier but is generally considered to be less secure.)
  2. Configuring the Zimbra web interface for the Apache JServ Protocol (AJP), and then using Apache's mod_proxy_ajp or mod_jk to access it.

Prerequisites

Zimbra and Apache should both be installed.

If you are installing Apache after installing Zimbra, you may first need to change the specific port numbers that the Zimbra web interface uses. For example, if you originally configured Zimbra to use port 80, you will need to change it to another port (such as 8080) in order for Apache to run on port 80. You can do this with the zmprov command.

These instructions include the commands to use under Ubuntu Linux, which may need to be modified slightly under other distributions.

Using an HTTP proxy

  • Install and enable mod_proxy in Apache. Under Ubuntu, mod_proxy is installed by default, so just use this command to enable it:
sudo a2enmod proxy
  • Create a new Apache site for Zimbra. Under Ubuntu, add these lines to a new file named /etc/apache2/sites-available/zimbra:
<IfModule mod_proxy.c>
ProxyRequests On
ProxyVia On

<Location "/service">
    Order deny,allow
    Deny from all
    Allow from 127.0.0.1
    Allow from 192.168.0.5
    Allow from your.domain.com
    # modify this to your needs, but do not skip this step!

    ProxyPass http://localhost:8080/service
    ProxyPassReverse http://localhost:8080/service
</Location>

<Location "/zimbra">
    Order deny,allow
    Deny from all
    Allow from 127.0.0.1
    Allow from 192.168.0.5
    Allow from your.domain.com
    # modify this to your needs, but do not skip this step!

    ProxyPass http://localhost:8080/zimbra
    ProxyPassReverse http://localhost:8080/zimbra
</Location>

</IfModule>
  • Enable the site. Under Ubuntu, use the command:
sudo a2ensite zimbra

(Instead of creating a site, you could also add the previous configuration block to either apache2.conf, httpd.conf, or to a new file in conf.d/.)

  • Restart Apache. Under Ubuntu, use the command:
sudo /etc/init.d/apache2 force-reload

Using Apache JServ Protocol

The application server (Tomcat for Zimbra 4.5 and earlier, or Jetty for Zimbra 5.0) will be configured to bind to port 8009, in addition to the other ports that it is currently bound to for the Zimbra web interface. The application server will serve requests on this port using the Apache JServ Protocol (AJP). Then Apache will be configured to access Zimbra through this port with AJP, using either mod_proxy_ajp or mod_jk.

Configuring the application server

For Zimbra 5.0

Edit the file /opt/zimbra/jetty/etc/jetty.xml.in:

  • Search for these lines:
    <!-- =========================================================== -->
    <!-- Set connectors                                              -->
    <!-- =========================================================== -->
  • Below them, add the following:
    <Call name="addConnector">
      <Arg>
        <New id="ajp" class="org.mortbay.jetty.ajp.Ajp13SocketConnector">
          <Set name="port">8009</Set>
        </New>
      </Arg>
    </Call>


Next, edit the file /opt/zimbra/jetty/etc/service.web.xml.in:

  • Search for instances of the allowed.ports parameter, which will look like this:
    <init-param>
      <param-name>allowed.ports</param-name>
      <param-value>%%zimbraMailPort%%, %%zimbraMailSSLPort%%, 7070, 7443, 7071</param-value>
    </init-param>
  • If the parameter value contains %%zimbraMailPort%% and %%zimbraMailSSLPort%%, as above, then add port 8009 to the end of the list, like this:
...
      <param-value>%%zimbraMailPort%%, %%zimbraMailSSLPort%%, 7070, 7443, 7071, 8009</param-value>
...
  • If you wish to enable access to the Zimbra administrative web interface, then also perform the above step on any instance of allowed.ports in which the value contains 7071.


Finally, restart the application server. Under Ubuntu, type:

sudo -u zimbra /opt/zimbra/bin/zmcontrol stop
sudo -u zimbra /opt/zimbra/bin/zmcontrol start

For Zimbra 4.5 and earlier

Edit the file /opt/zimbra/tomcat/conf/server.xml.in:

  • Search for these lines in the file, and note the value of redirectPort:
<!-- HTTPBEGIN -->
<Connector port="6080"
        acceptCount="1024"
        enableLookups="false" redirectPort="6443"
        maxThreads="100" minSpareThreads="100" maxSpareThreads="100"/>
<!-- HTTPEND -->
  • Then find this line:
<Engine name="Catalina" defaultHost="localhost">
  • Just before this line, add the following:
<!-- AJPBEGIN -->
<Connector port="8009"
        acceptCount="1024"
        enableLookups="false" redirectPort="6443"
        protocol="AJP/1.3" />
<!-- AJPEND -->

where 6443 is the same as the value of redirectPort found above.


Next, edit the files /opt/zimbra/tomcat/conf/service.web.xml.in and /opt/zimbra/tomcat/conf/zimbra.web.xml.in (and, if you would like to access the Zimbra administrative web interface, /opt/zimbra/tomcat/conf/zimbraAdmin.web.xml.in):

  • Search for instances of the allowed.ports parameter, which will look like this:
    <init-param>
      <param-name>allowed.ports</param-name>
      <param-value>8080, 8443, 7070, 7443, 7071</param-value>
    </init-param>
  • For each instance, add ports 80 and 443 to the end of the list, like this:
...
      <param-value>8080, 8443, 7070, 7443, 7071, 80, 443</param-value>
...


Finally, restart the application server. Under Ubuntu, type:

sudo -u zimbra /opt/zimbra/bin/zmcontrol stop
sudo -u zimbra /opt/zimbra/bin/zmcontrol start

Configuring Apache

Using mod_proxy_ajp

  • Enable mod_proxy_ajp. Under Ubuntu, use the command:
sudo a2enmod proxy_ajp
  • Create a new Apache site for Zimbra. Under Ubuntu, add these lines to a new file named /etc/apache2/sites-available/zimbra:
<IfModule mod_proxy_ajp.c>
ProxyRequests On
ProxyVia On

<Location /service>
Order allow,deny
Allow from all
ProxyPass ajp://localhost:8009/service
ProxyPassReverse ajp://localhost:8009/service
</Location>

<Location /zimbra>
Order allow,deny
Allow from all
ProxyPass ajp://localhost:8009/zimbra
ProxyPassReverse ajp://localhost:8009/zimbra
</Location>

<!-- Uncomment these lines to enable access to the Zimbra administrative web interface
<Location /zimbraAdmin>
Order allow,deny
Allow from all
ProxyPass ajp://localhost:8009/zimbraAdmin
ProxyPassReverse ajp://localhost:8009/zimbraAdmin
</Location>
-->

</IfModule>
  • Enable the site. Under Ubuntu, use the command:
sudo a2ensite zimbra

(Instead of creating a site, you could also add the previous configuration block to either apache2.conf, httpd.conf, or to a new file in conf.d/.)

  • Restart Apache. Under Ubuntu, use the command:
sudo /etc/init.d/apache2 force-reload

Using mod_jk

  • Install mod_jk for Apache. Under Ubuntu, use the command:
sudo apt-get install libapache2-mod-jk
  • In the Apache configuration directory (/etc/apache2 in Ubuntu), create a file named workers.properties and add the following lines to it:
worker.list=zimbra
worker.zimbra.type=ajp13
worker.zimbra.host=localhost
worker.zimbra.port=8009
worker.zimbra.lbfactor=1
  • Add configuration for mod_jk to Apache. Under Ubuntu, create a file named /etc/apache2/mods-available/jk.conf and add the following lines:
# Modify the following two paths, according to your distribution's filesystem layout
JkWorkersFile       /etc/apache2/workers.properties
JkLogFile           /var/log/apache2/jk.log
JkLogLevel          info
JkLogStampFormat    "[%a %b %d %H:%M:%S %Y] "
JkRequestLogFormat  "%w %V %T"
JkOptions           +ForwardKeySize +ForwardURICompat -ForwardDirectories

JkMount             /zimbra         zimbra
JkMount             /zimbra/        zimbra
JkMount             /zimbra/*       zimbra
JkMount             /service        zimbra
JkMount             /service/       zimbra
JkMount             /service/*      zimbra

# Add the following lines to enable access to the Zimbra administrative web interface
JkMount             /zimbraAdmin    zimbra
JkMount             /zimbraAdmin/   zimbra
JkMount             /zimbraAdmin/*  zimbra

(Alternatively, you can add the previous block to either apache2.conf, httpd.conf, or a new file in conf.d/.)

  • Enable mod_jk. Under Ubuntu, use the command:
sudo a2enmod jk

Known Issues

When using the Documents Wiki (zmwiki), the links on the wiki page use the port that Zimbra is configured for (i.e., 8080). Currently, you must copy the link to the address bar in your browser, and change the port number in the address.

Credits

Thanks to everyone at the Forums for posting about their problems and efforts in trying to run Zimbra with Apache using mod_jk. Also, thanks to the original Using_Tomcat_with_Apache_(mod_jk) entry (a lot has been borrowed from it). This how-to is a result of their efforts.

See Also

Jump to: navigation, search