Frequently Asked Questions

Show all answers  /  Print

Why do .gif and .jpg files placed in the docs directory appear as broken images when referenced from login.htm?

The files in the docs subdirectory act as templates for certain EZproxy functions such as login. EZproxy will only serve its own specific files from the docs subdirectory, totally ignoring any other files placed in this directory.

In EZproxy 1.x, the only way to include graphics on your login page is to point to copies of your graphics that are held on another web server, such as:

<img src="">

In EZproxy 2.0, the docs subdirectory contains three new subdirectories: public, limited, and loggedin. Each of these can be used to hold arbitrary web content.

Any document that is placed in the public directory is available to all users. If you have graphics, style sheets, scripts, or other content you would like to use with your login.htm page, you can place them in this directory. From login.htm, you can reference them with a relative URL such as:

<img src="/public/logo.gif">

Files that are in the limited directory are available to people who have already logged into EZproxy, or people who are within an excluded IP range. You can place files in this directory that should be available to any of your users who are either on-site or remotely authenticated. The URL to files in this directory might look like:

Files that are in the loggedin directory are only available to people who have logged into EZproxy. This is a good place to put files that contain sensitive information. You might use it if you want a place to share private information with your users. A sample URL might look like:

Files that are placed in public, limited, and loggedin may only be formed with basic letters (A-Z, a-z), digits (0-9), periods (.), hyphens (-), and underscores (_). Files that contain any other characters will not be served by EZproxy and will result in a 404 error to the user.

There is no default document for these directories (e.g., no index.html, default.htm, etc.), so attempts to access /public, /limited, and /loggedin without a filename result in a 404.

My users are seeing page not found errors, my server is reporting MaxVirtualHosts exceeded, my database is not proxying correctly, or I am having another problem with EZproxy. Where should I start?

If you are having problems with your EZproxy server, the best place to start diagnosis is Troubleshooting Common Problems which provides steps to diagnose and resolve the most common EZproxy configuration issues.

How many ports does EZproxy use?

What is "/status" and how do I access it?

The URL:

is available to administrative users. EZproxy Administration describes how to set up an administrative user account.

In the Hosts section of this page, there are a variety of statistics listed. The creation date and time of the first host indicates when EZproxy was last started, and for all other hosts, indicates when this virtual web server was created. The accessed entries indicate the last time someone accessed any content with a URL pointing to this virtual web server and how many times total people have retrieved content through this virtual web server. The referenced entries indicate the last time that the real host name appeared in a web page that was being rewritten and how many times that real host name has appeared in a web page that was being rewritten.

What is a starting point URL?

This term is used frequently within the EZproxy documentation. See Starting Point URL.

Before people login, my starting point URLs do not take users to the correct database, but instead take them either to the database menu or to one specific database. After people login, my starting point URLs work correctly. What's wrong?

The most common cause of this problem occurs if the files login.htm or loginbu.htm lose their hidden "url" field. Both of these files should contain lines like this within the login form:

<input type="hidden" name="url" value="^U">

EZproxy uses this hidden field to preserve the destination URL through the authentication process. The key part is the entry:


as EZproxy looks for ^U and automatically replaces it with the URL from your starting point URL.

If this hidden field is missing, your users will end up at the database menu after login. If your users always go to the same database, the database your users are reaching is likely listed as the value for this and needs to be replaced by ^U.

If you are using CGI authentication, your script must preserve the destination URL as well to insure that your users will ultimately be routed on to the correct database.

What impact do firewalls have on EZproxy?

This question really breaks into two parts: firewalls at your institution and firewalls at the remote user's site. Ultimately, unless your remote user can access the ports used by EZproxy, the remote user will not be able to access EZproxy.

Firewalls at your institution

If you have a firewall at your institution, it must be configured to allow web requests to get to EZproxy. Exactly which ports are used was discussed above. If you also use Network Address Translation (NAT), you should review additional information here.

Firewalls at the remote user's site

