Does Enfold Proxy (EP) require IIS?

Enfold Proxy is a custom ISAPI filter/extension for Internet Information Service (IIS) which lets you load balance and cache content. It only works if you have IIS to begin with.

Why should IIS and EP be on the same machine?

Because EP is an ISAPI filter for IIS, it needs to exist on the same machine as IIS. But it should also exist on a different machine from Plone or Enfold Server. On the other hand, the Zope clients on the Enfold Server or Plone server typically use a significant amount of RAM or CPU. Separating the caching server from the machine with the Zope clients reduce the overall load on the Enfold Server.

Can Enfold Proxy run on the same machine as Plone or Enfold Server?

Absolutely yes. For larger setups, system administrators would normally put Plone and EP on different machines for performance reasons, but for smaller setups, keeping both EP and Plone on the same machine may be the best solution. If EP runs on the same machine as Plone/Enfold Server, you may need to modify the ports to avoid conflicts. Plone and IIS cannot both listen on port 80 at the same time. In fact, IIS will not start. Typically you will want IIS/EP to handle port 80 requests and Plone to talk to it using the management port (normally port 8080).

Do I need Enfold Server to run Enfold Proxy? In what kinds of situations would I need to use Enfold Server and Enfold Proxy together?

Enfold Proxy can work with a generic Plone version -- regardless of OS and regardless of whether it is hosted on the same machine or a different machine. Enfold Server is simply a Plone implementation which contain hooks for Plone to use Active Directory data and Windows Single Sign On capability. Single Sign On is performed by IIS and requires a fair amount of testing. To find out how to configure Single Sign On or Active Directory groups, consult the documentation for Enfold Server, especially the section on Single Sign On for Enfold Server

How does an IIS + Enfold Proxy solution compare with Apache-based solutions?

Apache is an open source HTTP server which lets you add new functionality through modules. These modules can offer extra power and flexibility for the skilled sysadmin, but the configuration of these modules can become complex and hard to manage over time. These modules also can pose unique challenges for the Plone Administrator.

Unlike Apache (which was originally written for UNIX and ported to Windows only later), Internet Information Services (IIS) was developed and optimized specifically for Windows.

Enfold Proxy is an IIS plugin designed mainly for ease of use. The EP configuration tool provides functionality comparable to Apache's mod_proxy, mod_cache, mod_proxy_balancer and mod_rewrite into a single GUI tool. It was designed precisely for common site setups faced by Plone Administrators. Unlike Apache-based solutions, Enfold Proxy also provides a way to purge cached content for individual Plone sites.

Does Enfold Proxy 5 support IIS 5?

4x versions of Enfold Proxy supported IIS 5, but 5x EP versions support only IIS 6 and 7.

Should I turn off IIS when I install or upgrade Enfold Proxy?

IIS must be left running whenever you install/uninstall/upgrade version 5x of Enfold Proxy. If turned off during EP Version 5x installation, the EP check tool may function incorrectly. If turned off during an EP upgrade, that may even cause EP to be installed multiple times on the same machine. If you suspect that IIS might have been turned off when you installed or upgraded EP, uninstall EP when IIS is still running, then reinstall EP again. It should never be necessary to turn IIS off when installing/uninstalling/upgrading EP.

Do I need Active Directory authentication to run Enfold Proxy?

Enfold Proxy does not do AD authentication; this is handled by Enfold Server and ultimately IIS. If you are using Enfold Server and Windows-based authentication, you need to set an authentication profile which allows either Trusted Proxy Authentication (recommended) or Cookie Authentication. Sometimes authentication issues appear after EP is reconfigured (because a change to EP might expose different parts of the Default Web Site in IIS to the user), but this is usually repaired by changing IIS directory permissions or modifying Active Directory permissions. For more information, see this diagram about NTLM Authentication with Active Directory.

Enfold Proxy is not working with NTLM authentication - why not?

Windows authentication issues have more to do with IIS or Enfold Server than with Enfold Proxy. See the IIS troubleshooting checklist for help. For more information, see this diagram about NTLM Authentication with Active Directory.

Can I configure IIS to use multiple worker-processes for a site?

Yes, but only 1 such process will have access to the EP cache. All other processes will act as if the cache has been disabled. When Enfold Proxy detects this situation, it will write a warning entry to the cache log:

