EZproxy Administration

Why Is This Important?

The EZproxy Administration page provides access to a variety of configuration, logging, monitoring, security, and test options. Access to these administrative options can be necessary to configure and maintain many of the settings described throughout this support site.

EZproxy servers have an administrative URL of one of the following forms:

Self-hosted - http://ezproxy.yourlib.org/admin

Hosted - https://yourlib.idm.oclc.org/admin

To access your admin page, self-hosted libraries replace ezproxy.yourlib.org with your library's EZproxy server name or hosted libraries replace yourlib with the domain name you selected during implementation. Use the admin credentials you created in your user.txt to log in as an administrator. If you have not added admin credentials, follow the steps in the Admin Users tab.

EZproxy Administration

The following table provides a brief overview of what can be done using each hyperlink on the /admin page. The path can be appended to your server's URL for quick access to any of these pages.

Additional details about certain pages are provided in the above tabs labeled with the page path.

Current Activity

View server status

/status Security, Database Configuration, Server Maintenance
  • Provides a snapshot of who is currently logged in to EZproxy, the databases configured on your server, the login ports being used, and the hosts being accessed.
  • Allows you to perform maintenance on your server.

View and clear intrusion attempts



(Based on IntruderIPAttempts and IntruderUserAttempts directives.)

  • Displays failed logins that have occurred recently.
  • Allows admin to reinstate access for suspended users.

View usage limits and clear suspensions



(Based on UsageLimit directive.)

  • Displays UsageLimit settings.
  • Displays any users who have exceeded limits if UsageLimit has been set to enforce.
  • Allows admin to reinstate access to suspended users.

View audit events


Security, Authentication Troubleshooting, User Maintenance

(Based on Audit directive.)

  • Displays viewable list of days with available Audit Events recorded.
  • Allows admin to search for users, events, IP addresses, locations, and other fields.

View messages.txt


Server Maintenance, Troubleshooting

  • Displays server events logged in messages.txt for the preceding number of lines selected. 

View ezproxy.log



  • Displays events logged in ezproxy.log for the preceding number of lines selected.

View messages.txt lines containing


Server Maintenance, Troubleshooting

  • Allows admin to search for specific events that could have been recorded in messages.txt. The log file search depends on how these logs have been configured in your config.txt file.

View ezproxy.log lines containing



  • Allows admin to search for specific events that could have been recorded in ezproxy.log. The log file search depends on how these logs have been configured in config.txt.

Restart EZproxy


Server Maintenance, Configuration
  • Allows admin to quickly restart EZproxy after changes have been made to config.txt or to address other issues.

Your Status
(These pages can be viewed by any user who has logged in to EZproxy.)

View your IP address


Server Maintenance

  • Displays the IP address you are using to connect to EZproxy.
  • Admins can ask users to visit the /ip URL to confirm the IP address they are using to connect to EZproxy and troubleshoot access issues.



  • Logs you out of EZproxy.
  • Admins can ask users to visit the /logout URL to confirm that they have terminated an EZproxy session before further troubleshooting.

View your group memberships


Configuration, User Maintenance

(Based on Group directive in config.txt and user.txt.)

  • Displays the resource groups that can be accessed during the current session.
  • Admins can ask users to visit the /mygroups page to confirm the groups they are part of during a given session and troubleshoot resource-group access.

Manage SSL (https) certificates

(For more details about this page see SSL Configuration.)


Security, Configuration

  • Displays the SSL certificates currently available on your EZproxy server. Active Certificate is annotated.
  • Begin creating or adding new SSL Certificates on this page. 

View database group assignments

(For more details about this page see the Testing tab on the Groups page.)


Configuration, User Maintenance

  • Displays the resource groups you can access using the current session’s credentials.
  • Allows admin to test group configurations by turning off access to certain groups for current session.

Test user.txt configuration


Authentication, Troubleshooting

  • Test user.txt authentication configuration.
  • Debug configurations that are not working and identify potential problems.

Test network connectivity


