Skip to main content
OCLC Support

Expressions

Learn more about the the constant, variables and functions that are available to create complex expressions in EZproxy.

Overview

EZproxy has the ability to perform complex string and math manipulations to allow advanced authorization decisions. The following information explains the constant, variables and functions that are available to create complex expressions.

The EZproxy administration page provides a Test user.txt configuration option, which can be used to experiment with variables and functions.

From the Test user.txt configuration page, you can check the Force Debug option and then enter a test like this:

::Common 
If login:user eq "test"; Msg user is test 
If login:user =~ "/^(.)(.)(.)(.)$/" { 
Set rev = re:4 . re:3 . re:2 . re:1 
Msg 4-letter username reversed and stored in rev 
} 
/Common 

If you paste in this example, try entering the 4-letter usernames test and TEST, noting that only the lower-case test triggers the message "user is test" to appear since eq is case-sensitive.

Conventions

aggvar
The base name of a variable that can have one or more value, such as the base name of an array or the name of an auth: variable that returns multiple values; when used with an aggregate test, EZproxy will also include any non-array variable of the specified name in the test (e.g., abc, abc[1], and abc["xyz"] are all considered when performing an aggregate test for the variable abc).
bool, bool1, bool2
For Boolean values, empty strings and 0 are considered to be false, all other values are considered true.
The result of a Boolean operation is 0 if the value is false or 1 if the value is true.
dt
A numeric value representing a date/time as the number of seconds that have elapsed since midnight, January 1, 1970.
int, int1, int2
An integer numeric value (any decimal portion is ignored).
num, num1, num2
A numeric value that can include decimal points.
str, str1, str2
A string value.
re
A string containing a regular expression; the string must starts with a non-alpha, non-digit character, a pattern, the same non-alpha, non-digit character, and may optionally be followed by i for a case-insensitive comparison and/or g to indicate a global replace.
wild
A wildcard comparison string which is compared using a case-insensitive comparison and in which ? matches to any single character and * matches 0 or more characters.

Constants

Numeric constants are formed from digits and an optional decimal point.