Another process is already using the cache - caching is disabled for this Enfold Proxy instance

A separate but related issue is changing the default permissions or identities of IIS worker processes. Enfold Proxy generally works when the default settings for worker processes are used; if you change the identity of worker processes, you may encounter unexpected behavior. (For more information, see http://www.isapirewrite.com/docs/#security).

Why isn't the remote Plone server recognizing my username?

If IIS is enabled for NTLM authentication, you must configure Plone to use "Trusted Proxy Authentication". In this mode, Plone looks at a header sent by EP to determine the username who initiated the request. Although EP will always send this header, it will be ignored by Plone unless Trusted Proxy Authentication is enabled. See the Plone or Enfold Server documentation for more information.

Does EP 5.0 support Windows Vista or Windows Server 2008?

Yes, but on machines using IIS 7, you will need to enable several options in IIS which are normally turned off. See this note about EP support on Vista and EP support on Server 2008.

Which version of Enfold Server or Plone does EP support?

EP works with Enfold Server 3, 4 and eventually 5.

When load balancing, can I mix Zope clients created by Enfold Server with clients created by generic Plone?

It is indeed possible to mix and match Zope clients for the sake of load balancing. This arrangement will work on the condition that Zope clients on different machines are configured to access the same ZEO server and same file storage location and Zope mount point. Before you add Zope clients from multiple machines you should verify that they point to the same mount point. (See adding and subtracting load balancing clients ).

What's the minimum number of Zope clients I can use when load balancing?

If load balancing, Enfold Server generally recommends using 3 or more Zope clients. They can be on one or more different machines, but they all must share the same mount point. (See adding and subtracting load balancing clients ).

My second Plone instance looks generic; how do I give it Enfold Server's customizations?

If you have purchased a license to Enfold Server, there are customized products included with the install. The initial Plone instance should have these products available by default, but if you are adding another Plone site, you will need to go to Plone Site Setup --> Add Products --> Enable Products.

Why does it take so long for the site to load initially?

During the initializing process, it is normal for the browser to wait longer than usual. This could last up to 60 seconds in some cases. After this initializing period is over, Plone performs normally.

Can you use Proxy Server with general Zope or Plone? With other applications?

Enfold Proxy has been tested to work with Enfold Server as well as deployments of generic Plone in a Windows Environment. Other applications which are configured to run in IIS can coexist with Plone if the Proxy Definition in EP uses excludes or includes to ensure no overlapping of URLs. (See Integrating Non-Plone Content with Plone Content).

How or when do I stop/start/restart Enfold Proxy(EP)?

You can't. Because Enfold Proxy is an ISAPI filter within Internet Information Service (IIS), it is turned on whenever IIS is on. The only way you can "turn it off" is to turn off IIS. You can either restart the IIS site itself (by rightclicking the IIS site and choosing Start/Stop/Pause) or restart the IIS application (which restarts EVERY IIS site). To restart the entire IIS application, open IIS, and in the left panel, right-click your computer name and choose All Tasks, then select, Restart IIS.

How do I verify that Enfold Proxy is working?

There are various ways. First, if you can launch the configuration tool from the Start Menu (Start --> Enfold Proxy --> Enfold Proxy Configuration Utility), that is a good sign. Second, does your proxy definition cause the URL to redirect successfully? That suggests that Enfold Proxy is working. Third, if you run the eep check utility from the Configuration Utility and receive no obvious error, that is also a positive sign. In general though, EP is working whenever the IIS application is turned on. If you think you have misconfigured EP, you can make a backup copy of the eep.ini file in the Enfold Proxy and start from scratch. See also the Troubleshooting Checklist .

How much downtime is required in upgrading Enfold Proxy?

Generally, upgrading Enfold Proxy takes very little time and entails little risk (especially if you save a backup copy of eep.ini file). But it will involve a manual restart of IIS. (Read upgrading Enfold Proxy).

How do I disable Enfold Proxy or a proxy definition?

As stated above, Enfold Proxy exists within IIS, so it is not possible to start or stop it separately unless you decide to turn IIS off as well. If you are stuck or wish to view your Plone/IIS site without Enfold Proxy or your proxy definitions, the easiest thing to do is to backup the configuration file (eep.ini) to a safe place. and delete the normal file. That will wipe out the proxy definitions until you copy the eep.ini file back. Your changes will take effect after you run eep.exe. This is especially useful for eliminating the possibility of IIS misconfiguration problems. If you just want to disable one proxy definition, comment out the appropriate portion of the eep.ini configuration file and restart your IIS. Remember: Whenever you modify the eep.ini file, you must run eep.exe afterwards. If you do not, your edits may not take effect or won't be visible in the Enfold Proxy configuration utility.

What is a proxy definition? How is that different from 'hosts'?

Previous EP versions used the word 'host' instead of 'proxy definition'. That caused confusion. For this version, proxy definition refers to any EP settings for one IIS site which has a unique host header. See adding a proxy definition.

What name should I give to my proxy definition?

The name you choose for your proxy definition is arbitrary and only appears in the EP configuration tool.

If I modify a proxy definition in EP, when do the changes take place? Do they happen automatically?

It should take effect immediately. But you may need to confirm that these changes are reflected in IIS. In most cases, whenever you save something in EP, the affected IIS site will be reconfigured to have these changes. Occasionally, you may need to restart IIS for these changes to show up.

How do I back up my configuration settings?

The easiest way is to copy the eep.ini file to a safe place. Typically, it is located in C:\Program Files\Enfold Proxy directory). If this file is not visible, be sure you have configured Windows to allow you to see .ini files (Control Panel --> Folder Options --> View) and be sure Show Hidden Files is checked. For easy restore of your settings, you can replace the entire file with your backed up copy or copy the relevant contents into the new file.

