Configuring a web proxy

Authors:Michael JasonSmith; Fabien Hespul
Contact:Michael JasonSmith <mpj17@onlinegroups.net>
Date:2016-02-18
Organization:GroupServer.org
Copyright:This document is licensed under a Creative Commons Attribution-Share Alike 4.0 International License by OnlineGroups.net.

Introduction

While GroupServer can run as a stand-alone web-server, it is highly recommended that a proxy is used when making the site available to the public to provide the following services:

  • To mediate between the low level HTTP port (port 80) and the high-port that Zope runs on (normally port 8080).
  • To rewrite the URL to include a skin directive.
  • To rewrite the URL to support virtual hosting.
  • To provide caching.
  • To provide a secure connection.

In this document we explain how to add a virtual host to either Apache or nginx, update the DNS, and change the reported port in GroupServer. We then explain how to change the skin, before we outline how to set up secure connections.

Note

You will need to be the root user to carry out most of these tasks. Commands that need to be run as root will be shown with # prompt, rather than a $.

Add a virtual host

If you have a new domain [1] that you want to use with your GroupServer installation first you must update the GroupServer configuration and then add a virtual host to Apache or Add a virtual host to nginx.

Update the GroupServer configuration

If you used a host such as gstest to try out GroupServer then you will need to update the configuration for GroupServer itself.

  1. Log into the ZMI (see Access the ZMI).
  2. Visit the folder for your site at groupserver ‣ Contents ‣ initial_site.
  3. Open the DivisionConfiguration object.
  4. Set the canonicalHost to the domain for your new site.
  5. Set the canonicalPort to 80.
  6. Click the Save Changes button.

Add a virtual host to Apache

To add a virtual host to Apache carry out the following steps.

  1. Ensure the rewrite, proxy, and proxy_httpd modules are enabled in Apache:

    # a2enmod rewrite proxy proxy_http
    # service apache2 restart
    
  2. Open /etc/apache2/sites-available/groupserver in a text-editor.

  3. Add the following to the file

    # GroupServer site
    <VirtualHost *:80>
      ServerAdmin support@example.com
      ServerName groups.example.com
    
      RewriteEngine on
      RewriteRule ^/(.*) http://localhost:8080/groupserver/Content/initial_site/VirtualHostBase/http/%{HTTP_HOST}:80/VirtualHostRoot/$1 [L,P]
    
      ProxyVia On
    
      ErrorLog ${APACHE_LOG_DIR}/error.log
    
      # Possible values include: debug, info, notice, warn, error, crit,
      # alert, emerg.
      LogLevel info
    
      CustomLog ${APACHE_LOG_DIR}/access.log combined
    </VirtualHost>
    
    # ZMI Support
    <VirtualHost *:80>
      ServerAdmin support@example.com
      ServerName zmi.groups.example.com
    
      RewriteEngine on
      RewriteRule ^/(.*) http://localhost:8080/VirtualHostBase/http/%{HTTP_HOST}:80/VirtualHostRoot/$1 [L,P]
    
      ProxyVia On
    
      ErrorLog ${APACHE_LOG_DIR}/zmi-error.log
    
      # Possible values include: debug, info, notice, warn, error, crit,
      # alert, emerg.
      LogLevel info
    
      CustomLog ${APACHE_LOG_DIR}/access.log combined
    </VirtualHost>
    
    • Two virtual sites are defined: one that presents GroupServer (which is used most of the time) and one for the ZMI.
      • Change the address for the GroupServer site from groups.example.com to that of you new virtual host.
      • Change the address for the ZMI from zmi.groups.example.com to that of your new virtual host, keeping the zmi at the start.
    • Change the email address for ServerAdmin from support@example.com to the value of the support_email in the config.cfg file in the GroupServer directory.
  4. Link the configuration for your host:

    # cd /etc/apache2/sites-enabled/
    # ln -s ../sites-available/groupserver 100-groupserver
    
  5. Restart Apache using service

    # service apache2 restart
    

Add a virtual host to nginx

