Install EZproxy 5.0c GA [Athens] for Windows
This document describes how to install
EZproxy 5.0c GA [Athens] for Windows.
If you are updating from an older version of EZproxy, please refer to the
update instructions.
The only functional differences between the
Linux, Solaris, and Windows versions of EZproxy are:
- support in the Windows version to authenticate
users against a Windows domain.
- support in the Windows version to authenticate
users against ODBC data sources.
- lack of support in the Solaris 10 (x86) version for Athens authentication.
The link to download this program can be found within the installation instructions.
Overview
EZproxy is an easy to setup and easy to maintain program for providing your users with remote access to web-based licensed databases. It operates as an intermediary server between your users and your licensed databases. Your users connect to EZproxy, then it connects on their behalf to your licensed databases to obtain web pages and send them back to your users. Since EZproxy runs on a machine on your network, your database vendor sees the requests as coming from an IP address on your network, so it permits access.
Let's assume that ezproxy.yourlib.org is your EZproxy server and that you subscribe to somedb.com. To make this database available, you need only edit ezproxy.cfg and add these lines:
Title Some Database
URL http://somedb.com/search/
Domain somedb.com
With these lines in place, you could makes this database available from
any web server with a URL like this:
<a href="http://ezproxy.yourlib.org:2048/login?url=http://somedb.com/search">Some Database</a>
If on-site users click on such a link, they are sent straight to the database.
Off-site users are required to authenticate before proceeding. Once authenticated,
the off-site user accesses the database through a "virtual web server."
When one of your users remotely accesses ezproxy.yourlib.org and requests access to somedb.com, EZproxy automatically creates a virtual web server for somedb.com. In this example, http://somedb.com might be assigned to a virtual web server named http://ezproxy.yourlib.org:2050. All virtual web servers use the same naming convention, with different ports (e.g., 2050) distinguishing them.
When this user requests documents from this virtual web server, EZproxy makes the same request to the somedb.com then sends the response back to this user. During this transaction, the request to somedb.com comes from your own server, so somedb.com views it as one of your IP addresses and allows the access.
Ability versus right
EZproxy allows you to extend your databases to remote users. However, your licensing agreement with database vendors may not authorize you to provide remote access. As an implementer of remote access, it is your responsibility to verify licensing agreements and only permit remote access as authorized.
System requirements
EZproxy runs on Windows NT 4.0, Windows 2000, Windows 2003, and Windows XP. For Windows NT 4.0,
service pack 4 or later is required and both Workstation and Server are supported.
All versions of Windows 2000 and Windows 2003 are supported, as is Windows XP Professional.
The minimum recommended configuration for an EZproxy for
Windows server is
a Pentium II 400 with 256 MB of RAM.
10 MB of disk space is required for installation. Additional disk space is required to accommodate user authentication files and server log files.
This program can be executed from a non-privileged account, so please consider
running it from
a non-administrative account.
If your site employs a proxy server for all outgoing connections to the Internet, you will need to enter the host and port information for this proxy server into the ezproxy.cfg file using the Proxy directive.
If your site is protected by a firewall, external users may be unable to connect to EZproxy unless your firewall administrator
allows incoming traffic to ports 2048 and above.
User authentication
EZproxy provides a variety of methods for authenticating users. For more
information on these options, see User Authentication.
EZproxy files
EZproxy uses the following files:
| Filename | Purpose
|
|
ezproxy.exe |
This binary file is the actual EZproxy program. |
| ezproxy.cfg |
This user editable text file contains configuration directives, including information on your licensed databases. |
| ezproxy.usr |
This user editable text file contains user authentication information. At its simplest, this file contains usernames and passwords. |
| ezproxy.log |
This text file is a record of proxy server usage in the NCSA web server log file format. If used with standard web log analysis software, this file can provide information on the volume of remote use. |
| ezproxy.msg |
This text file is a record of certain informational and error conditions that occurred when EZproxy was running. |
| ezproxy.hst |
This text file contains information on active users and virtual web server proxies. |
| license.txt |
This text file is the licensing agreement for this program.
|
| *** The following user editable HTML files are located in the docs subdirectory. *** |
| cookie.htm |
EZproxy uses a domain-based cookie as its ongoing verification that a user has authenticated. If the remote user disallows the cookie, the contents of this file are sent to explain the reason why the cookie is required. |
| login.htm |
When the built-in user validation feature is used, this web page is sent to the remote user to prompt for authentication. |
| loginbu.htm |
If the user does not successfully authenticate to the login.htm page, the user is sent this page. |
| logout.htm |
When the user logs out from EZproxy, this web page is sent to confirm the logout. |
| menu.htm |
This web page provides a basic menu of databases. In most instances, this file
is only used for testing purposes. For production use, you are more likely to create URLs in remote documents that look like http://ezproxy.yourlib.org:2048/login?url=http://somedb.com which users will then use to connect to remote databases. See also LoginMenu.
|
You will only download ezproxy-athens-win32.exe.
All of the other files are created automatically during the
installation process.
EZproxy installation instructions for Windows
EZproxy is a completely stand-alone application. It does not require
nor use any existing web server that is already installed on your server.
If you are already running a web server on the system where EZproxy is
running, do not attempt to install EZproxy within directories that
are used by that web server.
If you are running IIS, do not install EZproxy within the
inetpub directory, and do not try to configure a web server for EZproxy
within IIS Manager.
-
Before you can install the Athens-enabled version of EZproxy for Windows,
you must install the Athens Windows Agent. Refer to
Installing the Athens Windows Agent for information
on how to download and install the Agent.
- Open a "Command Prompt" window by going to
Start | Run..., typing
cmd
in the Open: box, then clicking OK.
- Create a directory for EZproxy and make it your current directory with commands such as:
c:
md \ezproxy
cd \ezproxy
- Download ezproxy-athens-win32.exe into this directory.
-
Rename ezproxy-athens-win32.exe to ezproxy.exe with the command:
rename ezproxy-athens-win32.exe ezproxy.exe
- To create the default version of most of the files mentioned above, issue the command:
ezproxy -m
The "-m" stands for "missing file replacement" and this command can be used at any time to reconstruct any missing files without overwriting existing files that you have changed.
If you receive an error similar to "This application has failed to start
because athens_agent.dll was not found," you may have skipped the first step
of these instructions describing how to install the Athens Windows Agent.
If you did skip this step, perform it at this time and then retry the
"ezproxy -m" command.
- If you are installing EZproxy on Windows XP Service Pack 2, follows the steps in Windows Firewall in Windows XP Service Pack 2 to configure the Windows Firewall
to work with EZproxy.
- To verify whether EZproxy can automatically detect your host name correctly, as well as to check whether firewalls may interfere with your ability to use EZproxy, issue the command:
ezproxy -c
This command will make your server connect to the www.usefulutilities.com server. Your server will provide its name and IP address, then the www.usefulutilities.com server will attempt to verify this information. Your server will then display various messages to let you know what changes may be required for EZproxy to function properly.
If you do not like the idea of your server connecting to the www.usefulutilities.com server, you may omit this step.
If your network requires the use of a standard proxy server to connect
out to the Internet, this test will fail. In this case, you will need
to configure EZproxy to use your outgoing proxy server using the
Proxy directive, and then you can complete the network
connectivity test by finishing
the installation of EZproxy and using a browser installed either on the
same server or within your network to log in to the
EZproxy Administration page, where you
can use the
Test network connectivity option. This
performs a more thorough network test, including offering the option
to incorporate your outgoing proxy server in the test.
- Use a text editor to edit the file ezproxy.cfg. If suggested from the previous step, manually specify your host name in this file. The file also contains suggestions for other changes.
- Use a text editor to edit the file ezproxy.usr. To this file, add a line similar to this:
someuser:somepass:admin
changing someuser to the username you want to use for testing and somepass to the password you want to use for testing. In this
example, admin should appear literally as shown.
- Start the server with the command:
ezproxy
- Using your web browser, connect to your server on port 2048. If your EZproxy server was named ezproxy.yourlib.org, you would use this URL:
http://ezproxy.yourlib.org:2048/admin
-
Enter the username and password that you created when you edited the ezproxy.usr file. This should bring you to the main server
administration page.
If, instead of the menu page, you end up at a page indicating
that the EZproxy cookie was blocked,
see EZproxy Cookie Blocked for information on
why this happened and how to address it.
The options presented and how effectively they work will depend on how well you customized ezproxy.cfg.
As you make additional changes to ezproxy.cfg, you will need to stop and restart ezproxy to make the changes take effect.
Resetting all files
If you want to reset all of the files to their original distributed contents, you can use the command:
ezproxy -r
If you want to restore just one or two of the original files, rename or delete the existing file that you want replaced, then issue the command:
ezproxy -m
Installing as a Windows service
The configuration steps required to install EZproxy as a service
so it starts up when the system is booted
are available at Configure EZproxy to Run as a Windows Service.
Next step
Now that EZproxy is working, you should continue on to
User Authentication to learn how to create
URLs that link to specific databases on the EZproxy server and how
to set up user authentication for your environment.
Technical details
Those who are curious about the technical details behind EZproxy should take a look at
EZproxy Technical Details.
馆员工具箱:
