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. On the other hand, the Zope clients on the 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 machine with Plone.

Does Enfold Proxy support IIS 5?

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

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

It is not necessary to reboot the server machine on which IIS runs when upgrading Enfold Proxy. All you need to do is to restart the IIS services on your server machine via the command line.

You should turn off IIS via the command line instead of using the IIS configuration tool to do it. Using the command line to stop IIS ensures that all services have been stopped (Read more about upgrading).

Do I need Active Directory authentication to run Enfold Proxy?

Enfold Proxy does not do AD authentication; this is handled by Plone and ultimately IIS. If you are using Plone 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 Plone 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 documentation for more information.

Does EP 7.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 Plone does EP support?

Any reasonably recent version of Plone.

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

If load balancing, you should generally use 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 ).

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 Enfold Proxy to work with other applications besides Plone?

Enfold Proxy has been tested to work with Plone in a Windows or Unix 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).

Is Enfold Proxy compatible with using XDV themes?

Yes, see this XDV tutorial.

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). You should leave IIS running when upgrading, but stop/restart IIS services via the command line (Read upgrading Enfold Proxy).

How do I disable Enfold Proxy or a proxy definition?

You can temporarily disable one or more proxy definitions by using the EP configuration tool. If you click on a proxy definition on the left panel, under basic options on the right panel will be a checkbox, Temporarily disable this proxy definition. If you check this checkbox, this proxy definition will be disabled until you enable it again.

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.

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 10 or more proxy definitions. It may be easier 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 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 Plone whenever I make a change to EP?

No! In general, EP changes affect IIS, not Plone. 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 Proxy is compatible with plone.app.caching. It is also compatible with CacheFu (which is now deprecated with Plone 4).

Which settings in plone.app.caching should I use with Enfold Proxy?

The add-on plone.app.caching is now the recommended add-on for handling caching on Plone 4 and Plone 3. Options for configuring plone.app.caching are in Plone Site Setup --> Caching. After you include this add-on, you need to Enable Caching. On the tab for Import Settings, you should choose With caching proxy or With caching proxy (and split-view caching).

Which CacheFu caching policy do I need to select?

The add-on plone.app.caching is now the recommended add-on for handling caching on Plone 4 and Plone 3. If you still 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 plone.app.caching yet, 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 cache html content within Plone with content 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 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?

After the plone.app.caching add-on is enabled, the Plone Administrator can configure cache settings from the Caching menu in Plone Site Setup. There are many advanced settings available here which can determine how long an item is to be considered fresh or stale. 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.

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.

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 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 plone.app.caching, 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. 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.

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.