Difference between revisions of "Provide HTTP(s) Integration with Apache"

m (Step 1)
 
(50 intermediate revisions by 3 users not shown)
Line 1: Line 1:
=Setting up HTTP and HTTPS support through Apache VirtualHosts=
+
{{Archive}}{{Unsupported}}=Setting up HTTP and HTTPS support through Apache VirtualHosts=
  
  
Line 6: Line 6:
 
Single production server, with public IP address running apache web server hosting multiple virtual domains, and Zimbra Groupware server to providing email and webmail access to users in multiple virtual domains.
 
Single production server, with public IP address running apache web server hosting multiple virtual domains, and Zimbra Groupware server to providing email and webmail access to users in multiple virtual domains.
  
The example domain used in this article is 'server.com' - replace with your own domain.
+
The example domain used in this article is 'server.com' - replace with your own domain and is aimed at Redhat/CentOS based machines - the syntax of most commands will no doubt succeed on alternative Linux distributions but the file structuring may differ slightly.
  
 
===Aims===
 
===Aims===
Line 12: Line 12:
 
* You want to provide both http (insecure) and https (secure) access to clients through the webmail interface.
 
* You want to provide both http (insecure) and https (secure) access to clients through the webmail interface.
  
* On 'server.com' you want to provide webmail access when users visit 'http://webmail.server.com' and secure acces when they visit 'https://webmail.server.com'.
+
* On 'server.com' you want to provide webmail access when users visit 'http://webmail.server.com' and secure access when they visit 'https://webmail.server.com'.
  
 
* The Apache server listens on default ports 80 and 443, the Zimbra server listens on port 81 and uses the insecure login authentication method (zmtlsctl http).
 
* The Apache server listens on default ports 80 and 443, the Zimbra server listens on port 81 and uses the insecure login authentication method (zmtlsctl http).
Line 18: Line 18:
 
===System Requirements===
 
===System Requirements===
  
