Key concepts and features

This section covers key concepts and features you can reference when implementing Lua scripting in FortiWeb:

• Definition of terms

• Control structures

• Operators

• Functions

• String library

• Special characters

Lua package compatibility

FortiWeb uses Lua version 5.4.

Definition of terms

Frontend

The connection established between the client and FortiWeb when accessing a virtual server service.

Backend

The connection between FortiWeb and the real server after FortiWeb receives and load-balances the client request.

Source IP address (frontend)

The client IP address on the frontend connection.

Destination address (frontend)

The virtual server IP address on the frontend connection.

Source IP address (backend)

The IP address of FortiWeb’s outgoing interface on the backend connection.

Destination address (backend)

The real server IP address on the backend connection.

Control structures

The following table lists the Lua control structures.

if condition1 then
    ...
elseif condition2 then
    ...
    break
else
    ... 
    goto location1 
end
 
::location1::

for k, v in pairs(t) do
...
end

Operators

Operators are symbols used to perform specific mathematical or logical manipulations.

The Lua language includes the following categories of built-in operators:

• Arithmetic operators

• Bitwise operators

• Relational operators

• Logical operators

• Miscellaneous operators

For more details, see the Lua Reference Manual.

Arithmetic operators

The arithmetic operators listed below operate on real numbers. In the Example column, assume that variable A is 10 and variable B is 20.

Bitwise operators

Bitwise operators convert its operands to integers, operate on all bits of those integers, and result in an integer.

In the Example column, assume we have two integer variables with binary representations:

a = 1100; // (12 in decimal)

b = 1010; // (10 in decimal)

Relational operators

Lua provides the Relational operators listed below. This type of operator always results in true or false.

In the Example column, assume variable A is 10 and variable B is 20.

Logical operators

Lua provides the Logical operators listed below. This type of operator considers false and nil both as false, and anything else as true.

In the Example column, assume variable A is 0 and variable B is 10.

Miscellaneous operators

Miscellaneous operators supported by Lua include concatenation and length.

Functions

FortiWeb supports basic lua commands. Additional capabilities can be implemented by creating custom functions using these commands.

Syntax

function function_name(parameter)
…
End

For example, this function extracts all IPs from XFF headers and returns IP array:

function extract_xff(xff)
    local t = {}
    local k, v, s
    for k, v in ipairs(xff) do
        for s in v:gmatch("([^,]+)") do
            t[#t + 1] = s:gsub("%s+", "")
        end
    end
    return t
end
when HTTP_REQUEST {
    local ips = extract_xff(HTTP:header("X-Forwarded-For"))
    local r, i, v
    for i, v in ipairs(ips) do
        r = ip.reputation(v) -- check ip, will return an array
        if #r > 0 then -- Found IP in reputation database
            debug("Found bad IP %s in XFF headers, reputation: <%s>, GEO country: <%s>, GEO country code: %s\n",
                v, table.concat(r, ', '),
                ip.geo(v) or "unknown", ip.geo_code(v) or "unknown")
            HTTP:close() -- force close this HTTP connection
            return -- Stop script and return
        end
    end
}

String library

The FortiWeb OS supports only the Lua string library. All other libraries are disabled. The string library includes the following string-manipulation functions:

• string.byte(s, i)

• string.char(i1,i2…)

• string.dump(function)

• string.find(s, pattern)

• string.format

• string.gmatch

• string.gsub

• string.len

• string.lower

• string.match

• string.rep

• string.reverse

• string.sub

• string.upper

• string.starts_with

• string.ends_with

If you want to use regular expression match, you can use string.match with Lua patterns. All relational operators >, <, >=, <=, ~=, == can be applied to strings. In particular, == can be used to test if one string equals to another string. string.find can be used to test whether one string contains another string.

For a tutorial on scripting with the Lua string library, see http://lua-users.org/wiki/StringLibraryTutorial.

Special characters

When written in a string, these characters look like this (between double quotes): "~!@#$^&*()_+{}[].?"

Note: The back slash (\) and the percent (%) signs are handled in a unique way in log and debug scripts. To print out %, you must use %%; to print out \, you must use \\.

HTTP data body commands

HTTP data body commands support regular expressions, where special characters such as $ ^ ? * + . | ( ) [ ] { } \ " have special meanings. You must escape these characters to treat them as literal values.

To escape a special character, prefix it with two backslashes (\\).

For example, to use the literal caret (^) in an HTTP data body command, enter \^.

For grouping characters such as parentheses (), square brackets [], or braces {}, prefix each character with two backslashes.

For example, to use the {and}, enter \\{and\\}.