Anatomy of a Stanza

Symptom

• Need the best order of directives when creating a stanza

Applies to

• EZproxy

Resolution

If there is already a published stanza for the resource. If there is, the published stanza should be used.

Additionally, all of these directives are not required when creating a stanza; this page outlines the most appropriate locations for placing them.

The following order is recommended for directives when creating a custom stanza.

HTTPMethod

• Global Directive
• Position Independent
• Used to allow methods beyond the defaults
  • GET
  • POST
  • HEAD
• Can occur multiple times in a single stanza for different methods
  • OPTIONS
  • PUT
  • DELETE
  • CONNECT
  • TRACE
  • SEARCH
  • SUBSCRIBE
  • PATCH

Cookie

• Preloads the value of a cookie to send to the remote server
• Position dependent

Option Cookie, Option DomainCookieOnly, Option NoCookie, Option CookiePassThrough

• Only ONE of these options can be used in each stanza
• Option Cookie is the default function
  • EZproxy will pass through cookies that do not include a domain
  • EZproxy will intercept and handle cookies that do include a domain.
  • Cookies are stored on user session
• Option DomainCookieOnly
  • EZproxy handles all the cookies, no user browser interference
  • Cookies set by JavaScript are blocked from reaching remote web server
• Option NoCookie
  • No Cookies will be forwarded from the browser to the web server
  • No Cookies will be sent from the EZproxy server to the web server
• Option CookiePassThrough
  • If a domain is referenced in the cookie EZproxy server edits to proxy domain
  • Forwards edited cookie to the browser

ProxyHostnameEdit  (PHE)

• Repeatable position-dependent directive
• Used to create a rule for renaming hostnames generated by proxy by hostname
• Can occur multiple times in a single stanza
• Use caution when using to change sitename.com to www-sitename-com because this change will prevent http versions of the URL from proxying correctly
• Some will attempt to use this directive as a workaround for buying the correct SSL certificate for EZproxy when using proxy by hostname. If they try to work around the certificate requirement by using this directive they will still likely have issues proxying a site. This is because of the previous statement. If a site has mixed content using HTTP and HTTPS this directive will prevent the HTTP traffic from loading correctly. 

AnonymousURL

• Position Dependent
• Allows users to access select content without authenticating
• Helps eliminate Cross-Origin Resource Sharing (CORS)
• Only applies to the stanza directly following the directive
• Can occur multiple times in a single stanza for different URLs
• Can also be used with file types (.gif, .jpg, etc.)

Title (T)

• Only once per stanza
• Specifies the title to associate with the database stanza
• Includes an arbitrary label
• -Hide option can be used to prevent the title from appearing on the menu page

HTTPHeader (Localized)

• Can occur multiple times in the same stanza for different headers
• Location is critical to keep the function localized to just one stanza
• Allows EZproxy to process custom headers
• Can be used to allow, block, or even edit/rewrite a header
• Most often utilized to allow authentication and Intrusion Prevention Systems to work with EZproxy

URL

• Operates the same as a Host (H) line
• If JavaScript is necessary, a separate HJ should be included for the origin
• This URL will be used in the link generated on the menu.htm page

Host (H)

• Can occur multiple times in a single stanza
• EZproxy operates on the stanza that contains the origin first
• Host lines should not be duplicated within a single EZproxy configuration
•  Authorizes the specified URL to be used in the Starting Point URLs
• Default is HTTP, HTTPS must be specified if needed
• Open Access resources should never be places in a Host line (Google, YouTube, etc)

HostJavaScript(HJ)

• Accomplishes all functions of a Host line with additional JavaScript processing
• Allows EZproxy to rewrite URL’s within JavaScript Content
• EZproxy assumes HTTP handling if none is specified
• This requires EZproxy to recognize the value as a URL
• Relative links frequently require additional find/replace statements to function successfully
• HostJavaScript will take precedence over Host (H) lines, duplication is not necessary

Domain (D)

• Can occur multiple times in a single stanza.
• The origin value should only be once in a config.txt
• EZproxy operates on the stanza that contains the origin first
• Domain lines should not be duplicated within a single EZproxy configuration
• Specifies an Internet domain whose URLs should be rewritten by EZproxy
• The value should only exist once in an EZproxy configuration for each origin
• Open Access resources should never be included in Domain lines (Google, YouTube, etc)

DomainJavaScript (DJ)

• Identical function to Domain with the added functionality of JavaScript processing
• Takes priority and enables additional processing
• Performs additional processing to rewrite anything that appears to be a URL in any retrieved content that is identified as being HTML, JavaScript, or XML.
• DomainJavaScript will take precedence over Domain (D) lines, duplication is not necessary

Find/Replace

• Position dependent
• Find and Replace statements are always paired
• Used to identify values that EZproxy needs to manipulate and how to process those values
  • Rewrite secure (^s)
  • Rewrite non-secure (^p)
  • Don’t rewrite (^A)
• Values are explicit and only operate on exact matches
• Allows EZproxy to identify and operate on relative URLs

AnonymousURL -*

• Required in conjunction with AnonymousURL directive at the close of the stanza
• Prevents AnonymousURL from affecting other stanzas causing collateral conflicts

Option Cookie

• Should always be included on the last line if any cookie handling is specified at the beginning of the stanza
• Return the server to default cookie management for the following stanza

NeverProxy

• Should be placed with the stanza it applies
• Always global and applies to every stanza regardless of position
• Should be as specific as possible
• Should not include cloudflare.com, cloudfront.com, or aws.com without the identifier specific to the site (2134sd45st43rf434.cloudflare.com)

Page ID