This appendix contains the following topics:
The If
, ElseIf
, and Else
tags enable you to define the conditions under which a set of directives will be executed. These tags can only appear inside an Object
tag. In addition, these tags can evaluate an expression, then conditionally execute one or more contained directives. The usage of these tags is summarized below:
If
and ElseIf
tags offer a richer expression syntax, including support for regular expressions. For more information about the If
and ElseIf
expression syntax, see Expressions.
If
, ElseIf
, and Else
tags can contain other tags.
If
and ElseIf
expressions are evaluated once per request, not once per contained directive.
If
, ElseIf
, and Else
tags cannot contain multiple types of directives.
Directives within the If
and ElseIf
tags can contain regular expression backreferences.
When used, an ElseIf
or Else
tag must immediately follow an If
or ElseIf
tag. ElseIf
and Else
tags are skipped if the preceding If
or ElseIf
expression evaluates to logical true.
The following example shows If
, ElseIf
, and Else
tag syntax:
<If $path eq "/"> <If $browser =~ "MSIE"> NameTrans fn="rewrite" path="/msie.html" </If> <ElseIf $browser =~ "Mozilla"> NameTrans fn="rewrite" path="/mozilla.html" </ElseIf> <Else> NameTrans fn="rewrite" path="/unknown.html" </Else> </If>
This example displays a different page based on whether the browser is Microsoft Internet Explorer, Mozilla Firefox, or another browser.
The Oracle® Fusion Middleware includes a set of variables predefined by the server, and the capability for you to define custom variables. This section includes the following topics:
Predefined variables are implicitly defined by the server. The following table lists the predefined variables and their descriptions:
Variable | Description |
---|---|
$ n |
Regular expression backreference (value of the nth capturing subpattern, n = 1...9), for example, $1 .
Regular expression backreferences are only available within the body of |
$& |
Value that matched a regular expression.
Regular expression backreferences are only available within the body of |
$ n |
Regular expression backreference (value of the nth capturing subpattern, n = 1...9), for example, $1 .
Regular expression backreferences are only available within the body of |
$& |
Value that matched a regular expression.
Regular expression backreferences are only available within the body of |
$body |
Contains the entity-body (if any) of the current HTTP request that OTD receives from the client (browser). The size of the data stored in this variable is configured using the body-buffer-size sub-element of the http element in server.xml. |
$browser |
Web browser version (alias for $headers{'user-agent'} if the client sent a User-Agent header or an empty string). |
$chunked |
Boolean variable that indicates whether the request body was sent using chunked encoding. |
$code |
Response status code. |
$cookie{' name'} |
Value of the cookie name from the request. |
$dns |
Alias for $client{'dns'} . |
$env{' name'} |
Value of the environment variable name (includes CGI/SHTML environment variables). |
$headers{' name'} |
Value of name from rq->headers , that is, value of the request header name where name is a lowercase string. |
$id |
Virtual server ID as specified by the name subelement of the virtual-server element in the server.xml file. |
$internal |
Boolean value that indicates whether request was internally generated. |
$ip |
Alias for $client{'ip'} . |
$keep_alive |
Boolean value that indicates whether the connection is kept open. |
$keysize |
Alias for $client{'keysize'} . |
$method |
Request method (alias for $reqpb{'method'} ). |
$path |
Requested path (either URI, partial path, or file system path depending on stage).
The predefined variable |
$path_info |
Alias for $vars{'path-info'} . |
$ppath |
Alias for $vars{'ppath'} . |
$protocol |
Request protocol (alias for $reqpb{'protocol'} ). |
$query |
Request query string (alias for $reqpb{'query'} ). |
$reason |
Response reason phrase. |
$referer |
Alias for $headers{'referer'} . |
$reqpb{' name'} |
Value of name from rq->reqpb . |
$restarted |
Boolean value that indicates whether the request was restarted. |
$secret_keysize |
Alias for $client{'secret-keysize'} . |
$server_url |
Prefix for self-referencing URLs. |
$time |
Time the request was received as the number of seconds since 00:00:00 UTC, January 1, 2006. |
$time_day |
Day of the month when the request was received. Value can be from 01 to 31. |
$time_hour |
Hours since midnight when the request was received. Value can be from 00 to 23. |
$time_min |
Minutes after the hour when the request was received. Value can be from 00 to 59. |
$time_mon |
Month of the year when the request was received. Value can be from 01 to 12. |
$time_sec |
Seconds after the minute when the request was received. Value can be from 00 to 61. |
$time_wday |
Day of the week when the request was received. Value can be from 0 to 6, where 0 corresponds to Sunday. |
$time_year |
Four-digit year when the request was received. |
$type |
Alias for $srvhdrs{'content-type'} . |
$uri |
URI of the requested resource (alias for $reqpb{'uri'} ). |
$url |
URL of the requested resource. |
$urlhost |
Host name to which the client connected. |
$vars{' name'} |
Value of name from rq->vars . |
$security |
Boolean value that indicates if a secure transport was used. |
$senthdrs |
Boolean value that indicates if a response headers were been sent. |
$srvhdrs{' name'} |
Value of name from rq->srvhdrs , that is, value of response header name where name is a lowercase string. |
You can define custom variables in the server.xml
file using the variables
element. These variables can then be used in function parameters in obj.conf
functions. You can also define variables at request time using the set-variables
function in the obj.conf
file.
Note:
The predefined variables take precedence over custom variables. It is a best practice to use uppercase names for custom variables. Using uppercase avoids conflicts with the lowercase predefined variables, if the list of predefined variables is extended in the future.The server uses the following order when resolving a $variable
:
Predefined variables
Variables defined at request time using set-variable
in obj.conf
Variables defined by the virtual-server
element's variable
subelement in server.xml
Variables defined by the server
element's variable
subelement in server.xml
When you define a $variable
at request time, it is stored as a name-value pair in the rq->vars
pblock
. These variables are given a higher precedence than server.xml
variables so that server.xml
variables can be overridden at request time.
Expressions enable you to dynamically construct server application function (SAF) parameters and to select which SAFs to execute on a request-by-request basis. Expressions are constructed from literals, variables, functions, and operators. Use expressions in If
and ElseIf
tags, in log format strings, and SAF parameters.
This section contains the following topics:
The expression syntax is similar to the syntax used in Perl. Expressions are constructed from literals, variables, functions, and operators.
The following example illustrates how to use expressions in an If
tag:
<If not $internal and $uri =~ "^/private/(.*)$" and $referer !~ "^https?://example.com/"> NameTrans fn="redirect" url="http://example.com/denied.jsp?file=$1" </If>
This example expression checks to see if a request meets certain criteria, for example if it is an internal request. If it does not meet the criteria, the server redirects the request to a request denied URL.
The expression contains the following components:
Literals - "^/private/(.*)$"
and "^https?://example.com/"
Variables - $internal
, $uri
, and $referer
Operators - not
, and
, =~
, and !~
For more information about If
and ElseIf
tags, see "If, ElseIf, and Else Tags".
In some circumstances, for example, after evaluating an If
or ElseIf
expression, the server must treat the result of an expression as a Boolean value. The server uses the following rules when converting a numeric value to a Boolean value:
Zero evaluates to false.
All other numeric values evaluate to true.
The server uses the following rules when converting a string to a Boolean value:
Zero-length strings evaluate to false.
The string 0 (zero) evaluates to false.
All other strings evaluate to true.
Expression literals are divided into string and numeric literals.
A string literal is enclosed by either single quotation marks ('
) or double quotation marks ("
). When single quotation marks enclose a string literal, the value of the literal is the value within the quotation marks. When double quotation marks are used, any references to variables or expressions within the quotation marks are interpolated. For more information, see String Interpolation.
The following expression examples show the use of single and double quotation marks.
# This expression evaluates to true. ('foo' eq "foo") # This expression evaluates to false. ('foo' eq "bar") # This expression evaluates to true. ('foo' eq "f$(lc('O'))o") # This expression may evaluate to true or false, # depending on the value of the variable $foo ('$foo' eq "$foo")
To include an uninterpolated dollar sign $
in a string enclosed in a double quotation marks, use the two dollar sign or a backslash dollar sign $$
or \$
escape sequences.
When a double quotation marks appears within a literal enclosed by double quotation marks, it must be prefixed with a backslash. When a single backslash (\
) appears within a literal bracketed by double quotes, it must be prefixed with a backslash. When a single quote character appears within a literal bracketed by single quotes, it must be prefixed with a backslash.
The following examples show valid and invalid literals:
# The following are examples of valid literals 'this string literal is bracketed by single quotes' "this string literal is bracketed by double quotes" "the backslash, \\, escapes characters in double quote string literals" 'it\'s easy to use strings literals' # The following are examples of invalid literals 'it's important to escape quote characters' "any \ characters in double quote string literals must be escaped"
A numeric literal can consist of decimal digits and an optional decimal point, a leading zero followed by octal digits, or a leading 0x
prefix followed by hexadecimal digits. Hexadecimal and octal numbers are automatically converted to decimal form.
The following examples show expressions that use numeric literals:
# The following expressions evaluate to true (1 < 2) (0x10 == "16") (1 == 1.00) # The following expressions evaluate to false (1 > 2) ("0x10" == 16) (1 != 1.00)
Any $variable
can be used as a variable in an expression. To mirror the Client
tag syntax, the dollar sign $
prefix is optional for predefined variable names in expressions. For example, the following three portions of the obj.conf
file are semantically equivalent:
<If $uri = "*.html"> ... </If> <If uri = "*.html"> ... </If> <Client uri = "*.html"> ... </Client>
Any variable names you define must use the $
prefix. For example, the following expression is invalid even if somecustomvariable
is defined in a server.xml
variable
element:
<If somecustomvariable = "foo"> ... </If>
To make this expression valid, add the dollar sign prefix:
<If $somecustomvariable = "foo"> ... </If>
The following table lists the operators that are used in expressions.
Operator Symbol | Operator Name |
---|---|
! |
C-style logical not |
= |
Wildcard pattern match |
=~ |
Regular expression match |
!~ |
Regular expression mismatch |
+ |
Addition or unary plus |
- |
Subtraction or unary minus |
. |
String concatenation |
defined | Value is defined |
-d |
Directory exists |
-e |
File or directory exists |
-f |
File exists |
-l |
Symbolic link exists |
-r |
File is readable |
-s |
File size |
-U |
URI maps to accessible file or directory |
< |
Numeric less than |
<= |
Numeric less than or equal to |
> |
Numeric greater than |
>= |
Numeric greater than or equal to |
lt |
String less than |
le |
String less than or equal to |
gt |
String greater than |
ge |
String greater than or equal to |
== |
Numeric equal |
!= |
Numeric not equal |
eq |
String equal |
ne |
String not equal |
^ |
C-style exclusive or |
&& |
C-style logical and |
|| |
C-style logical or |
not |
Logical not |
and |
Logical and |
or |
Logical or |
xor |
Logical exclusive or |
The following table lists the precedence of operators within expressions from highest to lowest precedence.
Symbol | Operands | Associativity | Description |
---|---|---|---|
( ) , [ ] |
0 | Left to right | Parentheses |
! , unary + , unary - |
1 | Right to left | Sign operators |
= , =~ , !~ |
2 | Non-associative | Pattern matching operators |
+ , - , . |
2 | Non-associative | Additive operators |
defined , -d , -f , -l , -r , -s , -U |
1 | Right to left | Named operators |
< , lt , <= , le , > , gt , >=, ge |
2 | Non-associative | Relational operators |
== , eq , != , ne |
2 | Non-associative | Equality operators |
^ |
2 | Left to right | C-style exclusive or operator |
&& |
2 | Left to right | C-style logical and operator |
|| |
2 | Left to right | C-style logical or operator |
not |
1 | Right to left | Logical not operator |
and |
2 | Left to right | Logical and operator |
or , xor |
2 | Left to right | Logical or operators |
The numeric operators (<
, <=
, >
, >=
, ==
, and !=
) are intended to operate on numbers and not strings. To facilitate comparing numbers, dates, and timestamps, the numeric operators ignore any white space, colons, slashes, and commas in their arguments. Dashes after the first digit are also ignored.
Note:
It is generally incorrect to use the numeric operators on non-numeric values.For example, the following expression evaluates to true:
# The following expression evaluates to true because both # "foo" and "bar" are numerically equivalent to 0 ("foo" == "bar")
Expression functions manipulate data for use in expressions. Expression functions are different from SAFs. While SAFs perform the actual work associated with an HTTP request, expression functions are used to select which SAFs run and what parameters to pass to the SAFs.
Some expression functions require one or more arguments. An expression function's argument list is enclosed in parentheses (()
) and the individual arguments are separated by commas (,
).
The individual expression functions are listed in the following sections:
The atime
function returns the time of the last access for the specified file or directory.
atime
(path)
The following table describes the argument for the expression function.
Argument | Description |
---|---|
path | The absolute path to the directory or file name for which you are requesting the last access. |
The choose
function parses pipe-separated values from values and returns one at random.
choose (values)
The following table describes the argument for the expression function.
Argument | Description |
---|---|
values | The list of values to choose from, separated by the pipe character (|) |
The following obj.conf
code demonstrates the use of choose
to randomly select one of three images:
NameTrans fn="rewrite" from="/images/random" path="/images/$(choose('iwsvi.jpg|0061.jpg|webservervii.jpg'))"
The ctime
function returns the time of the last status change for the specified file or directory.
ctime (path)
The following table describes the argument for the expression function.
Argument | Description |
---|---|
path | The absolute path to the directory or file name for which you are requesting the last status change |
The escape
function encodes the URI using util_uri_escape
, converting special octets to their percentage encoded equivalent and returns the result.
escape(uri)
The following table describes the argument for the expression function.
Argument | Description |
---|---|
uri | The URI that the expression function converts |
See Also:
unescapeThe external
function passes a value to an external rewriting program and returns the result.
Each invocation of external
results in a single newline-terminated line being written to the external rewriting program's stdin
. For each line of input, the program must produce a single line of output. When developing an external rewriting program, it is important to avoid buffering stdout
. In Perl, for example, $| = 1
; is used to disable buffering. Because the server expects the external rewriting program to produce one line of output for each line of input, the server can stop responding if the external rewriting program buffers its output.
external (program, value)
The following table shows the arguments for the external
function.
Argument | Description |
---|---|
program | The program argument is the file name of an external rewriting program. Because program is executed using the operating system's default shell (/bin/sh on Unix/Linux ) or the command interpreter (CMD.EXE on Windows), program should be an absolute path or the name of a program in the operating system's PATH . The server starts the external rewriting program on demand. A given server process never executes more than one instance of the program at a time. |
value | The value passed to the rewriting program. |
The following is an example of an external rewriting program rewrite.pl, used to change the prefix /home/ to /u/
:
#!/usr/bin/perl
$| = 1;
while (<STDIN>) {
s|^/home/|/u/|;
print $_;
}
In this example, the external expression function used to invoke rewrite.pl
is as follows:
NameTrans fn="rewrite" path="$(external('rewrite.pl', $path
))"
The httpdate
function returns an RFC 1123 date time stamp for use in HTTP header fields such as Expires
.
httpdate (time)
The following table describes the argument for the httpdate
function.
Argument | Description |
---|---|
time | The time value. |
The following obj.conf
code could be used to set an Expires
header that indicates a response is not cached for more than one day:
ObjectType fn="set-variable"
insert-srvhdrs="$(httpdate($time + 86400))"
The lc
function converts all the US ASCII characters in the string to lowercase and returns the result.
lc(string)
The following table describes the argument for the lc
function.
Argument | Description |
---|---|
string | The string the expression function converts to lowercase. |
The following obj.conf code can be used to redirect clients, who erroneously used uppercase characters in the request URI to the equivalent lowercase URI:
<If code == 404 and not -e path and -e lc(path)>
Error fn="redirect" uri="$(lc($uri))"
</If>e($time + 86400))"
See Also:
ucThe length
function returns the length of its argument, that is, a number representing the length of the string.
length (string)
The following table describes the argument for the expression function.
Argument | Description |
---|---|
string | The string for which the expression function computes the length. |
The following obj.conf code can be used to send a 404 Not found error to clients that request URIs longer than 255 bytes:
<If length($uri) > 255)>
PathCheck fn="deny-existence"
</If>
The lookup
function inspects a text file for a name-value pair with name name and returns the corresponding value. The name-value pairs in the file are separated by white space.
If the file does not contain a name-value pair with the specified name, this function returns the value of defaultvalue, if specified, or returns an empty string.
lookup(filename, name, defaultvalue)
The following table describes the argument for the expression function.
Argument | Description |
---|---|
filename | Indicates the name of a text file that contains one name-value pair per line. filename can be an absolute path or a path relative to the server's config directory. Names and values are separated by white space. Lines beginning with a pound sign (#) are ignored. |
name | The name of the name-value pair for which the function looks in the text file. |
defaultvalue | The value returned by the function if filename exists but does not contain a name-value pair with a name matching the value of name. If defaultvalue is not specified, it defaults to an empty string. |
The following example shows a text file called urimap.conf that could be used with the lookup function to map shortcut URIs to URIs:
# This file contains URI mappings for Oracle Traffic Director.
# Lines beginning with # are treated as comments.
# All other lines consist of a shortcut URI, whitespace, and canonical URI.
/webserver /software/products/web_srvr/home_web_srvr.html
/solaris /software/solaris/
/java /software/java/
Using the previous sample text file, you could use the following lookup expression to implement shortcut URIs for commonly accessed resources:
<If lookup('urimap.conf', uri)>
NameTrans fn="redirect" url="$(lookup('urimap.conf', uri))"
</If>
The lookupregex
function inspects a text file for a regular expression-value pair. This function takes a string as an input and matches it with the regular expression in each line. It returns the corresponding value only if it matches. If the file does not contain a match, this function returns the default value, if specified, or returns an empty string.
lookupregex (filename,string,defaultvalue)
The following table describes the argument for the expression function.
Argument | Description |
---|---|
filename | The filename is the name of a text file that contains one regular expression-value pair per line. filename can be an absolute path or a path relative to the server's configuration directory. |
string | The string to match with every regular expression in the text file. |
defaultvalue | The value returned by the function if the filename exists but does not contain a matching regular expression-value pair. If defaultvalue is not specified, it defaults to an empty string. |
The mtime
function returns the time of the last data modification for the specified file or directory.
mtime(path)
The following table describes the argument for the expression function.
Argument | Description |
---|---|
path | The absolute path to the directory or file name for which you are requesting the last data modification. |
The owner
function returns the owner of a file.
owner(path)
The following table describes the argument for the expression function.
Argument | Description |
---|---|
path | The absolute path to the directory or file name for which you are requesting the last data modification. |
The uc
function converts all the US ASCII characters in string to uppercase and returns the result.
uc(string)
The following table describes the argument for the expression function.
Argument | Description |
---|---|
string |
The string that the expression function converts to uppercase. |
See Also:
lcThe unescape function decodes the URI using util_uri_unescape, converting percent-encoded octets to their unencoded form, and returns the result.
unescape(uri)
The following table describes the argument for the expression function.
See Also:
escapeThe If
and ElseIf
expressions can evaluate regular expressions using the equal sign and tilde (=~)
and exclamation point and tilde (!~)
regular expression matching operators. These regular expressions use the Perl-compatible syntax implemented by Perl-compatible Regular Expressions (PCRE).
By default, regular expressions are case sensitive. The (?i)
option flag can be added to the beginning of a regular expression to request case insensitivity, for example:
$uri =~ '^/[Ff][Ii][Ll][Ee][Nn][Aa][Mm][Ee]$' $uri =~ '(?i)^/filename$'
When an If
or ElseIf
expression contains a regular expression, regular expression backreferences can appear within arguments in the container body. Regular expression backreferences are of the form $
n where n is an integer between 1 and 9 corresponding to the capturing subpattern of the regular expression, for example:
<If $path =~ '^(.*)(\.html|\.htm)$'> NameTrans fn="rewrite" path="$1.shtml" </If>
In the preview example, two subpatterns are used in the If
expression, so $1
and $2
can be used as backreferences. In the example, the value of the first capturing subpattern is used within a NameTrans fn="rewrite"
parameter. The value of the second capturing subpattern is ignored.
An If
or ElseIf
expression can contain backreferences to earlier regular expressions in that same If
or ElseIf
expression, for example:
<If "foo" =~ "(.*)" and $1 eq "foo"> # Any contained directives will be executed # since $1 will evaluate to "foo" ... </If>
The contents of the preview If
expression are executed, because the given If
expression always evaluates to true.
However, If
and Elseif
expressions, and contained directives, cannot contain backreferences to regular expressions in parent containers. For example, the following obj.conf
entry is invalid:
<If $path =~ '(.*)\.css'> <If $browser = "*MSIE*"> # This example is invalid as $1 is not defined AuthTrans fn="rewrite" path="$1-msie.css" </If> </If>
You can use the dollar sign and ampersand $&
to obtain the value that last successfully matched a regular expression. Use the following obj.conf
entry to redirect requests for HTML files to another server:
<If $path =~ '\.html$' or $path =~ '\.htm$' > NameTrans fn="redirect" url="http://docs.example.com$&" </If>
Strings that contain references to variables or expressions are called interpolated strings. When you use interpolated strings, the embedded expressions and variables are evaluated, and the result is inserted into the string. The act of inserting data into a string is called string interpolation.
Use interpolated strings in expressions, log formats, and obj.conf
parameters. In expressions, only string literals enclosed in double quotation marks are interpolated. For more information, see Expression Literals.
To include the value of a variable in a string, prefix the name of the variable with the dollar-sign ($
). For example, the following format
element in server.xml
logs the client IP address, requested URI, and corresponding file system path for each HTTP request:
<access-log> <file>access</file> <format>$ip "$uri" $path</format> </access-log>
In this example, $ip
, $uri
, and $path
are predefined variables. For more information, see Variables.
For more information about access logs and log format, see "Using the Custom Access-Log File Format".
If the name of the variable is ambiguous, add braces {}
to the name. For example, the following string contains a reference to the predefined $path
variable:
"${path}html"
Without the braces, the string contains a reference to a hypothetical variable named pathhtml
.
To include the result of an expression in a string, prefix the expression with a dollar sign and a left parenthesis ($(
and follow it with a right parenthesis )
. For example, the following two strings are identical after interpolation:
"$(2 + 2)" "4"
When an interpolated string is used as an obj.conf
parameter, the string is interpolated each time the corresponding instruction is executed. For example, the following lines could be used in the obj.conf
file to redirect clients based on the requested URI and the contents of the file redirect.conf
:
<Object ppath="/redirect/*"> NameTrans fn="redirect" url="$(lookup('redirect.conf', $uri, '/'))" </Object>
In this example, the expression lookup('redirect.conf', $uri, '/')
is evaluated each time the NameTrans
directive is invoked, and the result is passed to the redirect
SAF in its url
parameter.
Oracle Traffic Director supports wildcard pattern matching in expressions. To use a wildcard without any special meaning, precede it with a backslash (\
).
The following table describes various wildcard patterns and their uses.
Wildcard | Use |
---|---|
* |
Matches zero or more characters. |
? |
Matches one occurrence of any character. |
| |
An or expression. The substrings used with this operator can contain other special characters such as an asterisk * or dollar sign $ . The substrings must be enclosed in parentheses, for example, (a|b|c ), but the parentheses cannot be nested. |
$ |
Matches the end of the string. This is useful in or expressions. |
[abc] |
Matches one occurrence of the characters a , b , or c . Within these expressions, the only character that must be treated as a special character is the right bracket ] ; all others are not special. |
[a-z] |
Matches one occurrence of a character between a and z . |
[^az] |
Matches any character except a or z . |
*~ |
This expression, followed by another expression, removes any pattern matching the second expression. |
The following table lists wildcard examples with pattern and the result.
Wildcard | Result |
---|---|
*.example.com |
Matches any string ending with the characters .example.com . |
(quark|energy).example.com |
Matches either quark.example.com or energy.example.com . |
198.93.9[23].??? |
Matches a numeric string starting with either 198.93.92 or 198.93.93 and ending with any 3 characters. |
*.* |
Matches any string with a period in it. |
*~example-* |
Matches any string except those starting with example- . |
*.example.com~quark.example.com |
Matches any host from domain example.com except for a single host quark.example.com . |
*.example.com~(quark|energy|neutrino).example.com |
Matches any host from domain .example.com except for hosts quark.example.com , energy.example.com , and neutrino.example.com . |
*.com~*.example.com |
Matches any host from domain .com except for hosts from sub domain example.com . |
*~*.gif* |
Matches any string except those including gif . |