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.
- Log into the ZMI (see Access the ZMI).
- Visit the folder for your site at .
- Open the DivisionConfiguration object.
- Set the canonicalHost to the domain for your new site.
- Set the canonicalPort to
80
. - Click the Save Changes button.
Add a virtual host to Apache¶
To add a virtual host to Apache carry out the following steps.
Ensure the
rewrite
,proxy
, andproxy_httpd
modules are enabled in Apache:# a2enmod rewrite proxy proxy_http # service apache2 restart
Open
/etc/apache2/sites-available/groupserver
in a text-editor.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 thezmi
at the start.
- Change the address for the GroupServer site from
- Change the email address for
ServerAdmin
fromsupport@example.com
to the value of thesupport_email
in theconfig.cfg
file in the GroupServer directory.
- Two virtual sites are defined: one that presents
GroupServer (which is used most of the time) and one for
the ZMI.
Link the configuration for your host:
# cd /etc/apache2/sites-enabled/ # ln -s ../sites-available/groupserver 100-groupserver
Restart Apache using service
# service apache2 restart
Add a virtual host to nginx¶
Open /etc/nginx/sites-available/groupserver
in a
text-editor.
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 firstserver
fromgroups.example.com
to the address of you new virtual host. - Change the host name for the ZMI, defined by the second
server
fromzmi.groups.example.com
to that of your new virtual host, keeping thezmi
at the start.
- Change the
- Two virtual sites are defined: one that presents
GroupServer (which is used most of the time) and one for
the ZMI.
Link the configuration for your host:
# cd /etc/nginx/sites-enabled/ # ln -s ../sites-available/groupserver 100-groupserver
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.
- Login to the ZMI for your site.
- Visit the folder for your site, at groupserver/Content/initial_site.
- Open the DivisionConfiguration object.
- Select the check-box next to the canonicalPort line.
- 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 thanhttp
.
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.
- Login to the ZMI for your site.
- Visit the folder for your site at .
- Select the DivisionConfiguration object.
- Set the canonicalPort to
443
. - Select the useHTTPS check-box (the one to the right, sorry it is confusing).
- 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. |