Skip to main content
OCLC Support

EZproxy Self Service - How to make changes to EZproxy

  1. Last updated
  2. Save as PDF
Applies to
  • EZproxy Self Service
Answer

Overview

EZproxy Self Service allows you to make changes to your database stanzas, authentication configurations, and webpage html files. Using the self-service option, you can add stanzas for new resources, troubleshoot stanzas that are not working correctly, make changes to how your users authenticate, and customize your EZproxy webpages. Once you become familiar with the process, you can edit, deploy, and see the result of these updates in roughly half an hour. Please note that this functionality is only currently available in the Americas region.

EZproxy Self Service Files

The files that you will edit to make changes using EZproxy Self Service have different names and contain different configurations than the files used by Standalone sites. Please ensure that you only edit and create files according to the Self Service naming and configuration conventions (for more details about the directives that cannot be used with the Self Service option, please see the Troubleshooting guide).

The files you will see in the /expert folder when you connect to the file transfer server for the first time are as follows:

  • /docs folder - This folder contains html files and a folder that you can use to customize your EZproxy webpages. Any html files should be placed in the /docs folder. Any additional files referenced in those files, such as images or css, should be placed in the /public folder in the /docs folder.
  • ezproxy.cfg - This is the equivalent of the config.txt file referred to in EZproxy documentation on the support site. Use this file to make changes to your database stanzas and other non-authentication configurations.
  • ezproxy.usr - This is the equivalent of the user.txt file referred to in EZproxy documentation on the support site. Use this file to make changes to your authentication settings.

/expert Folder Detail

shibuser.txt (Shibboleth authentication ONLY)

If you use Shibboleth as your authentication method, your /expert folder will also contain this file for you to edit your Shibboleth configuration.

The files you see the first time you log in with the SFTP client contain the current configurations or html code for your EZproxy and its accompanying webpages. The first time you log in to the file transfer server, download all files and save them as master, backup copies. Do not edit these master files directly; always make copies, and edit the copies. This will ensure you always have a working EZproxy configuration to upload if you make changes that cause EZproxy to stop working, and you cannot identify the changes that caused the problem.

EZproxy Self Service Test and Production Environments

With EZproxy Self Service, you will have access to two separate EZproxy environments: preproduction and production, defined below.

Preproduction (preprod) is a test environment running at port numbers 9080 and 9443 (SSL). You can access your preprod sites at either of the following URLS by substituting your library’s site name for abclibrary:

                http://abclibrary.idm.oclc.org:9080 OR https://abclibrary.idm.oclc.org:9443

The purpose of the preprod environment is for you to test the changes you have made before you deploy them to production. This allows you to experiment with your changes without impacting your working site or your users’ ability to access resources through EZproxy.

Production (prod) is a live environment running at default port numbers 80 and 443 (SSL). Your regular site URLs will give you access to your prod sites. Once you deploy your configurations to prod, your users will be able to see these changes. OCLC suggests that you only deploy to prod after you have tested and know the changes are working as expected in preprod.

How to Make Changes

Follow the steps below to make changes to your EZproxy configuration.

  1. Open your SFTP client.
  2. Connect to the file transfer server using the following credentials, provided in your EZproxy Self Service Pilot Welcome Email:
    1. The OCLC host: scp.oclc.org
    2. Your username
    3. Your password
  3. Click Quickconnect (or your client’s Connect button.)
  4. After you have connected to the file transfer server, you will see your local file directory in the left section of the client and the Hosted EZproxy directory in the right section of the client.
  5. Open the /expert folder located in the Hosted EZproxy directory.
  6. Find the file you wish to edit and drag it to your machine. Save a copy of this file as a backup and make a copy to edit.

     Note: This will ensure that you have the latest working copy of your file if your edits break EZproxy.

  7. Open the copied file on your machine and make edits using a plain text editor such as Notepad or Note. Please see the Troubleshooting Guide for additional guidance on what edits are acceptable and what edits EZproxy Self Service will not recognize or deploy.
  8.  After you are satisfied with your edits, save the file, then place it back in the /expert folder.
  9. Using a plain text editor, create a new file with only the word preprod in the first line. Save this file as flag.txt.

     Note: This flag.txt file designates that the other file(s) in the /expert folder should be deployed into a preprod, test environment. You must deploy the files to preprod before you can deploy them to prod.

  10. Drag and drop the flag.txt file into the /expert folder with your edited files. The flag.txt file will notify EZproxy Self Service that you have files ready for pickup. This will trigger EZproxy Self Service to pick up these files and deploy them to preprod. Files are picked up every 15 minutes. Your flag.txt file will disappear when the files have been collected.

     Note:  The permissions on the files in the expert directory need to be 660 (rw-rw----), or self-service will not pick them up.
    To fix this you can right-click on the file and choose File Permissions (in Filezilla) or Properties (in WinSCP).
     
  11. Once your files have been picked up, you will receive an email notifying you of the preprod deployment’s success or failure.
    • If the email states that the upload has been rejected because it is an unacceptable file type or a restricted directive, please see the Troubleshooting Guide for details about file naming and acceptable directives. Make edits, then repeat steps 7-9.
    • If the email states the changes have been deployed to preprod, you are ready to begin testing—proceed to step 11.
  12. After your change has been successfully deployed to preprod, open a web browser and enter your EZproxy sitename, followed by the preprod port. Your URL should look similar to the following, but you should substitute your site name for abclibrary: http://abclibrary.idm.oclc.org:9080 or https://abclibrary.idm.oclc.org:9443

    If this page will not open, and you receive an Unable to connect error, view the Troubleshooting Guide for common problems that cause EZproxy not to restart.
     
  13. Log in and see if the changes you made have been reflected in the test environment. If your tests do not produce the expected results, see the Troubleshooting Guide for common issues. Then repeat steps 7-9, making changes to your files and re-deploying them to preprod to test.
  14. If testing is successful in the preprod environment, then you are ready to deploy these changes to production. Open your text editor and create a new file. Enter only the word prod in the first line. Save this new file as flag.txt. Drag and drop it into the /expert folder.
  15. Once the changes have been deployed into production, you will receive an email notifying you that the deployment is complete.
  16. Open a web browser and enter your library’s EZproxy address. Your URL should look similar to the following: http://abclibrary.idm.oclc.org OR https://abclibrary.idm.oclc.org>
  17. Log in and verify that the changes you made are visible in the production environment.

     Note: If you do not see the changes as expected, view the Troubleshooting Guide for common reasons why changes may not be visible. Repeat steps 7-13, making changes as necessary, and deploy the edited file.

Page ID
40362