sde sandscript reference guide r.6.40 a02.pdf

SDE Release 6.40.00, SandScriptReference

05-00246-A022013-9-12

Themost current version of this document is available on the Sandvine Customer Support web site at https://support.sandvine.com.

This document and the products described within are subject to copyright. Under copyright laws, neither this document nor theproduct may be reproduced, translated, or reduced to any electronic medium or machine readable or other form without priorwritten authorization from Sandvine.

Copyright 2013, Sandvine Incorporated ULC. All rights reserved. Sandvine is a trademark of Sandvine Incorporated ULC. Allother product names mentioned herein are trademarks of their respective owners.

Sandvine is committed to ensuring the accuracy of our documentation and to continuous improvement. If you encounter errorsor omissions in this user guide, or have comments, questions, or ideas, we welcome your feedback. Please send your commentsto Sandvine via email at https://support.sandvine.com.

Contacting Sandvine

To view the latest Sandvine documentation or to contact Sandvine Customer Support, register for an account athttps://support.sandvine.com.

For a list of Sandvine Sales and Support offices, see http://www.sandvine.com/about_us/contact.asp.

SDE Release 6.40.00, SandScript Reference205-00246-A02

Notices

Contents1 Functions......................................................................................................................................................................5

1.1 General Functions.................................................................................................................................................6

1.1.1 Conversion Functions.....................................................................................................................................6

1.1.2 Octet Conversion Functions...........................................................................................................................7

1.1.3 Time Functions...............................................................................................................................................9

1.1.4 String Functions...........................................................................................................................................10

1.1.5 Logical Operator Functions..........................................................................................................................11

1.1.6 Math Functions.............................................................................................................................................12

1.1.7 Network Functions........................................................................................................................................13

1.1.8 Encryption Functions....................................................................................................................................14

1.2 Map Functions.....................................................................................................................................................16

1.2.1 String Map Functions...................................................................................................................................16

1.2.2 Hostname Map Functions............................................................................................................................16

1.2.3 URL Map Functions......................................................................................................................................17

1.3 Table Functions...................................................................................................................................................17

1.4 Diameter Functions.............................................................................................................................................18

1.5 Subscriber Mapping Functions............................................................................................................................18

1.6 DHCP Functions..................................................................................................................................................19

1.6.1 DHCPv4.......................................................................................................................................................19

1.6.2 DHCPv6.......................................................................................................................................................19

1.7 RADIUS Functions..............................................................................................................................................20

1.7.1 RADIUS Client Function...............................................................................................................................20

1.7.2 RADIUS Server Function.............................................................................................................................20

2 SandScript Fields.......................................................................................................................................................23

2.1 Measurements.....................................................................................................................................................25

2.1.1 Measurement Fields.....................................................................................................................................25

2.1.2 Measurement Fields Usage.........................................................................................................................27

2.2 Classifiers............................................................................................................................................................27

2.3 Timers..................................................................................................................................................................28

2.4 Tables..................................................................................................................................................................28

2.5 Events..................................................................................................................................................................29

2.6 Subscriber Session Fields...................................................................................................................................29

2.7 Subscriber and Session Attributes......................................................................................................................31

2.8 Utility Fields.........................................................................................................................................................32

2.9 Expressions for Unique-by..................................................................................................................................32

2.10 Provisioning.......................................................................................................................................................32

3SDE Release 6.40.00, SandScript Reference05-00246-A02

2.10.1 Provisioning NAT........................................................................................................................................34

2.10.2 Provisioning.Subscriber.Get ......................................................................................................................35

2.10.3 Provisioning.Subscriber.Delete..................................................................................................................35

2.11 Published Expressions......................................................................................................................................36

2.12 Environment Fields............................................................................................................................................36

2.13 Diameter Fields.................................................................................................................................................36

2.14 DHCPv4.............................................................................................................................................................38

2.14.1 DHCPv4 Mandatory Fields.........................................................................................................................39

2.14.2 DHCPv4 Optional Fields............................................................................................................................40

2.15 DHCPv6.............................................................................................................................................................41

2.15.1 DHCPv6 Mandatory Fields.........................................................................................................................42

2.15.2 DHCPv6 Optional Fields............................................................................................................................43

2.16 GTP-C...............................................................................................................................................................43

2.16.1 GTP-Cv1 Event-specific.............................................................................................................................44

2.16.2 GTP-Cv2 Event-specific.............................................................................................................................45

2.16.3 GTP-C Unknown Session..........................................................................................................................47

2.16.4 GTP-C Session Universal..........................................................................................................................47

2.16.5 GTP-C Session Reference in Message Scope..........................................................................................47

2.16.6 GTP-Cv1 Message Scope..........................................................................................................................48

2.16.7 GTP-Cv2 Message Scope..........................................................................................................................50

2.17 ID Allocation......................................................................................................................................................56

2.17.1 IdAllocation.Lookup () ................................................................................................................................58

2.17.2 IdAllocation.Delete() ..................................................................................................................................59

2.18 LDAP ................................................................................................................................................................60

2.18.1 ....................................................................................................................................................................60

2.18.2 Ldap.Get()..................................................................................................................................................61

2.18.3 Ldap.GetAttributes ()..................................................................................................................................62

2.18.4 Ldap.Search().............................................................................................................................................62

2.19 RADIUS.............................................................................................................................................................63

2.19.1 RADIUS Command Header.......................................................................................................................64

2.19.2 RADIUS AVP..............................................................................................................................................65

2.19.3 RADIUS Special Expressions....................................................................................................................66

2.20 Text Input...........................................................................................................................................................66

2.21 Failover Cluster.................................................................................................................................................67

2.22 External Command............................................................................................................................................67


4 | Sandvine | TOC

1Functions "General Functions" on page 6

"Map Functions" on page 16

"Table Functions" on page 17

"Diameter Functions" on page 18

"Subscriber Mapping Functions" on page 18

"DHCP Functions" on page 19

"RADIUS Functions" on page 20

1.1 General FunctionsFunctions take one or more arguments (in the form of expressions) and return a value.

The function argument types and names are specified. Optional arguments are enclosed in { } and the default value follows theequal sign. For example: {integer optional=10}.

1.1.1 Conversion FunctionsFunctions that convert input to some other form are:

TypeDescriptionFunction

StringConverts s to a binary string by interpreting special backslash-escapedcharacters. Supported special characters are:

BinaryString (string s)

\n -> newline \r -> carriage return \" -> " \' -> ' \\ -> \

BooleanConverts the value of the expression to a boolean. Accepts integer, floatand string types. For integers and floats, returns true for non-zero values,false otherwise. For strings:

Boolean(expression e)

true, t, yes, y are converted to true false, f, no, n are converted to false any other string returns null

Takes a readable MAC in string format (xx:xx:xx:xx:xx:xx orxx-xx-xx-xx-xx-xx) and converts it to a compact format (xxxxxxxxxxxx)

CompactMac(string MAC, {booltoLower})

by removing the separator - or :. If argument toLower is false or notspecified, the compact format uses upper- case characters. If toLoweris true, it uses lower-case characters.

FloatConverts the value of the expression to a float. Typically used to convertstring (for example "12.345", "0xab"). If the conversion is invalid (for

Float(expression e)

example float("nowork")) returns NULL. Will accept integer, string, andboolean types.

IntegerConverts the value of the expression to an integer. Typically used toconvert strings (for example "12345", "0xab"). If the conversion is invalid

Integer(expression e)

(for example integer("nowork")) returns NULL. Will accept float, string,and boolean types.

IpAddressConverts the value of the expression to an IP address. Typically usedto convert strings. For example:

IpAddress(expression e)

"192.168.1.1" "2001:1::3"

StringConverts the integer IP value to a formatted string. Can be used toconvert IP fields like Flow.Client.IpAddress to human readable form.

IpToString(integer ip)


FunctionsGeneral Functions

TypeDescriptionFunction

Returns the prefix length of a netmask represented as an IP address. Incase of an input which is not a valid mask, the function returns null. Forexample:

NetmaskToPrefixLength (ipaddressip)

NetmaskToPrefixLength(StringToIp(FFFF::)) returns 16 NetmaskToPrefixLength(StringToIp(255.255.255.0)) returns 24 NetmaskToPrefixLength(StringToIp(255.128.255.0)) returns null

Returns a netmask represented as an IP address that matches the prefixlength in the input. If isV4=true, an IPv4 netmask is returned. If isV4=false,

PrefixLengthToNetmask (integerlength, {bool isV4})

then an IPv6 netmask is returned. If the length argument is less than 0or greater than the maximum length of the requested IP version, null isreturned. For example:

