EP Interface Guide

EP Interface Guide

EP Interface Guide

Here is a reference guide to the most common fields within the Enfold Proxy (EP) utility. If you examine the eep.ini configuration file inside C:\Program Files\Enfold Proxy, these same fields will appear. Although you can manually configure the eep.ini file, it is easier and more reliable to use the EP configuration utility. However, certain features (like XSLT caching ) require hand-editing of the eep.ini file.

Having problems? Check the troubleshooting checklist or the common tasks in Enfold Proxy or the FAQ.

Proxy Definition Settings

These are the most common settings you will need when setting up a proxy definition. See also: Adding a proxy definition .

User interface Configuration file Default Description
Local host root lh_root / The local host root i.e., the leading IIS path specifier for requests to this host. Leading and trailing slashes may be omitted. If this is blank or /, the root of the IIS server will be used. For example, if this was Sales, your Plone site would be accessed via http://iis_server/Sales/
Virtual hosts vh_hosts   The DNS name and port number of all Zope servers used by the site. The default value is 'localhost:8080' and multiple names can be separated by spaces. Note that the http:// prefix and path portions are not specified.
Virtual host root vh_root /Plone The root folder on the Plone site which will be exposed via IIS . Assuming you only want to expose a Plone site rather than the entire Zope site, this should generally be set to Plone. All leading and trailing slashes are ignored.
Rewrite mode rewrite_mode vhm The method used by EP to form the URLs requested from the proxied machine. Valid values are 'vhm' or 'simple'. See Proxying non-Plone/Zope sites for more details.
Local host server lh_server   Generally, leave this blank. Setting this option tells EP to ignore the host name IIS reports and use this value instead. See special note below.
Local host port lh_port   Generally, leave this blank. Setting this option tells EP to ignore the local port number IIS reports and use this value instead. See special note below.
Preserve Host Header preserve_host_header False If set to True, Enfold Proxy will use the original Host header received with the request for the request to the proxy server. If False, Enfold Proxy will construct a new Host header which correctly identifies the proxy.
Special Note for Local Host Server and Local Host port: In certain exceptional situations, you may need to override the usual IIS host headers and/or port numbers in order to accommodate unusual DNS configurations for the purpose of an external load balancer (beyond the basic load balancing provided through EP). Imagine a site with a "production" machine and a "standby" machine. Some front end tools are automatically capable of routing a request for 'production' to the machine 'standby' when it detects an error. However, the 'standby' machine would still assume it is named 'standby' even though it is handling requests for a machine named 'production'. In this case, you would configure 'standby' to use 'production' as the localhost name and modify the port number if necessary. For most configuration scenarios (such as the ones described on EP help topics), you should leave this field blank.

Request Matching Options

See Includes and Excludes for more information. There are 3 sections of note regarding the request matching in the Enfold Proxy Configuration Utility: Site, Includes and Excludes. These options dictate how IIS and EP examine requests to indicate if the request should be handled by EP.

User interface Configuration file Default Description
Host Headers host_headers  

This allows you to have 2 different domains hosting 2 different Plone sites from the same IIS instance. Host names are case insensitive, but otherwise must match exactly. This is particularly useful when you are using a version of IIS that does not support multiple sites.

Warning If your IIS server has the ability to create multiple IIS sites, you should leave this blank! If you have already configured IIS itself to have multiple sites based on 'host' header matching, then you should not need to configure this setting in EP - just specify the specific IIS site via the 'site' option - IIS will have already performed that filtering when redirecting to the appropriate IIS site.

Auto excludes auto_excludes   The list of existing IIS items at the proxy location which should automatically be excluded. See auto_excludes for more information.
Includes includes   List of literal file or directory names to be included. See Includes and Excludes for details.
Local excludes excludes   List of literal file or directory names to be excluded. See Includes and Excludes for details.
Includes regex includes_regex   List of regular expressions to match against incoming path names for inclusion. See Includes and Excludes for details.
Excludes regex excludes_regex   List of regular expressions to match against incoming path names for exclusion. See Includes and Excludes for details.
site site  