Configuration, Troubleshooting

  • Test connectivity from IP address.
  • Identify your IP address for remote hosts.

Check for database definition conflicts


Configuration, Troubleshooting

  • Identify any duplicate hosts in database stanzas in your config.txt.



Authentication, Troubleshooting

  • Test your LDAP configuration by entering appropriate fields.

Manage Shibboleth


Authentication, Troubleshooting

  • View details for the metadata providers used in your Shibboleth configuration.

The ability to access the /admin URL is limited to administrative users.

You can create an administrative user by editing user.txt and adding a line like:


The :admin at the end of the line indicates that rdoe is an administrative user.

If your institution does not include a place to enter a password on your login form, then omit the password and use an unusual username, such as:


Once you have added the appropriate line to user.txt, you can go to the /admin URL of your server, log in, and you should see a page of administrative options.

Special Note for CAS, CGI and Shibboleth Authentication

If you are using an authentication method that redirects users to a different place for authentication, including CAS, CGI, and Shibboleth, logging in as an administrative user requires that you use a URL like this:


where you specify your administrative username and password as part of the /login URL. If you have to log in in this manner, limit the characters in your username and password to letters, digits, hyphens (-), underscores (_), and periods (.).

Security Note: Use this method to log in to your admin account with caution as this entire URL, containing your username and password, will be stored in your EZproxy log file whenever you log in.  

After you log in, you can then access:


Administrative User Groups

This feature is available in EZproxy 6.2.2 and later. Previously, the EZproxy Administration features were an (almost) all or nothing proposition in which users either had total administrative privilege or none.  The only exception was the ability to give users access to the Token cross-reference feature.

The majority of options on the Administration page can now be granted to users individually by assigning them to special groups.  When setting up this type of access, the historical Admin command is no longer used, but instead users are placed into special groups that correspond to the URL over the Admin feature.  For example, the Audit page is available from /audit, so the group that grants access to this is Admin.Audit.

The groups available are:

  • Admin.Audit
  • Admin.DecryptVar
  • Admin.Groups
  • Admin.Intrusion
  • Admin.LDAP
  • Admin.Messages
  • Admin.Restart
  • Admin.Shibboleth
  • Admin.SSLUpdate
  • Admin.SSLView
  • Admin.StatusUpdate
  • Admin.StatusView
  • Admin.Token
  • Admin.Usage
  • Admin.UsageLimits
  • Admin.User
  • Admin.Variables

The /admin page automatically adjusts based on group membership to display the options that correspond to these group memberships.

The SSL and Status pages have the ability to change key aspects of EZproxy’s behavior, so these features have been divided into Update and View groups.  Users in the Update group have the full functionality available in previous versions, whereas users in the View group are only able to view information on these pages.

Users who are full administrators through the classic Admin command or who have the Admin.Groups privilege can see a list of all of these groups at the /groups URL.

Admin users are assigned to these groups via user.txt. They cannot be used within config.txt.

Do not assign individuals to groups as follows:


The above entry is equivalent to:


which tells EZproxy that all users from that point forward should be assigned into the Admin.StatusView group.

Instead, add users to groups following this example:


This would assign both someuser and otheruser into the StatusView group in addition to any other groups already set up, while ensuring that users who follow will not be in this special group.

Within an authentication method such as LDAP, sample usage would be:

    ::LDAP BindUser CN=ezproxy,CN=users,DC=yourlib,DC=org
    BindPassword verysecret
    IfUnauthenticated; Stop
    IfUser jdoe; Group +Admin.StatusView

in which specific users are identified and have the special group enabled.

When initially deploying groups, OCLC recommends using:

    Audit Most Login.Success.Groups

This tells EZproxy’s Audit feature to include the groups to which a user is assigned in the Other column, making it easy to determine if users are being assigned to the expected groups.


The Server Status screen displays details about your EZproxy installation, configuration, current users, and maintenance options. This information can be useful in troubleshooting configuration problems and performing regular maintenance on EZproxy. The different sections and options on the page are described below.

Initial Information

Version and Startup Information