PrefixLengthToNetmask(23) returns 255.255.254.0 PrefixLengthToNetmask(23, true) returns 255.255.254.0 PrefixLengthToNetmask(23, false) returns FFFF:FE00:: PrefixLengthToNetmask(38) returns FFFF:FFFF:FC00:: PrefixLengthToNetmask(129) returns null

StringConverts the value of the expression to a string. Will accept integer, float,boolean and IpAddress types.

String(expression e)

IpAddressConverts a human readable IPv4 or IPv6 address in string format to anIP Address. For example:

StringToIp(string ip)

StringToIp("192.168.1.1") StringToIp("2001:1::3")

Note:If a string literal is passed to this function instead of a field, and thestring is not a valid IP address, policy will fail to reload.

IntegerTakes a readable MAC in string format and converts it to an integer. TheMAC string format is:

StringToMac(string mac)

xx:xx:xx:xx:xx:xx

1.1.2 Octet Conversion FunctionsThese functions convert to and from octets:

DescriptionFunction

Converts a hex formatted string to its octet string equivalent. Odd length strings willassume a leading zero. null is returned on invalid hex characters. Valid hex charactersare: 0-9, a-f, A-F. For example:

HexToOctets(string hexString)

HexToOctets("0054FEDE") returns {00,54,FE,DE}

Returns a string with the specified IP address converted to either a 4-byte or 16-byteoctet string, for IPv4 and IPv6 addresses respectively. Conversion is to network order.Only returns null if the input is null.

IpToOctets(ipaddress ip)

If the string is 4 bytes, returns an IPv4 address formed by reading the string in networkbyte order. If the string is 16 bytes, returns an IPv6 address formed by reading the

OctetsToIp(string s)



DescriptionFunction

string in network byte order. If the string is other than 4 or 16 bytes in length, returnsnull.

Converts the octet sequence string to its dotted/colon IPv4/IPv6 policy stringequivalent. PolicyString must be either 4 or 16 bytes. IPv6 addresses are returnedin their compressed format. For example:

OctetsIpToString(string OctetsIP)

OctetsIpToString({C0,A8,00,01}) returns 192.168.0.1 OctetsIpToString({C0,A8,00,01, 01, 01}) returns null OctetsIpToString({C0,A8}) returns null OctetsIpToString({C0,A8,00,01,01,01,01,01,01,01,01,01,01,01,01,01}) returns

c0a8:1:101:101:101:101:101:101

Converts a string of octets (binary) to its hex string equivalent with leading zeros.This means each byte will be converted to a two-character string. The string is

OctetsToHex(string octetsString)

converted in order, so the first byte will be the first two characters, and the firstcharacter will be the first 4 bits or the first byte. For example:OctetsToHex({00,54,FE,DE}) returns "0054fede"

Converts a list of policy expressions into an octet string. Each format character,except the padding, requires an additional argument to be provided to the Serializefunction. For example:

Serialize(string format, expression e1,{expression e2, {...}})

Serialize(ccx2, 5, 9) returns {05, 09, 00, 00}The octet string uses these format characters, as indicated.Integers:

c - 8 bit integer s - 16 bit integer, little endian S - 16 bit integer, big endian i - 32 bit integer, little endian I - 32 bit integer, big endian w - 64 bit integer, little endian W - 64 bit integer, big endianInteger types may be followed by a "u" to indicate an unsigned value.Floating point values:

q - 64 bit floating point, little endian Q - 64 bit floating point, big endianPadding:

x - 1 byte of null (0) character paddingThe padding type may be followed by a count if more than one padding byte isrequired.Strings:

a - string padded by null (0) characters A - string padded by spacesString types may be followed by a count specifying a fixed length or by * if anarbitrary length string must be serialized. If a fixed length is specified, the input stringwill be padded or truncated to match the specified length. Arbitrary length strings willnot be padded.IP address values:



DescriptionFunction

Z - IP address, network order. 4 bytes are serialized if the input expression is anIPv4 address. 16 bytes are serialized if the input expression is an IPv6 address

Z4 - IPv4 address, network order. If the input expression is an IPv6 address, theaddress 0.0.0.0 is serialized

Z6 - IPv6 address, network order. If the input expression is an IPv4 address, theaddress will be serialized using IPv4-mapped-IPv6 format

z4 - IPv6 address, little endian. If the input expression is an IPv6 address, theaddress 0.0.0.0 is serialized

Converts the dotted IPv4 policy string to its 4 byte octet string equivalent. For example:StringIpToOctets(string ip)StringIpToOctets(192.168.0.1) returns {C0,A8,00,01}

1.1.3 Time FunctionsFunctions that can be used to manage time data or timestamps are:

DescriptionFunction

Constructs and returns a timestamp integer from the specified arguments representingUTC.

GmTime(integer year, integer month,integer day, {integer hour=0}, {integerminute=0}, {integer seconds=0})

Constructs and returns a timestamp integer from the specified arguments representinglocal time.

LocalTime(integer year, integer month,integer day, {integer hour=0}, {integerminute=0}, {integer seconds=0})

Returns an integer that uniquely identifies the current month.TimeIntervalMonth(integer rollover_day)The value returned will change on the day of the month specified by the rollover_dayargument. For example, if rollover_day is 8, the value will change on the 8th day ofeach month, at 00:00 local time. The function returns NULL for rollover_day valuesless than 1 and greater than 28.

Returns an integer that uniquely identifies the current week. The value returned willchange on the day of the week specified by the rollover_day_of_week argument,

TimeIntervalWeek(integerrollover_day_of_week)

where 0 is Sunday, 1 is Monday, etc., 6 is Saturday. For example, ifrollover_day_of_week is 2, the value will change every Tuesday at 00:00 local time.The function returns NULL for rollover_day_of_week values less than 0 and greaterthan 6

Returns an integer that uniquely identifies the current day. The value returned willchange at the top of the hour specified by the rollover_hour argument. For example,

TimeIntervalDay(integer rollover_hour)

if rollover_hour is 22, the value will change each day at 22:00 local time. The functionreturns NULL for rollover_hour values less than 0 and greater than 23.

Returns an integer that uniquely identifies the current hour. The value returned willchange at the minute of each hour specified by the rollover_minute argument. For

TimeIntervalHour(integer rollover_minute)

example, if rollover_minute is 45, the value will change each hour at 45 minutes pastthe hour, local time. The function returns NULL for rollover_minute values less than0 and greater than 59.

Returns the number seconds remaining before the value returned byTimeIntervalMonth will change.

TimeIntervalMonth.Remaining (integerrollover_day)



DescriptionFunction

Returns the number seconds remaining before the value returned byTimeIntervalWeek will change.

TimeIntervalWeek.Remaining (integerrollover_day)

Returns the number seconds remaining before the value returned by TimeIntervalDaywill change.

TimeIntervalDay.Remaining (integerrollover_day)

Returns the number seconds remaining before the value returned by TimeIntervalHourwill change.

TimeIntervalHour.Remaining (integerrollover_day)

Converts a timestamp string (for example, "2007-12-31T23:59Z") to an integer valuecorresponding to the number of seconds since January 1, 1970.

Timestamp(string s)

Converts a timestamp string (for example, "2007-12-31T23:59.123Z") to an integervalue corresponding to the number of milliseconds since January 1, 1970. Similar toTimestamp(), but with millisecond resolution.

TimestampMs(string s)

Converts an integer or float expression to have units microseconds. The expressionmust have time units. For example, calling ToMicroseconds on an expression witha value of 5 milliseconds returns 5000 microseconds.

ToMicroseconds(expression e)

Converts an integer or float expression to have units milliseconds. The expressionmust have time units. For example, calling ToMilliseconds on an expression with avalue of 5 seconds returns 5000 milliseconds.

ToMilliseconds(expression e)

Converts an integer or float expression to have units seconds. The expression musthave time units. For example, calling ToSeconds on an expression with a value of1000 milliseconds returns 1 second.

ToSeconds(expression e)

These functions extract and return an integer representing the unit of time specifiedby the timestamp argument. DayOfWeek() returns 0 for Sunday, 1 for Monday, andso on.

Year(integer timestamp)Month(integer timestamp)Day(integer timestamp)DayOfWeek(Integer timestamp)Hour(integer timestamp)Minute(integer timestamp)Second(integer timestamp)

1.1.4 String FunctionsFunctions for manipulating strings are:

DescriptionFunction

Returns the source string with the delimiter string inserted at regular intervals. Returnsnull if the source or delimiter strings are null, or if the interval is 0, negative or greaterthan the source string length.

AddDelimiter(string source, stringdelimiter, integer interval)

For example:AddDelimiter("HelloWorld", " ", 5) returns "Hello World"AddDelimiter("123456789abc", ":", 2) returns "12:34:56:78:9a:bc"