Is it better to use the Proxy Configuration Tool or to edit the config file manually?

See Configuring EP Manually. Generally, it is better to use Proxy Configuration tool. It reduces the possibility of misconfiguration.

What is the maximum number of proxy definitions I can set up?

Generally there is no maximum. However, the EP configuration utility will become unwieldly if you use it to create 10 or more proxy definitions. If you are setting up more than 10, it might be better to configure the proxy definitions manually by editing the eep.ini file. See Configuring EP Manually.

Whatever happened to the virtual _plone folder which appeared in IIS after a proxy definition was created?

A virtual folder named _plone used to appear in the IIS Management console after a proxy definition was created. This no longer is the case.

How do proxy logs get rotated?

Go to EP Configuration utility and choose settings. You can set backup count and the maximum file size for each log file. See logging options.

Does EP affect the gathering of web statistics?

Because EP is simply a filter for IIS, the IIS log files should not be affected. For this reason, any web statistical tool which analyzes IIS log files should provide accurate data.

Can I use multiple proxy definitions for the same IIS site? What restrictions apply?

Typically, an IIS site is associated with a single proxy definition in EP. But EP doesn't restrict you from having multiple proxy definitions. IIS itself has restrictions regarding how multiple sites can be configured - see the IIS docs for details.

How do I force all Zope/Plone logins to be Secure Sockets Layer (SSL)?

To force all web accesses for a web domain to be by SSL, you need to configure IIS to require SSL login. Open IIS, right-click Default Web Site, select Directory Security, Secure Communications (edit). Choose the option "Require Secure Channel." (This assumes that you have already created a new SSL Certificate for the server or imported an existing one; read your IIS documentation for how to do that).

Is EP like Virtual Hosting Monster (VHM) in Zope?

EP uses VHM to ensure Zope generates correct references in URLs. But EP includes another mode (Simple rewrite_mode ) to proxy non-Zope requests as well. (See Simple Rewrite Mode).

How do I verify that Load-balancing is working?