* [http://httpd.apache.org/ Installed Apache webserver]
+
* [http://www.europe.redhat.com/ RedHat] or [http://www.centos.org/ CentOS] Linux installation
* [http://httpd.apache.org/docs/1.3/vhosts/examples.html Familiarity with Apache VirtualHost configurations]
+
* Installed [http://httpd.apache.org/ Apache] web-server
* [http://wiki.zimbra.com/index.php?title=Installation_Articles Working Zimbra installation]
+
* Familiarity with [http://httpd.apache.org/docs/1.3/vhosts/examples.html Apache Virtualhost] configuration files
 +
* Working [http://wiki.zimbra.com/index.php?title=Installation_Articles Zimbra] installation
  
 
===Time To Implement===
 
===Time To Implement===
Line 28: Line 29:
 
===Advice===
 
===Advice===
  
The article has been written by community members, Zimbra administrators and experienced coders - the proof reading may not be perfect and aims to provide ideas and an exampe of a successful working practice.
+
The article has been written by community members, Zimbra administrators and experienced coders - the proof-reading may not be perfect and aims to provide ideas and an example of a successful working practice.
  
Please feel free to use the [http://www.zimbra.com/forums/ Zimbra Forums] to request more specific help, follow the article closely and do not rush - it will only take longer !!
+
Please feel free to use the [http://www.zimbra.com/forums/ Zimbra Forums] to request more specific help, follow the article closely and do not rush - it will only take longer !
 +
 
 +
[[#Setting up HTTP and HTTPS support through Apache VirtualHosts|Top]]
  
 
=Laying the foundations=
 
=Laying the foundations=
Line 36: Line 39:
 
===Plan of Action===
 
===Plan of Action===
  
* Configure Zimbra to run on port 81.
+
* [[#Step 1|Configure Zimbra to run on port 81]].
 +
 
 +
* [[#Step 2|Configure Zimbra to use simple http authentication]].
 +
 
 +
* [[#Step 3 - requires root access|Install a new virtual host to catch all webmail.server.com requests]].
  
* Configure Zimbra to use simple http authentication.
+
* [[#Step 4 - requires root access|Install a new virtual host to catch all secure webmail.server.com requests]].
  
* Install a new virtual host to catch all webmail.server.com requests.
+
All following commands are issued whilst logged in with the 'zimbra' user.
  
* Install a new virtual host to catch all secure webmail.server.com requests.
+
<code>
 +
<pre>sudo su - zimbra</pre></code>
 +
 
 +
[[#Setting up HTTP and HTTPS support through Apache VirtualHosts|Top]]
  
 
===Step 1===
 
===Step 1===
Line 48: Line 58:
 
* Ensure Zimbra is running on port 81
 
* Ensure Zimbra is running on port 81
  
<code>
+
Using the syntax : zmprov ms <your-server> zimbraMailPort <your-port-number>
<pre>sudo su - zimbra</pre>
+
<code><pre>zmprov ms server.com zimbraMailPort 81</pre>
<pre>zm
 
 
</code>
 
</code>
 +
 +
======Step 1 Breakdown======
 +
 +
We logged in as the 'zimbra' user, then using the zmprov command to manipulate server name pair values, tell Zimbra to use the mail port number 81.
  
 
n.b. [http://www.zimbra.com/forums/administrators/7986-change-zimbra-webmail-port-number.html a more detailed thread here]
 
n.b. [http://www.zimbra.com/forums/administrators/7986-change-zimbra-webmail-port-number.html a more detailed thread here]
 +
 +
[[#Setting up HTTP and HTTPS support through Apache VirtualHosts|Top]]
  
 
===Step 2===
 
===Step 2===
* Create a new apache configuration file to contain our virtualhosts
+
 
 +
* Tell Zimbra to use the http authentication method - this does not redirect logins to SSL basically.
 +
 
 +
<code>
 +
<pre>zmtlsctl http</pre>
 +
<pre>zmcontrol stop;zmcontrol start</pre>
 +
</code>
 +
 
 +
======Step 2 Breakdown======
 +
 
 +
We issued the 'zmtlsctl' command and passed the http value (other options include https,both,mixed,redirect but they do not apply to this article)
 +
 
 +
The Zimbra server was then restarted using the 'zmcontrol' command.
 +
 
 +
[[#Setting up HTTP and HTTPS support through Apache VirtualHosts|Top]]
 +
 
 +
===Step 3 - requires root access===
 +
 
 +
* Create a new apache configuration file to listen for  webmail requests on port 80 within /etc/httpd/conf.d/zimbra.conf.
 +
 
 +
<code>
 +
<pre>sudo su - </pre>
 +
<pre>nano /etc/httpd/conf.d/zimbra.conf</pre>
 +
</code>
 +
 
 +
Once within your text editor ensure it looks like this:
 +
 
 +
<code>
 +
<pre>
 +
<VirtualHost *:80>
 +
    ServerAlias webmail.*
 +
    ProxyPass / http://server.com:81/
 +
    ProxyPassReverse / http://server.com:81/
 +
    ErrorLog /var/log/httpd/zimbra-error.log
 +
</VirtualHost>
 +
</pre>
 +
</code>
 +
 
 +
======Step 3 Breakdown======
 +
 
 +
We logged in as root using the 'sudo su - ' command, allowing us write access to the Apache configuration directory - located at /etc/httpd/conf.d/.
 +
 
 +
Then created a new virtual host that listens on port 80 on all network interfaces.
 +
 
 +
The new virtual host has a server alias of webmail.* - meaning any virtual domain on your server's IP addresses beginning with webmail. will be handled here.
 +
 
 +
The proxypass line silently redirects all traffic to the zimbra port without the user knowing what is going on behind the scenes.
 +
 
 +
The proxypassreverse line, simply listens for traffic coming back from the redirect - again without the end user knowing what is going on behind the scenes.
 +
 
 +
Always useful - we tell Apache to keep a log of any errors in the usual /var/log/httpd/ directory using the ErrorLog line- in case we experience problems we can use the log to troubleshoot. (If all runs smoothly just a # to the beginning of this line to turn the error logging off).
 +
 
 +
[[#Setting up HTTP and HTTPS support through Apache VirtualHosts|Top]]
 +
 
 +
===Step 4 - requires root access===
 +
 
 +
* Create a new apache configuration file to listen for  webmail requests on port 443 within /etc/httpd/conf.d/zimbra.conf
 +
 
 +
<code>
 +
<pre>sudo su - </pre>
 +
<pre>nano /etc/httpd/conf.d/zimbra.conf</pre>
 +
</code>
 +
 
 +
Add the following underneath our previous entry:
 +
 
 +
<code>
 +
<pre>
 +
<VirtualHost *:443>
 +
        ServerAlias webmail.*
 +
        SSLProxyEngine ON
 +
        SSLEngine On
 +
        SSLCertificateFile /opt/zimbra/ssl/ssl/server/server.crt
 +
        SSLCertificateKeyFile /opt/zimbra/ssl/ssl/server/server.key
 +
        ProxyPass / http://server.com:81/
 +
        ProxyPassReverse / http://server.com:81/
 +
        ErrorLog /var/log/httpd/zimbra_ssl-error.log
 +
</VirtualHost>
 +
</pre>
 +
</code>
 +
 
 +
======Step 4 Breakdown======
 +
 
 +
We logged in as root using the 'sudo su - ' command, allowing us write access to the Apache configuration directory - located at /etc/httpd/conf.d/.
 +
 
 +
Then we created a new virtual host that listens for https requests on port 443 on all network interfaces.
 +
 
 +
The new virtual host, again, has a server alias of webmail.* - meaning any virtual domain on your server's IP addresses beginning with webmail. will be handled here - as before but ensuring all https requests are acknowledged.
 +
 
 +
The proxypass line silently redirects all traffic to the zimbra port without the user knowing what is going on behind the scenes, as before but this time wrapping the insecure back-end within the https front-end to the client's browser.
 +
 
 +
The proxypassreverse line, simply listens for traffic coming back from the redirect - again without the end user knowing what is going on behind the scenes, again wrapping the insecure back-end responses ready for the secure server to client transfer.
 +
 
 +
Always useful - we tell Apache to keep a log of any SSL errors in the usual /var/log/httpd/ directory, using the ErrorLog line- in case we experience problems we can use the log to troubleshoot. (If all runs smoothly just a # to the beginning of this line to turn the error logging off).
 +
 
 +
[[#Setting up HTTP and HTTPS support through Apache VirtualHosts|Top]]
 +
 
 +
===Apache Config check===
 +
 
 +
* Test the configuration file to ensure we have no syntax errors before restarting the server
 +
 
 +
<code>
 +
<pre>sudo httpd -t</pre>
 +
</code>
 +
 
 +
======Apache config breakdown======
 +
 
 +
Using the 'sudo' command to elevate our privileges, we run the httpd binary and the -t switch to test all configuration files for syntax errors.
 +
 
 +
Hopefully, the response should be:
 +
 
 +
<code>
 +
<pre>Syntax OK</pre>
 +
</code>
 +
 
 +
If not read the error carefully, check and re-check your zimbra.conf file and utilise your resources - i.e. Google, the Zimbra forums etc.
 +
 
 +
[[#Setting up HTTP and HTTPS support through Apache VirtualHosts|Top]]
 +
 
 +
===Restart and test your login===
 +
 
 +
* Restart Apache
 +
 
 +
<code>
 +
<pre>sudo /etc/init.d/httpd restart</pre>
 +
</code>
 +
 
 +
* Open your browser and test your insecure login page
 +
 
 +
http://webmail.server.com
 +
 
 +
* Open a new tab and test your secure login page
 +
 
 +
https://webmail.server.com
 +
 
 +
[[#Setting up HTTP and HTTPS support through Apache VirtualHosts|Top]]
 +
 
 +
=Zimbra and mod_security=
 +
After recently installing mod_security, post zcs install, I noticed the webmail interface had problems when using proxy virtualhost configurations.
 +
 
 +
After a lot of effort I decided the easiest thing to get the job working with minimal fuss was to simply disable the security filter for webmail virtualhosts.
 +
 
 +
This still leaves mod_security to do it's job with other virtualhosts by default.
 +
 
 +
Just add the following fot http virtualhosts:
 +
<code>
 +
<pre>
 +
<VirtualHost *:80>
 +
    ServerAlias webmail.*
 +
    SecFilterEngine Off
 +
    ProxyPass / http://server.com:81/
 +
    ProxyPassReverse / http://server.com:81/
 +
    ErrorLog /var/log/httpd/zimbra-error.log
 +
</VirtualHost>
 +
</pre>
 +
</code>
 +
 
 +
and for https virtualhosts:
 +
 
 +
<code>
 +
<pre>
 +
<VirtualHost *:443>
 +
        ServerAlias webmail.*
 +
        SecFilterEngine Off
 +
        SSLProxyEngine ON
 +
        SSLEngine On
 +
        SSLCertificateFile /opt/zimbra/ssl/ssl/server/server.crt
 +
        SSLCertificateKeyFile /opt/zimbra/ssl/ssl/server/server.key
 +
        ProxyPass / http://server.com:81/
 +
        ProxyPassReverse / http://server.com:81/
 +
        ErrorLog /var/log/httpd/zimbra_ssl-error.log
 +
</VirtualHost>
 +
</pre>
 +
</code>
 +
 
 +
Created by [[User:Costa-101|Costa-101]]
 +
 
 +
= ERROR: mod_proxy with Apache2 =
 +
If you are getting some "500 Internal Server Error" when accessing  http://webmail.server.com/, and you find an error like this in your "zimbra-error.log":
 +
<code>
 +
<pre>
 +
[DATE TIME] [warn] proxy: No protocol handler was valid for the URL /favicon.ico. If you are using a DSO version of mod_proxy, make sure the proxy submodules are included in the configuration using LoadModule.
 +
</pre>
 +
</code>
 +
 
 +
This problem could most likely be solved by linking and therefore loading a required mod. Run the following as root:
 +
<code>
 +
<pre>
 +
ln -s /etc/apache2/mods-available/proxy_http.load \
 +
/etc/apache2/mods-enabled/proxy_http.load
 +
</pre>
 +
</code>
 +
verify that apache configuration is working fine by running
 +
<code>
 +
<pre>
 +
apache2ctl configtest
 +
apache2ctl graceful
 +
</pre>
 +
</code>
 +
 
 +
Added by [[User:Mordred|Mordred]]
 +
=External Links=
 +
 
 +
* [http://wiki.zimbra.com/index.php?title=Scripts_to_sync_to_a_remote_Zimbra_backup_machine Scheduling backups]
 +
* [http://lcrm.co.uk/ LCRM Zimbra Support]
 +
* [http://serendipity.ruwenzori.net/index.php/2006/12/24/proxy-no-protocol-handler-was-valid-for-the-url]
 +
 
 +
{{Article Footer|unknown|2/17/2008}}
 +
 
 +
 
 +
 
 +
[[Category:CentOS]]
 +
[[Category:Linux]]
 +
[[Category:RHEL]]

Latest revision as of 14:28, 30 March 2015

Setting up HTTP and HTTPS support through Apache VirtualHosts

Scenario

Single production server, with public IP address running apache web server hosting multiple virtual domains, and Zimbra Groupware server to providing email and webmail access to users in multiple virtual domains.

The example domain used in this article is 'server.com' - replace with your own domain and is aimed at Redhat/CentOS based machines - the syntax of most commands will no doubt succeed on alternative Linux distributions but the file structuring may differ slightly.

Aims

  • You want to provide both http (insecure) and https (secure) access to clients through the webmail interface.
  • The Apache server listens on default ports 80 and 443, the Zimbra server listens on port 81 and uses the insecure login authentication method (zmtlsctl http).

System Requirements

Time To Implement

Outside of meeting the system requirements, and reading this article through - the actual coding will take between 5-15 minutes depending on how familiar you are with the Linux command-line and the Zimbra server.

Advice

The article has been written by community members, Zimbra administrators and experienced coders - the proof-reading may not be perfect and aims to provide ideas and an example of a successful working practice.

Please feel free to use the Zimbra Forums to request more specific help, follow the article closely and do not rush - it will only take longer !

Top

Laying the foundations

Plan of Action

All following commands are issued whilst logged in with the 'zimbra' user.

sudo su - zimbra

Top

Step 1

  • Ensure Zimbra is running on port 81

Using the syntax : zmprov ms <your-server> zimbraMailPort <your-port-number>

zmprov ms server.com zimbraMailPort 81

Step 1 Breakdown

We logged in as the 'zimbra' user, then using the zmprov command to manipulate server name pair values, tell Zimbra to use the mail port number 81.

n.b. a more detailed thread here

Top

Step 2

  • Tell Zimbra to use the http authentication method - this does not redirect logins to SSL basically.

zmtlsctl http
zmcontrol stop;zmcontrol start

Step 2 Breakdown

We issued the 'zmtlsctl' command and passed the http value (other options include https,both,mixed,redirect but they do not apply to this article)

The Zimbra server was then restarted using the 'zmcontrol' command.

Top

Step 3 - requires root access

  • Create a new apache configuration file to listen for webmail requests on port 80 within /etc/httpd/conf.d/zimbra.conf.

sudo su - 
nano /etc/httpd/conf.d/zimbra.conf

Once within your text editor ensure it looks like this:

<VirtualHost *:80> 
     ServerAlias webmail.*
     ProxyPass / http://server.com:81/
     ProxyPassReverse / http://server.com:81/
     ErrorLog /var/log/httpd/zimbra-error.log
</VirtualHost>

Step 3 Breakdown

We logged in as root using the 'sudo su - ' command, allowing us write access to the Apache configuration directory - located at /etc/httpd/conf.d/.

Then created a new virtual host that listens on port 80 on all network interfaces.

The new virtual host has a server alias of webmail.* - meaning any virtual domain on your server's IP addresses beginning with webmail. will be handled here.

The proxypass line silently redirects all traffic to the zimbra port without the user knowing what is going on behind the scenes.

The proxypassreverse line, simply listens for traffic coming back from the redirect - again without the end user knowing what is going on behind the scenes.

Always useful - we tell Apache to keep a log of any errors in the usual /var/log/httpd/ directory using the ErrorLog line- in case we experience problems we can use the log to troubleshoot. (If all runs smoothly just a # to the beginning of this line to turn the error logging off).

Top

Step 4 - requires root access

  • Create a new apache configuration file to listen for webmail requests on port 443 within /etc/httpd/conf.d/zimbra.conf

sudo su - 
nano /etc/httpd/conf.d/zimbra.conf

Add the following underneath our previous entry:

<VirtualHost *:443> 
        ServerAlias webmail.*
        SSLProxyEngine ON
        SSLEngine On
        SSLCertificateFile /opt/zimbra/ssl/ssl/server/server.crt
        SSLCertificateKeyFile /opt/zimbra/ssl/ssl/server/server.key
        ProxyPass / http://server.com:81/
        ProxyPassReverse / http://server.com:81/
        ErrorLog /var/log/httpd/zimbra_ssl-error.log
</VirtualHost>

Step 4 Breakdown

We logged in as root using the 'sudo su - ' command, allowing us write access to the Apache configuration directory - located at /etc/httpd/conf.d/.

Then we created a new virtual host that listens for https requests on port 443 on all network interfaces.

The new virtual host, again, has a server alias of webmail.* - meaning any virtual domain on your server's IP addresses beginning with webmail. will be handled here - as before but ensuring all https requests are acknowledged.

The proxypass line silently redirects all traffic to the zimbra port without the user knowing what is going on behind the scenes, as before but this time wrapping the insecure back-end within the https front-end to the client's browser.

The proxypassreverse line, simply listens for traffic coming back from the redirect - again without the end user knowing what is going on behind the scenes, again wrapping the insecure back-end responses ready for the secure server to client transfer.

Always useful - we tell Apache to keep a log of any SSL errors in the usual /var/log/httpd/ directory, using the ErrorLog line- in case we experience problems we can use the log to troubleshoot. (If all runs smoothly just a # to the beginning of this line to turn the error logging off).

Top

Apache Config check

  • Test the configuration file to ensure we have no syntax errors before restarting the server

sudo httpd -t

Apache config breakdown

Using the 'sudo' command to elevate our privileges, we run the httpd binary and the -t switch to test all configuration files for syntax errors.

Hopefully, the response should be:

Syntax OK

If not read the error carefully, check and re-check your zimbra.conf file and utilise your resources - i.e. Google, the Zimbra forums etc.

Top

Restart and test your login

  • Restart Apache

sudo /etc/init.d/httpd restart

  • Open your browser and test your insecure login page

http://webmail.server.com

  • Open a new tab and test your secure login page

https://webmail.server.com

Top

Zimbra and mod_security

After recently installing mod_security, post zcs install, I noticed the webmail interface had problems when using proxy virtualhost configurations.

After a lot of effort I decided the easiest thing to get the job working with minimal fuss was to simply disable the security filter for webmail virtualhosts.

This still leaves mod_security to do it's job with other virtualhosts by default.

Just add the following fot http virtualhosts:

<VirtualHost *:80> 
     ServerAlias webmail.*
     SecFilterEngine Off
     ProxyPass / http://server.com:81/
     ProxyPassReverse / http://server.com:81/
     ErrorLog /var/log/httpd/zimbra-error.log
</VirtualHost>

and for https virtualhosts:

<VirtualHost *:443> 
        ServerAlias webmail.*
        SecFilterEngine Off
        SSLProxyEngine ON
        SSLEngine On
        SSLCertificateFile /opt/zimbra/ssl/ssl/server/server.crt
        SSLCertificateKeyFile /opt/zimbra/ssl/ssl/server/server.key
        ProxyPass / http://server.com:81/
        ProxyPassReverse / http://server.com:81/
        ErrorLog /var/log/httpd/zimbra_ssl-error.log
</VirtualHost>

Created by Costa-101

ERROR: mod_proxy with Apache2

If you are getting some "500 Internal Server Error" when accessing http://webmail.server.com/, and you find an error like this in your "zimbra-error.log":

[DATE TIME] [warn] proxy: No protocol handler was valid for the URL /favicon.ico. If you are using a DSO version of mod_proxy, make sure the proxy submodules are included in the configuration using LoadModule.

This problem could most likely be solved by linking and therefore loading a required mod. Run the following as root:

ln -s /etc/apache2/mods-available/proxy_http.load \
/etc/apache2/mods-enabled/proxy_http.load

verify that apache configuration is working fine by running

apache2ctl configtest
apache2ctl graceful

Added by Mordred

External Links

Verified Against: unknown Date Created: 2/17/2008
Article ID: https://wiki.zimbra.com/index.php?title=Provide_HTTP(s)_Integration_with_Apache Date Modified: 2015-03-30



Try Zimbra

Try Zimbra Collaboration with a 60-day free trial.
Get it now »

Want to get involved?

You can contribute in the Community, Wiki, Code, or development of Zimlets.
Find out more. »

Looking for a Video?

Visit our YouTube channel to get the latest webinars, technology news, product overviews, and so much more.
Go to the YouTube channel »

Jump to: navigation, search