Appends a value to a delimited list if it is not already present in the list and returnsthe resulting string.

AppendIfNotPresent(string list, expressionvalue, string delim)

The list should start and end with the delimiter (for example, ";1;2;", not "1;2" or "1;2;"or ";1;2"). If value is null the list is returned unmodified. If list is null, a list containingonly value is returned.



DescriptionFunction

Concatenates all of the arguments together and returns the resulting string. Thearguments can be of any type (for example, Concat("hello", 123) returns "hello123").

Concat(expression e1, {expression e2,{e3, {...}}})

Returns true if s contains substr, false otherwise.Contains(string substr, string s)

Extract a string field from a character-delimited list. The first field has index 0, thesecond has index 1, and so on. Negative indices can be used to locate fields starting

Extract(string delim, integer index, strings, {boolean nullIfEmpty=false})

at the end of the string (the last field has index -1). The optional nullIfEmpty argument,available only in 5.60 and higher, can be specified to return null instead of the emptystring. For example:

Extract(",", 0, "abc,,de,f") returns "abc" Extract(",", 2, "abc,,de,f") returns "de" Extract(",", -1, "abc,,de,f") returns "f" Extract(",", 1, "abc,,de,f", true) returns null

Joins together a list of expressions separated by a constant single-character delimiterand returns the resulting string.

Join(string delim, expression e1,{expression e2, {e3, {...}}})

Join is a specialized, optimized version of Concat. The expression arguments canbe of any type (for example Join(",", "hello", 123, true) returns "hello,123,true").

Returns a string made up by the first count characters of s.Left(string s, {integer count=1})

Returns an integer representing the length of s.Length(string s)

Extract a substring of s of length count, starting at position pos. If count is notspecified, it defaults to 1.

Mid(string s, integer pos, {integercount=1})

Returns true if s matches regular expression reg, false otherwise.Regex(string reg, string s)

Returns the string s with the parts that match the regular expression reg replaced bythe value of the string replacement.

RegSub(string reg, string replacement,string s)

Returns the string s with the first occurrence of substr replaced by the value of thestring replacement. Returns s if s does not contain substr.

ReplaceFirst(string substr, stringreplacement, string s)

Returns a string made up by the last count characters of s.Right(string s, {integer count=1})

Extract a substring of s of length count, starting at position pos. If count is notspecified, the substring is extracted to the end of s.

SubStr(string s, integer pos, {integercount=end})

Converts s to lower case.ToLower(string s)

Converts s to upper case.ToUpper(string s)

1.1.5 Logical Operator FunctionsThese functions perform logical operations:

DescriptionFunction

Returns true only if all of the arguments are true. Returns false if any of the argumentsare false, even if some of the arguments are null. The arguments must all be of type

All(expression e1, {expression e2, {e3,{...}}})

boolean. This function is an optimized form of a compound AND expression (e1 ande2 and e3 ...).



DescriptionFunction

Returns true if any of the arguments are true, even if some of the arguments are null.Returns false only if all of the arguments are false. The arguments must all be of type

Any(expression e1, {expression e2, {e3,{...}}})

boolean. This function is an optimized form of a compound OR expression (e1 or e2or e3 ...).

Returns true if e1 is equal to e2, or e3, etc. At least two arguments, of any type. Forexample:

OneOf(expression e1, {expression e2,{e3, {...}}})

OneOf(subscriber.attribute.color, "red", "green", "blue", "yellow")is equivalent tosubscriber.attribute.color="red" or \subscriber.attribute.color="green" or \subscriber.attribute.color="blue" or \subscriber.attribute.color="yellow"Except the OneOf() version is shorter and much more efficient.

1.1.6 Math FunctionsFunctions used for mathematical operations are:

DescriptionFunction

Returns the absolute value of value. Returns an integer if value is an integer, returnsa float if value is a float.

Abs(integer value)Abs(float value)

Returns true if any of the value arguments are within the range (lower

DescriptionFunction

Returns the maximum value from the list of arguments.Maximum(expression value1, expressionvalue2, {expression value3 ..}) Returns the dominant type of the arguments specified.

Returns the minimum value from the list of arguments.Minimum(expression value1, expressionvalue2, {expression value3 ..}) Returns the dominant type of the arguments specified.

Returns a float that is value rounded to the nearest integer value. The secondargument may specify the number of digits to the right (if positive) or to the left (if

Round(float value, {integer precision=0})

negative) to round to. The default value is 0. For example, Round(1.234, 1) will return1.2, Round(123.9, -2) will return 100.

Returns null if e1 is null, otherwise returns e2. The arguments can be of any type.Equivalent to (e1 is null ? null : e2).

TestNull(expression e1, expression e2)

1.1.7 Network FunctionsFunctions used to manage and manipulate data relating to the network or policy are:

DescriptionFunction

Returns the IP address obtained by applying a subnet mask of the input length tothe input IP address. If the input address is an IPv4 address and the input length is

ApplySubnetMask(address ip, integerlength)

greater than 32, then a length of 32 will be used. If the input address is an IPv6address and the input length is greater than 128, then a length of 128 will be used.If either argument is null, or the length argument is negative, the function will returnnull. For example:

ApplySubnetMask(IPAddress(192.168.0.1), 8) returns the IP address 192.0.0.0 ApplySubnetMask(IPAddress(1234:5678:9ABC:DEF0::), 32) returns the IP

address 1234:5678::

Returns domain truncated to the registered domain name and suffix.DomainRollup (string domain)This function uses the Mozilla Public Suffix List to determine the longest applicablesuffix and returns the suffix plus one additional label to the left. This allows URLsfrom the same top domain to be rolled up and grouped typically for use with reportingbase on top level domains. For example:

DomainRollup("www.google.com") returns "google.com" DomainRollup("video1.youtube.co.uk") returns "youtube.co.uk" DomainRollup("video2.youtube.co.uk") returns "youtube.co.uk"

Converts s to unicoded String if s is IDN-encoded. Otherwise does no conversion.IDNADecode(string s)

Returns an integer, either 4 or 6, depending on the IP version of the ip argument.Only returns null if the ip argument is null.

IpVersion(ipaddress ip)

Returns path in normalized form as a string. Normalization is done in a fashion similarto RFC 1808. The path is made up of a series of folders, separated by slashes. If a

NormalizePath(string path)

folder name is a single period, that folder is treated as if it wasn't there. If the foldername is two periods, that folder and the previous folder is treated as if it wasn't there.If there are extra folders named ".." without preceding folders to removed, the extra".." folders are ignored. Paths are also modified to make sure they always start witha slash. This policy function can be used to normalize a the resource path of an HTTPtransaction to test against known paths, to ensure that the test isn't circumvented by



DescriptionFunction

using these special folders to specify paths that look different but resolve to the sameURL. For example:

NormalizePath(/folder1/./index.html) returns /folder1/index.html NormalizePath(/folder1/../index.html) returns /index.html NormalizePath(index.html) returns /index.html

Returns s with percent-encoded characters decoded back to ASCII, as per RFC3986. This function undoes the operation performed by PercentEncode. This policy

PercentDecode(string s)

function can be used to decode any percent-encoding in a the resource path of anHTTP transaction to test against known paths, to ensure that the test isn'tcircumvented by using percent-encoding to specify paths that look different but resolveto the same URL.

Returns s with special characters percent-encoded as per RFC 3986.PercentEncode(string s)Percent-encoding is a process where irregular characters are represented by replacingthem with a percent sign, followed by that character's ASCII value in hex. Charactersthat are left untouched by this function are:

lower-case letters upper-case letters numbers dash (-) underscore (_) period (.) exclamation mark (!) tilde (~) asterisk (*)This function can be used to construct URLs for redirecting subscribers using a HTTP307 response.

1.1.8 Encryption FunctionsFunctions to handle encrypted data are:

DescriptionFunction

Encrypts the value of text using an Advanced Encryption Standard (AES) cipher andthe key. The key must be base64 encoded. Use Base64Encode or HexToBase64functions to format the key.

AES(string key, string text)

The input string text is padded to a length that is a multiple of 16 bytes to ensurecorrect decryption. The padding scheme uses the syntax of PKCS#7 as specified inRFC 5652.

Encrypts or decrypts the value of the text argument using an Advanced EncryptionStandard (AES) cipher and the argument key. The key must be base64 encoded.

AESEncrypt(string key, string text)AESDecrypt(string key, string text)

Use the Base64Encode or HexToBase64 functions to format the key. Returns a rawstring. The same key must be used both for encryption and decryption.Example:

AESEncrypt(Base64Encode( \"abcdefghijklmnopqrstuvwxyz123456"), "Sandvine")



DescriptionFunction

Translates the specified string into a base 64 representation.Base64Encode(string value)

Translates the specified hex string (two hexadecimal characters per byte) into a base64 representation of the corresponding binary data. Useful for specifying keys forencryption functions in hex format, for example:

AES(HexToBase64("00010203050607080A0B0C0D0F101112", ...))

HexToBase64(string value)

Produces a keyed-Hash Message Authentication Code for text using key and theSHA1 hash function. Use Base64Encode or HexToBase64 functions to format thekey.

HMACSHA1(string key, string text)

Returns a raw string (can be converted back to base 64 with Base64Encode).Base64Encode(HMACSHA1(key (in base 64), text)).

Produces a keyed-Hash Message Authentication Code for text using key and therespective number of bits in the SHA2 hash function. Use Base64Encode orHexToBase64 functions to format the key.

HMACSHA2_224(string key, string text)HMACSHA2_256(string key, string text)HMACSHA2_384(string key, string text)

Returns a raw string (can be converted back to base 64 with Base64Encode). Forexample:

Base64Encode(HMACSHA2_224(key (in base 64), text))

HMACSHA2_512(string key, string text)

Produces a keyed-Hash Message Authentication Code for text using key and anMD5 hash function. Use Base64Encode or HexToBase64 functions to format thekey.

HMACMD5(string key, string text)

Returns a raw string (can be converted back to base 64 with Base64Encode).Base64Encode(HMACMD5(key (in base 64), text)).

Encrypts the value of text using an RC5 cipher and the key. The key must be base64encoded. Use Base64Encode or HexToBase64 functions to format the key.

RC5(string key, string text)

The input string text is padded to a length that is a multiple of 16 bytes to ensurecorrect decryption. The padding scheme uses the syntax of PKCS#7 as specified inRFC 5652.

Encrypts or decrpts the value of text using an RC5 cipher and the key key. Thekey must be base64 encoded. Use Base64Encode or HexToBase64 functions to

RC5Encrypt(string key, string text)RC5Decrypt(string key, string text)

format the key. Returns a raw string. The same key must be used in encryption anddecryption.Example:

RC5Encrypt(HexToBase64( \"00010203050607080A0B0C0D0F101112"), "Sandvine")

Calculates the SHA1 hash value. Returns a raw string . (can be converted back tobase 64 with Base64Encode). Base64Encode(SHA1(text))

SHA1(string text)

Calculates the SHA2 hash value for the respective number of bits. Returns a rawstring. Can be converted back to base 64 with Base64Encode). For example:

Base64Encode(SHA2_224(text))

SHA2_224(string text)SHA2_256(string text)SHA2_384(string text)SHA2_512(string text)



1.2 Map FunctionsEach map type provides extended functionality and optimizations targeted towards a specific use case. See the SDE SandScriptConfiguration Guide for additional information on Map Functions.

The different map types are:

Allows for a map to contain any string.String map:Provides options to perform normalized match of hostnames.Host map:Provides option to perform normalized match of URLs. For use cases where maps containonly full URLs.

URL map:

A map that is optimized to search for IP addresses.IP Address map:

Each map function has this syntax:

Map..

Where:

is the unique name given to the map in the map definition.

is the name of a function. Each function transforms input and finds a match according to optional parametersspecified in the map declaration.

1.2.1 String Map FunctionsFunctions to handle a string map are:

DescriptionFunction Name

Returns true if string is matched by a key/pattern in the map, compared as specified bycase_sensitive parameter in the map declaration.

Contains(string)

Returns the label associated with a key/pattern, if string is matched by a key/pattern in the map,compared as specified by the case_sensitive parameter in the map declaration. The return typeis an integer/string as specified by label_type parameter in the map declaration.

FindLabel(string)

Returns the key/pattern associated with a key/pattern, if string is matched by a key/pattern inthe map, compared as specified by the case_sensitive parameter in the map declaration.

FindPattern(string)

1.2.2 Hostname Map FunctionsFunctions to handle a hostname map are:


Returns true if string is matched by a key/pattern in the map, compared as specified by normalizeand case_sensitive parameters in the map declaration.

Contains(hostname)

Returns the label/value associated with a key/pattern, if string is matched by a key/pattern inthe map, compared as specified by normalize and case_sensitive parameters in the mapdeclaration. The return type is an integer/string based on the label_type in the map declaration.

FindLabel(hostname)


FunctionsMap Functions


Returns the key/pattern associated with a key/pattern, if string is matched by a key/pattern inthe map, compared as specified by normalize and case_sensitive parameters in the mapdeclaration.

FindPattern(hostname)

Returns the host, if hostname is matched by a key/pattern in the map using a compared asspecified by normalize and case_sensitive parameters in the map declaration.

FindHost(hostname)

1.2.3 URL Map FunctionsFunctions to handle a URL map are:


Returns true if string is matched by a key/pattern in the map, compared as specified by normalize,case_sensitive and resource_param_match_order parameters in the map declaration.

Contains(hostname, resource)

Returns the label/value associated with a key/pattern, if string is matched by a key/pattern inthe map, using a compared as specified by normalize, case_sensitive and

FindLabel(hostname,resource)

resource_param_match_order parameters in the map declaration. The return type is aninteger/string based on the label_type in the map declaration.

Returns the key/pattern associated with a key/pattern, if string is matched by a key/pattern inthe map, using a compared as specified by normalize, case_sensitive andresource_param_match_order parameters in the map declaration.

FindPattern(hostname,resource)

Returns the host, if hostname is matched by a key/pattern in the map, compared as specifiedby the normalize, case_sensitive and resource_param_match_order parameters in the mapdeclaration.

FindHost(hostname, resource)

Returns the resource, if resource is matched by a key/pattern in the map, compared as specifiedby normalize, case_sensitive and resource_param_match_order parameters in the mapdeclaration.

FindResource(hostname,resource)

Returns the URL, if URL is matched by a key/pattern in the map, compared as specified bynormalize, case_sensitive and resource_param_match_order parameters in themap declaration.

FindUrl(hostname, resource)

1.3 Table FunctionsTable functions take one or more arguments (in the form of expressions) and return a value.

Table functions operate on specific rows and columns of a particular table. Table functions can be used on any defined tables.

DescriptionField

Returns true only if all of the arguments are true. Returns false if any of the argumentsare false, even if some of the arguments are null. The arguments must all be of type

Table.. All(expression e1,{expression e2, {e3, {...}}})

boolean and of the form Table... This function is anTable.[Key]. All(expressione1, {expression e2, {e3, {...}}}) optimized form of a compound AND expression that contains only boolean columns

of a table (Table..ColumnName1 andTable..ColumnName2 and Table..ColumnName3).


FunctionsTable Functions

DescriptionField

Returns true if any of the arguments are true, even if some of the arguments are null.Returns false only if all of the arguments are false. The arguments must all be of type

Table.. Any(expression e1,{expression e2, {e3, {...}}})

boolean and of the form Table... This function is anTable.[Key]. Any(expressione1, {expression e2, {e3, {...}}}) optimized form of a compound OR expression that contains only boolean columns

of a table (Table..ColumnName1 or Table..ColumnName2or Table..ColumnName3).

Returns a table row, creating the row if it does not exist, where TableName is thename of the table. Used to assign a row to a cursor local variable. Optionally specifya Key list for explicit access to a table row.

Table..Create()Table..Create(Key)

Returns the current number of rows in the table TableName. ColumnName can beany column in the table.

Table...Count()Table.[Key]..Count()

1.4 Diameter FunctionsDiameter functions reveal information about Diameter peers or the state of the Diameter subsystem.

Diameter functions take one or more arguments (in the form of expressions) and return a value. Diameter functions are availableaccording to a dictionary defined by the Diameter subsystem.

DescriptionField

Returns a string description of the Diameter result code provided by integer i.DictionaryName is the name of the Diameter dictionary containing the mapping from

Diameter..ErrorToText(integer i)

result code to description. Each Diameter dictionary makes one of these functionsavailable to SandScript. If the expression is null, or if the result code is not definedin the dictionary, then null will be returned.

Returns true to indicate that the peer identified by the string s is in the connectedstate. Returns false otherwise. If the argument is null, or if no peer with a matchingidentity can be found, then false is returned to indicate a lack of connectivity.

Diameter.PeerStatus(string s)

Returns an integer value representing the percent of the outgoing queue that is fullof a Diameter peer identified by the string s. If the argument is null, or if no peer with

Diameter.TransmitQueue Percent(strings)

a matching identity can be found, then the integer value 100 is returned to indicatea full queue.

1.5 Subscriber Mapping FunctionsFunctions that retrieve a session ID are:

DescriptionFunction

Returns the identifier of a session whose key is the given IP Addressand site number. Returns NULL if no session is mapped with theprovided key.