Load balancing the server load with more than one Zope clients (which are configured in Enfold Server or Plone). The easiest way to verify that load balancing works is to try access webpages using its management port instead of port 80. (such as http://localhost:8080/ or http:www.originalfunsite.com:9090. In this case, you will probably not see the Plone site but the front page to the Zope management Interface. To see the actual Plone site, you'd have to type the path with the Plone site folder (such as http://localhost:8080/Plone).

How do I verify that my Include/Exclude/Rewrite rule has processed successfully?

Typing a specific URL in the browser would be the easiest way to see if the rule worked. You can also run the command line tool eepcheck . If you execute it with a --show-excludes argument, this will print a list of all items found by this auto-exclude processing.

Do I need to restart Enfold Server whenever I make a change to EP?

No! In general, EP changes affect IIS, not Plone or Enfold Server. Generally, whenever you make a change inside the EP Configuration Utility, pressing the Save button will make IIS aware of the changes. Occasionally, you may need to restart the specific IIS site (by right-clicking the IIS site itself) or restarting the IIS server itself if these changes aren't working.

Can I use the ISAPIRewrite product with EP for more advanced rewriting requirements?

Yes, but only the full version (with free 30 day trial) - EP does not work correctly with the "lite" free version.

Which caching product is compatible with Enfold Proxy?

Enfold Server (the Enfold-branded version of Plone for Windows) comes with a simple caching product called Chasseur. It also works with CacheFu, a popular Plone product for configuring caching. Users report that Chasseur Profiles product is easier to use. These products work by adding headers to http requests so EP can know how to cache them properly.

Which CacheFu caching policy do I need to select?

CacheFu is a third party Plone product which is not officially supported by Enfold. If you use CacheFu with Enfold Proxy on Windows, more than likely the policy you need is the Zope Behind Squid policy.

Do I NEED to install a caching Plone product for Enfold Proxy to cache items?

Generally yes. If you have not installed a product like CacheFu or Chasseur (which comes in Enfold Server by default), EP will cache static resources like cascading style sheets (css), JavaScript (js) and images. That certainly helps, but the biggest "wins" comes from EP's ability to customize cache settings for specific Plone directories (such as http://www.originalfunsite.com/news).

However, developers may choose to specify http headers in the Plone templates; in this case, it might be helpful to consult the list of supported headers on Enfold Proxy.

How does EP decide if an item should be cached?

See Caching Goals and Strategies.

How long are web resources cached in EP?

The question could be broken down into two questions: 1) when will it take for an item to be considered stale? and 2) how much space has already been used on the file system for caching?

You set general parameters in various caching products in Plone about how long an item is to be considered fresh or stale. (In Enfold Server, the caching product used is one called Chasseur). You don't need Enfold Proxy to do that. EP can intercept these caching messages from Plone and keep cached copies on its hard drive and serve these cached items to browsers without troubling Plone or Enfold Server.

EP may still store the item in the cache - but it will immediately be considered stale. Thus, the next request for this item will cause EP to validate the item with the remote server - and if the item has not changed at the server, EP will use the cached copy instead of sending the request to Plone/Enfold Server.

For the second example. suppose the default_age was 5 seconds. For the first 5 seconds after a request, EP would serve it directly from its cache. After 5 seconds, it remains in the cache, but is considered stale. The next request is as above - validated at the server. If the server indicates it is fresh, the default_age is used again. Thus, if default_age is 5, you would expect at least 5 seconds between validations.

Note that an item becoming stale is not enough to have it evicted from the cache, for exactly these reasons. The cache may have a number of stale items, but each of these can potentially be made fresh again with a simple validation.

I am trying to purge my cache, but it's not working --Why?

Most likely, you are trying to purge cache on a remote machine (i.e., one different from the machine with EP). By default, EP refuses PURGE requests from remote machines unless you have specifically named the IP address inside the EP Configuration utility (under Settings). Make sure the IP address of your remote machine is listed under Caching Purge Sources. To be absolutely sure the machine making the PURGE request is safe (i.e., a trusted proxy), you can also check the HTTP accesses on the IIS server logs to verify its IP address.

How do I prevent EP from serving cached content if Plone/Enfold Server is down?

Unless Plone uses the Cache Control: must-revalidate or Cache Control: proxy-revalidate header, EP will serve a cached copy of this page if the backend Plone server goes down. When this header is set, you will receive an error message instead of a stale page.

Is it necessary to purge my cache for a proxy definition if I change cache settings in Enfold Proxy?

Purging cache generally is not necessary if you use Enfold Proxy configuration tool to make a modification to your cache setting. However, if you change your cache headers inside a Plone template or inside a caching product like CacheFu, it is recommended to purge the cache.

My site is working, but the CSS is messed up; why?

This usually is a sign that the proxy redirect has worked, but the path to the .css file and .js files don't seem to be accessible. If you are using Includes, make sure directories for web resources like css are JavaScript are available. (Check /portal_javascripts/ and /portal_css/

How do I change the directory on the server machine where the cache files should go?

