SurgeWeb Clustering

There are several different ways to configure surgeweb depending on what you are trying to achieve.

The core of surgeweb is conceptually really just a "serverside normal IMAP client" and should be able to talk to any IMAP server. In addition, some features require surgeweb to be talking to a surgemail backend server - these include the contacts features, surgeplus, and user.cgi features such as spam handling.

Single Server

This is the default normal surgemail and surgeweb deployment. Both surgeweb and IMAP are hosted by one surgemail process. Surgeweb will talk to imap on the same server as necessary.

No special configuration is necessary other than a normal surgemail install.

Frontend / Backend Configuration

In this configuration, surgeweb talks directly to the backend imap server. The server running Surgeweb only hosts temporary files and all the mail, surgeweb configuration files, and the surgeweb contacts (personal and shared) are stored on the primary IMAP server. There are two main reasons that you may want to split the default configuration into a frontend / Backend configuration:

Spreading of load

By installing surgeweb on a separate server all surgeweb related load will be handled by one or more frontend servers, and only a minimal loading is placed on the main server. Surgeweb is designed to minimise the load on the IMAP server - using surgeweb as a client actually provides a lot lighter loading on the imap server than a normal desktop IMAP client.
Reliability & Testing

Under single server configuration, any problems in surgeweb that result in a surgemail restart will affect all mail services. By running surgeweb on a separate server most problems you might encounter in surgeweb will only affect any other surgeweb users actually using the system.
Also, as surgeweb is still under active development and a lot of changes are still being made you are likely to want to upgrade surgeweb more frequently than your primary mail server. The preferred way is to use mirrored systems and installing the latest version on the mirror, have your "test users" using the mirror and if all proves well upgrade the primary system. Alternatively you can run surgeweb on a frontend system and have this pointing at your primary server.

To configure a frontend system:

Make sure your backend system has surgemail fully configured and operational.
Install surgemail on the frontend server and make sure that it is configured pretty much identically to the backend system. Primarily you just need the same vdomains defined, but it is recommended to have the global and per domain settings as similar as possible to the primary system.

On the frontend system you just need to add the domain settings:

	surgeweb_backend_server "main.server.com"

and if non default you may need settings along these lines:

	surgeweb_backend_smtp "main.server.com"
	surgeweb_backend_web "main.server.com"
	surgeweb_backend_web "https://main.server.com:port"

Now test that everything is correctly configured by logging on to surgeweb on the front end system and seeing if you see the correct details of the mail account on the backend system. Also test the contacts interface and usercgi/surgeplus functionality to make sure it is autologging into surgemail correctly.

Possible Gotchas

1) Instead of using the per domain settings a global setting has been available for quite some time.

	g_surgeweb_backend "backend.mydomain.com"

However in versions of surgemail prior to 6.1e-28 a bug existed where the surgeweb - user.cgi autologin also needed the domain setting surgeweb_backend to be set instead / as well as it was not picking up "just" the g_surgeweb_backend setting.

2) In a frontend - backend configuration of surgeweb end users must still be able to connect to user.cgi directly on the backend mailserver so this must be open on the firewall.

3) The *backend_server and *backend_smtp settings can be local subnet ip addresses instead of an intenet resolvable hostname. If these are subnet ip addresses surgeweb_backend_web setting MUST added as an internet resolvable hostname for user.cgi and surgeplus functionality to work correctly.

Not Recommended

The *surgeweb_backend* settings can be used to have surgeweb connect to arbitrary "Non Surgmail" imap servers, however if the backend servers are not surgemail dealing with email should generally work, but surgemail only functionality will not work. (In most cases it will be visible in the interface but just not functional).

	surgeweb_backend_server "imap.gmail.com:993"
	surgeweb_backend_smtp "smtp.gmail.com:465"

Instead use SurgeWall configuration discussed below: eg

	surgewall "imap.gmail.com:993"
	surgewall_options smtp="smtp.gmail.com:465" imap="imap.gmail.com:993"