Session.GetIdFromSite(ipaddress ip, integersite-number)


FunctionsDiameter Functions

DescriptionFunction

Returns the identifier of a session whose private IP maps to theprovided public IP and port number in the NATmapping table. Returns

Session.GetIdFromPort(ipaddress public-ip, integerport-number)

NULL if no session is mapped with the provided public IP and portnumber.

1.6 DHCP FunctionsDHCP subsystem consists of the DHCPv4 and DHCPv6 subsystems.

Both subsystems are dictionary configurable. The dictionary file is located at /usr/local/sandvine/etc/dhcp_dictionary.xml

All DHCP policy expressions are not case sensitive. For example both these expressions are valid:

DHCPv4.Offer.TransactionIddhcpV4.OFFER.transactionID

1.6.1 DHCPv4The DHCPv4 functions are:

DescriptionFunction

Returns list of configured DHCP Lease Query IPs for given site number.DHCPv4.GetServerList(SiteNumber: number)SiteNumber is the configured site numberIf there is no DHCP Lease Query server configured with given site numberthe action will return NULL. Otherwise it returns a string filled with commaseparated list of server IPv4 addresses. These IPs can be used inLeaseQueryByIp or LeaseQueryByMac actions.

Sends lease query requests to configured DHCPv4 servers by IP or MAC.DHCPv4.LeaseQueryByIp(Status: st,TransactionId: trid, Peer: ServerIP, IpAddress:ClientIP)

Returns true on success and false on failure. If an action failed the "st" willindicate the failure reason.

DHCPv4.LeaseQueryByMac(Status: st,TransactionId: trid, Peer: ServerIP, MacAddress:ClientMAC)

Parameters are:

Status - optional output parameter that indicates error reason

TransactionId - optional output parameter that returns transaction idassigned to the sent request.

Peer - mandatory parameter that specifies one of configured DHCPservers.

IpAddress -mandatory parameter that specifies required client IP.

MacAddress -mandatory parameter that specifies required client MAC.

1.6.2 DHCPv6The DHCPv6 functions are:


FunctionsDHCP Functions

DescriptionFunction

Sends lease query requests to configured DHCPv6 servers by IP or clientID.

DHCPv6 .LeaseQueryByIp(Status: st,TransactionId: trid, Peer: ServerIP, IpAddress:ClientIP) Returns true on success and false on failure. If an action failed the "st" will

indicate the failure reason.DHCPv6. LeaseQueryByClientId(Status: st,TransactionId: trid, Peer: ServerIP, MacAddress:ClientID)

Parameters are:

Status - optional output parameter that indicates error reason

TransactionId - optional output parameter that returns transaction idassigned to the sent request.

Peer - mandatory parameter that specifies one of configured DHCPservers.

IpAddress -mandatory parameter that specifies required client IP.

ClientID -mandatory parameter that specifies required client ID.

1.7 RADIUS FunctionsThe RADIUS subsystem allows sending RADIUS requests (Client Actions) and replying for arrived RADIUS requests by sendingRADIUS responses (Server Actions).

Actions returns true on success and false on failure. All RADIUS policy expressions are not case sensitive.

1.7.1 RADIUS Client FunctionClient functions are used to initiate RADIUS requests.

RADIUS.(Peer: PeerId, [AVPName1: AVPValue1] [, AVPName2: AVPValue2] ...)

Where:

Peer - configured RADIUS peer identification string. Mandatory parameter.

AVPName - name of one of AVPs from the dictionary, Optional parameter.

Example:This policy example sends an Access-Request packet using the configured peer labeled as "Myself". The packet's AVPUser-Name is set to "bob", the AVP User-Password is set to "bobs password" and the AVP Framed-IP-Address is set to10.10.10.10.

Radius.Access-Request(Peer: "Myself", User-Name: "bob",\User-Password: "bobs password", Framed-IP-Address: StringToIP("10.10.10.10")

)

1.7.2 RADIUS Server FunctionServer Actions are used to reply to a RADIUS requests.

To reply to a request, the policy should know these request parameters:


FunctionsRADIUS Functions

request authenticatorrequest transaction Idrequest sender IP addressrequest sender IP portrequest server Id

The syntax is:

RADIUS.(Server-Id: ServerId, Peer-IP-Address: PeerIPAddress, \Peer-IP-Port: PeerIPPort, Id: RequestId, Request-Authenticator: Auth, \[AVPName1: AVPValue1] [, AVPName1: AVPValue1] ...)

Where:

Id of the listener interface through which the request was received. Mandatoryparameter.

Server-Id

the request sender IP.Peer-IP-Address

the request sender port.Peer-IP-Port

the request transaction ID.Id

the request authenticator.Request-Authenticator

name of one of the AVPs from the dictionary.AVPName

Example:This example sends an Accounting-Response as a reply to an Accounting-Request packet using the listener interfacethrough which the request was received. The reply is sent back to the request originator. The packet will have the sameauthenticator and transaction ID as the original request, and the AVP Called-Station-ID set to value 100.

if expr(RADIUS.Accounting-Request.Id is not null) then \RADIUS.Accounting-Response(Server-Id: RADIUS.Accounting-Request.Server-Id, \Peer-IP-Address: RADIUS.Accounting-Request.Peer-IP-Address, \Peer-IP-Port: RADIUS.Accounting-Request.Peer-IP-Port, \Id: Radius.Accounting-Request.Id, \Request-Authenticator: Radius.Accounting-Request.Auth, \Called-Station-ID: 100)



2SandScript Fields "Measurements" on page 25

"Classifiers" on page 27

"Timers" on page 28

"Tables" on page 28

"Events" on page 29

"Subscriber Session Fields" on page 29

"Subscriber and Session Attributes" on page 31

"Utility Fields" on page 32

"Expressions for Unique-by" on page 32

"Provisioning" on page 32

"Published Expressions" on page 36

"Environment Fields" on page 36

"Diameter Fields" on page 36

"DHCPv4" on page 38

"DHCPv6" on page 41

"GTP-C" on page 43

"ID Allocation" on page 56

"LDAP " on page 60

"RADIUS" on page 63

"Text Input" on page 66

"Failover Cluster" on page 67

"External Command" on page 67


SandScript Fields

2.1 MeasurementsEach measurement defined in a policy has an associated field, where is the name of the measurement.The field returns the current value of the measurement based on the measurement type.

For more information on using measurements, see Measurements in the PTS SandScript Configuration Guide.

2.1.1 Measurement FieldsMeasurements are taken over time:

Measurements with an over interval specified expose values from both the current and previous interval. The regular (non-current) fields return the value from the end of the previous interval. The current fields return the value so far, from the current interval. Current fields are not available for Top-N measurements,

or measurements over infinity.

TypeDescriptionField

IntegerEach measurement defined in SandScript has an associatedfield, where is the name of the

Measurement.

measurement defined in policy.conf. The field returns thecurrent value of the measurement based on the measurementtype.

connections: current number of active connections bitrate: current bitrate, in bits per second hosts: current number of hosts expression: current value of the expression sum or generic: the previous interval value of the

measurement if it is over some interval, the current valueotherwise, settable for generic measurements

histogram: returns NULL. Histogram measurements do nothave a single value

IntegerReturns the peak value of the measurement. If unique-by,returns the peak value of the highest instance measured.

Measurement..Peak

IntegerThe total number of instances being counted by a unique-bymeasurement.

Measurement..Instances

The number of instances may be larger than the number of theunique-by qualifier. For example, for a measurement unique-bysubscriber and the subscriber has multiple IPs, each IP couldbe assigned to different processing modules. Since eachsubscriber instance is counted for each assignment, there aremore instances counted than there are unique-by qualifiers.

IntegerReturns the peak value ofMeasurement..Instances

Measurement..PeakInstances

IntegerThe sum of the values for all instances of a unique-bymeasurement.

Measurement..Total

IntegerReturns the peak value ofMeasurement..Total

Measurement..PeakTotal


SandScript FieldsMeasurements


BooleanReturns true if the current instance was in the top N during theprevious measurement interval, otherwise returns false.Available for top measurements only.

Measurement..IsTop

FloatReturns the floating point minimum value observed by themeasurement. Available for histogram measurements only.

Measurement..Min

FloatReturns the overall minimum value observed by all instancesof the measurement. Available for unique-by histogrammeasurements only

Measurement..OverallMin

FloatReturns the floating point maximum value observed by themeasurement. Available for histogram measurements only.

Measurement..Max

FloatReturns the overall maximum value observed by all instancesof the measurement. Available for unique-by histogrammeasurements only

Measurement..OverallMax

FloatReturns the floating point sum of all values observed by themeasurement. Available for histogram measurements only.

Measurement..Sum

