config.txt Directives

  • MaxVirtualHosts (MV)

MaxVirtualHosts (MV)

MaxVirtualHosts may appear once anywhere within config.txt, with typical placement toward the top. It applies to both proxy by port and proxy by hostname configurations.

MaxVirtualHosts is followed by a number that establishes the maximum number of virtual hosts that EZproxy can create for proxying access to remote web servers. The default value is 200.

If you are using proxy by port and if you have enough databases resources that MaxVirtualHosts exceeds 2000, OCLC recommends that you move your configuration to proxy by hostname.


MaxVirtualHosts 300

The role of MaxVirtualHosts

EZproxy places itself between remote users and remote web servers by creating virtual hosts that represents the remote web servers. For example, if your EZproxy server is named and it wants to proxy access to, it creates a virtual web server to represent this In proxy by port, EZproxy assigns a unique TCP/IP port number (e.g. 2050) and in proxy by hostname, EZproxy assigns a unique DNS hostname such as As EZproxy encounters URLs to other web servers that it is configured to proxy, it assigns additional virtual hosts to represent those web servers. For example, might distribute its load to 50 different servers named,, ...,, which would result in the creation of 50 additional virtual hosts.

Signs of a MaxVirtualHosts issue

When EZproxy creates a virtual host, it retains the information for that virtual host and restores it when EZproxy is restarted. In environments with a large number of databases, this can lead to the need for hundreds of virtual hosts. If EZproxy reaches the MaxVirtualHosts limit, it is unable to proxy any additional web servers. In current versions of EZproxy, this causes this message to display to remote users:

EZproxy Server Error

Please tell your server administrator to check messages.txt for a MaxVirtualHosts error

On older versions of EZproxy, new web servers simply fail to be proxied with no obvious indication that the problems stems from a MaxVirtualHosts error, giving the appearance of database misconfiguration.

When MaxVirtualHosts is exceeded, different versions of EZproxy record different messages in messages.txt. Sample messages include:

Reached maximum virtual host limit, use MV in config.txt to increase

config.txt MaxVirtualHosts at limit; unable to proxy

Correcting issues with MaxVirtualHosts

If you encounter the MaxVirtualHosts error, you should use the information at EZproxy Administration to login to your server as an administrator and access the server status page. Look through the hosts section of the file to verify that EZproxy has established virtual hosts only for web servers used by your database vendors. As long as everything looks correct, edit your config.txt file and look for any lines like:

MV 200
MaxVirtualHosts 200

(MV is an abbreviation for MaxVirtualHosts). If you have more than one such line, remove all but the last such line. If you do not have any such lines, your server is using the default of 200.

To increase MaxVirtualHosts, add 100 to the existing MaxVirtualHosts value by either increasing the number on the existing line or adding a new line like:

MaxVirtualHosts 300

After increasing MaxVirtualHosts, restart EZproxy.

Ports that EZproxy does not use

EZproxy will not assign virtual web servers to ports 2049, 2064, 2115, 2140, or 2401 since these are commonly assigned for other services.

"Page not found," "Cannot find server or DNS," or browser waits and wait

If you are using EZproxy in proxy by port and if you have a firewall either directly on your EZproxy server or on your institutional firewall, this firewall may be set to only allow incoming access on specific ports. When you increase MaxVirtualHosts, you increase the potential ports that EZproxy can use.

In a default EZproxy configuration with no MaxVirtualHosts entry, EZproxy may use ports 2048 through 2252. If you increase MaxVirtualHosts to 300, EZproxy would now try to use ports 2048 to 2352. Whenever you adjust MaxVirtualHosts, you should also review your firewall configuration to see if it requires adjustment.

If enough ports are not open, you will see errors such as "Page not found," "Cannot find server or DNS," or the remote browser will wait and wait. If this occurs, refer to Troubleshooting Common Problems for more information on how to confirm this problem along with suggestions of how to adjust your firewall to address it.

Highest port assigned by EZproxy in proxy by port

In default configurations using port 2048 as their start and not using any SkipPort directives, the highest port that EZproxy will assign may be found by the formula:

MaxVirtualHosts + 2052

If you have no interest to know why this is the case, you may skip the rest of this section.

The actual formula to compute the worst case highest port that EZproxy may assign is:

FirstPort + MaxVirtualHosts + #NoUse + #SkipPort - 1

where these values are defined as:

FirstPort The first port assigned by EZproxy; default 2048
MaxVirtualHosts The value of MaxVirutalHosts; default 200
#NoUse The number of ports that EZproxy will not assign as discussed earlier in this page; default 5
#SkipPort The number of SkipPort directives in config.txt; default 0

In the default EZproxy configuration, the worst case value is 2048+200+5+0-1 or 2252.

The astute reader will realize that 2251 is actually the highest port that can be assigned in the default configuration, since #NoUse has a practical value of 4 until EZproxy reaches port 2401. The value of 5 is used throughout for convenience.

See also

FirstPort SkipPort