Troubleshooting

Troubleshooting

Troubleshooting

Initial Information Gathering

  • Run the Check utility in the Enfold Proxy (EP) configuration tool. Alternatively, run the command line tool eep_check.exe. What error messages does this show? (These error messages can be somewhat misleading because they can mask the real problem. But it helps to pinpoint which proxy definition needs to be reconfigured).
  • Can you access the management port of the Zope client (i.e., http://localhost:8080). If no, then the Zope client isn't running and you need to solve that first.
  • Are all the IIS sites currently running in the IIS control panel? (It will say "stopped" in parenthesis if no).
  • When you try to access a URL, are the error messages coming from Zope or IIS (or do you have no error message at all)?
  • Check the Proxy logs

Sometimes, GUI tools can hang or show outdated/wrong information. If you think this could be the case, try refreshing your view (F5), or close the GUI tool and open it again. As a last resort, you can restart the entire IIS server. It is not usually necessary to restart the Zope client with the Enfold Server configuration utility (especially if you are able to access the management port). You do not need to "restart" EP because EP exists as an ISAPI filter within IIS. On the other hand, you need to make sure that the changes you record through EP's configuration tool are reflected in IIS (and steps for doing that are mentioned below).

Should I Restart the IIS Server? In most cases, this will not be necessary. After you make a change in EP, the change should already be reflected in IIS. In certain cases, you may need to restart an individual IIS site by right-clicking the site name, choosing Stop/Start/Pause. In very rare cases, you may need to restart the IIS service (Choose Administrative Tools --> Services --> IIS Admin Service and Restart the Service. It is generally not necessary to restart Plone unless the management port (i.e., http://localhost:8080) is inaccessible.

This troubleshooting checklist lists symptoms for EP problems, IIS problems, Plone problems and caching problems. If all else fails, try some General Troubleshooting Strategies. If you are having problems with Single Sign On and Enfold Server, check the troubleshooting checklist for Single Sign On. (also at http://www.enfoldsystems.com/software/server/docs/4.0/troubleshooting_ad.html).

Tip: Be sure to test in 2 browsers. Sometimes a problem may be related to a specific browser (or the specific state in which a browser is in). For example, Enfold Proxy tweaks the cache settings, so if you have not cleared the cache on a browser, you may not see accurate results.

Although this checklist should cover a large majority of the problem situations you will encounter, you can also check two places on the Enfold for the latest information. First, Enfold Systems uses a public issue tracker to handle support issues (See https://entrack.enfoldsystems.com/browse/DESKTOPPUB ). You can view and search these issues (which often include resolutions) even if your subscription has ended. This can have great information about troubleshooting.

Another common place to check is the Known Issues page on Enfold Proxy's documentation page. See http://www.enfoldsystems.com/software/proxy/docs/4.0/changes.html#known-issues. This is periodically updated.

Enfold Proxy Configuration Problems

Common Symptoms

  • one or more IIS sites cannot be restarted no matter how many times you try
  • certain portions of your Plone site are inaccessible even though you are logged in as administrator (such as css, jpegs, etc).
  • you see Plone error messages but not IIS error messages (IIS error messages typically indicate an IIS configuration issue; see the IIS Configuration problem section below)
  • Error while connecting to server/ 502 Bad Gateway (with Enfold Proxy footer visible).

Things to check:

Note: Basic configuration errors can be identified by running the Check utility in the EP configuration tool.

  • Have you verified that IIS is running? (Enfold Proxy won't work at all until you are sure IIS is running. A sign that an IIS site is not running is that you will see a crossed out red circle over the Site icon. Normally, just restarting the IIS will resolve the problem; if IIS is improperly configured, you may need to resolve that first before you can start using Enfold Proxy).
  • Are you using IIS 7 and having problems with the installation? (You need to tweak a few settings in IIS 7 before installing Enfold Proxy. See how to make Enfold Proxy work on Windows Vista or how to make Enfold Proxy work on Server 2008).
  • Have you installed IIS recently for the first time? (Some users report that for fresh installs of IIS, you need to restart Windows before installing EP).
  • Have you verified that the port number listed in the Virtual Host of your proxy definition is the same as the management port actually being used by a Zope client? (If your Virtual Host URL goes to http://localhost:8080 but your Zope client's management port is 8081, there will be an error).
  • Have you closed and restarted the browser? Have you started another browser? (Sometimes a browser cache causes the wrong page to show up. It's best to close the browser and restart it every time. Sometimes you may even need to clear the cache).
  • Do you have Zope clients running on the same machine which are accepting port 80 requests? (Zope clients proxied by EP should not be accepting port 80 requests. Instead IIS (and by implication EP) should be handling port 80 requests on behalf of each Zope client.
  • Are more than one Zope clients attempting to use the same management port? (Each new Zope client must have a unique management port number). Check Enfold Server's configuration utility.
  • Does Virtual Host Root for your proxy definition correspond exactly to a directory inside the ZMI? (This path must exist, and it is case sensitive. Remember: http://localhost:8080/plone and http://localhost:8080/Plone are not identical! They are treated as different paths according to Plone and Enfold Proxy).
  • Have you verified that you can access your Plone site by typing in the IP address + management port + ZMI path directly as the URL? (For example, if you type http://192.168.1.150:8080/Plone and still don't see anything, the problem most likely involves your Zope clients on Enfold Server/Plone and has nothing to do with Enfold Proxy).
  • Have you selected the correct IIS site in your proxy definition? (Open Enfold Proxy configuration utility, select the appropriate proxy configuration and choose it from the dropdown list on the Site tab). If you have the wrong IIS site or if two proxy definitions are linked to the same IIS site, that will create problems.
  • Does every IIS have exactly one host or domain explicitly declared in the host headers? Do not leave the host header for any IIS site unspecified.
  • Have you been editing the configuration file (eep.ini) by hand instead of using the GUI? (Although hand-editing this file doesn't usually cause problems, sometimes an extra character or two prevents EP from reading it correctly. It may be beneficial to start from scratch editing with only the EP configuration utility. Sometimes it is merely sufficient to press the Save button in the configuration tool).
  • Does Enfold Proxy utility show the changes, but they don't seem to be taking effect in your browser? (Try closing your browser and reopening. Or try clearing your browser cache. Alternately, try restarting the entire IIS site).
  • Does the root URL show the generic Zope page and not the Enfold or Plone home page? (That usually means that Virtual Host root hasn't been set correctly).
  • Have you set any includes in your Proxy Definition? (Specifying any kind of include will hide your entire site except that which you explicitly allow. As an alternative, consider using an exclude instead or adding enough statements and/or directory paths to encompass ordinary HTTP requests).
  • Are components of your Plone site not available or is the styling/layout absent? (That can mean that an include in your proxy definition is preventing certain content from being accessed. To fix this, try to use an include_regex (See includes_regex).
  • Is your Virtual Hosts value in the correct format? (It must include the port number and not include the http://www.. Acceptable examples: 192.168.1.150:8080, localhost:8080, www.testidiot.com:80, iissite:8090 ).
  • Are you using Simple rewrite_mode for a Plone site? (All proxy definitions for Plone sites must use VHM mode).
  • Are you using Enfold Server AND using Windows authentication BUT NOT Cookie Authentication or Trusted Proxy Authentication? (The Authentication Profile needs to include Trusted Proxy authentication or Cookie Authentication for EP to do any proxying. See http://www.enfoldsystems.com/Products/Server/Documentation/ActiveDirectory for more information). See also this diagram about using NTLM Authentication with Active Directory.
  • Are you doing Load Balancing and have you manually started and/or stopped Zope clients recently? (Occasionally, IIS may need to be restarted to take into account the changed state of Zope clients. This is highly unusual).
  • Are people using Safari browser seeing error messages when they are attempting NTLM/Single Signon? (There are IIS issues with Safari connecting to Plone through IIS with Single Signon (NTLM). This is not an Enfold Proxy problem, but a problem with the Safari browser. Workarounds have been suggested, but Enfold recommends that Safari not be used if your users are connecting with NTLM. If you are not using single signon, then Safari will work fine. See the NTLM Troubleshooting Checklist at http://www.enfoldsystems.com/software/server/docs/4.0/troubleshooting_ad.html#troubleshooting-checklist-for-windows-single-sign-on).

IIS Configuration problems

Common Symptoms

  • Error Messages are from IIS, not from Enfold or Plone
  • No error page showing up at all.
  • IIS site is shown as (stopped).
  • "Bad Request (Invalid Hostname)"
  • "This Virtual Directory does not allow contents to be listed."
  • IIS shows an error message indicating a port conflict.
  • "The page must be viewed over a secure channel"
  • general erratic IIS behavior
  • You are experiencing login or authentication problems (and the resulting page from a failure does not come from Plone or Zope).

Things to check

  • Have you installed IIS recently for the first time? (Some users report that for fresh installs of IIS, you need to restart Windows before installing EP).

  • Have you verified that IIS is running? (Enfold Proxy won't work at all until you are sure IIS is running. A sign that an IIS site is not running is that you will see a crossed out red circle over the Site icon. Normally, just restarting the IIS will resolve the problem; if IIS is improperly configured, you may need to resolve that first before you can start using Enfold Proxy).

  • Have you verified that the host or domain resolves correctly? (Here's how to solve name resolution problems)

    • if you type ping www.originalfunsite, do you receive a response?
    • if you type nslookup www.originalfunsite on the command line, do you receive a response? (valid only when it has been entered on your DNS server)
  • Does Plone or Enfold Server currently use port 80 now? (Generally when you are using EP, you will want to disable port 80 in Enfold Server and enable port 80 in IIS. In other words, IIS will receive port 80 requests and forward them to EP, which will forward them to Zope clients via the client's management port (usually 8080). So in Enfold Server, you will disable the HTTP Port 80. If you have multiple Zope clients in Enfold Server, make sure all of the clients have disabled port 80).

  • Is another web server or application using port 80? (The IIS needs to have exclusive use of this port. Occasionally, another application will use this port. You can verify that port 80 is available by trying telnet localhost 80).

  • Does each IIS site have one host header declared? (Although IIS sites are fully capable of accepting requests for more than one hosts or domains, this causes problems for your proxy definitions).

  • Does the IIS site you are using have the correct Host Header Value -- such as localhost -- corresponding exactly to the URL you are trying to access--http://localhost? (If you forget to add a host header to your IIS site to be used for Plone, IIS might default to another website with different authentication).

  • Does more than one IIS site use the same host headers and/or port numbers? (These conflicts will cause web sites to be unable to start).

  • Have you verified that the IIS domain root document directory in Windows Explorer actually exists and is accessible? (If not, then your Windows permissions for that directory might be set incorrectly).

  • Go to IIS, right-click web site name. Go to Home directory tab.

    • Does the local path actually exist on the file system? (If no, you might need to create a directory or sample web page).
    • Is "Read" checked here? (For testing only, you might also enable "Directory browsing")
    • On the Documents tab, have you specified the default content page correctly? (in most cases it should be index.html or index.htm). This doesn't affect Plone or Enfold Proxy in any way, but it useful for troubleshooting IIS.
  • Go to IIS, right click Site name, go to Directory Security tab. Have the permissions been set correctly? (You might wish to uncheck permissions temporarily for testing purpose only).

  • Does the browser require you to use HTTPS to access the site? (That means your IIS is configured to require HTTPS. If you right-click the IIS site and choose Director Security --> Secure Communications --> Edit, you might notice that Require Secure Channel is checked. Unchecking this might solve this problem. See also Security Concerns and SSL ).

  • Have you modified the identity of your IIS worker processes or Application Pool? (Changing these settings could potentially affect the performance or reliability of Enfold Proxy. You should try to use the default settings when possible. For more information, see http://www.isapirewrite.com/docs/#security).

  • Are you experiencing problems or unexpected behavior with users trying to sign on?

    • Are users using single sign on -- or to put it in another way -- are they using their Windows domain account to login to the Plone website? (See the troubleshooting documents for Single signon with Enfold Server at http://www.enfoldsystems.com/software/server/docs/4.0/troubleshooting_ad.html#troubleshooting-checklist-for-windows-single-sign-on).
    • Does the Plone site use cookie-based authentication and is the user having trouble logging in? (This might be a browser issue, so clearing the cache and restarting the browser -- or trying a separate browser--might help. Also, your browser may be unable to use cookies. Perhaps the user disabled it, or a security program disabled it. Also, in some cases, running the purge command on your proxy definition can clear out cached content on your server which is using authentication data which is out-of-date but has not been cleared properly. See purging the cache ).
  • Have you deleted and added the same IIS site in the IIS Manager several times? Or have you edited the unique indentifier ID of the IIS site? Or does the proxy definition appear to work even though eepcheck gives an error message? (If you frequently add/remove IIS sites to IIS Server, the unique identifier ID of an IIS site may be changed even though the name looks correct in Enfold Proxy. In rare instances, the unique IIS site identifier number will be out of sync with the number listed in Enfold Proxy's eep.ini configuration file . This tends to happen if you frequently add/remove IIS sites--in particular with Default Web Site, whose unique identifier is usually 1. If you notice such a mismatch,there are two ways to fix this. First, you can make a trivial change to your proxy definition and press Save. Pressing Save will trigger EP to make sure the two numbers are identical. Or you can edit the eep.ini manually to reflect the actual IIS identifier ID for the IIS site. Either method should work. To determine the identifier ID for a IIS site in Server 2003, select Details view and Web Sites on the left panel. To identify the identifier ID for a IIS site in Server 2008 or Vista, select Internet Information Services on the left panel, and Sites in the middle panel).

General Zope/Plone/Enfold Server Problems

Common Symptoms

  • can't reach ZMI's application root
  • Zope doesn't allow you to login (You may need to create an emergency user for your Zope client in Enfold Server configuration utility and change the password in the ZMI).
  • You can't login even though you are using the correct admin password.

Things to Check

  • Are you trying to login to ZMI using the hyperlink on the Plone site setup page? (Doing this only lets you view the ZMI for the single Plone instance -- not the application root).
  • Can you access ZMI's application root by typing in the IP address and management port (i.e., http://192.168.1.150:8080)? (If yes, then the problem is with your proxy definition. If no, then probably your Zope client or clients are not running or the Enfold/Plone server is not handling external requests).
  • Are all of the Zope clients running? (Open the Enfold Server configuration utility, check the status of each client and attempt to restart),
  • If you access the logs for the Zope client, do you see a message, "ready to serve requests" after you restart? (If not, that usually means that a product or template you have added is causing problems. Check documentation on Plone.org for how to solve these kinds of things).
  • Does Zope time out or shows error message in event.log or zeo.log? (This is more likely to be a Zope/Plone issue than an EP issue).
  • Have you made a recent change to the way that Plone content is cached? (If you make a change to a cache policy--either within Plone or Enfold Proxy--you should run the purge command; that prevents the possibility of a person's browser from keeping old authentication data which Plone is unable to process).

Caching and Performance Problems

Common Symptoms

  • sluggish site performance
  • You see too many X-Cache: MISS messages on items you would expect to be cached.
  • The hitrate percentage (listed periodically in your proxy.log file) is declining or lower than you expected.

Things to Check

  • Have you recently restarted Plone or Enfold Server? (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).
  • Has the Chasseur product been enabled in the Plone control panel? (This is a Plone product for caching installed in Enfold Server. It should be listed as an installable product in the Plone control panel).
  • Are you viewing from a browser which is logged in? (You should keep open two browsers such as IE and Firefox. Use one for system administration and the other for testing cache performance)
  • Have you closed the browser and opened up a new one? (Frequently cookies, cache and other settings may confuse the browser).
  • Have you cleared the cache using the appropriate method for your browser? (Sometimes your browser is keeping private cache which interferes with an accurate reading).
  • Are you using Aggressive Caching Profile in Chasseur? (Aggressive caching sometimes stores items inside the browser and cannot be cleared except manually by the user. For that reason, the aggressive caching profile is generally not recommended. When the browser is using a local/private copy instead of receiving a cached copy from Enfold Proxy, the browser will still indicate X-Cache: MISS messages. The way to make sure this is not happening is to clear your browser cache manually every time you try the URL in the request.
  • Can you confirm that the cache directory actually exists on EP's machine? (It should have been automatically created and named Host Originalfunsite or something coinciding with the name you gave to the proxy definition).
  • Are you trying to cache XSLT files? (If yes, then X-Cache: MISS http headers are normal because it is RAM-based cache).
  • Is your cache directory already reaching the maximum size in your proxy definition? (While this is not bad by itself, this may indicate that you need to increase your maximum size of your proxy definition's cache). See Configuring your cache settings .
  • Is the web item unusually large? (In EP on the Caching (Advanced) tab, there is an option for Maximum Item Size which you can increase, if necessary).
  • Does your site contain a lot of photos and/or items which are larger than the maximum item size (default = 100 K)? (Although caching larger items will increase the size of your cache directory, increasing maximum item size could speed access time as long as your cache directory doesn't exceed its quota too quickly. This especially makes sense if these larger files are accessed frequently by users).
  • Is Zope running in debug mode? (Sometimes a server being tested runs in debug mode to make it easier to detect coding errors. This significantly degrades performance).
  • Have you made a recent change to the way that Plone content is cached? (If you make a change to a cache policy--either within Plone or Enfold Proxy--you should run the purge command; that prevents the possibility of a person's browser from keeping old authentication data which Plone is unable to process).

General Troubleshooting Strategies

  1. Make a minor edit to the proxy definition file and press Save. This will update the IIS site with your proxy definition.
  2. Restart the machine. Not necessary 99% of the time, but might work if you recently installed a Windows program or made another change affecting the OS (such as networking).
  3. Backup the configuration file (eep.ini) and delete all the proxy definitions. Next add them one at a time through the EP Configuration tool. This is especially useful for eliminating the possibility of IIS misconfiguration problems.