EP Interface Guide

Proxy Definition Settings
- Request Matching Options
- Cache Options
Object Cache Options
ZEO and Load Balancing options
Log Configuration Options
Miscellaneous Options

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.

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	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. For more information see If your IIS Version Supports Only One 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

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.

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

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
Virtual Directory	virtualdir	_plone	The internal IIS virtual directory used by the extension. This directory name is never seen by visitors to your site, and should be considered an invisible implementation detail. Note that you should run `eep.exe remove` before changing this value, otherwise EP will not remove the directory with the old name. Alternatively, the old virtual directory can be removed via the IIS configuration utility.
Timeout	timeout	90	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_timeout	90	The number of seconds to wait for the worker threads
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.