FloatReturns the sum of all values observed by all instances of themeasurement. Available for unique-by histogrammeasurementsonly.

Measurement..TotalSum

FloatReturns the number of values observed by the measurement.Available for histogram measurements only

Measurement..Samples

FloatReturns the number of values observed by all instances of themeasurement. Available for unique-by histogrammeasurementsonly.

Measurement..TotalSamples

IntegerReturns the value of the measurement from the current interval.Settable for generic measurements with an over interval.

Measurement..Current

IntegerReturns the peak value of the measurement from the currentinterval.

Measurement..CurrentPeak

IntegerThe total number of instances being counted by a unique-bymeasurement from the current interval.

Measurement..CurrentInstances

IntegerThe peak number of instances being counted by a unique-bymeasurement from the current interval.

Measurement..CurrentPeakInstances

IntegerThe sum of the values for all instances of a unique-bymeasurement from the current interval.

Measurement..CurrentTotal

IntegerThe peak sum of the values for all instances of a unique-bymeasurement from the current interval.

Measurement..CurrentPeakTotal

FloatReturns the floating point minimum value observed by themeasurement from the current interval. Available for histogrammeasurements only.

Measurement..CurrentMin

FloatReturns the overall minimum value observed by all instancesof the measurement from the current interval. Available forhistogram measurements only.

Measurement..CurrentOverallMin


SandScript FieldsMeasurements


FloatReturns the floating point maximum value observed by themeasurement from the current interval. Available for histogrammeasurements only.

Measurement..CurrentMax

FloatReturns the overall maximum value observed by all instancesof the measurement from the current interval. Available forhistogram measurements only.

Measurement..CurrentOverallMax

FloatReturns the floating point sum of all values observed by themeasurement from the current interval. Available for histogrammeasurements only.

Measurement..CurrentSum

FloatReturns the sum of all values observed by all instances of themeasurement from the current interval. Available for histogrammeasurements only.

Measurement..CurrentTotalSum

FloatReturns the number of values observed by the measurementfrom the current interval. Available for histogrammeasurementsonly.

Measurement..CurrentSamples

FloatReturns the number of values observed by all instances of themeasurement from the current interval. Available for histogrammeasurements only.

Measurement..CurrentSamples

2.1.2 Measurement Fields UsageFields are used to access existing measurements and information about them.

Example:This example defines a measurement BittorrentUpPercentage which expresses the upstream bandwidth consumed byBitTorrent as a percentage of the total available bandwidth (constant 15000000). An expression must be used to createthe percentage measurement. Note that only scalar integer expressions can be used to create measurements. Theseexpressions are not specific to any packet, flow, or subscriber.

measurement "UploadToExternal" bitrate where receiver class "external"measurement "UpToExternalPercentageTot" \expr(Measurement.UploadToExternal*100/15000000)

2.2 ClassifiersClassifiers are used to apply labels to SandScript contexts such as subscribers, and/or for categorization into meaningful groups.A classifier's value is set and checked through its field. See the Classifiers section of the SandScript Configuration Guide foradditional information.


policy- definedUsed to set or check the value of a classifier, where is the name of the classifier.

Classifier.

StringRepresents the name of an enumerated classifier.Classifier..Name


SandScript FieldsClassifiers


IntegerA constant field used to set the value of an enumeratedclassifier. One of these is defined for each value specified inan enumerated classifier definition.

Classifier..

2.3 TimersSandScript timers generate an event at some point in the future. When the event occurs, SandScript rules available in the timer'scontext are evaluated. See the Timers section of the SandScript Configuration Guide for additional information.


BooleanReturns true if the current SandScript policy run was causedbecause timer expired, otherwise this is false.Use this field to cause SandScript to run when a timer expires.

Timer..Expired

BooleanReturns true if the timer is currently armed.Otherwise it returns false.

Timer..IsArmed

IntegerReturns a timestamp for the time when timer will expire. You can interpret the integer as the number of

Timer..ExpiryTime

seconds since January 1, 1970. This returns NULL if the timeris not armed.

IntegerReturns the time when the specified timer will expire. You caninterpret the integer as the number of milliseconds since January1, 1970. This returns NULL if the timer is not armed.

Timer..ExpiryTimeMs

2.4 TablesTables are used to store state and build state machines in SandScript and are similar to tables in a database. See the Tablessection of the SandScript Configuration Guide for additional information.


policy- definedThe field used to read from or write to a table, where is the name of the table and is

Table..Table.[Key].

the name of the column. For explicit access to a table row,specify a Key list within square bracket accessors.

table.:cursor

The delete_row action must reference this field to delete a rowfrom a table, where is the name of the table. Youcan also use this field to assign a row to a cursor local variable.

Table.Table.[Key]

For explicit access to a table row, specify a Key list withinsquare bracket accessors.

Returns the current number of rows in the secondary index thatcontains .

Table..[].Count

Returns the first table row in the secondary index with thespecified value. This is mainly useful when the secondary index

Table..[].First

happens to be unique. It permits access to the row without the


SandScript FieldsTimers


foreach statement. You can also use this field to assign a rowto a cursor local variable.

2.5 EventsYou can use SandScript to define events to let one application raise an event that other applications can listen for and take actionon. See the Events section of the SandScript Configuration Guide for additional information.


BooleanReturns true whenever the event is raised. Otherwise, it returnsfalse.

Event.

policy- definedReturns the value of argument of event. Returns null if the argument was not specified

Event..

when the event was raised. This field is only evaluated whenthe event is raised.

2.6 Subscriber Session FieldsYou must have Subscriber IP mapping deployed to use subscriber IP mapping fields.

Session fields are identical to subscriber-scope IP mapping fields when used without square bracket accessors. When used withsquare bracket accessors, session fields are more versatile than regular IP mapping fields since they can access properties andattributes of any subscriber session for which the IP address or session ID is known.

For Session fields, may be one of these types:

IP Address - returns results for the subscriber session mapped to this IP address (in site 0), or NULL if no session is mappedto this IP address.

Integer- returns results for the subscriber session with a session ID equal to this value, or NULL if there is no session in thesystem with the given ID.


IP addressReturns the user prefix of the IP address mapped to thissubscriber session.

Session.IpPrefixSession[].IpPrefix

The user prefix is the first N bits of the IP address, where N isthe value that the Session.PrefixLength field returns.

IpAssignment.IpPrefix

IP addressReturns the length of the IP prefix mapped to this subscribersession.

Session.PrefixLengthSession[].PrefixLength

If a subscriber is assigned an IPv6 address with a 64-bit prefix,this field will return 64.

IpAssignment.PrefixLength

BooleanReturns a boolean value having the value true if the subscriberfor this session is discovered.

Session.IsMappedSession[].IsMapped

BooleanReturns a boolean value indicating whether or not the host ismapped. This field is only used in a subscriber-scoped rule.

Subscriber.IsMappedIpAssignment.IsMapped

IntegerReturns the number of seconds that has elapsed since asubscriber mapping request was sent for the specified IPaddress.

Session.AgeSession[].Age


SandScript FieldsEvents


IntegerReturns the number of seconds that has elapsed since asubscriber mapping request was sent for the specified node.

IpAssignment.Age

IntegerReturns the mapped subscriber identification for the specifiedIP address. Returns NULL if the IP is not mapped.

Session.SubscriberSession[].SubscriberSession.Subscriber.IdSession[].Subscriber.Id

StringReturns a string representing the qualifier that applies to thissubscriber session. Examples are: Site:10 or Site:200.Returns NULL if no subscriber session exists.

Session.SessionQualifierSession[].SessionQualifier

Returns a list of public IP addresses and port ranges associatedwith the current subscriber session. These fields are typically

Session.PublicIPsSession[].PublicIPs

used to acquire details about the post-NAT IP address and portranges in use by this subscriber. This field can be used in aforeach statement, where the following fields can be accessed: IPContains the actual IP address portion of the public IP.

LowPortContains the lower bound (inclusive) of the rangeof ports for this public IP.

HighPortContains the higher bound (inclusive) of therange of ports for this public IP.

For example:

foreach "mapping" in Session.PublicIPs { \if expr(mapping.IpAddress =

StringToIP("10.10.10.1") and \mapping.LowPort > 100 and \mapping.HighPort < 1000) then\increment Measurement.SpecificMappings

}

IntegerReturns the site session qualifier number of the subscribersession.

Session.SiteSession[].Site

IntegerReturns an integer representing a unique identifier for thissubscriber session. Returns NULL if no subscriber sessionexists.

Session.IdSession[].Id

IntegerSubscriber scope field returning the mapped subscriberidentification. Returns NULL if the IP is not mapped.

SubscriberSubscriber.IdIpAssignment.Subscriber.Id