An option exists for this in the configuration tool. Open this tool (Start --> Enfold Proxy --> Enfold Proxy), choose your proxy definition and choose the Caching tab at the top of the right panel. (Read more about changing the cache directory).

How can I verify items are being cached?

The easiest way is to view the headers of the response served from EP. You can do this by inspecting Enfold Proxy's logs. If caching is enabled, each response will have an 'X-Cache' header, which either HIT or MISS as the value.

Proxy server log files also provide a clear indication of what items are being cached. One of the log levels (called the Headers log level) lets you see more detailed information about how individual items are being cached.

What percentage of HTTP requests is being cached by EP?

You can now measure this by examining the logs to see the cache hit ratio.

This does not benchmark overall performance. For that you need a more generic tool like jmeter.

Why are only some items being cached?

The remote server can override the cache settings. If the remote server indicates a page should not be cached (generally via a Cache-Control header), then it is honoured by EP. You should check the headers of the remote response to see if any such headers are present.

How do I delete items in the cache?

(See Purging Cached Content).

Can EP cache non-Plone sites using simple rewrite_mode?

See the documentation about Using Simple Rewrite_Mode to Proxy Non-Plone Sites . Assuming that 1) the server is able to serve relative URLs correct for the proxy AND 2)the server sets the cache headers appropriately, then Enfold Proxy will cache the content. To determine whether the cache headers are set appropriately, consult the cacheability engine.

Can Plone error pages be cached?

The default option is for Plone error pages never to be cached. But you can change this setting to allow EP to cache error pages. To do this, open the EP configuration tool, choose the relevant proxy definition, go to the Advanced Caching tab and check the box for the option "Allow error pages to be cached." Even after doing this, these pages will not automatically be cached unless the cache headers in the Plone error pages allow this.

How do I change the directories which will store my proxy definition's cache?

See the topic changing the cache directory.

Can EP cache error pages?

Yes, see the topic caching error pages.

How can I see if the remote Plone server is giving errors?

If you are not using a load balancer (ie, your vh_hosts option only specifies a single remote host), then simply visit the EP version of the page in your browser. For example, if your Plone site is not running and you visit the EP page proxying that server, you will see a HTML page with details of the error. In the body of this page you will see details similar to:

No response from server

504 Gateway Timeout
Internal error number: 10061
Message: Connection refused
Function: n/a

This should help you to diagnose connection related issues.

If you are using a load balancer, then EP will behave slightly differently - the error will be logged, and another host will be tried. If there are no hosts available, EP will not an error indicating this fact - but this means the initial errors which caused the problem are not rendered in the browser. In this case, you need to enable INFO logging, which will result in entries similar to the following:

...|INFO|3596|2580|marking host (u'localhost', 8765) down (socket.error: (10061, 'Connection refused'))
...|INFO|3596|2580|Connection to localhost:8765 failed - attempting another server

This gives you some detail about the error on a particular host.

When using the load balancer, why do I sometimes see an error saying "Gateway Error: All remote hosts are down"?

If each of the remote hosts specified encounters an error, there are no hosts which EP can use to satisfy the request. When this situation happens, a WARNING log entry will be written, similar to the following:

...|WARNING|2248|2720|All servers are down!  Aggressively checking all hosts

To determine what problem each host encountered, see the item above.

Why aren't my configuration options being used?

You may have specified an invalid value for a config option - check the proxy log for errors. For example, if your config file has:

[options]
timeout=60s

You will notice an entry in the proxy log:

...|WARNING|2860|2696|Attribute 'timeout' is invalid - must be an integer.  Using default of 180

as the trailing 's' is invalid - all values are already seconds.

Alternatively, you may have misspelt the option name, or added it to the incorrect section. Check the EP documentation. To diagnose the values EP is actually using, set the proxy log to DEBUG level and restart IIS. You will notice many log entries of the form:

...|DEBUG|1984|3580|Loading configuration options
...
...|DEBUG|420|3968|Config option [options]/timeout=60
...|DEBUG|420|3968|Config option [options]/thread_pool_size not found - using default 20

This indicates that the value of timeout (60) was read from the [options] section of the configuration file, but the value of thread_pool_size was not found, so a default value was used. This can help you diagnose issues with your configuration file.

See the IIS troubleshooting checklist for help.