The name or ID of the IIS web-site that this section applies to. If not specified, it applies to all web sites. This is handy if you want a single EP instance to work with 2 different sites, each with different host configurations. The name can be specified as either the name as it appears in the IIS management console (for example, "Default Web Site"), or by its IIS site ID (for example, "1", "2", etc).

Note: If you manually change this option, you must re-execute eep.exe to ensure EP is installed in the new web site (and removed from the old one if necessary). This is not necessary if you change this value via the configuration utility.

For more information see handling multiple sites and domains.

Not present via_id   The name of the site, as included in a 'Via' header, as defined in RFC2616. This can be the literal string 'None' (case insensitive) which means no 'Via' header will be included. If not specified, the name of the server will be used (lh_server will be used if specified), including the port. If specified (and not 'none'), then the value as specified will be used directly; if you want a port specified, you must include it in the value.

Cache Options

See also Configuring Cache with Enfold Proxy.

Note about configuring these options manually: All the cache options for a particular [host] section are set directly in that [host] section inside the eep.ini file. (In eep.ini, each [host] section corresponds with a proxy definition).

All cache related configuration options are prefixed with cache_.

User interface Configuration file Default Description
Cache enabled cache_enabled True Indicates if caching should be enabled.
Cache directory cache_directory   Leaving it blank will put cache directory inside ..\Program Files\Enfold Proxy\cache directory. If you change, you must use an absolute paths (i.e., C:\My Documents\cache). See the cache directory for more information.
Default age for items cache_default_age 0 For content without explicit expiry information, how long (in seconds) should the page be considered fresh? If this is not zero, EP will cache everything for at least that duration, even data that is updated frequently.
Maximum size of cache cache_max_size 100000000 The maximum size of the cache in bytes. This size may temporarily be exceeded, depending on the transient_load_factor option.
Maximum item size cache_max_item_size 200000 The maximum size of an item that will be cached. Items larger than this will not be stored. Note that when items bound for the cache are read from the remote host they will be buffered in memory, so this value will affect memory usage.
Transient load factor cache_transient_load_factor 1.2 The factor by which the cache may temporarily exceed max_size, until the cache scavenger reduces it back. This is to avoid a client connection taking the penalty of cache expiry if the cache is full.
Scavange delay cache_scavenge_delay 60 How often the cache scavenger runs. The cache scavenger will reduce the cache back down to max_size, and flush the cache index to disk.
Cache other response allow_non_200 False Enables caching of responses other than 200, such as redirects (301, 302) and not founds (404) if such responses have appropriate cache headers.

Object Cache Options

These options modify the in-memory cache used by the XSLT processing, as described in XSLT caching. You cannot enable these options with the EP Configuration Tool; instead you need to add the options by manually configuring the eep.ini file.

Configuration file Default Description
object_cache_enabled False Is the object cache enabled?
object_cache_max_len 50 Number of items in the cache
object_cache_default_age 600 (10 mins) Length of time these items are cached.
object_cache_log_level WARNING The level of logging messages generated by this cache. The log messages are currently sent to the main proxy.log.

ZEO and Load Balancing options

See also: Configuring Load Balancing

Enfold Proxy has the ability to balance requests between any number of hosts. It is assumed that all these hosts are identical Plone installations using a common ZEO Server.

To configure load balancing options for your proxy definition, open the EP Configuration Utility, select your proxy definition, then choose the Balancing tab at the top. For these options to be effective, the Basic --> Virtual Hosts must have multiple lines (referring to multiple Zope clients); otherwise any options set here will be ignored.

User interface Configuration file Default Description
Scheduler scheduler leastconns

