Configuring EP Manually
Configuring EP Manually
(Having problems? Check the troubleshooting checklist or the common tasks in Enfold Proxy or the FAQ).
There are two ways to configure Enfold Proxy(EP): by using the GUI configuration tool (called Encontrol) and by editing the eep.ini file. The preferred way to configure Enfold Proxy is through the GUI configuration tool.
Advantages to Configuring through the GUI configuration tool:
- Using Encontrol prevents the possibility of making syntax errors associated with hand-editing a file.
- Encontrol provides useful descriptions and help hyperlinks to give you better information about which settings are appropriate.
- Using Encontrol resolves various permission issues when you press Submit. (This affects the writeable log directories and directories for cached files).
- Using Encontrol registers certain changes in IIS. (For example, the Virtual Directory won't appear in IIS until you save your proxy definition).
However, these problems are not insurmountable. For one thing, you can avoid the last two issues simply by running eep.exe (which can be found in C:\Program Files\Enfold Proxy ) every time you manually edit the file.
Also, the check utility can detect several configuration errors. (You can run this either through Encontrol or through a command line utility).
In the worst case, scenario, you could make a backup copy of your eep.ini file and add proxy configurations one at a time.
Advantages to Editing the eep.ini file manually:
- Certain EP functions are not available through the Encontrol interface. For example, object caching (i.e., XSLT caching) can only be configured if you configure by hand.
- You can set global settings to apply to ALL proxy definitions in a [DEFAULT} section.
- You can use variables to avoid unnecessary duplication in proxy definitions.
Probably the most important reason to be aware of the eep.ini is for backup and troubleshooting. If you need to move machines, you can simply copy the eep.ini to the new machine with EP.
If you are having problems getting your proxy definitions to work and want to start from scratch, you can simply make a backup copy of this file and add new proxy definitions one by one.
A note about terminology Previous EP versions did not use the phrase proxy definitions. Instead they were called "hosts" (and in fact you can see host sections within the eep.ini file). Because of the inherent ambiguities in the word 'host', the documentation and the Encontrol configuration tool now use the phrase proxy definition instead of host.
The rest of this topic goes into more detail about best practices for configuring your eep.ini file manually. Remember that if you only use the EP configuration tool, this information will not apply.
Tips for Editing the eep.ini file
Vista Users: Vista's security model is intended to prevent the user from accidentally writing/editing system or configuration files. The Encontrol configuration utility will automatically prompt for the necessary elevation of privileges, but if you wish to edit this file by hand, you will need to do so from a process that is already elevated (ie, started with "Run as Administrator"); see the Vista documention about how to do that.
In order to use the configuration file directly, go to Start > Enfold Proxy > Configuration File. This file can be edited with any text editor, and is laid out like any other Windows INI file. Throughout this documentation this image is used to highlight instructions for editing the configuration file.
Don't forget: If you edit eep.ini manually, you must run eep.exe afterwards. If you do not, your edits may not take effect.
Most settings are insensitive to case, but lines should begin in the left column (i.e., have no leading whitespace) unless they are part of a line continuation (see section below).
Except where noted, all settings can be changed without restarting IIS - however, the new options will not be processed until a connection is made to Enfold Proxy. If you make a configuration change, you should visit the proxy in your browser to ensure the changes have taken effect as expected.
If your site configuration is quite complex such that your INI file becomes difficult to manage, be sure to read the documentation on using variables in configuration files.
Continuing Long Lines
If you maintain the configuration file in a text editor rather than via the UI utility, it is possible to split configuration values over multiple lines. Simply continue the value on the next line, but ensure that line begins with at least one space or tab.
For example:
[host 1]
includes = file1 file2 file3
file4 file5
Note that the UI utility may merge the multiple lines back into one when saving.
Using Variables in Configuration Files
Enfold's INI files have a feature that make setting up large configuration files quite simple - you can define 'variables' in the INI file and can then refer to these variables in the configuration values.
In the simplest example, let assume you had a large number of excludes to specify. One way of doing this is as follows:
[host something] jpg_files = foo.jpg bar.jpg css_files = logo.css myapp.css excludes = %(jpg_files)s %(css_files)s
In this example, we have defined 2 variables jpg_files and css_files. As these variable names to not match any configuration options used by EP, they have no effect on EP itself. excludes is an EP option and its value is defined as being the concatenation of 2 variables.
This is equivalent to as if the configuration file had read:
[host something] excludes = foo.jpg bar.jpg logo.css myapp.css
Note the format of the variable substitution - %(variablename)s - the s at the end indicates the format of the substitution is a string, which is almost always what you want. The variables used to substitute can be other values defined in this section (as in our example), or from a special section called DEFAULT.
The [DEFAULT] section
There is a special section named [DEFAULT] which offers some powerful facilities:
- Any values defined in that section are used as the default value for all sections. For example, if every host section in your file has an identical lh_server setting, you need only set the lh_server variable in the [DEFAULT] section
- Any other variables defined in this section can be used for variable substitution in any section.
To demonstrate these features, consider an INI file with a large number of [host] sections, but each host required the exact same value for lh_server. We can set this variable directly in the [DEFAULT] section.
So, instead of using:
[host 1] lh_server=192.168.0.1 vh_hosts = PloneSite1:8080 lh_root = PloneSite1 [host 2] lh_server=192.168.0.1 vh_hosts = PloneSite2:8080 lh_root = PloneSite2
You could write:
[DEFAULT] lh_server=192.168.0.1 [host 1] vh_root = PloneSite1 lh_root = PloneSite1 [host 2] vh_root = PloneSite2 lh_root = PloneSite2
We now notice that each individual sites specifies identical values for vh_root and lh_root. The variable substitution mechanism allows us to simply this file even further.:
[DEFAULT] lh_server=192.168.0.1 lh_root = %(site_name)s vh_hosts = %(site_name)s:8080 [host 1] site_name = PloneSite1 [host 2] site_name = PloneSite2
In this example, the DEFAULT section defines additional values for lh_root and vh_root - however, they are defined in terms of another variable called site_name which is defined differently in each section. When the value of lh_root is read for the section [host 1], the value of site_name defined in that section will be used.
Note that the above 3 INI file examples are all exactly equivalent - just how the values are defined changes. This can be a particularly powerful technique when you have a large number or [host] entries defined which all share common values.