The first line of text on the page will look similar to the following:

EZproxy 6.1.6 GA [SOURCE:6.0.8] [Windows] [2015-10-30T13:03:00Z] started at 2015-07-17 16:15:23

This information gives you the EZproxy version number currently running on your server, the last time the server was able to validate the license, and the last time EZproxy was started.


The Options line provides additional customization of the Server Status page. Select the option and click Update to enable it.

Option Description
Show "From" hostnames Updates From column of Sessions table with user's hostname instead of IP address.
Include extended information Shows additional processing directives associated with the database stanzas in config.txt, in the Databases table.
Enable Sorting Allows ascending or descending column sorting for the Sessions and Login ports tables.

Quick Links

To jump to a section of the page, click the blue hyperlink.


This table shows any currently open EZproxy sessions. The information in your table will vary depending on options configured in config.txt. By default the table will contain the following columns:

Column Name
Session A unique ID generated for every new session a user begins.
Username The username used to log in and begin a session.
From The IP address from which the user connected. Selecting the Show "From" hostnames option will change the IP address to the user's hostname.
The date and time that the session began.
Accessed The date and time the session was last accessed.
Location (optional) If the Location directive is configured, you will see the location associated with the session's IP address.


This table shows all the databases defined in your config.txt file. Configurations are grouped by index number, with an index for each stanza and the related directives for the given resource. New indices are created in config.txt with the addition of a new Title directive statement. Any directive statements that do not correspond to a Title statement will be added the the preceeding database stanza.

Column Name
Index The number assigned to the database by EZproxy for processing. This is based on the stanza's position in config.txt.
Database This is taken from the Title line of a database stanza.
Hosts The number of unique hosts and domains configured and accessed with a particular database stanza. For example if you have a Database titled Research Database with separate host lines configured for the URLS http://www.researchdb.com and http://www.researchdatabase.com, if a user visits both of these URLs, your Databases table will show two Hosts for that Database.
Domains All of the Host, Domain, HJ, and DJ directives configured for a given stanza. If you see statements that are not related to the Database, check your config.txt file and add Title statements to separate the Domains of different resources.
URL The URL given in the URL directive statement of the database stanza. The hyperlinked URL contains the proxy prefix and the target URL, and clicking will take you to the proxied URL.

Login ports

This table provides information about the login ports you have configured for use with EZproxy.

Column Name Description
Interface The interface that the given port should listen on for incoming requests.
SSL Y if the port is configured for SSL; N if the port is not configured for SSL.
Port A port number configured with the above settings for use with EZproxy.


This table shows details from the ezproxy.hst file.

Column Name
SSL Y if the host is configured for SSL; N if the host is not configured for SSL.
My Port The port number on your server used by EZproxy to access the host.
Database Index The database stanza with which the host is associated.
JavaScript Enabled Y if the host follows an HJ or DJ line; N if the host follows an H or D line.
Host The hostname corresponding to the given characteristics and access information.
Created The date and time a user first attempted to access the host.
Accessed The date and time the host was last successfully accessed on the given port.
Counts The number of times the host was successfully accessed on the given port.
Referenced The date and time a user last attempted to access the host (this was not necessarily a successful attempt).
Counts The number of times users attempted to access the host (these are not necessarily successful attempts).

Host Maintenance

This section allows you to perform routine maintenance on your EZproxy installation to ensure that it runs correctly and has sufficient hosts available to proxy resources. Host maintenance can be done at any time. Removing hosts does not modify the config.txt file. It only removes a host from the ezproxy.hst file. The next time a user attempts to access a resource, it will be added back to the ezproxy.hst

Four options may appear depending on your EZproxy usage.