StringReturns the name of the subscriber mapped to the specified IPaddress. Returns NULL if the IP is not mapped.

Session.Subscriber.NameSession[].Subscriber.Name

StringSubscriber scope field returning the name of the subscriber.Returns NULL if the IP is not mapped.

IpAssignment.Subscriber.Name

IntegerReturns a timestamp (number of seconds since epoch)indicating the time that a subscriber mapping request was sent

Session.CreatedTimeSession[].CreatedTime

for the specified IP address. Returns NULL if no subscribersession exists.

IntegerReturns a timestamp (number of seconds since epoch)indicating the time that a subscriber mapping request was sentfor the specified node. Returns NULL if the IP is not mapped.

IpAssignment.CreatedTime

IntegerReturns a timestamp (number of milliseconds since epoch)indicating the time that a subscriber mapping request was sent

Session.CreatedTimeMsSession[].CreatedTimeMs

for the specified IP address. Returns NULL if no subscribersession exists.

IntegerReturns a timestamp (number of seconds since epoch)indicating the time that the session at the specified IP address

Session.MappedTimeSession[].MappedTime


SandScript FieldsSubscriber Session Fields


becamemapped (subscriber mapping response was received).Returns NULL if no subscriber session exists.

IntegerReturns a timestamp (number of seconds since epoch)indicating the time that the specified node became mapped

IpAssignment.MappedTime

(subscriber mapping response was received). Returns NULLif the IP is not mapped.

IntegerReturns a timestamp (number of milliseconds since epoch)indicating the time that the session at the specified IP address

Session.MappedTimeMsSession[].MappedTimeMs

becamemapped (subscriber mapping response was received).Returns NULL if no subscriber session exists.

IntegerReturns a timestamp (number of seconds since epoch)indicating the time of session creation on the accounting host

Session.NetworkMappedTimeSession[].NetworkMappedTime

(beginning of authorization server host accounting record).Returns NULL if the IP is not mapped.

IntegerReturns a timestamp (number of milliseconds since epoch)indicating the time of IP assignment on the accounting host

Session.NetworkMappedTimeMsSession[].NetworkMappedTimeMs

(beginning of authorization server host accounting record).Returns NULL if no subscriber session exists.

IntegerReturns a timestamp (number of seconds since epoch)representing the expiry time of the subscriber mapping at the

Session.TimeoutSession[].Timeout

specified IP address. Returns NULL if no subscriber sessionexists.

IntegerReturns a timestamp (number of seconds since epoch)representing the expiry time of the subscriber mapping. ReturnsNULL if the IP is not mapped.

Subscriber.Timeout

IP addressReturns the IP address of an IP assignment (an IP that hasbeen looked up for subscriber mapping).

Session.IpAddressSession[].IpAddressIpAssignment.IpAddress

BooleanReturns true the first time SandScript runs on an IP that hasjust been mapped to a subscriber, otherwise returns false.

Session.IsNew

BooleanReturns true the first time SandScript runs on an IP that hasjust been mapped to a subscriber, otherwise returns false.

IpAssignment.IsNew

BooleanReturns true the first time SandScript runs on an IP that hasjust been unmapped, otherwise returns false.

Session.IsEndIpAssignment.IsEnd

BooleanReturns true when Session.IsEnd is true and the IP becameunmapped due to a logout notification, otherwise returns false.

Session.IsLogoutIpAssignment.IsLogout

BooleanReturns true when Session.IsEnd is true and the IP mappingtimed out due to an absence of traffic over a configured period

Session.IsTimeoutIpAssignment.IsTimeout

of time (see the output of this CLI command: show configservice subscriber-management timeoutinactivity).

2.7 Subscriber and Session AttributesA session attribute is associated with a single subscriber session (a single subscriber to IP mapping). When that session ends,the attribute is no longer defined, even if the subscriber has other active sessions.

Subscriber attributes are writable, but session attributes are read-only. Session attributes are typically gleaned from a subscriber'sDiameter/RADIUS login session.


SandScript FieldsSubscriber and Session Attributes


user- definedReturns the value of the subscriber attribute for the specified IP address.

Session.Subscriber. Attribute.Session[]. Subscriber.Attribute.

user- definedReturns the value of the subscriber attribute .The returned value can be used to specify a load-balancing,unique-by or shared-by specification, or in subscriber scope tocheck/set the value of the subscriber attribute.

Subscriber.Attribute.

BooleanReturns true the first time SandScript runs on a subscriberwhose subscriber attribute was changedexternal to SandScript, false otherwise.

Session.Subscriber.Attribute..IsUpdatedSubscriber.Attribute..IsUpdated

policy- definedReturns the value of the session-based attribute.

Session.Attribute. Session[].Attribute.

The returned value can be used to specify a unique-by orshared-by specification, or to check the value of the sessionattribute.Session Attributes are read-only.

BooleanReturns true the first time SandScript runs on a subscriberwhose session-based attribute was changedexternal to SandScript, false otherwise.

Session.Attribute. .IsUpdated

2.8 Utility FieldsUtility fields include:


FloatReturns a value between 0 and 1.Random

IntegerReturns a value representing the number of seconds elapsed since January 1, 1970.Now

IntegerReturns a value representing the number of milliseconds elapsed since January 1, 1970.NowMs

2.9 Expressions for Unique-byUnique-by clauses can use single expressions or multiple expressions by putting expressions in expression lists.

Treat different categories of subscribers appropriately. This is useful for measurements, and tables. For subscriber scopeunique-by, subscriber IP mapping is required.

2.10 ProvisioningThe Provision fields are:


SandScript FieldsUtility Fields


BooleanProvision events indicate when an action has occurred. Set to TRUE whenthe event happens.

Provision.Session.ReconcileProvision.Session.IsComplete

These events have different policy contexts. They cannot be combined intoa single expression.

IP AddressThe subscriber's IPv4 or IPv6 address.If only one IP address is used, the form "IPv4.Address" may be used as asynonym for "IPv4[0].Address". The same goes for "IPv6.Address". It may

Provision.Session.IPv4[i].AddressProvision.Session.IPv6[i].Address

be an integer expression. The index cannot be a literal NULL - if it is, thepolicy will fail to load.

StringThe address prefix and qualifier.If only one IP address is used, the form "IPv4.Address" may be used as asynonym for "IPv4[0].Address". The same goes for "IPv6.Address". It may

Provision.Session.IPv4[i].DescriptionProvision.Session.IPv6[i].Description be an integer expression. The index cannot be a literal NULL - if it is, the

policy will fail to load.

IntegerThe subscriber's IPv4 or IPv6 prefix length.Provision.Session.IPv4[i].PrefixProvision.Session.IPv6[i].Prefix

StringIdentifies the subscriber.Provision.Session.SubscriberID

StringIdentifies the session.Provision.Session.SessionQualifier

IntegerThe site numberProvision.Session.SessionQualifier.SiteNumber

IntegerIdentifies the session realm.Provision.Session.Realm

StringIdentifies the server that should be queried in order to reconcile the session.The ReconcileID is provided in the provision request.

Provision.Session.ReconcileID

IntegerIndicates the state of the request. Possible values are:Provision.Session.State

Provision.STATE_LOGIN_SUCCESS

Provision.STATE_LOGOUT_SUCCESS

Provision.STATE_PROCESSING_FAILED

IntegerIdentifies the network source. The subscriber mapping policy applicationuses this to determine whether the source of the session was RADIUS,GTP-C, or DHCP traffic.

Provision.Session.NetworkSource

StringAny opaque data that was set at theProvisioning.Session.ProvisionSubscriber action. N can be from 0 to 19.

Provision.Session.OpaqueDataProvision.Session.OpaqueData[N]

IntegerIdentifies the transaction ID of the request.Provision.Session.TransactionID

IntegerIdentifies the reason that the reconcile event was raised. Possible valuesare:

Provision.Session.ReconcileSource

Provision.RECONCILE_SOURCE_TTL - Reconcile triggered due to TTLexpiration.

Provision.RECONCILE_SOURCE_CACHE_MISS - Reconcile triggeredby a cache miss received from the SPB.

Provision.RECONCILE_SOURCE_NONE - No reconcile was sent yet.


SandScript FieldsProvisioning


IntegerThe type of the reques. Possible values are:Provision.Session.Presence

Provision.PRESENCE_LOGIN: Subscriber logged in, or updated.

Provision.PRESENCE_LOGOUT: Subscriber logged out

IntegerIndicates the time in milliseconds of the provisioning request. This time isused by the SPB for session management.

Provision.Session.Timestamp

2.10.1 Provisioning NATProvision.Nat.* expressions are available in all three NAT contexts: Provision.Nat.Map.IsComplete, Provision.Nat.Unmap.IsCompleteand Provision.Nat.Map.Reconcile.