Most ISPs do not limit the areas their users can access on the Internet, so home users do not tend to encounter problems with firewalls. However, corporate sites often do employ firewalls and may be highly restrictive in what their employees can access. If you provide content for a given corporate site, the corporate site may be willing to open access through their firewall to your EZproxy server. However, if a corporate site refuses to open access, your users will not be able to access EZproxy.

It is important to understand that corporate firewall restrictions are not unique to EZproxy, but are actually encountered when implementing any proxy server solution for remote access.

How do I setup EZproxy to run as a Windows service?

When I start EZproxy as a Windows service, I get error 1067. How do I fix this?

Why doesn't the menu appear automatically when I use exclude lines?

If you use a link like:

the login page will always appear, even if you have added exclude lines to your ezproxy.cfg file. The menu will not appear until a login occurs. This page appears to allow local administrators to login, so they can view things like the /status.

Exclude lines are designed to work with starting point URLs.

EZproxy has been installed and working for awhile, but suddenly, new database host names aren't being proxied? Where should I look first?

If you are having problems with your EZproxy server, the best place to start diagnosis is Troubleshooting Common Problems, which provides steps to diagnose and resolve the most common EZproxy configuration issues.

Why doesn't EZproxy recycle port numbers?

When running in its original "proxy by ports" configuration, EZproxy allocates ports to represent different web servers. As an example, EZproxy might assign port 2050 to represent, 2051 to represent, etc. As users access databases through these ports, various records are made of these port numbers. These occur not only in obvious places such as bookmarks, but also in more subtle locations such as web browser caches and Internet web server caches.

When a browser requests a document, it often says "give me this page, unless it hasn't been modified since this date that's on a copy of the page I already have in cache." If port 2050 represented one day, but the next day, you can readily encounter an instance were the web page viewed by the user could contain elements from both company's web servers (this effect was actually seen during early development of EZproxy, when this subtlety had yet to be realized).

Do I need to purchase Microsoft Client Access Licenses (CALS) for use with EZproxy?

Microsoft's licensing model is complex and varies over time. Please refer this question to Microsoft.

How do I determine what version of EZproxy is running on my server?

EZproxy has been installed and working for awhile, but suddenly all login attempts state "Attempt to authenticate to non-existent session." What should I check?

The most common cause of this issue is that EZproxy is running on Linux, and the ezproxy.log file has grown to be 2 gigabytes in size. When this occurs, EZproxy restarts every time it tries to log something to the log file. If this is the case, renaming the ezproxy.log file will resolve this issue.

Can links contained inside of Adobe Acrobat PDF documents be proxied?

EZproxy is unable to rewrite the links contained inside of Adobe Acrobat PDF documents. If you are able to arrange non-IP access (e.g., some type of username/password), OCLC can work with you to configure EZproxy to use this information instead of IP authentication to provide access, which should then allow these links to work. Contact OCLC support for additional help.

Does EZproxy support Flash?

EZproxy does not support Flash because EZproxy cannot rewrite embedded URLs inside a Flash file. This is pointed out on the EZproxy listserv ( You may be able to get Flash to work by making sure there are no absolute pathnames in URLs, but we do not support Flash with EZproxy. There are similar problems with Java Applets and streaming media, therefore, we cannot support it. Unfortunately, this is a limitation of EZproxy and one that we do not expect to overcome.

Proxying (in General) is possible because EZproxy acts like a simple web browser and faces the database. EZproxy then takes apart the whole html document and rewrites it so all the database links go back to EZproxy. When a user clicks a database link, the action goes to EZproxy and EZproxy presents the authenticated request to the database. If the link is hidden inside flash or a java application or a streaming video player EZproxy can't do the rewrites. So if a user requests an action, it is possible it will go straight to the provider and will appear to be from some random unauthorized web user. When there are "no absolute path names" the traffic might route back through EZproxy (and then could be passed on to the provider through the authenticated connection).