String constants must be surrounded by either a single quote (') or a double quote (") characters. The use of a single quote (') or double quote character (") has identical meaning to EZproxy. Within a string, the backslash (\) can be used to escape the string quoting character (e.g. O'Grady can be specified as 'O\'Grady' or "O'Grady"). Since backslash acts as an escape character, two backlashes (\\) must be used within a string to specify a single backslash (\) character.

Variables

Standard variables are case-sensitive and must start with a letter which can be followed by any combination of letters, digits, underscores (_), and at signs (@). Variables may also be followed by an opening square bracket, an expression that forms an associate index, and a closing square bracket to store values in an associative array.

There are several namespace prefixes that are used to access special variable sets. The standard namespace prefixes are auth:, db:, login:, re:, and session:.

The auth: namespace is used to access variables from an authentication source. Examples of support authentication methods include CAS, HIP, III, LDAP, Shibboleth, SIP, and TLC. The auth: variables are only available during the processing of user.txt, so any value that needs to be retained should be stored in a session: variable. See the example below. If an authentication source can return more than one value for the same variable, access the first value by include [0] at the end of the variable names, [1], for the second, etc. When using auth:, the variable names can include any of these additional special characters: ! # $ % & * + - . / ^ | ~

The db: prefix provides access to database definition information within the ^B/^E loop of menu.htm. The variables available include db:title, db:description, and db:url.

The env: prefix provides access to operating system environment variables.

The login: prefix provides access to key variables that come from login.htm and loginbu.htm during login, including login:auth, login:pass, login:pin, login:url, and login:user. If a value is assigned to login:loguser during login process, the assigned value is used as the username for the user. A value may be assigned to login:user to override the username that is tested by authentication methods.

The re: namespace provides access to the last values that matches during a regular expression comparison, with re:0 holding the last value matched, and re:1 through re:9 holding any values captured by parentheses.

The session: namespace can be used to store values in variables that survive across the entire user session. These variables can be used in files such as menu.htm using the syntax ^{expression}. The special variable session:admin returns 1 if the logged in user is an administrator, 0 if not. The special variable session:user provides the current username if some function has activated username tracking (e.g., if auditing is enabled).

Expressions

Expressions are formed by mixing constants and variables using any appropriate combination of the following comparisons, operations, and functions.

The most common uses for expressions occur in user.txt with an authentication method block using the If or Set directives. For example:

::SIP
Host sip.yourlib.org
SIP2
IfUnauthenticated; Stop
If auth:BV >= 10 || auth:AT > 5; Deny delinquent.htm
Set session:fullname = auth:AE
/SIP 

can be used to deny access if someone's outstanding fines (BV in SIP) are $10 or higher, or if the user has five or more items overdue (AT in SIP), and to store away the person's name (AE in SIP) in a session variable called fullname that can then be referenced in menu.htm with ^{session:fullname}.

Numeric operations

num1 + num2
Add num1 to num2
num1 - num2
Subtract num2 from num1
num1 * num2
Multiply num1 by num2
num1 / num2
Divide num1 by num2
int1 % int2
Integer modulus of int1 and int2 (the integer remainder of the division of int1 and int2)
int1 & int2
Bitwise and of int1 and int2
int1 | int2
Bitwise or of int1 and int2

String operation

str1 . str2
Concatenate str1 and str2 together into a single string

Boolean operations

For Boolean operations, empty strings and 0 are considered to be false, all other values are considered true. The result of a Boolean operation is 1 if the value is true or 0 if the value is false.

! bool
1 if bool is considered false, 0 otherwise (not operator)
bool1 && bool2
1 if bool1 and bool2 are considered true, 0 otherwise (and operation)
bool1 || bool2
1 if bool1 or bool2 are considered true, 0 otherwise (or operation)
bool ? val1 : val2
val1 if bool is considered true, val2 otherwise (ternary operation); this expression now evaluates to be equivalent to var = (bool ? val1 : val2)

Miscellaneous operations

var = val
Used to assign a value to variable
expression1, expression2
Multiple expressions be combined with a comma, which is most often used to perform multiple variable assignments in a single expression (e.g., a = 1, b = 2, c = 3).

Numeric comparisons

These comparisons are based on the numeric values of the values being compared (e.g., 2 is less than 10).

num1 < num2
1 if num1 is less than num2, 0 if not
num1 <= num2
1 if num1 is less than or equal to num2, 0 if not
num1 == num2
Note: this symbol is two equal signs and not just a single equal sign

1 if num1 equals num2, 0 if not
num1 != num2
1 if num1 is not equal to num2, 0 if not
num1 >= num2
1 if num1 is greater than or equal to num2, 0 if not
num1 > num2
1 if num1 is greater than num2, 0 if not

String comparisons

Unless otherwise noted, these comparisons are case-sensitive based on the sequences of characters in the string values being compared (e.g., "10" is less than "2" since the character "1" comes before the character "2", and "B" is less than "a" since internally "B" comes before the character "a"). To perform a case-insensitive comparison, use either the Upper or Lower function (e.g., Upper("B") is greater than Upper("a") since "B" is comes after "A", and likewise Lower("B") is greater than Lower("a") since "b" comes after "a").

str1 lt str2
1 if str1 is less than str2, 0 if not
str1 le str2
1 if str1 is less than or equal to str2, 0 if not
str1 eq str2
1 if str1 is equal to str2, 0 if not
str1 ne str2
1 if str1 is not equal to str2, 0 if not
str1 ge str2
1 if str1 is greater than or equal to str2, 0 if not
str1 gt str2
1 if str1 is greater than str2, 0 if not
str =* wild
1 if str is wildcard equal to wild, 0 if not
str =~ re
1 if str matches the regular expression re and set local variable re:0 to the match string and re:1 through re:9 to anything capture by parentheses, 0 if not.
str !~ re
0 if str matches the regular expression, 1 if not and set local variable re:0 to the match string and re:1 through re:9 to anything capture by parentheses

Functions

Function Description
ActiveGroupMember(str) This Boolean function returns 1 if the user has an active session and if the user is a member of any of the groups specified by str, or 0 if not.
ActiveSession() This Boolean function returns 1 if the user has an active session, or 0 if not.
All(aggvar, str) This Boolean function returns 1 if all of the values of aggvar are case-sensitive equal to str, 0 if not.
AllRE(aggvar, re) This Boolean function returns 1 if all of the values of aggvar equal the regular expression, 0 if not.
AllWild(aggvar, wild) This Boolean function returns 1 if all of the values of aggvar are wildcard equal to wild, 0 if not.
Any(aggvar, str) This Boolean function returns 1 if any of the values of aggvar is case-sensitive equal to str, 0 if not.
AnyRE(aggvar, re) This Boolean function returns 1 if any of the values of aggvar equal the regular expression, 0 if not.
AnyWild(aggvar, wild) This Boolean function returns 1 if any of the values of aggvar are wildcard equal to wild, 0 if not.
Authenticated() This Boolean function returns 1 if the user has successfully authenticated, or 0 if not.
Chr(int) The string function returns a string based on the character associated with the integer value (e.g., Chr(65) returns "A").
City() This string function returns the city associated with the user's IP address based on information provided by Location directives in config.txt.
Coalesce(str1 [,str2 , str3, ...]) This string function returns the first string that exists and is not blank.

CompareIP(str1, str2)

This numeric function compares two IP addresses provided in str1 and str2 and returns -1 if str1 is less than str2, 0 if str1 equals str2, and 1 if str1 is greater than str2. If str1 or str2 are not valid IP addresses or if str1 and str2 are not the same type of IP address, it returns null. This function normalizes the addresses, allowing equivalent addresses written in slightly different forms to match such as 192.168.0.1 to 192.168.000.001 and 0000::0001 to ::1. To determine if two addresses match it is better to use a string comparison such as:

If CompareIP("192.168.1.1", "192.168.001.001") eq "0"; Msg "Addresses match"

since using == 0 will not only match the correct case, but also the error case in which null is returned. This function relates to the HTTPHeader directive.

Count(aggvar) This numeric function returns the number of aggvar variables that exist.
Country() This string function returns the country associated with the user's IP address based on information provided by Location directives in config.txt.
CountryName() This string function returns the country name associated with the user's IP address based on information provided by Location directives in config.txt.
DateTime(year, month, day, hour, min, sec) This numeric function returns the number of seconds that have elapsed between midnight, January 1, 1970 and the date/time specified. If all values are omitted by specifying just DateTime(), return the value based on the current date and time. If year is specified, the default values for month and day are 1, and the default values for hour, min, and sec are 0. Hour is specified in military time from 0 to 23. Time is computer based on the local time zone.
Expired() This Boolean function returns 1 if the EZproxy attempted to authenticate the user and the credentials were accepted but were considered invalid, or 0 if not.
FormatDateTime(str, dt) Format a date specified as the number of seconds that have elapsed since midnight, January 1, 1970 using the specified string. The string can contain %Y for a 4-digit year, %y for the two-digits of the year, %m for the month, %d for the day, %H for the 24-hour clock hour, %I for the 12-clock hour, %M for the minutes, %S for the seconds, %p for the locale equivalent of a.m. or p.m. For example, FormatDateTime("%Y-%m-%d %H:%M:%S", DateTime()) can be used to obtain the current date and time in YYYY-MM-DD HH:MM:SS format.
GroupMember(str) This Boolean function returns 1 if the user would be assigned to any of the groups specified by str upon successful authentication, or 0 if not.
Hash(str1, str2 [, bool]) This string returns a hexadecimal representation of the cryptographic hash of str2 based on the value of str1. The supported values for str1 are "MD5", "SHA1", "SHA256", or "SHA512". The optional bool value indicates if alphabetic character in the hash should use upper-case (value 1) or lower-case (value 0), and defaults to 1.
HTMLEncode(str) This string function returns a copy of str with HTML special characters (e.g., <, >) encoded for safe display.
Index(str, substr) This numeric function check to see if substr is contained with str. Returns -1 if substr is not contained within str, or returns the position where substr begins based from 0 (e.g., Index("abc", "d") returns -1, Index("abc", "a") return 0, Index("abc", "c") return 2).
Invalid() This Boolean function returns 1 if the EZproxy attempted to authenticate the user but the credentials provided were invalid, or 0 if not.
IP() This string function returns the IP address of the remote user in dotted-quad format (e.g., 132.174.1.2).
Join(delim, str1 [,str2 , str3, ...]) This string function joins together one or more strings, inserting delim between each string (e.g., Join(" ", "sample", "join", "data") returns "sample join data").
Latitude() This numeric function returns the latitude associated with the user’s IP address based on information provided by Location directives in config.txt.
LatLongDistance(latitude, longitude, default) This numeric function returns the great-circle distance in miles from the specified latitude and longitude to the latitude and longitude associated with the user’s IP address based on information provided by Location directives in config.txt or the default value specified if there is no latitude and longitude information associated with the user’s IP address.
LatLongDistance(latitude1, longitude1, latitude2, longitude2) This numeric function returns the great-circle distance in miles from the first specified latitude and longitude to the second specified latitude and longitude.
Left(str, len) This function returns the first len characters of str.
Longitude() This numeric function returns the longitude associated with the user’s IP address based on information provided by Location directives in config.txt.
Lower(str) This string function returns a copy of str with all alpha characters converted to lower-case.
LTrim(str) This string function returns a copy of str with all left-side (leading) whitespace removed.
Mid(str, start [, len]) This string function returns a portion of str beginning at position start (based from 0) through the rest of the string if len is omitted, or for up to len characters.
NoActiveGroups() This Boolean function returns 1 if the user has an active session but is not currently assigned to any groups, or 0 if the user is not authenticated or if the user is assigned to any groups.
NoGroups() This Boolean function returns 1 if the user would not be assigned to any groups upon successful authentication, or 0 if there are groups to which the user would be assigned upon successful authentication.
Null(var) This Boolean function returns 1 if the variable var does not exist or 0 if the variable does exist.
Ord(str) This numeric function returns the numeric value of the first character of str.
ParseName(namestr, formatstr, namespacestr)

This function parses a name to extract specified components into individual variables. Extracted name components are placed in variables named title, forename, middleName, surname, and nameSuffix. These variable names are case-sensitive. If namespacestr is specified, then the variable names are prefixed with the value of namespacestr and a colon (:).

The formatstr may contain the letters T (title), F (forename), M (middleName), S (surname), X (nameSuffix), K (keep existing variable values), and the comma character (,).

Sample uses include:

# Example 1: name in surname, forename middleName, nameSuffix format
# store results to surname, title, forename, middleName, nameSuffix
Set ParseName(name, "S,TFM,X", "")
# Example 2: name in title forename middleName surname nameSuffix
# store results to session:title, session:forename, session:middleName,
# session:surname, session:nameSuffix,
Set ParseName(name, "TFMSX", "session")

By default, ParseName erases the values of all possible destination variables before it parses the name. To prevent the clearing of existing variables, add K anywhere in formatstr.

PPID(str1, [str2])

This string function returns a Private Personal Identifier (PPID). str1 is a relying part code (recommended length is 3 characters). The returned value will be generated based on the currently logged in user if str2 is omitted or on the value specified for str2.

This directive is designed for users with the SSOUsername config.txt directive. Sample use:

SSOUsername ssotest PPID("sts")

The values generated by PPID can be cross referenced using the Manage PPID Tokens page available from the main administration page. This page is available to administrators and people who have been added to the Admin.Token group.

Values are stored in the ezproxy.tkn file. If PPID is in regular use, please ensure that this file is backed up regularly.

QueryStringPass() This Boolean function returns 1 if a password came into EZproxy through the query string, or 0 if not.
Refused() This Boolean function returns 1 if a remote authentication server has yet to be accessed or if the server refused a connection request from EZproxy, or 0 if not.
Region() This string function returns the region associated with the user's IP address based on information provided by Location directives in config.txt. Region codes are based on the two-character ISO 3166-2 subcountry code for the US and Canada or the FIPS 10-4 subcountry code for other regions of the world.

RequestURL(str)

This string function returns the normal form of the URL that is actively being proxied. For the value of the URL requested by the user during the login process, use login:url and not this function. This function relates to the HTTPHeader directive.

REReplace(re, replace, str) This string function search str for matches to re and replaces them with replace.

RewriteURL(str)

This string function accepts a normal URL and returns either the rewritten form if EZproxy is configured to handle it or the provided value if not. This function relates to the HTTPHeader directive.
 

Right(str, len) This function returns the last len characters of str.
RTrim(str) This string function returns a copy of str with all right-side (trailing) whitespace removed.
SessionCount(str) This numeric function returns the number of active EZproxy sessions whose usernames match the specified str.  If str is the empty string (""), a count of all active sessions is returned.  When used as part of initial user login processing, the user who is logging in is not included in this count as the user does not yet have an active session.  During relogin processing, the user will have an active session included in this count.

UnwriteURL(str)

This string function accepts a rewritten URL and returns either the normal form if EZproxy is configured to handle it or the provided value if not. This function relates to the HTTPHeader directive.

Upper(str) This string function returns a copy of str with all alpha characters converted to upper-case.
URLEncode(str) This string function returns a copy of str with URL special characters percent-hex encoded.
UserFile(str)

This Boolean function directs EZproxy to try to open a file of the specified str and evaluate it based on the rules normally applied to user.txt and then returns 1 if the current user credentials are considered valid or 0 if not.

During user authentication, if the Admin directive has been used to declare a user as an administrator and then UserFile is called, the earlier Admin directive will be cancelled out. To avoid this, insure that any use of the Admin directive occurs either within the file invoked by UserFile or appears somewhere in the main file after UserFile is invoked.

The file specified does not need to include authentication directives, and may instead contain a simple ::Common /Common block of commands that manipulate variables. An advanced application of this concept to incorporate a time-of-day based greeting into login.htm might involve adding:

^{UserFile("greeting.txt"), greeting}

to login.htm and creating greeting.txt in the directory where EZproxy is installed with this content:

::Common
Set now = DateTime()
Set hour = FormatDateTime("%H", now)
Set timeOfDay = "afternoon"
If hour < 12; Set timeOfDay = "morning"
If hour >= 18; Set timeOfDay = "evening"
Set greeting = "Good " . timeOfDay
/Common
UserString(str) This Boolean function operates identical to the UserFile function, with the exception that str is a string variable that should be evaluated as though it was part of user.txt.
ValidStartingPointURLTarget(url) This Boolean function returns 1 if the specified URL is valid to use as the target of a starting point URL and 0 if not.

GeoLite data

This product includes GeoLite data created by MaxMind, available from www.maxmind.com .