Describes the technique used to determine which host should handle the request. The following options are valid:

  • leastconns will chose the host with the least currently open connections from the proxy (and use round-robin to select within all hosts with an equal number of connections
  • roundrobin will always select one host after another without consideration for connections.
  • random will chose any host at random.
Period for checking.. scheduler_dead_host_check_period 120 When a host is detected as being down, how long, in seconds, before we should check to see if it is back up?
Period for retrying.. scheduler_dead_host_sleep_period 15 How often, in seconds, should we check to see if any hosts have been dead for scheduler_dead_host_check_period

Log Configuration Options

See also ways to monitor EP. It is highly recommended to configure your logs using the EP configuration utility.

EP writes a log for general proxy related logging, and also a separate log file for each individual cache configured. Each of these types of log can be configured separately. There are 2 sections for logging in the Enfold Proxy Configuration Utility, Log (Proxy) and Log (Cache). In the configuration file (eep.ini) these two sections are called - [proxy log] and [cache log].

User interface Configuration file Default Description
Maximum Size max_size 500000 The maximum size of the log file in bytes. When the log reaches this size, it will be "rolled over", and a new log created. Depending on the setting of backup_count, a number of old logs will be kept. If this is zero, the log does not have a maximum size and will never rotate. Note that IIS must be restarted for this to have effect.
Backup Count backup_count 4 The number of old logs that will be kept once the current log reaches its maximum size.
Level (proxy) level STATS (cache) WARNING (proxy) The level of information written to the log. Acceptable values are DEBUG, URLS, INFO, STATS, WARNING, ERROR, CRITICAL or a numeric value, with 1 generating the most logging output. The default levels mean that in normal operation, you will see no log information written to the proxy log, and only see cache statistics written to the cache log. Setting the proxy log to URLS (or lower - for example, DEBUG) will log each URL handled by the proxy, and the time taken to process it.
Level (event log) eventlog_level CRITICAL The level of information written to the Windows event log. Logging events of this level or greater will be written to the Windows event log and the log file.
Not present filename (see below) The filename for the proxy log. This value is ignored if specified for the cache logs - see below for more information.

Note that the [cache log] section applies to all caches. It is not possible to adjust the logging levels of each individual cache.

The cache log filename cannot be specified. The cache log filename will be the same name as the [host] section it is defined in. For example, a cache defined in a section [host sales] could have a filename of 'logs/cache_sales.log'

If you are manually configuring the eep.ini file, you may encounter permission problems with log directories. Generally, you should execute eep.exe to ensure the permissions are set correctly. See manually configuring Enfold Proxy for more information.

Miscellaneous Options

With the exception of timeout, these options are considered part of an advanced setup. Virtual Directory is not an option which is available through the Encontrol interface, but must be configured manually into the eep.ini configuration file. (See manually configuring Enfold Proxy).

The [options] section in the eep.ini configuration file allows you to set some basic options for the proxy. There is no need for this section to exist in the configuration file; if it doesn't, the default values will be used. This section, if included in the eep.ini file, may have the following entries:

User interface Configuration file Default Description
Timeout timeout 180 The socket timeout in seconds for all operations to the proxied hosts.
Thread pool size thread_pool_size 20 The number of worker threads in the thread-pool. In general, this many threads will not be running concurrently as NT Completion Ports are used. See Microsoft KB article Q192800 for more details on Completion Port based thread-pools.
Thread pool shutdown thread_pool_shutdown 90 The number of seconds to wait for the worker threads
timeout _timeout   to terminate as EP terminates. As EP is recycled, worker threads may be waiting for remote connections to complete, which will delay shutdown. After this period of time, EP will stop waiting for worker threads, causing any requests they are serving to close unexpectedly. If your server has a long timeout value for remote hosts, you may like to increase this value to avoid connections being closed during a recycle.
Log original path log_original_path True If False, the IIS logs will include the 'encoded' version of the remote URL. If True, the original URL of the request will be written. There is a slight performance penalty associated with this operation, so it may be disabled if performance is a higher priority than human readable paths in the log. Note: IIS must be restarted before this option will take effect.