EZproxy for Windows install
Ability versus right
EZproxy allows you to extend access to 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.
Install EZproxy 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 getting started
EZproxy 7.3 requires users to obtain a WSKey to run the software. Before downloading EZproxy, please request your WSKey. To request and obtain a Key, please see Request a WSKey.
- Go to Start > Run... and use enter
cmd
into the Open box, click OK to open the Command prompt window. - Create a directory for EZproxy and make it your current directory using a command such as:
c:
md \ezproxy
cd \ezproxy
- Download ezproxy-windows.exe and ezproxy-windows-sha256.sum to the server where you will install EZproxy. To verify the integrity of the downloaded file, run the following Windows Powershell command:
certutil –hashfile ezproxy-windows.exe sha256
Compare the output of certutil and hashed summary in the ezproxy-windows-sha256.sum file to make sure that hashed summaries are the same.
- Rename ezproxy-windows.exe with the command:
rename ezproxy-windows.exe ezproxy.exe
- To create the default version of most of the files mentioned above, use 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 - Follow the instructions for your Windows Server to configure the Windows Firewall to work with EZproxy. This should include adding EZproxy as an exception using the firewall control panel. For more detailed steps, see documentation on firewall access for your server model.
- To verify whether EZproxy can automatically detect your hostname 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 an OCLC server. Your server will provide its name and IP address, and the OCLC 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.Note: If you do not like the idea of your server connecting to an OCLC server, you may omit this step.
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.
Note: 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 -
Use a text editor to edit the file config.txt. If suggested from the previous step, manually specify your hostname in this file. The file also contains suggestions for other changes.
- Use a text editor to edit file user.txt. To this file, add a line similar to this, replacing someuser with 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:
someuser:somepass:admin
- Copy your full WSKey from the OCLC Developer Network WSKeys screen (obtained by following the instructions at Request a WSKey, and paste it into your command prompt window with the key command as follows, substituting your complete key for 123456789101112:
ezproxy -k 123456789101112
Note: In the Windows Command prompt, the keyboard shortcut ctrl-V will not paste copied text into the command line. You must right-click to open a list of options and click paste to enter the copied text.
-
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 user.txt 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.
Note: The options presented and how effectively they work will depend on how well you customized config.txt. As you make additional changes to config.txt, you will need to stop and restart EZproxy to make the changes take effect.
After you have completed your installation and are able to log in to the administration page, you can find the database stanzas necessary to configure resources on the Database stanzas page and information about different authentication methods on the Authenticate users page.
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.
Windows Error 1067
When installing EZproxy as a service under Windows, you may receive error 1067 when you try to start the service. This is a general error message that indicates that EZproxy failed to start successfully.
When this occurs, try the following steps.
- Check the messages.txt file to see if any errors were recorded during startup. If so, try correcting the error then restarting the service. One particularly common error is for EZproxy to no longer be able to detect its name correctly, which is reported with an error like this:
Host name "ezproxy" does not include domain, please manually specify name in config.txt
If you see the name error, you need to manually specify the complete name of the EZproxy server. See Name for information on how to do this.
If EZproxy still will not start, continue on to step 2.
- Open a command prompt window, change your current directory to the EZproxy directory, and then issue the command:
ezproxy -sd
EZproxy will either start, or it will display an error message. If it displays an error message, this problem must be corrected before it will be possible to run EZproxy. Once this command can start EZproxy, try restarting the EZproxy service. If it starts, you are done. If not, proceed to step 3.
- If EZproxy starts successfully in step 2, then the service probably does not have access to the EZproxy directory. If you are running EZproxy as a service, you must give the System group full control over the directory where EZproxy is installed (or if you use the Services control panel to change the username EZproxy runs under, you must give that username full control over the directory where EZproxy is installed).
System requirements
EZproxy runs on Microsoft supported platforms: Windows 2008, Windows 2012, Windows 2016, Windows 2019, and Windows 10.
The minimum recommended configuration for an EZproxy for Windows server:
- Intel Core i3 (sixth generation or newer) or equivalent
- 4 GB of RAM
- 200 MB of disk space is required for installation
- Additional disk space is required to accommodate user authentication files and server log files
For a list of end of support dates for Microsoft platforms, see Windows lifecycle fact sheet and End of support for Windows Server 2008 and Windows Server 2008 R2.
Additional system considerations
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 conditions to the Internet, you will need to enter the host and port information for this proxy server into the config.txt 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 Authenticate users.
EZproxy files
EZproxy uses a number of files that are automatically created during the installation process. For a list of those files and their purpose, see EZproxy system elements.
When installing EZproxy for Linux, you will download ezproxy-windows.exe. This binary file is the download version of the EZproxy program for Linux. It must be renamed to ezproxy.
Technical details
Additional technical information can be found in EZproxy technical details.
Additional commands
The following are additional commands that can be used with EZproxy for Windows.
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 to be replaced, then issue the command:
ezproxy -m