SurgeWall Configuration - (Frontend Surgemail / Backend NON Surgemail)

In this configuration surgeweb is again part of surgemail installed on a separate server. The surgemail server logically sits "in front of" the backend mailserver that is actually storing the mail. In this way the surgewall server can provide mail filtering services and provide surgeweb access to the mail stored on the primary server.

All the surgeweb configuration files and contacts etc are stored on the surgemail server. Surgeweb connects to imap on the surgemail that is hosting surgeweb, any normal imap commands are proxied on to the backend server and any surgemail functionality - like contacts handling - is handled by surgemail.

None of the surgemail surgeweb_backend settings should be adjusted. Instead configure surgewall using the setting:

	surgewall "backend.mydomain.com"

or by ip address

	surgewall "192.168.1.100"

You can specify the imap and smtp servers separately in the surgewall_options settings. Specify an SSL port for surgeweb to connect to the backend using SSL. eg:

	surgewall "imap.gmail.com:993"
	surgewall_options smtp="smtp.gmail.com:465" imap="imap.gmail.com:993"

In this situation surgeweb will store its contact information, and additional xfile based settings etc on the surgemail frontend server, but all the actual mail will remain stored in the imap folders of your existing backend mailserver.

Surgeweb will also use user.cgi on the frontend server to display all the spam related mail. As such for any of the spam handling features to work, the surgemail frontend server must be the primary server accepting smtp connections from the internet and then passing the mail on the the existing backend server. If you are not wanting to use the surgemail spam handling features mail can be continued to be delivered to the backend server without needing to pass through surgemail.

For more information on surgewall see surgewall documentation

Server specific settings

I'm sure various other servers can be configured in different ways but we have had customer reports that the following may be needed:

Courier IMAP: Needs surgeweb to be configured to use imap namespaces using surgeweb config_*.dat setting. Note: SurgeMail version 6.2b-8+ contains a fix in surgemail's handling of namespaces that affects surgeweb's operation with Courier imap.

	imap_namespace INBOX.

Postfix : Expects "Inbox" instead of "INBOX" and as result surgeweb displays "Inbox" twice in folder list, use surgeweb config_*.dat setting of:

	 inbox_lower true

Exchange : No specific compatibility settings required.

Currently surgeweb expects the destination server to support the imap quota command. Surgeweb will be modified to make the use of the quota command optional, but for now you can enable the quota handling of the destination server if needed.

Using a Central Login with Surgeweb

For a simple login to surgeweb from an arbitrary web page this can be done as noted on the customisation page. If you wish to setup a central login that will allow you to maintain logged in state and to allow you to login to several websites including surgeweb, a different approach is required.

Direct links:

The first (STRONGLY DISCOURAGED) option is to pass out links or form posts that will submit a form with the username and password. This requires both the username and password to be sent to the browser, is very insecure, and may even result in the users credential getting displayed in the browser bar or referrer logs.

Redirection

A second option is for your central login cgi to maintain logged in status / ask for username password etc, and if it is determined that you are currently "logged in" to the central login service, to connect to surgeweb with the username and password and serve the contents of the following web request:

eg browser connects to

http://login.mydomain.com

which runs your very own login cgi that maintains central login state. If it determines you are logged in, it connects to surgeweb using this url (unwrapped), and serves the data that it receives back from surgeweb directly.

http://mail.mydomain.com/surgeweb?username_ex=user@mydomain.com&password=mypass
                     &cmd=login,show&page=external_login.htm&interface_ex=ajax

This will result in a redirection at the surgeweb level to correctly set the authentication cookie, and will result in a logged in surgeweb session. The actual user's password is only passed directly from your central login service to your surgeweb server, and is never used browserside where it may be a security risk.

note: Old style webmail autologin notes can be found in the webmail help. I may be implementing similar functionality for surgeweb although the above results in much the same overall effect.

note: Also note that surgeweb actually has built in cookie based "remember me" functionality that will keep you logged in for several weeks.


Search website:

Index