Open /etc/nginx/sites-available/groupserver in a text-editor.

  1. Add the following to the file

    upstream gs {
      server localhost:8080;
    }
    
    server {
      listen 80;
      server_name groups.example.com;
    
      location / {
        rewrite /(.*) /VirtualHostBase/http/$host:80/groupserver/Content/initial_site/VirtualHostRoot/$1 break;
        proxy_pass http://gs/;
        include proxy_params;
      }
    }
    
    server {
      listen 80;
      server_name zmi.groups.example.com;
    
      location / {
        rewrite /(.*) /VirtualHostBase/http/$host:80/VirtualHostRoot/$1 break;
        proxy_pass http://gs/;
        include proxy_params;
      }
    }
    
    • Two virtual sites are defined: one that presents GroupServer (which is used most of the time) and one for the ZMI.
      • Change the server_name in the first server from groups.example.com to the address of you new virtual host.
      • Change the host name for the ZMI, defined by the second server from zmi.groups.example.com to that of your new virtual host, keeping the zmi at the start.
  2. Link the configuration for your host:

    # cd /etc/nginx/sites-enabled/
    # ln -s ../sites-available/groupserver 100-groupserver
    
  3. Reload the nginx configuration using service:

    # service nginx reload
    

Update the DNS

The service that supplies your domain-name should provide instructions for updating the domain name to point to your new virtual host. You will also need the domain for the ZMI to also point to the same server. You can either

  • Add a DNS entry for the ZMI, or
  • Add an entry to your local /etc/hosts file.

Change the reported port

Notifications from GroupServer (such as the Welcome email to a new group member) normally contain links back to the site. These links will reference the port that was used when GroupServer was built (8080) rather than the new HTTP or HTTPS port provided by the proxy. To change the port that GroupServer says it is using carry out the following tasks.

  1. Login to the ZMI for your site.
  2. Visit the folder for your site, at groupserver/Content/initial_site.
  3. Open the DivisionConfiguration object.
  4. Select the check-box next to the canonicalPort line.
  5. Click the Delete button. The canonicalPort value will be deleted.

Note

In the unlikely case that a non-standard port is used, change the value of the canonicalPort and click the Save changes button, rather than deleting the property.

Change the skin

One of the advantages of adding a proxy is it allows the skin to be easily changed. GroupServer ships with two skins: green and blue. To change the skin you must alter the rewrite rule. In the case of nginx the rewrite rule will look like the following

rewrite /(.*) /++skin++gs_blue/VirtualHostBase/http/$host:80/groupserver/Content/initial_site/VirtualHostRoot/$1 break;

In the case of Apache the rewrite rule would look like the following

RewriteRule ^/(.*) http://localhost:8080/++skin++gs_green/groupserver/Content/initial_site/VirtualHostBase/http/%{HTTP_HOST}:80/VirtualHostRoot/$1 [L,P]

Secure connections: TLS, SSL, and HTTPS

Setting up a secure connection is done in two stages. First you set up your proxy, then you configure GroupServer.

Update the proxy configuration

Establishing a secure connection is done by the proxy rather than GroupServer itself. The proxy should still listen to port 80 (HTTP) and make a permanent redirect to the secure site by returning a 301 response. In nginx the rule would look like the following:

server {
  listen 80;
  server_name groups.example.com;

  return 301 https://$server_name$request_uri;
}

The proxy will also listen to the secure port and perform a rewrite to your GroupServer site. This is similar to the rewrite when you add a virtual host, but

  • There is configuration for the SSL certificates,
  • The port is 443, rather than 80, and
  • The protocol is https rather than http.
server {
  listen 443;
  server_name groups.example.com;

  ssl on;
  ssl_certificate /etc/nginx/ssl/groups.example.com.crt;
  ssl_certificate_key /etc/nginx/ssl/groups.example.com.key;

  location / {
    rewrite /(.*) /VirtualHostBase/https/$host:443/groupserver/Content/initial_site/VirtualHostRoot/$1 break;
    proxy_pass http://gs/;
    include proxy_params;
  }
}

You can change the skin in the rewrite rule, just like before.

Update GroupServer

GroupServer should use https links in email messages and in the Share button [2], to prevent potential attacks. To do this carry out the following tasks.

  1. Login to the ZMI for your site.
  2. Visit the folder for your site at groupserver ‣ Contents ‣ initial_site.
  3. Select the DivisionConfiguration object.
  4. Set the canonicalPort to 443.
  5. Select the useHTTPS check-box (the one to the right, sorry it is confusing).
  6. Click the Save Changes button.
[1]Acquiring and configuring a new domain is out of the scope for this documentation. However, you want the A-record for your new domain to point to the IP of your GroupServer site, and the MX-record to also point at your new site.
[2]On the web GroupServer normally uses links without a specified protocol.