For example:

if expr(Provision.Nat.Map.IsComplete) then \log values (Provision.Nat.InternalIP)


BooleanIndicates when NAT mapping, unmapping or reconcile has occurred. Set toTRUE when the event happens.

Provision.Nat.Map.IsCompleteProvision.Nat.Unmap.IsComplete

These events have different policy contexts. They cannot be combined intoa single expression.

Provision.Nat.Map.Reconcile

IntegerIdentifies the transaction ID of the request.Provision.Nat.TransactionID

IP AddressThe private IP address.Provision.Nat.InternalIP

IntegerThe IPv4 prefix length.Provision.Nat.InternalPrefix

IntegerThe IPv4 site number.Provision.Nat.InternalSiteNumber

IP AddressThe public IPv4 address.Provision.Nat.ExternalIP

IntegerThe low port block number.Provision.Nat.LowPort

IntegerThe high port block number.Provision.Nat.highPort

IntegerIndicates the time in milliseconds of the NAT mapping request. This time isused by the SPB for session management.

Provision.Nat.Timestamp

IntegerIndicates the state of the request. Possible values are:Provision.Nat.State

Provision.STATE_LOGIN_SUCCESS

Provision.STATE_LOGOUT_SUCCESS

Provision.STATE_PROCESSING_FAILED

IntegerInteger that identifies the reason that the reconcile event was raised. Thepossible values are:

Provision.Nat.ReconcileSource

Provision.RECONCILE_SOURCE_TTL - Reconcile triggered due to TTLexpiration.

Provision.RECONCILE_SOURCE_CACHE_MISS - Reconcile triggeredby a cache miss received from the SPB.

Provision.RECONCILE_SOURCE_NONE - No reconcile was sent yet.




StringAny opaque data that was set by the Provisioning.Nat.Map orProvisioning.Nat.Unmap action. N can be from 0 to 19.

Provision.Nat.OpaqueDataProvision.Nat.OpaqueData[N]

2.10.2 Provisioning.Subscriber.GetThe SandScript action fetches a subscriber profile by name from the SPB Database and returns a transaction ID to the Getrequest, or returns 0 in case of the Get request failure.

For example:

if expr(Provision.Subscriber.Get.State = Provision.STATE_GET_PROCESSING_FAILED) \then log values ("Provision.STATE_GET_PROCESSING_FAILED")


BooleanReturns an integer to identify the transaction ID of the request. Returning 0indicates failure.

Provision.Subscriber.Get.IsComplete

IntegerThe transaction ID issued by the SPB for the Get request.Provision.Subscriber.Get.TransactionID

IntegerIndicates the state of the Get request. Possible values are:Provision.Subscriber.Get.State

Provision.STATE_GET_SUCCESS

Provision.STATE_GET_SUBSCRIBER_NOT_FOUND

Provision.STATE_GET_PROCESSING_FAILED

StringThe subscriber name in the SPB table.Provision.Subscriber.Get.Name

StringThe subscriber ID in the SPB table.Provision.Subscriber.Get.SubscriberID

StringThe attribute that defines a subscriber. For example: Attribute.Tier:"Gold"

Provision.Subscriber.Get.Attribute.

StringAny opaque data that was set by the Provisioning.Subscriber.Get action. Ncan be integer expression. The value of N need to be from 0 to 19.

Provision.Subscriber.Get.OpaqueData [N]

2.10.3 Provisioning.Subscriber.DeleteProvisioning.Subscriber.Delete, deletes subscriber by name from the SPB.

For example:

if expr(Provision.Subscriber.Get.State = Provision.STATE_OPERATION_PROCESSING_FAILED) \then log values ("Provision.STATE_OPERATION_PROCESSING_FAILED")

Returns an integer to identify the transaction ID of the request. Returning 0 indicates failure. Thedata type is bollean.

IsComplete

The transaction ID issued by the SPB for the Get request. The data type is integer.TransactionIDIndicates the state of the Get request.The data type is integer. Possible values are:Name

Provision.STATE_GET_SUCCESS

Provision.STATE_GET_SUBSCRIBER_NOT_FOUND

Provision.STATE_GET_PROCESSING_FAILED



Any opaque data that was set by the Provisioning.Subscriber.Delete action. N can be integerexpression. The value of N need to be from 0 to 19. The data type is string.

OpaqueData [N]

2.11 Published ExpressionsSome PTS expressions can be periodically logged for reporting in Network Demographics.

The syntax used to publish an expression is:

publish "published_expr_name" expression

Where:

"published_expr_name" is a string which identifies the published expression. expression defines the value of the expression.

The expression published must be a scalar expression, which is not unique to individual subscribers, packets or flows. Publishedexpressions can be viewed using the CLI and via Network Demographics.

publish "MyMeasurement" measurement.MeasurementNamepublish "ShaperDroppedPackets" Shaper.HttpShaper.PacketsDroppedpublish "Limiter" Limiter.LimiterName.LimitedFlows

2.12 Environment FieldsEnvironment fields reveal the state of the element in policy.


StringReturns a string representing the hostname of the element on which thepolicy engine is running.

Element.Hostname

BooleanReturns true if policy is being run because of a successful reload. Thisfield is only available in policy reload scope.

Policy.Reloaded

IntegerReturns a timestamp for the last time policy was successfully reloaded,represented as the number of seconds elapsed since January 1, 1970.This field can be used in any scope.

Policy.ReloadTimestamp

IntegerReturns an integer representing the number of milliseconds that hadelapsed since January 1, 1970, the last time policy was successfullyreloaded. This field can be used in any scope.

Policy.ReloadTimestampMs

2.13 Diameter FieldsDiameter fields reveal information from Diameter messages according to a dictionary defined by the Diameter subsystem. Thesefields are available in a Diameter message scope defined by the subsystem.


SandScript FieldsPublished Expressions


Dictionary-definedReturns the value of a Diameter message header field.DictionaryName is the name of the dictionary that defines theAVP. CommandName is the name of the application commandthat defines the message.

Diameter...

CommandSuffix is one of:

Request Answer Answer-ErrorHeaderField is one of:

Proxiable: Returns true if the p-bit in the message headeris set, false otherwise.

Retransmitted: Returns true if the t-bit in the messageheader is set, false otherwise.

End-to-End: Returns the integer value of the end-to-endidentifier from the Diameter message header.

Hop-by-Hop: Returns the integer value of the hop-by-hopidentifier from the Diameter message header.

Application-Id: Returns the integer value of the application-idfrom the Diameter message header.

PeerIndex: Returns an integer that identifies the peer thatsent the Diameter message. The value of this field from arequest message should be used as the value for thePeerIndex argument when sending the answer to therequest.

Dictionary-definedReturns the value of an Attribute-Value Pair (AVP).DictionaryName is the name of the dictionary that defines theAVP. CommandName is the name of the application commandthat defines the message.

Diameter...{[Index1]}{.{[Index2]} ...}


Request Answer Answer-ErrorAvpName1 is the name of an AVP from the dictionary. Indexis an integer expression that specifies the instance of the AVPto access. If the Index expression is absent a value of 0 isassumed. Grouped AVPs are of type boolean.When a groupedAVP is present its value is true. When absent the value is null.If a dictionary name, command name, or AVP name starts withsomething other than a lower or upper case letter, or if the namecontains anything other than a alphanumeric characters orunderscores, then the name needs to be surrounded by singlequotes.For example: Diameter.Gy.'CC-Answer'.'Session-Id'

Dictionary-definedReturns the value of a request AVP.CommandName is the name of the application command thatdefines the message.

Diameter...Request.


Answer Answer-Error


SandScript FieldsDiameter Fields


All Diameter answers expose request AVP fields. The requestAVP fields can be accessed with the ".Request" and then theAVP accessor fields.For example:Diameter.Gy.'CC-Answer'.Request.'CC-Request-Type'

Dictionary-definedReturns the raw form of an AVP as a string. Each AVP can beaccessed in policy through its accessor field. The raw value of

.RawValue

an AVP can be accessed with the .RawValue field. The.RawValue field of an AVP evaluates to a string containingthe full raw AVP value which includes the AVP header, valueand padding. The request raw AVP values are also accessiblein an answer.FieldName is any Diameter AVP field.For example: Diameter.Gy.'CC-Answer'.'Result-Code'.RawValueDiameter.Gy.'CC-Answer'.Request.'CC-Request-Type'.RawValue

2.14 DHCPv4The DHCPv4 subsystem generates events for every

sde sandscript reference guide r.6.40 a02.pdf

Documents

string functions

a02noticescontents1

general functions

time functions

math functions

network functions

encryption functions

commentsto sandvine