Option Description
No action Does nothing
Remove # orphaned hosts that have !!! database indexes (requires EZproxy restart) Cleans up the host file by deleting hosts that are no longer in the config.txt file or may have changed hostnames. This will reduce the number of virtual hosts created on your EZproxy server. This may be necessary if you receive a MaxVirtual Hosts error.
Remove # hosts that have not been used in over 30 days (requires EZproxy restart)
Cleans up the host file by deleting hosts that no user has attempted to access in the past 30 days. This will free up hosts that are no longer be used by a particular resource so they can be used to proxy other resources. This may be necessary if you receive a MaxVirtual Hosts error.
Reset accessed and referenced dates and counts of all hosts (no restart required) Resets the access and reference date counts to (never) and 0. Doing this on a regular basis can help EZproxy administrators to identify how often certain resources are used during a given period of time. Once this information is reset, it cannot be retrieved on this screen.
Compress port usage by reassigning high ports into any available gaps (no restart required)
Reduces the range of port numbers being used to proxy resources by reassigning hosts at high port numbers to ports with lower port numbers. If ports are successfully reassigned, you will receive a confirmation message stating, # ports reassigned, after selecting this option and clicking process.


This section provides additional information about your EZproxy configuration, including limit settings, the peak value your server has experienced, and whether SSL has been enabled.

Limit Description
Peak Sessions active/limit: ###/### Shows the number of sessions active and the maximum number of sessions that can be active at one time. To increase the max active sessions, edit the MaxSessions directive in your config.txt file and increase the number of hosts (500 is the default).
Peak concurrent transfers active/limit: ###/### Shows the peak number of concurrent sessions that has occurred and the maximum number of transfers that can occur at the same time. To increase the max concurrent transfers, edit the MaxConcurrentTransfers directive in your config.txt and increase the number of hosts (200 is the default).
Peak virtual hosts/limit: ###/### Shows the peak number of virtual hosts that have been in use on your EZproxy server and the maximum number of virtual servers that may be in use. To increase the max virtual hosts, edit the MaxVirtualHosts directive in your config.txt file and increase the number of hosts (200 is the default).

Below the limit settings, you will see a message reporting whether SSL has been enabled for your EZproxy installation.


The Test user.txt Configuration page allows you to test the existing authentication configuration in your user.txt file and new configurations before adding them to your user.txt file.

Troubleshooting Existing Authentication Settings

To test the existing authentication settings in your user.txt file:

  1. Enter information into any of the following fields.

    Field Entry What this tests
    User Any username.
    Whether the username is valid and if that user has administrative permissions. What groups this user belongs to (if groups are configured). Additional access details. 
    Pass The password corresponding to the entered username. Whether the password is valid. If your authentication requires users to enter a password, both username and password must be entered and correct to return a Valid credentials message.
    URL A URL to evaluate for access.
    Whether the target URL alters the authentication result. This is typically used in combination with the IP field to determine how specific URLs will be handled when accessed from various IP addresses.
    IP An IP address from which to test access.
    How EZproxy would behave if the user's IP address is the one specified. This can help to determine if the starting point URL would be excluded from proxying, included for proxying after requiring authentication, or automatically proxied. If a URL is provided, the information provided is specific to that URL.
    Auth Any auth value to use for testing.
    Some advanced user.txt files use the auth variable to selectively enable or disable sections of user.txt, especially when multiple authentication methods are in use. Various values can be tested by providing them in this field.
    III Pin III pin to test if using the III option "Password Both" that requires the user's name in the Pass field and III pin in a separate field.
    Whether the III pin combined with name in the Pass field is valid. This field is NOT used when simply using "Password Pin" with III, nor is it used with any other authentication method.
    Force Debut Select if you would like to have debugging messages displayed as the test runs.
    Provides additional diagnostic details that may be helpful when determining why a particular authentication is failing.

  2. Click Test.

The results returned will provide information detailed in the "What this tests" column above and can serve as a starting point for making edits to your user.txt file to update your configuration.

Changing Authentication Methods

This can be useful if you are going to move from one authentication method to another. You do not have to alter your working user.txt file to test the configuration you will have to add for the new method.

To test a new authentication configuration:

  1. Create a new configuration according to the steps outlined for the method selected from the EZproxy Authenticate Users page.
  2. Enter the configuration in the text box at the bottom of the screen.
  3. Enter valid user and pass credentials.
  4. Click Test.

The results returned will tell you if the username and password are valid according to the new configuration entered in the test box.

Testing Groups

You can also use this page to ensure that the usernames you have configured in either the user.txt file or using a third party authentication method are working correctly and have been assigned to the correct groups.

Existing Group Configuration

If you have already added group configurations to your config.txt and user.txt files, enter a username and password from the group you would like to test, then click Test. Check the test results to see if the username has been assigned to the correct groups in the Assigned groups from user.txt line.

New Group Configuration

You can test a new group configuration by entering the user.txt configuration at the bottom of the screen. Make sure you have also added the groups to the config.txt file as well, or the user will not be added to the group. If you are not ready to assign resources to specific groups, you can just add the Group directive and name to the bottom of the config.txt file to test users' membership in the groups. After membership has been confirmed, you can add resources to the groups.

Third Party Group Attributes

You can also ensure that your third party authentication method is returning the correct attributes for group membership by entering a username and password that should be assigned to a particular group and checking the test results to ensure they have been assigned to the correct group.


The Check Database Conflicts page allows you to review your config.txt file for potential overlapping directive statements in your database stanzas. These overlaps may not always cause problems; however, if you are unable to access resources you believe to be configured correctly in your config.txt file, this test page can be a good place to begin troubleshooting.

When to Use This Tool

  1. Debugging Problems
    Run this tool when you are experiencing problems accessing a particular database, and you cannot solve the problem easily. If the tools shows overlapping definitions for the host or domain, as shown above, your access problem may be a result of this overlap. If the overlap is unintentional, you can consolidate the two definitions into one.

  2. Housekeeping and Preempting Problems
    Run this tool if you would like to find unintentional overlaps to prevent the access issues described above. Generally, it is a good idea to eliminate overlaps even if they are not causing access problems. This will simplify administration of your config.txt and database stanzas and make overlap problems less likely in the future.

How It Works

This tool reads all the database definitions in the config.txt file and compares them to each other. Any definitions that contain overlapping hosts, HJ, domain, or DJ statements are flagged and presented on the Check Database Conflicts results page.

To use the Conflict tool, click Check for database definition conflicts on the /status page. The Check Database Conflicts page will appear with each flagged set appearing as follows:

0 Research Database and 1 Research Javascript

Each line contains the following information:

  • The first number is the index for the database stanza and tells where the stanza appears in the config.txt file.
  • The index is followed by the title of the database in conflict.
  • The final information, in this case "Find/Replace Javascript" refers to the section of the stanza containing the overlapping directive statements.

Click on the hyperlinked text to view more information about the two stanzas and what directive statements overlap. The Database Conflict Detail page provides detailed information from the Databases table about the two stanzas with overlapping directive statements. You can use this information to determine if one stanza should be removed or if the overlap is not the cause of access issues.

What to Look For

Database definition overlaps may not impact your users' ability to access resources in all cases; however, there are instances where the overlap can cause a problem. EZproxy determines whether to proxy a URL based on the first database stanza that contains a match for that URL in the URL, Host, HJ, Domain, or DJ directive statements and ignores subsequent stanzas. The first stanza controls the proxying behavior.

If the Database Conflict Detail page for the stanzas above looked as follows:

Database Hosts Domains URL
0 Research Database 1

D researchdb.com
H www.researchdb.com:80

8 Research 0

DJ researchdb.com
HJ learn.researchdb.com


You will notice that the D line for Research Database and the DJ line for Research contain the same domain. In this case, EZproxy would proxy any URL with the domain researchdb.com without Javascript. EZproxy will read the D line first and use this as a basis for proxying. This could cause problems when users attempt to access URLs containing the domain researchdb.com that require javascript processing to proxy correctly. To fix this problem, you could change the first D statement to a DJ or remove the D statement, leaving only the DJ.


The following pages are referenced elsewhere on this page or contain additional related information to the /admin page.


Authenticate Users

Group (Directive)

Groups (Overview)




Restart EZproxy

SSL Configuration



This page last revised: November 14, 2016